Principes de base des API de planification d’Adobe Workfront

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

Une connaissance du 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 Workfront Planning à 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 externe, voir Exemples du champ de recherche externe dans un formulaire personnalisé.

URL de l’API Workfront Planning

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 de chaque opération, consultez la documentation destinée aux développeurs et développeuses de l’API Workfront Planning.

Types de champs et modificateurs de recherche utilisés avec

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 des instructions « And » et « Or »

Dans l’appel API, vous pouvez avoir des filtres 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 fields

Vous pouvez utiliser le paramètre de requête fields pour spécifier une liste séparée par des virgules de champs spécifiques à renvoyer. 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 requêtes d’API Planning renvoient 500 résultats, en commençant au début de la liste. Pour remplacer 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’envisager 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 à renvoyer.

Par exemple, si vous souhaitez renvoyer les résultats 2001-4000, vous pouvez utiliser la requête suivante. Cet exemple renvoie 2 000 enregistrements dont le statut est actif, à partir du résultat 2001 :

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 et n’ignore pas les résultats.

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