We ended support for API2 with the release of Shotgun 2.0, and with it, all remaining support for sg_system_task_type field on Tasks. One of the consequences of this change is that scripts relying on sg_system_task_type must be modified to work with Pipeline Steps. This guide includes some basic examples of the most common use cases.

Differences between sg_system_task_type and Steps

sg_system_task_type could be treated as a simple text field.

data = {
"content": "Some Task",
"sg_system_task_type": "Art"
}
task = sg.create("Task", data)

Pipeline Step must be treated as an entity field.

So you'll always need to pass in the 'id' key in your api calls. You can query Steps to find out these id's.

data = {
"content": "Some Task",
"step": {"type": "Step", "id": 9}
}
# The 'Art' Step has an id of 9
# Notice the key 'step' is in lowercase, but its 'type' key is 'Step'
task = sg.create("Task", data)

The back-story on sg_system_task_type

Task Type (sg_system_task_type) was a list field that had a special relationship with certain entities - like Assets, Elements, Shots, Scenes, and Sequences. But because this relationship pivoted on specific entities, as opposed to any entity, it was too brittle to scale. There was additionally the problem of Task Status summaries. Because Task status summaries were summarized on the Task Type field, the server would have to constantly recalculate them as Task Type values changed - which sometimes, under rare but reproducible race conditions, resulted in miscalculations. Lastly, reconfiguring Task Type with new values, or eliminating existing values would necessitate an extremely long system-wide recalculation of summaries. For clients with large amounts of scheduling data, this process was unreasonably onerous.

* Note: Up until 2.0, we supported the use of sg_system_task_type in api calls by handling the mapping of Task Types to Steps in the background. This is no longer the case.

Why we came up with Pipeline Steps

The main benefit of Steps lies in their flexibility to work with any entity type, while providing all the functionality of sg_system_task_type, and none of the background processing overhead associated with task status summaries and field reconfiguration. Pipeline Step is an entity field on Task that points to a 'Step' entity. Here's how it works:

A Step is an entity that has an entity_type field that points to 1 enabled entity type (eg: Asset, Shot, Element, even a Custom entity type)
Creating an ordered set of 1 or more Steps for 1 entity type defines the pipeline for that entity type
You can easily reconfigure Step names and short codes without triggering any long-running server processes
Even delete and undelete Steps - just like you would with other entities

sg.find()

Filtering for Tasks that have particular Step values - instead of sg_system_task_type values.

Using sg_system_task_type

filters = [["sg_system_task_type","is", 'Art']]
tasks = sg.find("Task", filters)
pprint (tasks)

This will return this error…

XMLRPC Fault 103:
API read() Task.sg_system_task_type doesn't exist:
{"relation"=>"is", "values"=>["Art"], "path"=>"sg_system_task_type"}

Using Steps (the correct way)

filters = [["Step", "is", {"type":"Step", "id": 9}]]
# Where 'Art' is the Step entity with id 9

tasks = sg.find("Task", filters)
pprint (tasks)

sg.create()

Creating a Task, and setting the Pipeline Step equivalent of sg_system_task_type.

Using sg_system_task_type

data = {
'content': "Surfacing",
'project': {"type": "Project", "id": 64},
'sg_system_task_type': "Art"
}

task = sg.create("Task", data)
pprint (task)

This will return this error…

XMLRPC Fault 103:
API create() Task.sg_system_task_type doesn't exist:
{"value"=>"Art", "field_name"=>"sg_system_task_type"}

Using Steps (the correct way)

data = {
'content': "Surfacing]",
'project': {"type": "Project", "id":64},
'step': {"type": "Step", "id": 9}
}
# Notice the similarity between the 'project' and 'step' keys

task = sg.create("Task", data)
pprint (task)

sg.update()

Editing a Task's Pipeline Step, changing it from 'Art' to 'Model'.

Using sg_system_task_type

#The task id we'll update
id = 7065
data = {
'sg_system_task_type': "Model"
}

task = sg.update("Task", id, data)
pprint (task)

This will return this error…

XMLRPC Fault 103:
API create() Task.sg_system_task_type doesn't exist:
{"value"=>"Model", "field_name"=>"sg_system_task_type"}

Using Pipeline Step (the correct way)

#The task id we'll update
id = 7065
data = {
'step': {"type": "Step", "id": 10}
}
# Where the 'Model' step has an id of 10

task = sg.update("Task", id, data)
pprint (task)

Querying Steps

In some cases, your scripts will need to query for the particular Step Id's that they'll need. This can be done using the Step's entity_type field - which corresponds to the CamelCase name of a particular entity type (eg: Asset).

Getting a list of all Asset Pipeline Steps

fields = ["code","entity_type"]
filters = [["entity_type", "is", "Asset"]]
steps = sg.find("Step", filters, fields)
pprint (steps)

This prints the following

[{'code': 'Art', 'entity_type': 'Asset', 'id': 9, 'type': 'Step'},
{'code': 'Model', 'entity_type': 'Asset', 'id': 10, 'type': 'Step'},
{'code': 'Rig', 'entity_type': 'Asset', 'id': 11, 'type': 'Step'},
{'code': 'Surface', 'entity_type': 'Asset', 'id': 12, 'type': 'Step'},
{'code': 'Canvas Step', 'entity_type': 'Asset', 'id': 13, 'type': 'Step'},
{'code': 'Client', 'entity_type': 'Asset', 'id': 14, 'type': 'Step'}]

Or, we could get ALL Steps for ALL entities

fields = ["code","entity_type"]
steps = sg.find("Step", [], fields)
pprint (steps)

This prints out something like this

[{'code': 'Client', 'entity_type': 'Shot', 'id': 1, 'type': 'Step'},
{'code': 'Online', 'entity_type': 'Shot', 'id': 2, 'type': 'Step'},
{'code': 'Roto', 'entity_type': 'Shot', 'id': 3, 'type': 'Step'},
{'code': 'MM', 'entity_type': 'Shot', 'id': 4, 'type': 'Step'},
{'code': 'Anm', 'entity_type': 'Shot', 'id': 5, 'type': 'Step'},
{'code': 'FX', 'entity_type': 'Shot', 'id': 6, 'type': 'Step'},
{'code': 'Light', 'entity_type': 'Shot', 'id': 7, 'type': 'Step'},
{'code': 'Comp', 'entity_type': 'Shot', 'id': 8, 'type': 'Step'},
{'code': 'Art', 'entity_type': 'Asset', 'id': 9, 'type': 'Step'},
{'code': 'Model', 'entity_type': 'Asset', 'id': 10, 'type': 'Step'},
{'code': 'Rig', 'entity_type': 'Asset', 'id': 11, 'type': 'Step'},
{'code': 'Surface', 'entity_type': 'Asset', 'id': 12, 'type': 'Step'},
{'code': 'Canvas Step', 'entity_type': 'Asset', 'id': 13, 'type': 'Step'},
{'code': 'Client', 'entity_type': 'Asset', 'id': 14, 'type': 'Step'}]

Step fields

The main fields on Steps your scripts will most likely work with are: code, entity_type, and id. Below is a list of all Step fields in this format:

Field Name (field type)
internal_field_name

Pipeline Step (text)
code
Updated by (entity) updated_by
Short Code (text) short_name
Order (number) list_order
Color (color) color
Date Created (date_time) created_at
Entity Type (text) entity_type
Date Updated (date_time) updated_at
Created By (entity) created_by
Id (number) id
Description (text) description

Questions?
Ask a question right here in the comments, create a new topic in our forum, or shoot us an email at support@shotgunsoftware.com. We're listening on all channels and will get right back to you.

History

7/7/2010: Doc published

Using Steps vs sg_system_task_type in your Scripts

Differences between sg_system_task_type and Steps

sg.find()

sg.create()

sg.update()

Querying Steps

Step fields

0 comments