Użyj dynamicznego mapowania, jeśli chcesz mapować dane z monday.com na pola w innej platformie.

Pojęcia

Czym jest mapowanie elementów?

Wiele natywnych integracji monday.com pozwala mapować dane z elementów i kolumn na obiekty w innych platformach. Mapowanie elementów umożliwia korzystanie z tej samej funkcji w przepisach integracji w Twojej aplikacji.

Przykładem jest przepis z naszej integracji z GitHubem: „Gdy w repozytorium zostanie utworzone zgłoszenie, utwórz element”:

Użytkownik może zmapować dane z obiektu utworzonego w innej platformie (zgłoszenia GitHub) na element w monday.com:

Kiedy używać dynamicznego mapowania?

Użyj dynamicznego mapowania z encjami niestandardowymi, jeśli:

• Chcesz wysyłać dane z monday.com do zewnętrznego źródła.
• Twoja integracja aktualizuje monday.com na podstawie zmian w obiekcie z innej platformy lub odwrotnie.

Schemat encji

Schemat encji określa, jakie pola zawiera obiekt i które z nich można mapować. Możesz używać tej samej encji niestandardowej w wielu przepisach i blokach.

Schemat określa pola, ich typy oraz wymagane zależności.

Dokumentacja

URL definicji pól

URL definicji pól to punkt końcowy na serwerze Twojej aplikacji, który zwraca schemat dostępny dla danej encji. Gdy użytkownik kliknie nazwę encji w przepisie, serwer monday apps pobierze jej pola ze zdalnego punktu końcowego.

Zależności

Zależności to części przepisu, które użytkownik musi skonfigurować, zanim użyje mapowania. Możesz użyć dowolnego pola, wbudowanego lub niestandardowego, jako zależności. Zależności zostaną przekazane do zdalnego adresu URL opcji.

Treść żądania

Treść żądania będzie wyglądać tak:

{
    "payload" : {
        "boardId" : 162169280, // boardId is a dependency
        "side" : "source" // or "target"
    }
}

Format odpowiedzi

Twój serwer powinien zwrócić kod stanu 200 i tablicę pól. Pola mogą być statyczne lub generowane dynamicznie na podstawie zależności. Każde pole powinno być obiektem JSON zawierającym następujące pary klucz-wartość:

Klucz	Opis	Typ
id	Identyfikator/klucz, z którym zostaną przekazane dane	string
title	Etykieta wyświetlana użytkownikowi	string
outboundType	Typ podstawowy pola podczas wysyłania	string, musi odpowiadać jednemu z obsługiwanych typów podstawowych
inboundTypes	Typy podstawowe, które akceptuje to pole	Tablica ciągów znaków

Przykładowy kod

Oto prosta implementacja URL definicji pól w NodeJS. Ten schemat zawiera 5 pól.

async function getRemoteFieldDefs(req, res) {
  return res.status(200).send([
    { id: 'name', title: 'Name', outboundType: 'text', inboundTypes: ['text'] },
    { id: 'desc', title: 'Description', outboundType: 'text', inboundTypes: ['empty_value', 'text', 'text_array'] },
    { id: 'dueDate', title: 'Due Date', outboundType: 'date', inboundTypes: ['empty_value', 'date', 'date_time'] },
    { id: 'people', title: 'People', outboundType: 'user_emails', inboundTypes: 'user_emails' },
    { id: 'creationDate', title: 'CreateDate', outboundType: 'date_time', inboundTypes: ['date', 'date_time'] },
  ]);
}

Obsługiwane podstawowe typy pól

Dynamiczne mapowanie obsługuje wiele typów pól i opiera się na ścisłym systemie typów.

Zdefiniowaliśmy 8 podstawowych typów, których możesz używać w polach encji niestandardowej.

Przykłady poszczególnych typów pól

Poniższy fragment przedstawia przykładową encję ze wszystkimi obsługiwanymi przez nas polami:

{
  "customEntity": {
    "text": "Working on it",
    "numeric": 123,
    "text_array": [
      "1dropdown",
      "2dropdown",
      "3drop"
    ],
    "date": "2020-09-27",
    "text_with_label": {
      "value": "http://www.google.com",
      "label": "Google"
    },
    "people": {
      "identifierType": "email",
      "identifierValue": ["email1@company.com", "email2@company.com"]
    },
    "boolean": true,
    "date_time": {
      "dateWithTime": "2020-09-27T21:38:00.000Z"
    }
  }
}

Zasady mapowania kolumn monday.com

Poniżej znajduje się lista kolumn obsługiwanych przez dynamiczne mapowanie wraz z odpowiadającymi im typami wejściowymi i wyjściowymi:

Nazwa kolumny	Typ wyjściowy	Typ wejściowy
Identyfikator elementu (Item ID)	numeric
Nazwa (Name)	text	text, text\_array, numeric
Tekst (Text)	text	text, text\_array, numeric, date, date\_time, boolean
Długi tekst (Long Text)	text	text, text\_array, numeric, date, date\_time, boolean
Status (Status)	text	text, numeric, boolean
Osoby (People)	user\_emails	user\_emails
E-mail (Email)	text	text, text\_array
Liczby (Numbers)	numeric	numeric
Ocena (Rating)	numeric	numeric
Lista rozwijana (Dropdown)	text\_array	text, text\_array, numeric
Data (Date)	date\_time	date, date\_time
Pole wyboru (Checkbox)	boolean	boolean
Łącze (Link)	text\_with\_label	text, text\_with\_label

Poradniki

1. Skonfiguruj encję niestandardową

Krok 1: Utwórz pole niestandardowe

W funkcji integracji kliknij kartę „Typy pól (Field Types)” i utwórz nowy typ pola:

• Skonfiguruj podstawowe informacje o encji niestandardowej.
• W sekcji konfiguracji automatyzacji wybierz „Mapowanie dynamiczne (Dynamic Mapping)”.
• W polu „URL definicji pól (Field Definitions URL)” wpisz punkt końcowy na serwerze, który pobiera definicje pól tej encji.
• Podaj wszystkie zależności encji.
• Kliknij „Zapisz (Save)”. Teraz możesz używać tej encji w przepisach swojej aplikacji!

2. Mapuj dane z monday do swojej aplikacji

Mapowanie wychodzące polega na mapowaniu danych z monday.com do Twojej aplikacji. Aby je wdrożyć, użyj encji w akcji niestandardowej i wybierz wyzwalacz obsługujący mapowanie.

Wyzwalacz obsługuje mapowanie, jeśli jednym z jego pól wyjściowych jest itemValues. Obecnie mapowanie obsługują następujące wyzwalacze:

• Gdy zostanie utworzony element
• Gdy zmieni się kolumna
• Gdy zmieni się status
• Gdy status zmieni się na określoną wartość

Skonfiguruj akcję niestandardową, dodając encję jako pole wejściowe

Aby użyć mapowania wychodzącego, utwórz akcję niestandardową i dodaj encję niestandardową jako pole wejściowe. Oto przykład takiej akcji niestandardowej - zwróć uwagę na encję niestandardową „Crossboard Item” w sekcji pól wejściowych:

📘 WSKAZÓWKA

Instrukcję tworzenia aplikacji z akcją niestandardową znajdziesz w naszym Przewodniku szybkiego startu: przepisy integracji.

Utwórz nowy przepis z akcją niestandardową

• Najpierw utwórz nowy przepis w funkcji integracji.
• Skonfiguruj wyzwalacz jak zwykle:

• Dodaj akcję niestandardową i zmapuj pole encji źródłowej. Encja źródłowa musi pochodzić z pól wyjściowych wyzwalacza i być mapowalnym polem itemValues.
• Określ zależności w konfiguracji akcji. Domyślnie wymagany jest identyfikator tablicy, a dodatkowe zależności również zostaną tutaj wymienione.
• Po wykonaniu tego kroku akcja będzie wyglądać tak:

Obsłuż żądanie wysłane do adresu URL Run

Po wywołaniu akcji serwer monday Apps wyśle do adresu URL Run następujący ładunek:

{
    "payload" : { 
        "inboundFieldValues" : { 
            "boardId" : 541329092,
            "crossBoardItem" : {
                "text" : "Hello world",
                "long_text" : "Hello, world?",
                "numbers" : 42,
                "people": { identifierType: "email", identifierValue: ["email1@company.com", "email2@company.com"] }
              }
          }
         "recipeId": 123456, //unique ID of the recipe for your app. if multiple accounts are using the same recipe, the same recipe ID will be sent
         "integrationId": 123456 //unique ID of the integration recipe added to your board
    }
}

3. Mapuj dane ze swojej aplikacji do monday.com

Mapowanie przychodzące polega na wysyłaniu danych z aplikacji do monday.com, a następnie mapowaniu ich na element na tablicy.

Utwórz wyzwalacz niestandardowy z encją jako polem wyjściowym

Aby użyć mapowania przychodzącego, utwórz wyzwalacz niestandardowy, który zawiera encję niestandardową jako jedno z pól wyjściowych. Dodaj wszystkie zależności jako pola wejściowe.

Najpierw utwórz nowy wyzwalacz niestandardowy w funkcji integracji. Dodaj encję do pól wyjściowych oraz uwzględnij wszystkie zależności wymagane przez wyzwalacz:

Utwórz przepis z wyzwalaczem niestandardowym

Po utworzeniu wyzwalacza użyj go w przepisie.

Dodaj wyzwalacz do przepisu:

Jeśli Twoja aplikacja korzysta z mapowania przychodzącego, musisz użyć akcji „Utwórz element na tablicy (Create an item in board)”. Ta akcja utworzy nowy element na tablicy i zmapuje dane encji na kolumny.

Dodaj akcję „Utwórz element na tablicy”

Skonfiguruj pole itemMapping w następujący sposób:

• Encja źródłowa: encja niestandardowa, która powinna znajdować się w polach wyjściowych wyzwalacza
• Pola zależności: tablica, której kolumny zostaną zmapowane

Po wykonaniu tego kroku konfiguracja akcji powinna wyglądać tak:

Wywołaj wyzwalacz

Gdy użytkownik zasubskrybuje Twój wyzwalacz, możesz wysłać dane encji pod adres URL webhooka. Dane zostaną zmapowane na nowy element w monday.com.

Dane wyjściowe webhooka powinny wyglądać tak:

{
  "trigger": {
    "outputFields": { ///values of all output fields, which were configured for your custom trigger
      "myEntity": {
        "field1" : "Hello world!",
        "field2" : "This is another field"
      }
    }
  }
}