Mutacja connect_project_to_portfolio łączy istniejącą tablicę projektu z tablicą portfolio, tworząc połączony element w portfolio. Domyślnie mutacja działa synchronicznie i bezpośrednio zwraca nowy identyfikator portfolio_item_id. Od wersji 2026-07 przyjmuje też opcjonalny parametr callback_url, który przełącza operację w tryb asynchroniczny.

🚧 Limit szybkości

Ta mutacja ma dodatkowy limit szybkości: 40 mutacji na minutę, oprócz standardowych limitów złożoności API.

Krok 1 - Znajdź identyfikatory tablic projektu i portfolio

Potrzebujesz dwóch identyfikatorów tablic:

• Tablica projektu - tablica z zadaniami, którą chcesz dodać do portfolio. Zawiera grupy Planning / Execution / Launch (informacje o tym, jak odróżnić tablicę z zadaniami od tablicy portfolio, znajdziesz w artykule Pobieranie statusu / kondycji projektu).
• Tablica portfolio - portfolio docelowe. Zawiera jedną grupę Projects (zobacz Tworzenie nowego portfolio i Wyświetlanie wszystkich projektów w portfolio).

Jeśli masz zwykłą tablicę, która nie jest jeszcze projektem, najpierw użyj mutacji convert_board_to_project, aby ją przekształcić.

Krok 2 - Połącz projekt (synchronicznie)

Uruchom mutację, podając oba identyfikatory. Gdy połączenie zostanie utworzone, odpowiedź zawiera nowy portfolio_item_id:

mutation {
  connect_project_to_portfolio(
    projectBoardId: 1234567890
    portfolioBoardId: 9876543210
  ) {
    success
    message
    portfolio_item_id
  }
}

Przykładowa odpowiedź potwierdzająca powodzenie:

{
  "data": {
    "connect_project_to_portfolio": {
      "success": true,
      "message": "Successfully connected project 1234567890 to portfolio 9876543210",
      "portfolio_item_id": "5555555555"
    }
  }
}

Użyj zwróconego portfolio_item_id, aby odczytać lub zaktualizować metadane projektu na poziomie portfolio (kondycję, etap, właściciela i oś czasu) dla nowego połączonego elementu. Zobacz Aktualizowanie statusu projektu.

Krok 3 - Połącz projekt za pomocą adresu URL wywołania zwrotnego (asynchronicznie, 2026-07 lub nowsza wersja)

🚧 Dostępne od wersji API 2026-07

Argument callback_url i pole process_id w odpowiedzi wymagają wersji 2026-07 lub nowszej.

Podaj adres HTTPS jako callback_url, aby przełączyć mutację w tryb asynchroniczny. Mutacja natychmiast zwraca process_id i success: true. Po zakończeniu operacji jej wynik jest wysyłany metodą POST na podany adres URL.

mutation {
  connect_project_to_portfolio(
    projectBoardId: 1234567890
    portfolioBoardId: 9876543210
    callback_url: "https://your-domain.com/webhook/portfolio-connect"
  ) {
    success
    message
    process_id
    portfolio_item_id
  }
}

W trybie asynchronicznym natychmiastowa odpowiedź wygląda tak:

{
  "data": {
    "connect_project_to_portfolio": {
      "success": true,
      "message": "Connection initiated. The result will be sent to your callback URL when available.",
      "process_id": "9c1f2a8b-7d3e-4c12-9b2f-7a0e1d4c8b6e",
      "portfolio_item_id": null
    }
  }
}

W natychmiastowej odpowiedzi portfolio_item_id ma wartość null - identyfikator pojawi się w treści wywołania zwrotnego.

Treść wywołania zwrotnego

Po zakończeniu operacji monday.com wysyła na adres callback_url żądanie POST z treścią JSON:

Pole	Typ	Opis
is_success	Boolean	true, jeśli projekt został połączony, lub false, jeśli operacja się nie powiodła.
process_id	String	Ten sam process_id, który zwróciła mutacja. Użyj go, aby powiązać wynik z operacją.
portfolio_item_id	String	Identyfikator nowego elementu portfolio. Występuje tylko wtedy, gdy is_success ma wartość true.

Przykładowa treść wywołania zwrotnego po pomyślnym zakończeniu:

{
  "is_success": true,
  "process_id": "9c1f2a8b-7d3e-4c12-9b2f-7a0e1d4c8b6e",
  "portfolio_item_id": "5555555555"
}

Przykładowa treść wywołania zwrotnego po niepowodzeniu:

{
  "is_success": false,
  "process_id": "9c1f2a8b-7d3e-4c12-9b2f-7a0e1d4c8b6e"
}

Kiedy używać wywołań zwrotnych

Korzystaj z trybu synchronicznego, jeśli możesz utrzymać otwarte żądanie GraphQL i od razu użyć portfolio_item_id. Wybierz tryb asynchroniczny (callback_url), gdy:

• Łączysz wiele projektów w ramach jednej operacji i chcesz uniknąć czekania na każde żądanie z osobna.
• Działasz w środowisku, w którym utrzymywanie długo otwartych żądań jest utrudnione (np. w procesach obsługujących kolejki lub środowiskach serverless).
• Chcesz trwale zapisać wynik operacji bez konieczności utrzymywania pierwotnego połączenia HTTP.

Ważne informacje

• Wersja mutacji: sama mutacja jest dostępna od wersji 2025-10. Tylko argument callback_url i pole process_id w odpowiedzi wymagają wersji 2026-07.
• Limit szybkości: również w trybie asynchronicznym limit 40 mutacji na minutę dotyczy wywołań mutacji, a nie dostarczania wywołań zwrotnych.
• Bezpieczeństwo wywołań zwrotnych: traktuj punkt końcowy wywołania zwrotnego jako niezaufany. Przed podjęciem działań na podstawie otrzymanych danych sprawdź, czy process_id odpowiada operacji zainicjowanej przez Ciebie.
• Idempotencja: ponowna próba połączenia tego samego projektu z tym samym portfolio zakończy się błędem walidacji. Jeśli nie możesz śledzić tego po swojej stronie, najpierw sprawdź, czy projekt znajduje się w portfolio, korzystając z artykułu Wyświetlanie wszystkich projektów w portfolio.
• Uprawnienia: wymagany jest zakres boards:write. Rozwiązania portfolio są dostępne tylko w planach Enterprise.