Class: Session

Constructor

Construct Session instance with API credentials.

class Session(serverUrl, apiUser, apiKey[, options])
Arguments:
  • serverUrl (string) – ftrack server URL
  • apiUser (string) – ftrack username for API user.
  • apiKey (string) – User API Key
  • options (Object) – options
  • [options.autoConnectEventHub=false] (Boolean) – Automatically connect to event hub.
  • [options.serverInformationValues=[]] (Array) – Optional list of server information values to retrieve.
  • [options.eventHubOptions={}] (Object) – Options to configure event hub with.
  • [options.clientToken=null] (string) – Client identifier included in update events caused by operations performed by this session.

Function call

Call API with array of operation objects in operations.

Returns promise which will be resolved with an array of decoded responses.

The return promise may be rejected with one of several errors:

ServerValidationError
Validation errors
ServerPermissionDeniedError
Permission defined errors
ServerError
Generic server errors or network issues
call(operations)
Arguments:
  • operations (Array) – API operations.

Function getSchema

Return schema with id or null if not existing.

getSchema(schemaId)
Arguments:
  • schemaId (string) – Id of schema model, e.g. AssetVersion.
Return Object|null:
 

Schema definition

Function query

Perform a single query operation with expression.

query(expression)
Arguments:
  • expression (string) – API query expression.
Return Promise:

Promise which will be resolved with an object containing data and metadata.

Function create

Perform a single create operation with type and data.

create(type, data)
Arguments:
  • type (string) – entity type name.
  • data (Object) – data which should be used to populate attributes on the entity.
Return Promise:

Promise which will be resolved with the response.

Function update

Perform a single update operation on type with keys and data.

update(type, keys, data)
Arguments:
  • type (string) – Entity type
  • keys (Array) – Identifying keys, typically [<entity id>]
  • data (Object) – Perform a single update operation on type with keys and data.
Return Promise:

Promise resolved with the response.

Function delete

Perform a single delete operation.

delete(type, keys)
Arguments:
  • type (string) – Entity type
  • keys (Array) – Identifying keys, typically [<entity id>]
Return Promise:

Promise resolved with the response.

Function: ensure

Return promise of entityType with data, create or update if necessary.

data should be a dictionary of the same form passed to create method.

By default, check for an entity that has matching data. If identifyingKeys is specified as a list of keys then only consider the values from data for those keys when searching for existing entity.

If no identifyingKeys specified then use all of the keys from the passed data.

Raise an Error if no identifyingKeys can be determined.

If no matching entity found then create entity using supplied data.

If a matching entity is found, then update it if necessary with data.

Return update or create promise.

ensureensure(entityType, data, identifyingKeys)
Arguments:
  • entityType (string) – Entity type
  • data (Object) – Entity data to create or update
  • identifyingKeys (Array) – Optional list of keys to consider when checking for existing entities.
Return Promise:

Promise resolved with the create or update response.

Function getComponentUrl

Return an URL where componentId can be downloaded.

getComponentUrl(componentId)
Arguments:
  • componentId (string) – Is assumed to be present in the ftrack.server location.
Return String|null:
 

URL where componentId can be downloaded, null if component id is not specified.

Function thumbnailUrl

Return an URL where a thumbnail for componentId can be downloaded.

thumbnailUrl(componentId, options)
Arguments:
  • componentId (string) – Is assumed to be present in the ftrack.server location and be of a valid image file type.
  • options (Object) – optional parameters: size. The size of the thumbnail. The image will be resized to fit within size x size pixels. Defaults to 300.
Return string:

URL where componentId can be downloaded. Returns the URL to a default thumbnail if component id is not specified.

Function createComponent

Create component from file and add to server location.

createComponent(file, options)
Arguments:
  • file (Object) – the file object to upload.
  • options (Object) – optional parameters: onProgress, xhr, onAborted.
Return Promise:

Promise resolved with the response when creating Component and ComponentLocation.