API Reference

class workfront.Session(domain, api_key=None, ssl_context=None, protocol='https', api_version='unsupported', url_template='{protocol}://{domain}.attask-ondemand.com/attask/api/{api_version}')

A session for communicating with the Workfront REST API.

Parameters:
  • domain – Your Workfront domain name.
  • api_key – An optional API key to pass with requests made using this session.
  • ssl_context – An optional SSLContext to use when communicating with Workfront via SSL.
  • protocol – The protocol to use, defaults to https.
  • api_version – The version of the Workfront API to use, defaults to unsupported, which is the newest available.
  • url_template – The template for Workfront URLs into which domain, protocol, and api_version will be interpolated.

Warning

ssl_context will result in exceptions being raised when used under Python 3.4, support exists in Python 2.7 and Python 3.5 onwards.

session_id = None

The session identifier if using session-base authentication.

user_id = None

The UUID of the user if using session-base authentication.

api = None

The APIVersion for the api_version specified.

request(method, path, params=None)

The lowest level method for making a request to the Workfront REST API. You should only need to use this if you need a method that isn’t supported below.

Parameters:
  • method – The HTTP method to use, eg: GET, POST, PUT.
  • path – The path element of the URL for the request, eg: /user.
  • params – A dict of parameters to include in the request.
Returns:

The JSON-decoded data element of the response from Workfront.
get(path, params=None)

Perform a method=GET request to the Workfront REST API.

Parameters:
  • path – The path element of the URL for the request, eg: /user.
  • params – A dict of parameters to include in the request.
Returns:

The JSON-decoded data element of the response from Workfront.
post(path, params=None)

Perform a method=POST request to the Workfront REST API.

Parameters:
  • path – The path element of the URL for the request, eg: /user.
  • params – A dict of parameters to include in the request.
Returns:

The JSON-decoded data element of the response from Workfront.
put(path, params=None)

Perform a method=PUT request to the Workfront REST API.

Parameters:
  • path – The path element of the URL for the request, eg: /user.
  • params – A dict of parameters to include in the request.
Returns:

The JSON-decoded data element of the response from Workfront.
delete(path, params=None)

Perform a method=DELETE request to the Workfront REST API.

Parameters:
  • path – The path element of the URL for the request, eg: /user.
  • params – A dict of parameters to include in the request.
Returns:

The JSON-decoded data element of the response from Workfront.
login(username, password)

Start an ID-based session using the supplied username and password. The resulting sessionID will be passed for all subsequence requests using this Session.

The session user’s UUID will be stored in Session.user_id.

logout()

End the current ID-based session.

get_api_key(username, password)

Return the API key for the user with the username and password supplied.

Warning

If the Session is created with an api_key, then that key may always be returned, no matter what username or password are provided.

search(object_type, fields=None, **parameters)

Search for Object instances of the specified type.

Parameters:
  • object_type – The type of object to search for. Should be obtained from the Session.api.
  • fields – Additional fields to load() on the returned objects. Nested Object field specifications are supported.
  • parameters – The search parameters. See the Workfront documentation for full details.
Returns:

A list of objects of the object_type specified.
load(object_type, id_or_ids, fields=None)

Load one or more Object instances by their UUID.

Parameters:
  • object_type – The type of object to search for. Should be obtained from the Session.api.
  • id_or_ids – A string, when a single object is to be loaded, or a sequence of strings when multiple objects are to be loaded.
  • fields – The fields to load() on each object returned. If not specified, the default fields for that object type will be loaded.
Returns:

If a single id is specified, the loaded object will be returned. If id_or_ids is a sequence, a list of objects will be returned.
workfront.session.ONDEMAND_TEMPLATE = '{protocol}://{domain}.attask-ondemand.com/attask/api/{api_version}'

The default URL template used when creating a Session.

workfront.session.SANDBOX_TEMPLATE = '{protocol}://{domain}.attasksandbox.com/attask/api/{api_version}'

An alternate URL template that can be used when creating a Session to the Workfront Sandbox.

exception workfront.session.WorkfrontAPIError(data, code)

An exception indicating that an error has been returned by Workfront, either in the form of the error key being provided in the JSON response, or a non-200 HTTP status code being sent.

code = None

The HTTP response code returned by Workfront.

data = None

The error returned in the response from Workfront, decoded from JSON if possible, a string otherwise.

class workfront.meta.APIVersion(version)

Receptacle for classes for a specific API version. The classes can be obtained from the APIVersion instance by attribute, eg:

session = Session(...)
api = session.api
issue = api.Issue(session, ...)

To find the name of a class your require, consult the Module Index or use the Search Page in conjunction with the API Explorer.

exception workfront.meta.FieldNotLoaded

Exception raised when a field is accessed but has not been loaded.

class workfront.meta.Field(workfront_name)

The descriptor used for mapping Workfront fields to attributes of an Object.

When a Field is obtained from an Object, it’s value will be returned, or a FieldNotLoaded exception will be raised if it has not yet been loaded.

When set, a Field will store its value in the Object, to save values back to Workfront, use Object.save().

class workfront.meta.Reference(workfront_name)

The descriptor used for mapping Workfront references to attributes of an Object.

When a Reference is obtained from an Object, a referenced object or None, if there is no referenced object in this field, will be returned. If the referenced object has not yet been loaded, it will be loaded before being returned.

A Reference cannot be set, you should instead set the matching _id Field to the id of the object you wish to reference.

class workfront.meta.Collection(workfront_name)

The descriptor used for mapping Workfront collections to attributes of an Object.

When a Collection is obtained from an Object, a tuple of objects, which may be empty, is returned. If the collection has not yet been loaded, it will be loaded before being returned.

A Collection cannot be set or modified.

class workfront.meta.Object(session=None, **fields)

The base class for objects reflected from the Workfront REST API.

Objects can be instantiated and then saved in order to create new objects, or retrieved from Workfront using workfront.Session.search() or workfront.Session.load().

Wherever fields are mentioned, they may be specified as either Workfront-style camel case names, or the Python-style attribute names they are mapped to.

id

The UUID of this object in Workfront. It will be None if this object has not yet been saved to Workfront.

api_url()

The URI of this object in Workfront, suitable for passing to any of the Session methods that generate requests.

This method cannot be used until the object has been saved to Workfront.

load(*field_names)

Load additional fields for this object from Workfront.

Parameters:field_names – Either Workfront-style camel case names or the Python-style attribute names they are mapped to for the fields to be loaded.
save()

If this object has not yet been saved to Workfront, create it using all the current fields that have been set.

In other cases, save only the fields that have changed on this object to Workfront.

delete()

Delete this object from Workfront.

API versions

The versions listed have been reflected from the relevant Workfront API metadata. The documentation below primarily gives the mapping betwen the API name and the pythonic name. The API Explorer may be an easier way to find the things.