Conceptos básicos de la API de Adobe Workfront Planning

El objetivo de la API de Planning de Adobe Workfront es simplificar la creación de integraciones con Planning mediante la introducción de una arquitectura RESTful que funcione a través de HTTP. Este documento supone que está familiarizado con las respuestas de REST y JSON.

Para obtener toda la referencia de extremo, esquemas de solicitud/respuesta y detalles específicos de la versión, consulte la documentación para desarrolladores de la API de Workfront Planning.

Autenticación

La API de Workfront Planning utiliza OAuth 2.0 para la autenticación. Las credenciales se configuran mediante Adobe Developer Console.

Admitimos los dos flujos siguientes en función de su tipo de integración:

Para empezar, cree un proyecto en Adobe Developer Console y añada la API de Workfront Planning para obtener sus credenciales.

Para configurar las credenciales, cree una aplicación OAuth2 en Workfront.

Para obtener más información, consulte Crear aplicaciones OAuth2 para integraciones de Workfront.

Versiones de API

Las versiones de la API de Planning se realizan mediante la ruta URL.

Las siguientes son las versiones compatibles actuales:

Para obtener más información sobre las versiones compatibles actuales, consulte el artículo Documentación para desarrolladores de API de Workfront Planning.

Se recomienda segmentar explícitamente una versión en todas las integraciones:

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

Cuando se publique una nueva versión principal, la versión anterior seguirá disponible hasta que se comunique una fecha de obsolescencia.

Siga las Notas de la versión de Workfront para mantenerse informado de los cambios de la API.

Estructura y operaciones de URL

Los objetos se manipulan enviando una petición HTTP a su URI único. La operación se especifica mediante el método HTTP.

Para obtener rutas de acceso de extremo completas y ejemplos de solicitud/respuesta, consulte la referencia de API en developer.adobe.com/wf-planning.

Códigos de estado HTTP

La API de Planning devuelve códigos de estado HTTP estándar:

Gestión de errores

La API de Planning devuelve errores en un formato coherente. Cada respuesta de error incluye un mensaje legible en lenguaje natural, un código de error legible en el equipo y un ID de solicitud para la escalación de soporte.

Ejemplo de respuesta de error:

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

Use errorCode (no status) para controlar la administración de errores de programación. Proporciona la clasificación más específica del error.

Filtrado de registros

Utilice el parámetro filter en las solicitudes de búsqueda de registros para devolver solo los registros que coincidan con criterios específicos. Para las solicitudes POST, filter es una propiedad JSON en el cuerpo de la solicitud. Para solicitudes GET, filter es un parámetro de consulta que contiene un grupo de filtros con codificación JSON. Los filtros utilizan una estructura compuesta con tipo con operadores lógicos explícitos.

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

Los filtros se pueden anidar utilizando los operadores AND / OR para generar condiciones compuestas:

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

Tipos de campo y modificadores de búsqueda

Puede utilizar modificadores y filtros con campos para controlar qué datos se devolverán en los resultados.

Para ver ejemplos, consulte la documentación para desarrolladores de API de Workfront Planning.

Uso de modificadores de búsqueda

Workfront Planning admite los siguientes modificadores de búsqueda:

Condiciones de filtro compatibles por tipo de campo

Filtrado por campos de personas

Los filtros de campo Personas (user, created-by, updated-by, approved-by) aceptan tanto los identificadores de usuario de IMS de Adobe como los de usuario de Workfront. Un valor de cadena sin formato se interpreta como un ID de usuario de Adobe IMS.

Para establecer el tipo de identificador para comprobar el ID de usuario de Workfront, debe pasar explícitamente los parámetros id y idType. Los valores admitidos para idType son “WF” para los identificadores de usuario de Workfront y “IMS” para los identificadores de usuario de IMS de Adobe.

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

Filtrado de campos de referencia externos por ID externo

Los campos de referencia externa vinculan registros a objetos de otros sistemas de Adobe (como proyectos o AEM Assets de Workfront). Internamente, Planning asigna los ID de registro de Planning a estos objetos. Para filtrar estos campos directamente por su identificador de objeto original, agregue "matchExternalId": true a una condición de filtro.

Este indicador solo es válido para campos de referencia donde referenceOptions.isExternal es true; se omite para campos de referencia no externos. Si no se puede resolver un solo valor de cadena, la solicitud falla con 400 Bad Request. Si se proporciona un valor de lista, las entradas sin resolver pasan sin cambios y simplemente no coinciden.

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

Campos de conexión externa

Los tipos de registros de Planning pueden alojar campos de referencia externos que vinculen registros a objetos de otros sistemas de Adobe en lugar de otros tipos de registros de Planning.

Para crear un campo de referencia externo a través de la API, establezca referenceOptions.recordTypeId en un nuevo campo REFERENCE al ID del tipo de registro externo deseado. El servidor deriva automáticamente referenceOptions.isExternal=true y los metadatos de conexión (connectionName, objectName) del tipo de registro de destino.

Los tipos de objetos externos admitidos son objetos de Workfront (proyectos, tareas, programas, portafolios, empresas, grupos, equipos y usuarios) y AEM Assets (recursos y fragmentos de contenido).

Orden

Ordene los resultados por cualquier campo incluyendo una matriz sort en la solicitud:

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

Los campos de ordenación múltiples se evalúan en orden. Aplique siempre una ordenación al paginar para garantizar un orden coherente entre las páginas.

Para agrupar los resultados, incluya una matriz de grupo junto con el orden:

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

Proyección de campos

Para limitar qué campos se devuelven en una respuesta, utilice los parámetros de consulta fieldIds o fieldAliases con una lista separada por comas. Esto reduce el tamaño de la carga útil de respuesta y se recomienda para integraciones de gran volumen o sensibles a la latencia.

Paginación

La API de Planning admite respuestas paginadas para administrar conjuntos de datos grandes.

Por ejemplo, utilice la siguiente solicitud para recuperar la segunda página de 500 registros de una búsqueda de registros:

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

Todas las respuestas paginadas incluyen un sobre estructurado que indica si hay más resultados disponibles. Aplique siempre una ordenación al paginar para garantizar un orden coherente entre las páginas.

Operaciones masivas

La API de Planning admite la creación, actualización, aplicación de parches y eliminación en lotes de registros en una sola solicitud. Consulte la referencia de API en developer.adobe.com/wf-planning para ver las rutas de extremos, los formatos de solicitud y los límites de registros por operación.

Permisos

Los permisos para entidades se administran mediante una API de permisos dedicada, independiente de los propios extremos de los recursos. Esto le permite leer los permisos actuales, administrar la lista de uso compartido y administrar las solicitudes de acceso independientemente de las operaciones de datos. Para obtener más información, consulte la sección “Referencias de API” en el artículo API de Workfront Planning.

Uso de la API de Planning con formularios personalizados de Workfront

Puede llamar a la API de Planning desde un campo de búsqueda externa en un formulario personalizado de Workfront para mostrar datos de Planning directamente en objetos de Workfront. Para obtener más información, vea Ejemplos del campo de búsqueda externa en un formulario personalizado.

Recursos relacionados

Para obtener más documentación relacionada con la API, consulte también los siguientes artículos: