Principes de base des API de planification Adobe Workfront

L’objectif de l’API de planification d’Adobe Workfront est de simplifier la création d’intégrations avec la planification en introduisant une architecture REST-ful qui fonctionne sur HTTP. Ce document suppose que vous connaissez les réponses REST et JSON et décrit l’approche adoptée par l’API de planification.

Une familiarité avec le schéma de planification Workfront vous aidera à comprendre les relations de base de données qui peuvent être utilisées pour extraire des données de la planification Workfront à des fins d’intégration.

Vous pouvez appeler l’API de planification à partir d’un champ de recherche externe dans un formulaire personnalisé Workfront.

Pour plus d’informations sur les champs de recherche externes, voir Exemples du champ de recherche externe dans un formulaire personnalisé.

URL de l’API de planification Workfront

Opérations

Les objets sont manipulés en envoyant une requête HTTP à leur URI unique. L’opération à effectuer est spécifiée par la méthode HTTP.

Les méthodes HTTP standard correspondent aux opérations suivantes :

Pour plus d’informations et d’exemples sur chaque opération, consultez la documentation destinée aux développeurs de l’API de planification Workfront.

Types de champ et modificateurs de recherche utilisés avec eux

Vous pouvez utiliser des modificateurs et des filtres avec des champs pour contrôler les données qui seront renvoyées dans les résultats.

Utilisation des modificateurs de recherche

Workfront Planning prend en charge les modificateurs de recherche suivants :

Types de champ

Vous trouverez ci-dessous la liste des types de champ pris en charge et les modificateurs de recherche pouvant être utilisés avec chacun de ces types de champ.

Utilisation d’instructions "Et" et "Ou"

Dans l’appel API, vous pouvez avoir des filtres qui sont basés sur plusieurs critères combinés par des instructions $and" et "$or".

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

Utilisation du paramètre de requête de champs

Vous pouvez utiliser le paramètre de requête de champs pour spécifier une liste de champs spécifiques séparés par des virgules qui doivent être renvoyés. Les noms de ces champs sont sensibles à la casse.

Par exemple, la requête

/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
                    },
....

renvoie une réponse similaire à la suivante :

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

Trier les résultats d’une requête dans l’API

Vous pouvez trier vos résultats selon n’importe quel champ si vous ajoutez les éléments suivants à votre appel API :

/v1/records/search

Corps de la requête :

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

Limites de requête et réponses paginées

Par défaut, les demandes d’API de planification renvoient 500 résultats, à partir du début de la liste. Pour contourner la limitation par défaut du nombre de résultats, vous pouvez utiliser le paramètre limit dans vos requêtes et le définir sur un nombre différent, jusqu’à 2 000 résultats.

Nous vous recommandons d’utiliser des réponses paginées pour les jeux de données volumineux en ajoutant le paramètre offset à vos requêtes. Les réponses paginées vous permettent de spécifier l’emplacement du premier résultat qui doit être renvoyé.

Par exemple, si vous souhaitez renvoyer les résultats 2001-4000, vous pouvez utiliser la requête suivante. Cet exemple renvoie les 2 000 enregistrements qui sont en état actif, à partir du résultat 2001st :

POST /v1/records/search

Corps de la requête :

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

Pour vous assurer que vos résultats sont correctement paginés, utilisez un paramètre de tri. Cela permet de renvoyer les résultats dans le même ordre, de sorte que la pagination ne se répète pas ou n’ignore pas les résultats.

Pour plus d’informations sur le tri, voir Tri des résultats de requête dans l’API de cet article.