Principes de base des API Adobe Workfront Planning

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

Pour obtenir une référence complète des points d’entrée, des schémas de requête/réponse et des détails spécifiques à la version, consultez la documentation du développeur de l’API Workfront Planning.

Authentification

L’API Workfront Planning utilise OAuth 2.0 pour l’authentification. Les informations d’identification sont configurées via le Adobe Developer Console.

Nous prenons en charge les deux flux suivants en fonction de votre type d’intégration :

Pour commencer, créez un projet dans Adobe Developer Console et ajoutez l’API Workfront Planning pour obtenir vos informations d’identification.

Pour configurer les informations d’identification, créez une application OAuth2 dans Workfront.

Pour plus d’informations, voir Création d’applications OAuth2 pour les intégrations Workfront.

Contrôle de version des API

Le contrôle de version de l’API Planning s’effectue via le chemin URL.

Voici les versions actuellement prises en charge :

Pour plus d’informations sur les versions actuellement prises en charge, consultez l’article Documentation destinée aux développeurs et développeuses de l’API Workfront Planning.

Nous vous recommandons de cibler explicitement une version dans toutes les intégrations :

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

Lorsqu’une nouvelle version majeure est publiée, la version précédente reste disponible jusqu’à ce qu’une date d’obsolescence soit communiquée.

Consultez les notes de mise à jour de Workfront pour rester informé des modifications apportées à l’API.

Structure et opérations de l’URL

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

Pour obtenir des chemins d’accès complets aux points d’entrée et des exemples de requête/réponse, consultez la référence d’API à l’adresse developer.adobe.com/wf-planning.

Codes d’état HTTP

L’API Planning renvoie des codes d’état HTTP standard :

Gestion des erreurs

L’API Planning renvoie des erreurs dans un format cohérent. Chaque réponse d’erreur comprend un message lisible par l’utilisateur, un code d’erreur lisible par la machine et un identifiant de demande pour l’escalade de l’assistance.

Exemple de réponse d’erreur :

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

Utilisez errorCode (non status) pour piloter la gestion des erreurs de programmation. Il fournit la classification la plus spécifique de l’échec.

Filtrer les enregistrements

Utilisez le paramètre filter dans les demandes de recherche d’enregistrements pour renvoyer uniquement les enregistrements correspondant à des critères spécifiques. Pour les requêtes POST, filter est une propriété JSON dans le corps de la requête. Pour les requêtes GET, filter est un paramètre de requête contenant un groupe de filtres codés JSON. Les filtres utilisent une structure composite typée avec des opérateurs logiques explicites.

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

Les filtres peuvent être imbriqués à l’aide d’opérateurs AND/OR pour créer des conditions composites :

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

Types de champs et modificateurs de recherche

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.

Pour obtenir des exemples, consultez la documentation du développeur de l’API Workfront Planning 🔗.

Utilisation des modificateurs de recherche

Workfront Planning prend en charge les modificateurs de recherche suivants :

Conditions de filtrage prises en charge par type de champ

Filtrer par champs Personnes

Les filtres de champ de personne (user, created-by, updated-by, approved-by) acceptent les ID utilisateur Adobe IMS et Workfront. Une valeur de chaîne simple est interprétée comme un identifiant utilisateur Adobe IMS.

Pour définir le type d’identifiant afin de vérifier l’ID utilisateur Workfront, vous devez transmettre explicitement les paramètres id et idType. Les valeurs prises en charge pour idType sont « WF » pour les ID utilisateur Workfront et « IMS » pour les ID utilisateur Adobe IMS.

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

Filtrer les champs de référence externes par ID externe

Les champs de référence externes lient les enregistrements aux objets d’autres systèmes Adobe (tels que les projets Workfront ou AEM Assets). En interne, Planning affecte des ID d’enregistrement Planning à ces objets. Pour filtrer ces champs directement en fonction de leur ID d’objet d’origine, ajoutez des "matchExternalId": true à une condition de filtre.

Cet indicateur n’est valide que pour les champs de référence où referenceOptions.isExternal est true ; il est ignoré pour les champs de référence non externes. Si une valeur de chaîne unique ne peut pas être résolue, la requête échoue avec 400 Bad Request. Si une valeur de liste est fournie, les entrées non résolues passent inchangées et ne correspondent tout simplement pas.

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

Champs de connexion externe

Les types d’enregistrements Planning peuvent héberger des champs de référence externes qui lient des enregistrements à des objets dans d’autres systèmes Adobe au lieu d’autres types d’enregistrements Planning.

Pour créer un champ de référence externe via l’API, définissez referenceOptions.recordTypeId sur un nouveau champ de REFERENCE l’identifiant du type d’enregistrement externe souhaité. Le serveur dérive automatiquement les referenceOptions.isExternal=true et les métadonnées de connexion (connectionName, objectName) du type d’enregistrement cible.

Les types d’objets externes pris en charge comprennent les objets Workfront (projets, tâches, programmes, portfolios, entreprises, groupes, équipes, utilisateurs) et AEM Assets (ressources, fragments de contenu).

Tri

Triez les résultats en fonction de n’importe quel champ en incluant un tableau de sort dans votre requête :

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

Plusieurs champs de tri sont évalués dans l’ordre. Appliquez toujours un tri lors de la pagination afin de garantir un ordre cohérent sur toutes les pages.

Pour regrouper des résultats, incluez un tableau de groupe à côté de trier :

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

Projection de champ

Pour limiter les champs renvoyés dans une réponse, utilisez les paramètres de requête fieldIds ou fieldAliases avec une liste séparée par des virgules. Cela réduit la taille de la payload de réponse et est recommandé pour les intégrations à volume élevé ou sensibles à la latence.

Pagination

L’API Planning prend en charge les réponses paginées pour gérer les jeux de données volumineux.

Par exemple, utilisez la requête suivante pour récupérer la deuxième page de 500 enregistrements à partir d’une recherche d’enregistrements :

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

Toutes les réponses paginées incluent une enveloppe structurée indiquant si d’autres résultats sont disponibles. Appliquez toujours un tri lors de la pagination afin de garantir un ordre cohérent sur toutes les pages.

Opérations en masse

L’API Planning prend en charge la création, la mise à jour, l’application de correctifs et la suppression en bloc d’enregistrements dans une seule requête. Consultez la référence d’API à l’adresse developer.adobe.com/wf-planning pour connaître les chemins de point d’entrée, les formats de requête et les limites d’enregistrement par opération.

Autorisations

Les autorisations d’entités sont gérées par le biais d’une API d’autorisations dédiée, distincte des points d’entrée des ressources eux-mêmes. Vous pouvez ainsi lire les autorisations actuelles, gérer la liste de partage et gérer les demandes d’accès indépendamment des opérations sur les données. Pour plus d’informations, consultez la section « Références de l’API » dans l’article API Workfront Planning.

Utilisation de l’API Planning avec des formulaires personnalisés Workfront

Vous pouvez appeler l’API Planning à partir d’un champ de recherche externe dans un formulaire personnalisé Workfront pour faire apparaître les données Planning directement dans les objets Workfront. Pour plus d’informations, voir Exemples du champ de recherche externe dans un formulaire personnalisé.

Ressources connexes

Pour plus d’informations sur les API, consultez également les articles suivants :