Grunderna i Adobe Workfront Planning API

Målet med Adobe Workfront Planning API är att förenkla byggintegreringen med Planning genom att införa en RESTful-arkitektur som fungerar över HTTP. Det här dokumentet förutsätter att du känner till REST- och JSON-svaren.

Fullständig slutpunktsreferens, fråge-/svarsscheman och versionsspecifik information finns i dokumentationen för Workfront Planning API-utvecklare.

Autentisering

Workfront Planning API använder OAuth 2.0 för autentisering. Autentiseringsuppgifterna konfigureras via Adobe Developer Console.

Vi stöder följande två flöden beroende på din integrationstyp:

Du kommer igång genom att skapa ett projekt i Adobe Developer Console och lägga till Workfront Planning API för att få dina inloggningsuppgifter.

Skapa ett OAuth2-program i Workfront om du vill konfigurera inloggningsuppgifter.

Mer information finns i Skapa OAuth2-program för Workfront-integreringar.

API-versionshantering

Planerings-API:t versionshanteras via URL-sökvägen.

Följande versioner stöds för närvarande:

Mer information om de aktuella versionerna som stöds finns i artikeln Workfront Planning API developer documentation.

Vi rekommenderar att ni uttryckligen inriktar er på en version i alla integreringar:

https://{customer-domain}/maestro/api/v2/...

När en ny större version släpps kommer den tidigare versionen att vara tillgänglig tills ett utgått.

Följ versionsinformationen för Workfront för att få information om API-ändringar.

URL-struktur och -åtgärder

Objekten ändras genom att en HTTP-begäran skickas till deras unika URI. Åtgärden anges av HTTP-metoden.

Fullständiga slutpunktssökvägar och exempel på begäran/svar finns i API-referensen på developer.adobe.com/wf-planning.

HTTP-statuskoder

Planerings-API returnerar standard-HTTP-statuskoder:

Felhantering

Planerings-API returnerar fel i ett konsekvent format. Varje felsvar innehåller ett läsbart meddelande, en maskinläsbar felkod och ett begärande-ID för eskalering av support.

Exempel på felsvar:

json
{
  "title": "Validation failed",
  "status": 400,
  "detail": "Request validation failed. See 'errors' for details.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "req-123",
  "errors": [
    { "field": "name", "message": "must not be blank" }
  ]
}

Använd errorCode (inte status) för att köra programmatisk felhantering. Det ger den mest specifika klassificeringen av felet.

Filtrera poster

Använd parametern filter i postsökningsbegäranden om du bara vill returnera poster som matchar specifika villkor. För POST-begäranden är filter en JSON-egenskap i begärandetexten. För GET-begäranden är filter en frågeparameter som innehåller en JSON-kodad filtergrupp. För filter används en typbestämd sammansatt struktur med explicita logiska operatorer.

json
{
  "filter": {
    "operator": "AND",
    "conditions": [
      { "fieldId": "<fieldId>", "condition": "IS", "value": "Active" },
      { "fieldId": "<fieldId>", "condition": "CONTAINS", "value": "marketing" }
    ]
  }
}

Filter kan kapslas med operatorerna AND / OR för att skapa sammansatta villkor:

json
{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "BETWEEN", "value": ["2024-03-31T20:00:00.000Z", "2024-04-01T20:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "IS_BETWEEN", "value": ["2024-04-15T00:00:00.000Z", "2024-04-16T00:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "planned" }
        ]
      }
    ]
  }
}

Fälttyper och sökmodifierare

Du kan använda modifierare och filter med fält för att styra vilka data som returneras i resultatet.

Se till exempel Utvecklardokumentationen för Workfront Planning API.

Använda sökmodifierare

Workfront Planning stöder följande sökmodifierare:

Filtervillkor som stöds per fälttyp

Filtrera efter personfält

Personfältsfilter (user, created-by, updated-by, approved-by) accepterar både användar-ID:n för Adobe IMS och användar-ID:n för Workfront. Ett oformaterat strängvärde tolkas som ett användar-ID för Adobe IMS.

Om du vill ställa in identifierartypen för att kontrollera Workfront användar-ID:t måste du skicka id- och idType-parametrarna explicit. Värden som stöds för idType är WF för Workfront användar-ID och IMS för Adobe IMS användar-ID.

{
  "filter": {
   "operator": "AND",
    "conditions": [
      {
        "fieldId": "<userFieldId>",
        "condition": "HAS_ANY_OF",
        "value": [
          { "id": "63e3b13000078c1795146248182d15dc", "idType": "WF" }
        ]
      }
    ]
  }
}

Filtrera externa referensfält efter externt ID

Externa referensfält länkar poster till objekt i andra Adobe-system (till exempel Workfront-projekt eller AEM Assets). Internt tilldelas dessa objekt ID:n för planeringspost i Planning. Om du vill filtrera sådana fält direkt efter deras ursprungliga objekt-ID lägger du till "matchExternalId": true i ett filtervillkor.

Den här flaggan är bara giltig för referensfält där referenceOptions.isExternal är true; den ignoreras för icke-externa referensfält. Om ett enskilt strängvärde inte kan matchas misslyckas begäran med 400 Bad Request. Om ett listvärde anges skickas olösta poster som oförändrade och matchar helt enkelt inte.

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {
        "fieldId": "<externalReferenceFieldId>",
        "condition": "IS_ANY_OF",
        "value": [
          "5f6a4f6e00000123456789abcdef0123",
          "/content/dam/wknd/en/adventures/bali-surf-camp"
        ],
        "matchExternalId": true
      }
    ]
  }
}

Externa anslutningsfält

Planeringsposttyper kan vara värd för externa referensfält som länkar poster till objekt i andra Adobe-system i stället för andra typer av planeringsposter.

Om du vill skapa ett externt referensfält via API anger du referenceOptions.recordTypeId i ett nytt REFERENCE-fält till ID:t för den önskade externa posttypen. Servern härleder automatiskt referenceOptions.isExternal=true och anslutningsmetadata (connectionName, objectName) från målposttypen.

Externa objekttyper som stöds är bland annat Workfront-objekt (projekt, uppgifter, program, portföljer, företag, grupper, team, användare) och AEM Assets (resurser, innehållsfragment).

Sortering

Sortera resultat efter fält genom att inkludera en sort-array i din begäran:

json
{
  "sort": [
    { "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" },
    { "fieldId": "F658afcbd4a0273c67c346fd5", "direction": "desc" }
  ]
}

Flera sorteringsfält utvärderas i ordning. Använd alltid en sortering vid sidnumrering för att säkerställa konsekvent ordning över sidorna.

Om du vill gruppera resultat inkluderar du en grupparray vid sorteringen:

{
  "sort": [{ "fieldId": "F001", "direction": "asc" }],
  "group": [{ "fieldId": "F002", "direction": "asc" }]
}

Fältprojektion

Om du vill begränsa vilka fält som returneras i ett svar använder du frågeparametrarna fieldIds eller fieldAliases med en kommaavgränsad lista. Detta minskar svarsnyttolastens storlek och rekommenderas för integreringar med stora volymer eller latenskänsliga.

Sidnumrering

Planerings-API:t stöder sidnumrerade svar för att hantera stora datamängder.

Använd till exempel följande begäran för att hämta den andra sidan med 500 poster från en postsökning:

POST /v2/record-types/{recordTypeId}/records/search?page=1&size=500
{
  "sort": [{ "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" }],
  "filter": { "operator": "AND", "conditions": [
    { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
  ] }
}

Alla sidnumrerade svar innehåller ett strukturerat kuvert som anger om fler resultat är tillgängliga. Använd alltid en sortering vid sidnumrering för att säkerställa konsekvent ordning över sidorna.

Massåtgärder

Planerings-API:t har stöd för att skapa, uppdatera, korrigera och ta bort poster i en enda begäran. Mer information om slutpunktssökvägar, begärandeformat och postbegränsningar per åtgärd finns i API-referensen på developer.adobe.com/wf-planning .

Behörigheter

Behörigheter till entiteter hanteras med ett dedikerat behörighets-API, som är skilt från resursslutpunkterna. Detta gör att du kan läsa aktuella behörigheter, hantera delningslistan och hantera åtkomstbegäranden oberoende av dataåtgärder. Mer information finns i avsnittet API-referenser i artikeln Workfront Planning API.

Använda Planning API med anpassade Workfront-formulär

Du kan anropa Planning API från ett fält för extern sökning i ett anpassat Workfront-formulär för att visa planeringsdata direkt i Workfront-objekt. Mer information finns i Exempel på ett externt sökfält i ett anpassat formulär.

Relaterade resurser

Mer API-relaterad dokumentation finns även i följande artiklar: