Począwszy od wersji API 2026-07, typ User i Query.users zyskują nowe pola, typy, wartości wyliczeniowe i argumenty, a także nowe zapytanie najwyższego poziomu user_configs. Wymuszona zostaje również paginacja w users. Kilka starszych pól typu User jest przestarzałych i ma zostać usuniętych w wersji 2026-10. Sprawdź dostępność za pomocą introspekcji lub informacji o wydaniu dla używanej wersji.

Ten przewodnik opisuje migrację integracji ze struktury encji User z wersji 2026-04 (lub wcześniejszej) do struktury z wersji 2026-10.

Krótka lista kontrolna

Przed migracją wyszukaj w bazie kodu:

• photo_original, photo_thumb, photo_thumb_small, photo_tiny, photo_small
• is_guest, is_admin, is_view_only, is_pending, enabled
• is_verified, join_date
• encrypt_api_token, sign_up_product_kind
• users(kind: ...), users(newest_first: ...), users(non_active: ...)
• wywołania users { ... } bez argumentu limit (niejawny limit paginacji wynoszący 200)
• users(emails: ...), w których dowolny element może mieć wartość null
• odczyty User.birthday, które parsują tę wartość jako Date
• odczyty User.created_at, które parsują tę wartość jako Date (bez części określającej godzinę)
• odczyty User.utc_hours_diff, które zakładają, że wartość jest liczbą całkowitą

W poniższych sekcjach znajdziesz zamiennik dla każdego z tych przypadków.

---

:rotating_light: Zmiany niekompatybilne wstecz

1. Pola zdjęcia → zagnieżdżony obiekt photo_url

Pięć płaskich pól zdjęcia jest przestarzałych. Zastąp je zagnieżdżonym obiektem PhotoUrl.

Przed (2026-04):

query {
  me {
    photo_original
    photo_small
    photo_thumb
    photo_thumb_small
    photo_tiny
  }
}

Po (2026-07+):

query {
  me {
    photo_url {
      original
      small
      thumb
      thumb_small
      tiny
    }
  }
}

photo_url może mieć wartość null (PhotoUrl). Każdy rozmiar również może mieć wartość null (String). Obsłuż przypadek, w którym użytkownik nie przesłał zdjęcia.

2. Wartości logiczne określające rodzaj użytkownika → ciąg znaków kind

Wartości logiczne is_guest, is_admin i is_view_only są przestarzałe. Zamiast nich użyj pola tekstowego kind.

Przed:

query { users { id is_admin is_guest is_view_only } }

Po:

query { users { id kind } }

Mapowanie wartości:

Przed (wartość logiczna true)	Po (wartość kind)
is_admin: true	kind == "admin"
is_guest: true	kind == "guest"
is_view_only: true	kind == "view_only"

Inne wartości kind, które możesz napotkać: member, agent_member, portal oraz kilka wariantów *_api_user (zobacz pełne wyliczenie UserKindFilter).

3. Wartości logiczne statusu → wyliczenie status

Pola is_pending i enabled zastępuje pole status: UserStatus!.

Przed:

query { users { id enabled is_pending } }

Po:

query { users { id status } }

Przed	Po
enabled: true, is_pending: false	status == ACTIVE
enabled: false	status == INACTIVE
is_pending: true	status == PENDING

4. is_verified → is_email_confirmed

Znaczenie pozostaje takie samo, ale zmienia się nazwa, a typ zostaje zawężony z Boolean do Boolean!.

Przed:

query { me { is_verified } }

Po:

query { me { is_email_confirmed } }

5. join_date → became_active_at

join_date było typu Date (YYYY-MM-DD). became_active_at jest typu ISO8601DateTime i zawiera pełną precyzję znacznika czasu.

Przed:

query { me { join_date } }     # "2023-09-02"

Po:

query { me { became_active_at } }  # "2023-09-02T13:22:48.000Z"

Jeśli kod parsuje join_date jako YYYY-MM-DD, pobierz pierwsze 10 znaków z became_active_at albo użyj parsera obsługującego pełny format ISO 8601.

6. Zmiana nazwy argumentu Query.users: kind → user_kind

Starszy argument kind: UserKind (wartości wyliczenia: all, guests, non_guests, non_pending) jest oznaczony jako przestarzały w wersji 2026-07 z wartością deprecationReason: "Use user_kind instead.". Zastąp go argumentem user_kind: UserKindFilterInput.

Przed:

query { users(kind: non_guests, limit: 200) { id name } }

Po:

query {
  users(
    user_kind: { not_in: [GUEST] }
    limit: 200
  ) { id name }
}

Mapowanie podczas migracji:

Wartość starszego kind	Nowe user_kind
all	pomiń argument
guests	{ in: [GUEST] }
non_guests	{ not_in: [GUEST] }
non_pending	(brak bezpośredniego odpowiednika - zamiast tego użyj status: [ACTIVE])

UserKindFilter obsługuje poszczególne rodzaje użytkowników (ADMIN, MEMBER, GUEST, VIEW_ONLY, AGENT_MEMBER, PORTAL), grupę BASIC (= admin + member + guest + view_only) oraz rodzaje użytkowników API. Użyj not_in, aby wykluczyć wartości z rozszerzonego zbioru in.

7. Argument Query.users: newest_first → sort

Argument newest_first jest oznaczony jako przestarzały w wersji 2026-07 z wartością deprecationReason: "Use sort instead.". Nadal działa w czasie wykonywania.

Przed:

query { users(newest_first: true, limit: 50) { id created_at } }

Po:

query {
  users(
    sort: [{ field: CREATED_AT, direction: DESC }]
    limit: 50
  ) { id created_at }
}

Argument sort przyjmuje listę UsersSortInput, więc można sortować według wielu pól (CREATED_AT jest obecnie jedynym dostępnym polem).

8. Argument Query.users: non_active → status

Argument non_active jest oznaczony jako przestarzały w wersji 2026-07 z wartością deprecationReason: "Use status instead.". Nadal działa w czasie wykonywania.

Przed:

query { users(non_active: true) { id } }      # wszyscy nieaktywni użytkownicy
query { users(non_active: false) { id } }     # (domyślnie) aktywni i oczekujący

Po:

query { users(status: [INACTIVE]) { id } }
query { users(status: [ACTIVE, PENDING]) { id } }   # (domyślnie, jeśli pominięto argument)

Jeśli pominięto status, serwer domyślnie ustawia [ACTIVE, PENDING] (tak samo jak w przypadku starego zachowania non_active: false).

9. Paginacja jest teraz wymuszana

	Przed 2026-07	W wersji 2026-07 i nowszych
users { ... } (bez limit)	zwracało wszystkich użytkowników	zwraca 200 użytkowników
users(limit: N) przy N > 1000	dozwolone	błąd: Limit exceeds the maximum allowed value of 1000.

Jeśli kod zakładał, że jedno wywołanie zwraca pełną listę użytkowników, dodaj jawną paginację:

Przed:

query { users { id email } }

Po:

query GetAllUsers($page: Int!) {
  users(
    limit: 1000
    page: $page
    sort: [{ field: CREATED_AT, direction: ASC }]
  ) {
    id
    email
  }
}

Wykonuj kolejne żądania dla page = 1, 2, 3, …, aż zwrócona tablica będzie zawierać mniej elementów niż wynosi limit.

10. Elementy tablicy Query.users(emails:) nie mogą być puste

Typ zmienia się z [String] na [String!]. Upewnij się, że w tablicy emails nie przekazujesz elementów o wartości null - sprawdź dane wejściowe po stronie klienta przed wysłaniem.

11. Zmiany typów skalarnych User (2026-07)

Pole	Typ w 2026-04	Typ w 2026-07 i nowszych
birthday	Date	String
created_at	Date	ISO8601DateTime!
utc_hours_diff	Int	Float

• birthday jest teraz zwracane jako String. Traktuj tę wartość jako dowolny ciąg znaków. Nadal ma format YYYY-MM-DD, ale schemat już tego nie gwarantuje.
• created_at zawiera teraz również godzinę (2023-09-02T13:22:48.000Z). Jeśli używasz parsera obsługującego wyłącznie Date, najpierw ogranicz wartość do 10 znaków.
• utc_hours_diff jest typu Float. Mogą pojawić się ułamkowe wartości godzin (na przykład 5.5, -3.5).

---

:white_check_mark: Dodatki niepowodujące zmian niekompatybilnych wstecz

Możesz wdrażać je we własnym tempie. Są dostępne od wersji 2026-07.

Nowe pola User

Można je bezpiecznie dodać do istniejących zapytań po ustawieniu nagłówka API-Version: 2026-07 (lub nowszego).

query {
  me {
    id
    account_id              # new
    status                  # new: UserStatus enum
    invitation_method       # new: InvitationMethod enum
    serial_number           # new: Int, nullable
    is_deleted              # new: Boolean!
    became_active_at        # new: ISO8601DateTime
    bb_visitor_id           # new: ID!
    is_email_confirmed      # new: Boolean!
    photo_url { original thumb }
    user_config { kind role_id visibility }
  }
}

Nowe zapytanie user_configs

query {
  user_configs {
    kind
    role_id
    visibility
  }
}

Wymaga uprawnienia users:read i autoryzacji użytkownika. Zwraca wszystkie konfiguracje użytkowników dla konta, posortowane rosnąco według role_id. Opcjonalne filtry: kinds: [String], visibility: String.

---

Migracja w zależności od wersji

Używana wersja	Minimalna wersja docelowa	Działanie
2025-10 lub wcześniejsza	2026-07	Wykonaj wszystkie powyższe kroki oraz migrację z 2026-04.
2026-04	2026-07	Zastosuj sekcje 1–11 po zmianie nagłówka API-Version.
2026-07	2026-10	Brak nowych zmian niekompatybilnych wstecz dotyczących samej encji użytkownika. Sprawdź, czy usunięto już starsze pola wymienione w sekcjach 1–5 - planowane jest ich całkowite usunięcie w wersji 2026-10.

Testowanie migracji

1. Ustaw nagłówek wersji: API-Version: 2026-07 (lub 2026-10).
2. Uruchom istniejące zapytania. Przestarzałe argumenty kind, newest_first i non_active nadal działają, więc zapytania, które ich używają, nie zakończą się błędem. Po ponownym wygenerowaniu kodu na podstawie nowego schematu narzędzia do generowania kodu i IDE wyświetlą jednak ostrzeżenia @deprecated. Zastąp te argumenty zgodnie z sekcjami 6–8.
3. Wszędzie, gdzie wcześniej wywoływano users { ... } bez limitu, dodaj jawne argumenty limit i page oraz pętlę. Niejawny limit 200 wierszy to najczęstsze zaskoczenie w wersji 2026-07.
4. Jeśli klient został wygenerowany na podstawie introspekcji, wygeneruj go ponownie na podstawie https://api.monday.com/v2/get_schema?version=2026-07. Jeśli używane narzędzie to obsługuje, przekaż includeDeprecated: true, aby przestarzałe argumenty pojawiły się w zrzucie schematu - domyślny punkt końcowy je pomija.
5. Przed wdrożeniem upewnij się, że uwzględniono wszystkie pozycje z krótkiej listy kontrolnej.