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
, andapi_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 theapi_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.
- method – The HTTP method to use, eg:
-
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.
- path – The path element of the URL for the request, eg:
-
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.
- path – The path element of the URL for the request, eg:
-
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.
- path – The path element of the URL for the request, eg:
-
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.
- path – The path element of the URL for the request, eg:
-
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 thisSession
.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 anapi_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.- object_type – The type of object to search for. Should be obtained
from the
-
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. Ifid_or_ids
is a sequence, a list of objects will be returned.- object_type – The type of object to search for. Should be obtained
from the
-
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 anObject
, it’s value will be returned, or aFieldNotLoaded
exception will be raised if it has not yet been loaded.When set, a
Field
will store its value in theObject
, to save values back to Workfront, useObject.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 anObject
, a referenced object orNone
, 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 theid
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 anObject
, atuple
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()
orworkfront.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.