API basics

Last update: Thu Dec 05 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Workfront API

CREATED FOR:

Developer

The goal for the 蜜豆视频 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, the Workfront API limits concurrent API threads. This guardrail prevents system problems caused by abusive API calls. The Sandbox environment has the same concurrent API thread 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鈥檙e 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.

Workfront API URL

For information about the URL that you will use to call the Workfront API, see Domain format for 蜜豆视频 Workfront API calls.

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 objects, valid ObjCodes, and object fields, see聽 API Explorer.

NOTE

In the context of the Workfront API, a custom form is a Category object, and a custom field is a Parameter object.

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

NOTE

When executing a GET request through your browser鈥檚 address bar, it is not necessary to include the sessionID as part of the request.

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 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

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.

NOTE

In order聽to protect against the possibility of CSRF (Cross Site Request Forgery) attacks, this method of authentication is only available for read-only operations.

IMPORTANT

Workfront no longer recommends the use of the /login endpoint or API keys. Instead, use one of the following authentication methods:

Server authentication with JWT
User authentication with OAuth2

For instructions on setting up these authentication methods, see Create OAuth2 applications for Workfront integrations

For instructions on using server authentication in Workfront, see Configure and use your organization鈥檚 custom OAuth 2 applications using JWT flow

For instructions on using user authentication in Workfront, see Configure and use your organization鈥檚 custom OAuth 2 applications using authorization code flow

NOTE

The procedure described in this section applies only to organizations that have not yet been onboarded to the 蜜豆视频 Business Platform. Logging in to Workfront through the Workfront API is not available if your organization has been onboarded to the 蜜豆视频 Business Platform.

For a list of procedures that differ based on whether your organization has been onboarded to the 蜜豆视频 Business Platform, see Platform-based administration differences (蜜豆视频 Workfront/蜜豆视频 Business Platform).

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.

NOTE

If you have a designated API user who is also an administrator, Workfront strongly suggests you use an API Key to log in.

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 鈥渁piKey鈥� 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 鈥渃learApiKey鈥� 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:

Navigate to your login screen, but do not log in.
Change the URL to /attask/api/v15.0/project/search.
Notice the page cannot be found.
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.
Change the URL back to /attask/api/v15.0/project/search.
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.

Modifier

Description

Example

returns results that are in the status of closed

鈥迟补迟耻蝉=肠濒蝉&#虫26;蝉迟补迟耻蝉冲惭辞诲=别辩鈥�

returns results that are not in the status of closed

鈥迟补迟耻蝉=肠濒蝉&#虫26;蝉迟补迟耻蝉冲惭辞诲=苍别鈥�

gte

returns results that have a percent complete greater than聽or equal to 50

鈥别谤肠别苍迟颁辞尘辫濒别迟别=50&#虫26;辫别谤肠别苍迟颁辞尘辫濒别迟别冲惭辞诲=驳迟别鈥�

lte

returns results that have a percent complete less than or equal to 50

鈥别谤肠别苍迟颁辞尘辫濒别迟别=50&#虫26;辫别谤肠别苍迟颁辞尘辫濒别迟别冲惭辞诲=濒迟别鈥�

isnull

returns results where the description is Null

鈥别蝉肠谤颈辫迟颈辞苍冲惭辞诲=颈蝉苍耻濒濒鈥�

notnull

returns results where the description is not Null

鈥别蝉肠谤颈辫迟颈辞苍冲惭辞诲=苍辞迟苍耻濒濒鈥�

contains

returns results where name contains 鈥淲orkfront鈥�

鈥补尘别=奥辞谤办蹿谤辞苍迟&#虫26;苍补尘别冲惭辞诲=肠辞苍迟补颈苍蝉鈥�

between

returns results that have an entry date within the last 7 days

鈥苍迟谤测顿补迟别=$$罢翱顿础驰-7诲&#虫26;别苍迟谤测顿补迟别冲搁补苍驳别=$$罢翱顿础驰&#虫26;别苍迟谤测顿补迟别冲惭辞诲=产别迟飞别别苍鈥�

NOTE

Search requests are case-sensitive. If you receive an error, ensure聽聽 _Mod and _Range have the correct capitalization.

Using OR Statements

You can enhance a search by adding a parameter that includes 鈥淥R鈥� 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鈥檚 filtering criteria. Filters are not implied across OR statement levels.

For example, if you want to filter for

Tasks that have a name containing 鈥淧lanning鈥� OR
Tasks in a portfolio named 鈥淔ixedAssets鈥� AND assigned to someone with a name containing 鈥淪teve鈥� OR
Tasks that have a parent task named 鈥淔inal 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" 
}

NOTE

These field names are case-sensitive.

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 鈥淒E:鈥�. For instance, to request a project with a parameter called 鈥淐ustomText,鈥� 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 `Count`

You can use count to return the number of results that match your query. This can be useful when you don鈥檛 need the data in the results. By returning only the count, the server can process the request more quickly and save 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 鈥減rimary 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.

Query Result

Limitation

Description

Default Number of Results

100

If no limit is specified in the query filter (i.e., $$LIMIT), the result can contain no more than 100 primary objects.
See Using Paginated Responses for instructions on how to override this limitation.

Max Number of Results

2,000

The query filter (i.e., $$LIMIT) can return no more than 2000 results. See "Paginated Responses" for more information.

Max Field Depth

When identifying the fields you wish to display, you cannot go more than four levels away from the object being queried.

Max Number of Objects

50,000

The result set cannot include 50000 primary and secondary objects.

Max Number of Fields

1,000,000

When the result set is fewer than 50000 objects, your results may include at most 1,000,000 fields.

Max Number of Batch Creates/Updates

100

The maximum batch create or update limit is 100.

Using Paginated Responses 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 鈥渁bc123鈥� 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鈥檚 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"
聽聽聽聽聽聽聽聽} 
聽聽聽聽] 
}

NOTE

While updates made to the top level are sparse, updates to a collection or nested object completely replace the existing collection. To edit a single assignment on a task without affecting the objects, use PUT on the assignment rather than on the task.

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

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

NOTE

Atomic batch operations can only return 鈥渟uccess: true鈥� or an error.

recommendation-more-help

5f00cc6b-2202-40d6-bcd0-3ee0c2316b43

蜜豆视频

API basics

Limits and Guidelines

Disclaimer

Workfront API URL

REST Basics

Object URI

Operations

Response

Authentication

Request Header Authentication

Cookie-Based Authentication

Login

Logout

GET Behavior

Retrieving Objects

Retrieving an Object Using the Object ID

Retrieving an Object Using the URI

Using Search Modifiers

Using OR Statements

Using Filter Parameters

Using the Map Request Parameter

Using the Fields Request Parameter

Searching for Nested Objects

Retrieving Nested Collections

Searching for Multiple Nested Fields

Retrieving Custom Data

Using聽Named Queries

Using Count

Requesting a Report

Sorting Query Results in the API

Considering Query Limits

Using Paginated Responses using-paginated-responses

Creating an Access Rule

POST Behavior

Creating an Object

Copying an Object

Uploading Documents

PUT Behavior

Editing Objects

Specifying JSON Edits

Making Nested Updates

Using the Action Request Parameter

Moving Objects

Sharing Objects

DELETE Behavior

Bulk Updates

Using `Count`