Noções básicas sobre a API do Adobe Workfront Planning

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

Uma familiaridade com o esquema do Workfront Planning o ajudará a entender os relacionamentos de banco de dados que podem ser utilizados para extrair dados do Workfront Planning para fins de integração.

Você pode chamar a API de planejamento a partir de um campo de pesquisa externo em um formulário personalizado do Workfront.

Para obter mais informações sobre campos de pesquisa externos, consulte Exemplos do campo de pesquisa externo em um formulário personalizado.

URL da API do Workfront Planning

Operações

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

Os métodos HTTP padrão correspondem às seguintes operações:

Para obter mais detalhes e exemplos de cada operação, consulte a documentação do desenvolvedor da API do Workfront Planning.

Tipos de campo e modificadores de pesquisa usados com eles

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

Uso de modificadores de pesquisa

O Workfront Planning suporta os seguintes modificadores de pesquisa:

Tipos de campo

Abaixo está a lista de tipos de campo suportados e quais modificadores de pesquisa podem ser usados com cada um desses tipos de campo

Uso de instruções "And" e "Or"

Na chamada da API, você pode ter filtros baseados em vários critérios combinados por instruções $and" e "$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"
            }
          ]
        }
      ]
    }
  ]
}

Uso do parâmetro de solicitação de campos

Você pode usar o parâmetro de solicitação de campos para especificar uma lista separada por vírgulas de campos específicos que devem ser retornados. Esses nomes de campos fazem distinção entre maiúsculas e minúsculas.

Por exemplo, a solicitação

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

retorna uma resposta semelhante à seguinte:

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

Classificação dos resultados da consulta na API

Você pode classificar os resultados por qualquer campo se anexar o seguinte à chamada de API:

/v1/records/search

Corpo da solicitação:

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

Limites de consulta e respostas paginadas

Por padrão, as solicitações da API de Planejamento retornam 500 resultados, começando do início da lista. Para substituir a limitação padrão do número de resultados, você pode usar o parâmetro limit em suas solicitações e defini-lo como um número diferente, até 2000 resultados.

Recomendamos que você considere usar respostas paginadas para conjuntos de dados grandes adicionando o parâmetro offset às suas solicitações. As respostas paginadas permitem especificar o local do primeiro resultado que deve ser retornado.

Por exemplo, se quiser retornar os resultados 2001-4000, você poderá usar a solicitação a seguir. Este exemplo retorna 2000 registros que estão no status ativo, a partir do resultado 2001:

POST /v1/records/search

Corpo da solicitação:

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

Para garantir que seus resultados sejam paginados corretamente, use um parâmetro de classificação. Isso permite que os resultados sejam retornados na mesma ordem, para que a paginação não repita ou ignore os resultados.

Para obter mais informações sobre classificação, consulte Classificar resultados da consulta na API neste artigo.