API basics

The goal for the Adobe Workfront API is to simplify building integrations with Workfront 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 Workfront API.

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

Limits and Guidelines

To ensure consistent Workfront on-demand system performance, each customer is limited to 10 concurrent API threads. The Sandbox environment has the same limit in place, allowing customers and partners to accurately test API calls before releasing code to production.

For production, preview, and test drive environments end user requests have a maximum URI length of 8892 bytes because they’re being routed through the Workfront CDN (Akamai). This limit only applies to URIs that are routed through the CDN.

Disclaimer

Any use of the API should be tested in the Workfront beta environment prior to being run in the production environment. If any customer uses the API for a process that Workfront reasonably believes to be burdensome to the on-demand software (i.e., the process causes a materially negative effect on the performance of the software for other customers), Workfront reserves the right to request that the customer discontinues that process. If the customer does not comply and the problem persists, Workfront reserves the right to terminate the process.

REST Basics

This section provides a high-level introduction of how to interact with the Workfront REST API for the following REST principles:

Object URI

Each object in the system is given a unique URI consisting of the object type and the ID. The following examples show URIs describing three unique objects:

/attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
/attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d1
/attask/api/v15.0/issue/4c78821c0000d6fa8d5e52f07a1d54d2

The object type is case insensitive and can be either the abbreviated ObjCode (such as proj) or the alternate object name (project).

For a list of valid ObjCodes, see  API Explorer.

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:

• GET - Retrieves an object by ID, searches for all objects by a query, runs reports, or executes named queries
• POST - Inserts a new object
• PUT - Edits an existing object
• DELETE - Deletes an object

In order to work around client deficiencies or protocol length limits, the method parameter can be used to override HTTP behavior. For example, a GET operation may be implemented by posting the following URI:

GET /attask/api/v15.0/project?id=4c78...54d0&method=get
GET /attask/api/v15.0/project/4c78...54d0?method=get

Response

Each request is given a response in JSON format. The response has either a data attribute if the request was successful or an error attribute if there was a problem. For example, the request

GET /attask/api/v15.0/proj/4c7c08b20000002de5ca1ebc19edf2d5

returns a JSON response similar to the following:

{
    "data": [
        {
            "percentComplete": 0,
            "status": "CUR",
            "priority": 2,
            "name": "Brand New Project",
            "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
        } 
    ] 
}

Special security has been added around PUT, POST, and DELETE requests. Any request that results in writing to or deleting from the database can only be executed if the sessionID=abc123 is included in the URI. The following examples show how this would look for a DELETE request:

GET /attask/api/v15.0/project?id=4c78...54d0&method=delete&sessionID=abc123
GET /attask/api/v15.0/project/4c78...54d0?method=delete&sessionID=abc123

Authentication

The API authenticates each request to ensure that the client has access to view or modify a requested object.

Authentication is performed by passing in a session ID which can be given using one the following methods:

Request Header Authentication

The preferred method of authentication is to pass a request header named SessionID containing the session token. This has the advantage of being safe against Cross-site Request Forgery (CSRF) attacks and not interfering with the URI for caching purposes.

The following is an example of a request header:

GET /attask/api/v15.0/project/search
SessionID: abc1234

Request Parameter Authentication

You can authenticate by passing a request parameter named sessionID, as shown in the following example: 

GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0?sessionID=abc1234

Cookie-Based Authentication

The API uses the same cookie-based authentication that is used by the web UI to the system. Where, if a client logs into Workfront using the web UI, any AJAX calls made from within the same browser uses the same authentication.

Login

Using a valid username and password, you can use the following request to obtain a session ID:

POST /attask/api/v15.0/login?username=admin&password=user

This sets a cookie to authenticate future requests as well as return a JSON response with the newly created sessionID, the userID of the logged in user, and other session attributes.

Generating an API Key

You can generate an API Key when you log into the system as that user, as shown in the following example:

PUT /attask/api/v15.0/user?action=generateApiKey&username= username&password=password&method=put

Retrieving a Previously-Generated API Key

You can also retrieve an API Key that has been previously generated for a particular user by running getApiKey:

PUT /attask/api/v15.0/user?action=getApiKey&username=user@email.com&password=userspassword&method=put

You can then use this result to authenticate any API call by adding “apiKey” as a request parameter with this value in place of a sessionID or username and password. This is beneficial from a security perspective.

The following request is an example of retrieving data from a project using the apiKey:

GET /attask/api/v15.0/project/abc123xxxxx?apiKey=123abcxxxxxxxxx

Invalidating an API Key

If the apiKey value has been compromised, you can run “clearApiKey” which invalidates the current API Key, as shown in the following example:

GET /attask/api/v15.0/user?action=clearApiKey&username=user@email.com&password=userspassword&method=put

Once cleared, you can run getApiKey again to generate a new API Key.

Logout

When a session is complete, you can use the following request to log the user out, preventing any further access with the sessionID.

GET /attask/api/v15.0/logout?sessionID=abc1234

The sessionID to be logged out can be specified either as a cookie, request header, or request parameter.

To log out a user:

1. Navigate to your login screen, but do not log in.

2. Change the URL to /attask/api/v15.0/project/search.
   Notice the page cannot be found.

3. Replace the word search with login?username=admin&password=user, substituting your username and password for admin and *user
   *This session is stored in the browser as a cookie and does not need to be restated in each subsequent GET request.

4. Change the URL back to /attask/api/v15.0/project/search.

5. Notice the response provided.

You must always include the sessionID provided after login when performing PUT, POST, and DELETE requests.

GET Behavior

Use the HTTP GET method to retrieve an object or multiple objects and to run reports.

Retrieving Objects

You can enhance a search for objects using modifiers and filters.

Retrieving an Object Using the Object ID

If you know the ID of an object, you can retrieve the object by accessing its unique URI. For example, the request

GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0

returns a response similar to the following:

{
    "percentComplete": 0,
    "status": "CUR",
    "priority": 2,
    "name": "Brand New Project",
    "ID": "4c7c08b20000002de5ca1ebc19edf2d5" 
}

You can retrieve multiple objects in the same request by specifying the id request parameter and giving a comma-separated list of IDs, as shown in the following example:

GET /attask/api/v15.0/project?id=4c78...54d0,4c78...54d1

Notice the /attask/api/v15.0/project?id=… request is the same as the /attask/api/v15.0/project/... request.

Retrieving an Object Using the URI

If you want to retrieve an object by criteria other than the ID, you can search for the URI.

For example, you can use the following request to return a list of all the projects in the system:

GET /attask/api/v15.0/project/search

You can specify filters using the request parameters as name-value pairs. For example, the following example shows a request that would find all current projects:

GET /attask/api/v15.0/project/search?status=CUR

The following request finds all the tasks that are not yet complete and that are assigned to a user named John.

GET /attask/api/v15.0/task/search?percentComplete=100
&percentComplete_Mod=lt &assignedTo:firstName=John

Using Search Modifiers

The following table lists some of the modifiers you can use with the Workfront API.

…status=cls&status_Mod=eq…

…status=cls&status_Mod=ne…

…percentComplete=50&percentComplete_Mod=gte…

…percentComplete=50&percentComplete_Mod=lte…

…description_Mod=isnull…

…description_Mod=notnull…

…name=Workfront&name_Mod=contains…

…entryDate=$$TODAY-7d&entryDate_Range=$$TODAY&entryDate_Mod=between…

Using OR Statements

You can enhance a search by adding a parameter that includes “OR” as well as a number to indicate the level of a filter or series of filters.

An OR statement returns only records in the API call that meet the OR statement’s filtering criteria. Filters are not implied across OR statement levels.

For example, if you want to filter for

• Tasks that have a name containing “Planning” OR
• Tasks in a portfolio named “FixedAssets” AND assigned to someone with a name containing “Steve” OR
• Tasks that have a parent task named “Final Task”

then use the following API call with its multiple OR statements:

GET /attask/api/v15.0/task/search?name=Planning
&name_Mod=contains
&OR:1:portfolio:name=FixedAssets
&OR:1:portfolio:name_Mod=eq
&OR:1:assignedTo:name=Steve
&OR:1:assignedTo:name_Mod=cicontains
&OR:2:parent:name=Final Task
&OR:2:parent:name_Mod=eq

Using Filter Parameters

One potential pitfall with using URL parameters for search filters is that Workfront parses certain parameters before checking for different authentication methods (i.e., username, password, apiKey, cookie). When this happens the parameters are not used as filters in the call. 

To avoid this problem, you can place these values in filter parameters with JSON formatting. For example, if you want to filter for the username testuser, instead of using 

/attask/api/v15.0/user/search?username=testuser@workfront.com

/attask/api/v15.0/user/search?filters={"username":"testuser@workfront.com"}

Using the Map Request Parameter

By default, the data returned from a search is a JSON array. Depending on your use case, it may be more efficient to get the result as a JSON object indexed by ID. This can be done by using the map request parameter. For example, the request 

/attask/api/v15.0/task/search?map=true

{
    "data": {
        "4c9a97db0000000f13ee4446b9aead9b": {
            "percentComplete": 0,
            "status": "NEW",
            "name": "first task",
            "ID": "4c9a97db0000000f13ee4446b9aead9b",
            "taskNumber": 1 
        },
        "4ca28ba600002024cd49e75bd43cf601": {
            "percentComplete": 0,
            "status": "INP:A",
            "name": "second task",
            "ID": "4ca28ba600002024cd49e75bd43cf601",
            "taskNumber": 2 
        } 
    } 
}

Using the Fields Request Parameter

By default, retrieving an object returns only the most commonly-used subset of fields.

You can use the fields request parameter to specify a comma-separated list of specific fields is returned. For example, the request

/attask/api/v15.0/task/search?fields=plannedStartDate,priority

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

For a list of possible field references, see the  API Explorer

Searching for Nested Objects

You can search for nested objects. By default, nested objects are returned with only the name and ID. For instance to get all issues along with their owners, use the following request:

/attask/api/v15.0/issue/search?fields=owner

/attask/api/v15.0/issue/search?fields=owner:title,owner:phoneNumber

{
    "name": "an important issue",
    "ID": "4c78285f00000908ea8cfd66e084939f",
    "owner": {
        "title": "Operations Specialist",
        "phoneNumber": "555-1234",
        "name": "Admin User",
        "ID": "4c76ed7a0000054c172b2c2d9f7f81c3" 
    } 
}

Retrieving Nested Collections

You can retrieve nested collections of objects. For example, to get a project with all its tasks, use the following request:

/attask/api/v15.0/project/search?fields=tasks

/attask/api/v15.0/task/search?fields=assignments

Searching for Multiple Nested Fields

By default, only the name and ID of each task is returned, but additional nested fields can be specified with colon syntax. To view all available fields for a related object or collection, simply append a colon and asterisk to the object/collection reference.

/attask/api/v15.0/task/search?fields=assignments:*

Retrieving Custom Data

You can retrieve custom data fields using the prefix “DE:”. For instance, to request a project with a parameter called “CustomText,” use the following request:

/attask/api/v15.0/project/search?fields=DE:CustomText

{
    "name": "custom data project",
    "ID": "4c9a954f0000001afad0687d7b1b4e43",
    "DE:CustomText": "task b" 
}

/attask/api/v15.0/project/search?fields=parameterValues

{
    "name": "custom data project",
    "ID": "4c9a954f0000001afad0687d7b1b4e43",
    parameterValues: { 
        "DE:CustomText": "task b", 
        "DE:CustomNumber": 1.4, 
        "DE:CustomCheckBoxes": ["first", "second", "third"] 
    } 
}

Using Named Queries

Some object types have named searches that are commonly executed and are available by appending the name of the query to the end of the object type URI. For example, the following request retrieves the work items (tasks and issues) to which the user is currently assigned:

/attask/api/v15.0/work/myWork

Using the Count Filter

You can specify the number of results you want to be returned by a given search. This allows the server to process the request more quickly and saves bandwidth. For example, the request

GET /attask/api/v15.0/project/count?status=CUR

{
    "count": 3 
}

Requesting a Report

You can perform a report request, where only the aggregate of some field is desired with one or more groupings. As shown in the following example, the report syntax is the same as the syntax for the SOAP API:

GET /attask/api/v15.0/hour/report?project:name_1_GroupBy=true&hours_AggFunc=sum

{
    "First Project": { 
        "sum_hours": 15 
    }, 
     "Second Project": { 
        "sum_hours": 30 
    } 
}

{
    "First Project": { 
        "sum_hours": 15 
    }, 
    "Second Project": { 
        "sum_hours": 30 
    }, 
    "$$ROLLUP": { 
        "sum_hours": 45 
    } 
}

Sorting Query Results in the API

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

&entryDate_Sort=asc

For example, if you want to sort by task Planned Start Date, remove entryDate and replace it with plannedCompletionDate.

This works for most fields in Workfront.

Considering Query Limits

When querying an object, special consideration should be taken concerning the relationship of related objects and search limitations. For example, as shown in the following table, a query for projects can return no more than 2,000 projects. These 2,000 projects are considered “primary objects.” If you query for the Tasks field on the projects, the Tasks field, which is a collection, becomes a secondary object to the primary object Project. A query for the Tasks field can include thousands of tasks on projects. In total, the combined number of objects (projects and tasks) returned cannot exceed the maximum of 50,000.

To ensure optimum performance the following table shows the limitations placed on search requests. 

Using Paginated Responses

To override the Default Number of Results query limitation and allow 200 results, you can include the $$LIMIT=200 filter in your query, as shown in the following example:

GET /attask/api/v15.0/project/search?$$LIMIT=200

To ensure reliability and performance for other tenants in the system, the maximum allowed results limit per query is 2000 objects. Attempting to specify a larger limit will result in an IllegalArgumentException error message. 

Therefore, we recommend you consider using paginated responses for large datasets. To specify the first result that should be returned, add the $$FIRST filter. For example, the following request returns results 201-250 for a query:

GET /attask/api/v15.0/project/search?$$FIRST=200&$$LIMIT=50

Note that in the above example, $$FIRST=200 returns the 201st result. $$FIRST=0 would return the first result. It may help to think of the $$FIRST value as the number of results you want to skip before returning results.

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 example, to sort using the object ID, use ID_Sort=asc.

Creating an Access Rule

You can create an access rule to determine who can access to an object. The following are examples of access rules you can set:

To set a project so it is shared only with a user with ID “abc123” use the following request:

GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?method=put &updates={ accessRules: [ {accessorID: 'abc123', accessorObjCode: 'USER', coreAction: 'VIEW'} ] }

GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx/share?method=put&accessorID=abc123&accessorObjCode=USER&coreAction=VIEW

GET /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?fields=accessRules:*

POST Behavior

POST inserts a new object. The syntax is identical to PUT, but with a few exceptions. Because the new object does not yet exist, it does not have an ID. For this reason, the URI does not include the ID.

Creating an Object

The following is an example of a request to create a new project:

POST /attask/api/v15.0/project?name=New Project

Copying an Object

Some objects support being copied. For these object types, it is possible to create new objects by posting with a copySourceID parameter. For example, the following request copies the given project and gives it a new name:

POST /attask/api/v15.0/project?copySourceID=4c7...&name=Copied Project

Uploading Documents

You can upload documents through the following API URL:

POST /attask/api/v15.0/upload

{
    "handle": "4c7c08fa0000002ff924e298ee148df4"
}

POST /attask/api/v15.0/document?updates={
    name: aFileName,
    handle: abc...123, (handle from the file upload)
    docObjCode: PROJ, (or TASK, OPTASK, etc)
    objID: abc...123,
    currentVersion:{version:v1.0,fileName:aFileName}
}

PUT Behavior

PUT is used to update an existing object.

The response for a PUT is identical to a GET. In both cases, the server returns the new state of the object after the update. All rules used to alter a response to a GET request also work with PUT, such as specifying additional fields to be returned, custom data, and so on.

Editing Objects

Updates to objects are always done by ID using the object’s unique URI. Fields to be updated are specified as request parameters. For instance, to change the name of a project you could send a request similar to the following:

PUT /attask/api/v15.0/project/4c7...?name=New Project Name 
PUT /attask/api/v15.0/project?id=4c7...&name=New Project Name

Specifying JSON Edits

As shown in the following example, you can use the updates request parameter to specify the fields to be updated using JSON syntax:

PUT /attask/api/v15.0/project/4c7...?updates= 
{
     name: "New Project Name", 
     status: "CUR", 
     ... 
}

Making Nested Updates

Some objects have privately-owned collections that can be updated. For example, the following example demonstrates how to overwrite the existing assignments for a given task:

PUT /attask/api/v15.0/task/4c7...?updates= 
{
    assignments: [ 
        { 
            assignedToID: "2222...54d0, 
            assignmentPercent: 50.0 
        },{ 
            roleID: "1111...54d0"
        } 
    ] 
}

The following example makes a project a public help desk queue. Note that the existing queue properties are replaced.

PUT /attask/api/v15.0/project/4c7...?updates= 
{ 
    queueDef: { 
        isPublic: 1 
    } 
}

Using the Action Request Parameter

Some objects support additional actions that can be performed in addition to simple edits. You can specify these actions using the action request parameter. For example, the following request recalculates the timeline for a given project:

PUT /attask/api/v15.0/project/4c7...?action=calculateTimeline

or

PUT /attask/api/v15.0/project/4c7.../calculateTimeline 

Moving Objects

The following demonstrates the syntax for moving a task from one project to another:

PUT /attask/api/v15.0/task/4c7.../move?projectID=5d8...

PUT /attask/api/v15.0/project/1234/approveApproval

PUT /attask/api/v15.0/project/1234/calculateFinance

PUT /attask/api/v15.0/project/1234/calculateTimeline

PUT /attask/api/v15.0/project/1234/calculateDataExtension

PUT /attask/api/v15.0/project/1234/recallApproval

PUT /attask/api/v15.0/project/1234/rejectApproval

PUT /attask/api/v15.0/task/1234/move

PUT /attask/api/v15.0/workitem/1234/markViewed

The following is an example of each action type: 

PUT /attask/api/v15.0/project/1234?method=put&updates={accessRules:[{accessorID: 'abc123', accessorObjCode: 'USER', coreAction: 'VIEW'}]}

Sharing Objects

The following example demonstrates the syntax for sharing a project with a team:

PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx/share?accessorID=123abcxxxxxxxxxxxxxxxxxxxxxxxxxx&accessorObjCode=TEAMOB

PUT /attask/api/v15.0/project/123abcxxxxxxxxxxxxxxxxxxxxxxxxxx?method=PUT&updates={accessRules:[{accessorID:'123abcxxxxxxxxxxxxxxxxxxxxxxxxxx',accessorObjCode:'TEAMOB',coreAction:'VIEW'}]}

PUT /attask/api/v15.0/task/4c7.../move?projectID=5d8...

DELETE Behavior

DELETE removes an object. In every case, the URI may include the parameter force=true to cause the server to remove the specified data and its dependants. In the following example, a task is deleted by executing the HTTP DELETE method on a URI:

DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0 
DELETE /attask/api/v15.0/task?id=4c78821c0000d6fa8d5e52f07a1d54d0 
DELETE /attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d0?force=true 
DELETE /attask/api/v15.0/task?id=4c78821c0000d6fa8d5e52f07a1d54d0?force=true

Bulk Updates

A bulk update statement updates multiple objects at the same time within a single API call. A bulk create API call is built similarly to a normal update call, as shown in the following examples:

PUT /attask/api/v15.0/proj?updates=[{"name":"Test_Project_1"},{"name":"Test_Project_2"}]&method=POST&apiKey=123ab-cxxxxxxxxxxxxxxxxxxxxxxxxxx

data: [{
    ID: "53ff8d3d003b438b57a8a784df38f6b3",
    name: "Test_Project_1",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priority: 0,
    projectedCompletionDate: "2014-08-28T16:12:00:000-0400",
    status: "CUR"
},
{
    ID: "53ff8d49003b43a2562aa34eea3b6b10",
    name: "Test_Project_2",
    objCode: "PROJ",
    percentComplete: 0usi,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priority: 0,
    projectedCompletionDate: "2014-08-28T16:12:00:000-0400",
    status: "CUR"
}]

PUT /attask/api/v15.0/proj?Umethod=PUT&updates=[{"ID":"123abcxxxxxxxxxxxxxxxxxxxxxxxxxx","name":"Test_Project_1_ Edit"},{"ID":"123abcxxxxxxxxxxxxxxxxxxxxxxxxxx","name":"Test_Project_2_Edit"}]&apiKey=123abcxxxxxxxxxxxxxxxxxxxxxxxxxx

data: [ {
     ID: "53ff8e15003b461d4560f7f65a440078",
     name: "Test_Project_1_Edit",
     objCode: "PROJ",
     percentComplete: 0,
     plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
     plannedStartDate: "2014-08-28T11:00:00:000-0400",
     priority: 0,
     projectedCompletionDate: "2014-08-28T16:16:00:000-0400",
     status: "CUR"
},
{
    ID: "53ff8e19003b46238a58d303608de502",
    name: "Test_Project_2_Edit",
    objCode: "PROJ",
    percentComplete: 0,
    plannedCompletionDate: "2014-08-28T11:00:00:000-0400",
    plannedStartDate: "2014-08-28T11:00:00:000-0400",
    priority: 0,
    projectedCompletionDate: "2014-08-28T16:16:00:000-0400",
    status: "CUR"
}]

Business.Adobe.com resources