Noções básicas da API do Planejamento do Adobe Workfront

O objetivo da API de planejamento do Adobe Workfront é simplificar a criação de integrações com o Planning, introduzindo uma arquitetura RESTful que opera via HTTP. Este documento supõe que você esteja familiarizado com as respostas REST e JSON.

Para obter referência completa do ponto de extremidade, esquemas de solicitação/resposta e detalhes específicos da versão, consulte a documentação do desenvolvedor da API do Workfront Planning.

Autenticação

A API do Workfront Planning usa o OAuth 2.0 para autenticação. As credenciais são configuradas por meio da Adobe Developer Console.

Dependendo do seu tipo de integração, oferecemos suporte aos dois fluxos a seguir:

Para começar, crie um projeto no Adobe Developer Console e adicione a API do Workfront Planning para obter suas credenciais.

Para configurar credenciais, crie um aplicativo OAuth2 no Workfront.

Para obter informações, consulte Criar aplicativos OAuth2 para integrações do Workfront.

Controle de versão da API

A versão da API do Planning é feita por meio do caminho do URL.

Estas são as versões atuais compatíveis:

Para obter mais informações sobre as versões atuais com suporte, consulte o artigo documentação do desenvolvedor da API do Workfront Planning.

Recomendamos o direcionamento explícito de uma versão em todas as integrações:

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

Quando uma nova versão principal for lançada, a versão anterior continuará disponível até que uma data de desativação seja comunicada.

Siga as notas de versão do Workfront para se manter informado sobre alterações na API.

Estrutura e operações de URL

Os objetos são manipulados enviando uma solicitação HTTP para seu URI exclusivo. A operação é especificada pelo método HTTP.

Para obter caminhos completos de pontos de extremidade e exemplos de solicitação/resposta, consulte a Referência da API em developer.adobe.com/wf-planning.

Códigos de status HTTP

A API do Planning retorna códigos de status HTTP padrão:

Tratamento de erros

A API de Planejamento retorna erros em um formato consistente. Cada resposta de erro inclui uma mensagem legível por humanos, um código de erro legível por computador e uma ID de solicitação para escalonamento de suporte.

Exemplo de resposta de erro:

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 (não status) para direcionar tratamento de erros programáticos. Ela fornece a classificação mais específica da falha.

Filtrar registros

Use o parâmetro filter em solicitações de pesquisa de registro para retornar somente registros que correspondam a critérios específicos. Para solicitações POST, filter é uma propriedade JSON no corpo da solicitação. Para solicitações GET, filter é um parâmetro de consulta que contém um grupo de filtros codificado em JSON. Os filtros usam uma estrutura composta digitada com operadores lógicos explícitos.

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

Filtros podem ser aninhados usando operadores AND / OR para criar condições compostas:

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 e modificadores de pesquisa

Você pode usar modificadores e filtros com campos para controlar quais dados serão retornados nos resultados.

Para obter exemplos, consulte a documentação para desenvolvedores da API do Workfront Planning.

Uso de modificadores de pesquisa

O Workfront Planning suporta os seguintes modificadores de pesquisa:

Condições de filtro compatíveis por tipo de campo

Filtragem por campos de pessoas

Os filtros de campo de pessoas (user, created-by, updated-by, approved-by) aceitam IDs de usuário do Adobe IMS e IDs de usuário do Workfront. Um valor de string simples é interpretado como uma ID de usuário do Adobe IMS.

Para definir o tipo de identificador para verificar a ID de usuário do Workfront, é necessário passar explicitamente os parâmetros id e idType. Os valores com suporte para idType são “WF” para IDs de usuário do Workfront e “IMS” para IDs de usuário do Adobe IMS.

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

Filtrar campos de referência externa por ID externa

Os campos de referência externa vinculam registros a objetos em outros sistemas Adobe (como projetos Workfront ou AEM Assets). Internamente, o Planning atribui IDs de registro do Planning a esses objetos. Para filtrar esses campos diretamente pela ID de objeto original, adicione "matchExternalId": true a uma condição de filtro.

Esse sinalizador só é válido para campos de referência onde referenceOptions.isExternal é true; ele é ignorado para campos de referência não externos. Se um único valor de cadeia de caracteres não puder ser resolvido, a solicitação falhará com 400 Bad Request. Se um valor de lista for fornecido, as entradas não resolvidas passarão inalteradas e simplesmente não corresponderão.

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

Campos de conexão externa

Os tipos de registro do Planning podem hospedar campos de referência externa que vinculam registros a objetos em outros sistemas Adobe, em vez de outros tipos de registro do Planning.

Para criar um campo de referência externa por meio da API, defina referenceOptions.recordTypeId em um novo campo REFERENCE como a ID do tipo de registro externo desejado. O servidor deriva automaticamente referenceOptions.isExternal=true e os metadados de conexão (connectionName, objectName) do tipo de registro de destino.

Os tipos de objetos externos compatíveis incluem objetos do Workfront (projetos, tarefas, programas, portfólios, empresas, grupos, equipes, usuários) e do AEM Assets (ativos, fragmentos de conteúdo).

Classificação

Classifique os resultados por qualquer campo incluindo uma matriz sort em sua solicitação:

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

Os campos de classificação múltipla são avaliados em ordem. Sempre aplique uma classificação ao paginar para garantir uma ordem consistente entre as páginas.

Para agrupar resultados, inclua uma matriz de grupo ao lado de classificar:

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

Projeção de campo

Para limitar quais campos são retornados em uma resposta, use os parâmetros de consulta fieldIds ou fieldAliases com uma lista separada por vírgulas. Isso reduz o tamanho da carga de resposta e é recomendado para integrações de alto volume ou sensíveis à latência.

Paginação

A API do Planning permite respostas paginadas para gerenciar grandes conjuntos de dados.

Por exemplo, use a seguinte solicitação para recuperar a segunda página de 500 registros de uma pesquisa de registro:

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 as respostas paginadas incluem um envelope estruturado indicando se mais resultados estão disponíveis. Sempre aplique uma classificação ao paginar para garantir uma ordem consistente entre as páginas.

Operações em massa

A API do Planning permite criar, atualizar, corrigir e excluir registros em massa em uma única solicitação. Consulte a Referência da API em developer.adobe.com/wf-planning para obter os caminhos de ponto de extremidade, formatos de solicitação e limites de registro por operação.

Permissões

As permissões para entidades são gerenciadas por meio de uma API de permissões dedicada, separada dos próprios endpoints de recursos. Isso permite que você leia as permissões atuais, gerencie a lista de compartilhamento e lide com as solicitações de acesso independentemente das operações de dados. Para obter mais informações, consulte a seção “Referências de API” no artigo API do Workfront Planning.

Uso da API do Planning com formulários personalizados do Workfront

Você pode chamar a API do Planning a partir de um campo de pesquisa Externo em um formulário personalizado do Workfront para exibir dados do Planning diretamente nos objetos do Workfront. Para obter mais informações, consulte Exemplos do campo de pesquisa Externa em um formulário personalizado.

Recursos relacionados

Para obter mais documentação relacionada à API, consulte também os seguintes artigos: