Grundlagen zur Adobe Workfront Planning-API

Das Ziel der Adobe Workfront Planning-API besteht darin, die Erstellung von Integrationen mit Planning zu vereinfachen, indem eine REST-ful-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, und der von der Planungs-API verfolgte Ansatz beschrieben.

Wenn Sie mit dem Workfront-Planungsschema vertraut sind, können Sie die Datenbankbeziehungen besser verstehen, die Sie zum Abrufen von Daten aus Workfront Planning zu Integrationszwecken verwenden können.

Sie können die Planning-API aus einem externen Suchfeld in einem benutzerdefinierten Workfront-Formular aufrufen.

Weitere Informationen zu externen Suchfeldern finden Sie unter Beispiele für das externe Suchfeld in einem benutzerdefinierten Formular.

Workfront Planning-API-URL

Vorgänge

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

Die standardmäßigen HTTP-Methoden entsprechen den folgenden Vorgängen:

Weitere Details und Beispiele für jeden Vorgang finden Sie in der Entwicklerdokumentation zur Workfront Planning API.

Feldtypen und Suchmodifikatoren, die mit ihnen verwendet werden

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

Verwenden von Suchmodifikatoren

Workfront Planning unterstützt die folgenden Suchmodifikatoren:

Feldtypen

Nachfolgend finden Sie eine Liste der unterstützten Feldtypen und darüber, welche Suchmodifikatoren mit den einzelnen Feldtypen verwendet werden können

Verwendung der Anweisungen „Und“ und „Oder“

Im API-Aufruf können Filter enthalten sein, die auf mehreren Kriterien basieren und durch $and“- und "$or“-Anweisungen kombiniert werden

{
  "recordTypeId": "recordTypeId",
  "offset": "integer",
  "limit": "integer",
  "filters": [
    {
      "$or": [
        {
          "launch_date": {
            "$isBetween": [
              "2024-03-31T20:00:00.000Z",
              "2024-04-01T20:00:00.000Z"
            ]
          }
        },
        {
          "$and": [
            {
              "launch_date": {
                "$isBetween": [
                  "2024-03-31T20:00:00.000Z",
                  "2024-04-01T20:00:00.000Z"
                ]
              }
            },
            {
              "status": "active"
            }
          ]
        },
        {
          "$and": [
            {
              "launch_date": {
                "$isBetween": [
                  "2024-04-15T00:00:00.000Z",
                  "2024-04-16T00:00:00.000Z"
                ]
              }
            },
            {
              "status": "planned"
            }
          ]
        }
      ]
    }
  ]
}

Verwenden des Anforderungsparameters „fields“

Mit dem Anforderungsparameter fields können Sie eine kommagetrennte Liste bestimmter Felder angeben, die zurückgegeben werden sollen. Bei diesen Feldnamen wird zwischen Groß- und Kleinschreibung unterschieden.

Beispiel: die Anfrage

/v1/records/search?attributes=data,createdBy

{
    "records": [
        {
            "id": "Rc6527ecb35df57c441d92ba00",
            "createdBy": "61a9cc0500002f9fdaa7a6f824f557e1",
            "createdAt": null,
            "updatedBy": null,
            "updatedAt": null,
            "customerId": null,
            "imsOrgId": null,
            "recordTypeId": null,
            "data": {
                "F666c0b58b6fee61a2ea6ea81": [
                    {
                        "externalId": null,
                        "id": "Rc665728ff95730b58bc757b13",
                        "value": null
                    },
....

Gibt eine Antwort ähnlich der folgenden zurück:

{
    "priority": 2,
    "name": "first task",
    "ID": "4c7c08fa0000002ff924e298ee148df4",
    "plannedStartDate": "2010-08-30T09:00:00:000-0600"
}

Sortieren von Abfrageergebnissen in der API

Sie können Ihre Ergebnisse nach einem beliebigen Feld sortieren, wenn Sie Folgendes an Ihren API-Aufruf anhängen:

/v1/records/search

Anfragetext:

{
    "recordTypeId": "Rt6527ecb25df57c441d92b9fa",
    "filters": [],
    "sorting": [
        {
            "fieldId": "F6527ecb25df57c441d92b9fc",
            "direction": "asc"
        },
        {
            "fieldId": "F658afcbd4a0273c67c346fd5",
            "direction": "desc"
        }
    ],
    "limit": 500,
    "offset": 0,
    "rowOrderViewId": "V6527ecb75df57c441d92ba03",
    "groupingFieldIds": []
}

Abfragebeschränkungen und paginierte Antworten

Standardmäßig geben Planning-API-Anfragen 500 Ergebnisse zurück, beginnend mit dem Anfang der Liste. Um die standardmäßige Begrenzung für die Anzahl der Ergebnisse zu überschreiben, können Sie den limit-Parameter in Ihren Anfragen verwenden und auf eine andere Zahl festlegen, bis zu 2.000 Ergebnisse.

Es wird empfohlen, die Verwendung von paginierten Antworten für große Datensätze zu erwägen, indem Sie den offset-Parameter zu Ihren Anfragen hinzufügen. Mit paginierten Antworten können Sie den Speicherort des ersten Ergebnisses angeben, das zurückgegeben werden soll.

Wenn Sie beispielsweise die Ergebnisse 2001-4000 zurückgeben möchten, können Sie die folgende Anfrage verwenden. In diesem Beispiel werden 2.000 Datensätze im Status Aktiv zurückgegeben, beginnend mit dem Ergebnis 2001:

POST /v1/records/search

Anfragetext:

{
    "recordTypeId": "recordTypeId",
    "offset": "2001",
    "limit": "2000",
    "filters": [
        { "status": "active" }
    ]
}

Um sicherzustellen, dass Ihre Ergebnisse ordnungsgemäß paginiert werden, verwenden Sie einen Sortierparameter. Dadurch können die Ergebnisse in derselben Reihenfolge zurückgegeben werden, sodass die Paginierung die Ergebnisse nicht wiederholt oder überspringt.

Weitere Informationen zum Sortieren finden Sie unter Sortieren von Abfrageergebnissen in der API in diesem Artikel.