Grundlagen zur Adobe Workfront-Planung-API

Das Ziel der Adobe Workfront Planning-API besteht darin, die Erstellung von Integrationen mit Planning zu vereinfachen, indem eine RESTful-Architektur eingeführt wird, die über HTTP ausgeführt wird. In diesem Dokument wird davon ausgegangen, dass Sie mit REST- und JSON-Antworten vertraut sind.

Eine vollständige Endpunktreferenz, Anfrage-/Antwortschemata und versionsspezifische Details finden Sie in der Entwicklerdokumentation zur Workfront Planning API.

Authentifizierung

Die Workfront Planning-API verwendet OAuth 2.0 zur Authentifizierung. Anmeldedaten werden über die Adobe Developer Console eingerichtet.

Je nach Integrationstyp werden die folgenden beiden Flüsse unterstützt:

Erstellen Sie zunächst ein Projekt in der Adobe Developer Console und fügen Sie die Workfront Planning-API hinzu, um Ihre Anmeldeinformationen abzurufen.

Um Anmeldeinformationen einzurichten, erstellen Sie ein OAuth2-Programm in Workfront.

Weitere Informationen finden Sie unter Erstellen von OAuth2-Programmen für Workfront-Integrationen.

API-Versionierung

Die Planning-API wird über den URL-Pfad versioniert.

Die folgenden Versionen werden derzeit unterstützt:

Weitere Informationen zu den derzeit unterstützten Versionen finden Sie im Artikel Entwicklerdokumentation für die Workfront Planning API.

Es wird empfohlen, eine Version in allen Integrationen explizit festzulegen:

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

Wenn eine neue Hauptversion veröffentlicht wird, ist die vorherige Version weiterhin verfügbar, bis ein Verfallsdatum mitgeteilt wird.

Folgen Sie den Workfront-Versionshinweisen , um über API-Änderungen auf dem Laufenden zu bleiben.

URL-Struktur und -Vorgänge

Objekte werden durch Senden einer HTTP-Anfrage an den eindeutigen URI bearbeitet. Der Vorgang wird durch die HTTP-Methode angegeben.

Vollständige Endpunktpfade und Anfrage-/Antwortbeispiele finden Sie in der API-Referenz unter developer.adobe.com/wf-planning.

HTTP-Status-Codes

Die Planning-API gibt Standard-HTTP-Status-Codes zurück:

Umgang mit Fehlern

Die Planning-API gibt Fehler in einem konsistenten Format zurück. Jede Fehlerantwort enthält eine für Menschen lesbare Nachricht, einen maschinenlesbaren Fehlercode und eine Anfrage-ID für die Support-Eskalation.

Beispielfehlerantwort:

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" }
  ]
}

Verwenden Sie errorCode (nicht status), um die programmgesteuerte Fehlerbehandlung zu steuern. Er bietet die spezifischste Klassifizierung des Fehlers.

Datensätze filtern

Verwenden Sie den filter-Parameter in Datensatzsuchanfragen, um nur Datensätze zurückzugeben, die bestimmten Kriterien entsprechen. Bei POST-Anfragen ist filter eine JSON-Eigenschaft im Anfragetext. Bei GET-Anfragen ist filter ein Abfrageparameter, der eine JSON-codierte Filtergruppe enthält. Filter verwenden eine typisierte zusammengesetzte Struktur mit expliziten logischen Operatoren.

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

Filter können mit AND/OR-Operatoren verschachtelt werden, um zusammengesetzte Bedingungen zu erstellen:

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" }
        ]
      }
    ]
  }
}

Feldtypen und Suchmodifikatoren

Sie können Modifikatoren und Filter mit Feldern verwenden, um zu steuern, welche Daten in den Ergebnissen zurückgegeben werden.

Beispiele finden Sie in der Entwicklerdokumentation zur Workfront Planning API.

Verwenden von Suchmodifikatoren

Workfront Planning unterstützt die folgenden Suchmodifikatoren:

Unterstützte Filterbedingungen nach Feldtyp

Nach Personenfeldern filtern

Personenfeldfilter (user, created-by, updated-by, approved-by) akzeptieren sowohl Adobe IMS- als auch Workfront-Benutzer-IDs. Ein einfacher Zeichenfolgenwert wird als Adobe IMS-Benutzer-ID interpretiert.

Um den Kennungstyp zur Überprüfung der Workfront-Benutzer-ID festzulegen, müssen Sie explizit id- und idType übergeben. Unterstützte Werte für idType sind “WF” für Workfront-Benutzer-IDs und “IMS” für Adobe IMS-Benutzer-IDs.

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

Filtern externer Referenzfelder nach externer ID

Externe Referenzfelder verknüpfen Datensätze mit Objekten in anderen Adobe-Systemen (z. B. Workfront-Projekten oder AEM Assets). Intern weist Planning diesen Objekten Planungsdatensatz-IDs zu. Um diese Felder direkt nach ihrer ursprünglichen Objekt-ID zu filtern, fügen Sie "matchExternalId": true zu einer Filterbedingung hinzu.

Dieses Flag ist nur für Referenzfelder gültig, bei denen referenceOptions.isExternal true ist. Bei nicht externen Referenzfeldern wird es ignoriert. Wenn ein einzelner Zeichenfolgenwert nicht aufgelöst werden kann, schlägt die Anfrage mit 400 Bad Request fehl. Wenn ein Listenwert angegeben wird, durchlaufen nicht aufgelöste Einträge unveränderte Elemente und stimmen einfach nicht überein.

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

Felder für externe Verbindungen

Planungs-Datensatztypen können externe Referenzfelder hosten, die Datensätze mit Objekten in anderen Adobe-Systemen verknüpfen, anstatt mit anderen Planungs-Datensatztypen.

Um ein externes Referenzfeld über die API zu erstellen, legen Sie referenceOptions.recordTypeId in einem neuen REFERENCE auf die ID des gewünschten externen Datensatztyps fest. Der Server leitet referenceOptions.isExternal=true und die Verbindungsmetadaten (connectionName, objectName) automatisch vom Zieldatensatztyp ab.

Zu den unterstützten externen Objekttypen gehören Workfront-Objekte (Projekte, Aufgaben, Programme, Portfolios, Unternehmen, Gruppen, Teams, Benutzer) und AEM Assets (Assets, Inhaltsfragmente).

Sortieren

Sortieren Sie die Ergebnisse nach einem beliebigen Feld, indem Sie ein sort-Array in Ihre Anfrage aufnehmen:

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

Mehrere Sortierfelder werden der Reihe nach ausgewertet. Wenden Sie bei der Paginierung immer eine Sortierung an, um eine konsistente Sortierung über Seiten hinweg sicherzustellen.

Um Ergebnisse zu gruppieren, fügen Sie neben Sortieren ein Gruppen-Array ein:

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

Feldprojektion

Um zu begrenzen, welche Felder in einer Antwort zurückgegeben werden, verwenden Sie die fieldIds oder fieldAliases Abfrageparameter mit einer kommagetrennten Liste. Dies reduziert die Größe der Antwort-Payload und wird für Integrationen mit hohem Volumen oder Latenzabhängigkeit empfohlen.

Paginierung

Die Planning-API unterstützt paginierte Antworten zum Verwalten großer Datensätze.

Verwenden Sie beispielsweise die folgende Anfrage, um die zweite Seite mit 500 Datensätzen aus einer Datensatzsuche abzurufen:

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" }
  ] }
}

Alle paginierten Antworten enthalten einen strukturierten Umschlag, der angibt, ob weitere Ergebnisse verfügbar sind. Wenden Sie bei der Paginierung immer eine Sortierung an, um eine konsistente Sortierung über Seiten hinweg sicherzustellen.

Massenvorgänge

Die Planning-API unterstützt das Massenerstellen, Aktualisieren, Patchen und Löschen von Datensätzen in einer einzigen Anfrage. Informationen zu Endpunktpfaden Anfrageformaten und Datensatzbeschränkungen pro Vorgang finden Sie in API-Referenz🔗 unter developer.adobe.com/wf-planning.

Berechtigungen

Berechtigungen für Entitäten werden über eine dedizierte Berechtigungs-API verwaltet, die von den Ressourcenendpunkten selbst getrennt ist. Auf diese Weise können Sie aktuelle Berechtigungen lesen, die Freigabeliste verwalten und Zugriffsanfragen unabhängig von Datenvorgängen verarbeiten. Weitere Informationen finden Sie im Abschnitt „API-Referenzen“ im Artikel Workfront Planning API.

Verwenden der Planning-API mit benutzerdefinierten Workfront-Formularen

Sie können die Planning-API über ein externes Suchfeld in einem benutzerdefinierten Workfront-Formular aufrufen, um Planungsdaten direkt in Workfront-Objekten einzublenden. Weitere Informationen finden Sie unter Beispiele für das externe Suchfeld in einem benutzerdefinierten Formular.

Verwandte Ressourcen

Weitere Informationen zur API finden Sie in den folgenden Artikeln: