蜜豆视频

蜜豆视频 Workfront Planning API basics

The goal for the 蜜豆视频 Workfront Planning API is to simplify building integrations with Planning by introducing a REST-ful architecture that operates over HTTP. This document assumes you are familiar with REST and JSON responses and describes the approach taken by the Planning API.

A familiarity with the Workfront Planning schema will assist you in understanding the database relationships that can be utilized to pull data out of Workfront Planning for integration purposes.

You can call the planning API from an External lookup field in a Workfront custom form.

For more information on External lookup fields, see Examples of the External lookup field in a custom form.

Workfront Planning API URL

Operations

Objects are manipulated by sending an HTTP request to their unique URI. The operation to be performed is specified by the HTTP method.

The standard HTTP methods correspond to the following operations:

For more details and examples of each operation, see the .

Field types and search modifiers used with them

You can use modifiers and filters with fields to control what data will be returned in results.

Using search modifiers

Workfront Planning supports the following search modifiers:

Field types

Below is the list of supported field types and what search modifiers can be used with each of those field types

Using 鈥淎nd鈥� and 鈥淥r鈥� statements

In the API call you can have filters that are based on several criteria combined by $and" and 鈥�$or鈥� statements

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

Using the fields request parameter

You can use the fields request parameter to specify a comma-separated list of specific fields that should be returned. These field names are case-sensitive.

For example, the request

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

returns a response similar to the following:

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

Sorting query results in the API

You can sort your results by any field if you append the following to your API call:

/v1/records/search

Request body:

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

Query limits and paginated responses

By default, Planning API requests return 500 results, starting from the beginning of the list. To override the default limitation for number of results, you can use the limit parameter in your requests and set it to a different number, up to 2000 results.

We recommend that you consider using paginated responses for large datasets by adding the offset parameter to your requests. Paginated responses allow you to specify the location of the first result that should be returned.

For example, if you want to return the results 2001-4000, you can use the following request. This example returns 2000 records that are in active status, starting from the 2001st result:

POST /v1/records/search

Request body:

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

To make sure your results are properly paginated, use a sorting parameter. This allows the results to be returned in the same order, so that the pagination does not repeat or skip results.

For more information on sorting, see Sorting query results in the API in this article.