Python¶
The Python API can be used to access information contained in the NIM database. Python requests can be made to read information from the database, create new data, update existing data, and delete entries from the database. All requests responses are received in the form of JavaScript Object Notation (JSON) formatted objects if successful, and either text explaining the error or a value of FALSE.
API Example¶
The following example displays how the NIM API can be used by render farm managers that support script integration. The python code below uses the NIM API to add a render, log elements, and upload a daily to a known task ID:
import nim_core.nim_api as nimAPI
result = nimAPI.add_render(taskID=14941, renderName='myRender')
if result['success'] == 'true':
nimAPI.upload_renderIcon(renderID=result['ID'],img='/path/to/icon.jpeg')
nimAPI.upload_reviewItem(renderID=result['ID'],path='/path/to/movie/myImages.mov',submit=0)
nimAPI.add_element( parent='render', parentID=result['ID'], path='/path/to/frames', name='myImage.####.exr', \
startFrame=1, endFrame=128, handles=12, isPublished=False )
nimAPI.add_element( parent='render', parentID=result['ID'], path='/path/to/frames', name='myImage_matte.####.exr', \
startFrame=1, endFrame=128, handles=12, isPublished=False )
API Keys¶
NIM API keys are an optional security feature that restricts API access with time limited per user keys. Requiring API keys restricts all API access to only those users with an API key. If the user is not authenticated, the API will return an error message.
If Require API Keys is enabled in ADMIN/Security - Options, two HTTP headers are expected by the API:
X-NIM-API-USER |
This is the users username |
X-NIM-API-KEY |
This is the users API key |
In the Python API, this is managed by the connect() function which handles communication to the VM through HTTP/HTTPS.
Note
By default, the connect() function reads the user’s NIM URL and username from the NIM preferences file and API key stored in the ~/.nim directory. The NIM API URL, NIM username, and user API key used for any request can be overrode using the nimURL, apiUser, and apiKey parameters respectively. Passing these values to the connect() function to authenticate the user will bypass the reading of the user’s NIM preferences. The functions in the python API provide parameters to pass the NIM URL, NIM username, and API key to the connect() function.
The end users will be presented with a dialog box the first time they attempt to use a NIM Connector. API keys are unique to each user. Enter the NIM API key provided to you by your NIM administrator.
Note
It is recommended to ensure that all traffic is using HTTPS when enabling API keys to encrypt all communication. For more information on routing the NIM VM traffic please refer to the nim-ssl script in the Virtual Machine Shell Scripts section of the documentation.
For more information on enabling NIM API Keys please refer to the API Keys section of the documentation. For information on creating user API keys please refer to the Users Grid section of the Administration documentation.
API Common Functions¶
Test API¶
Used to test connectivity to the NIM API
def testAPI(nimURL=None, nim_apiUser='', nim_apiKey='')
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL The url to access the NIM API string YES
nim_apiUser The username of the NIM user string
nim_apiKey THe API key of the NIM user string
Return:
example: [{"version":"2.5.15.161123","keyValid":"false","keyRequired":"false","error":""}]
version - The current NIM version
keyValid - Is the API key valid
keyRequired - Is Require API Keys enabled
error - Any additional error messages
Get Connect Info¶
Returns the connection information stored in preferences
def get_connect_info()
Return:
type: dictionary
values:
nim_apiURL - The URL to the NIM API
nim_apiUser - The NIM username of the person accessing the API
nim_apiKey - The NIM API key of the person accessing the API
Get API Key¶
Retrieves the API key from the users ~/.nim/nim.key file
def get_apiKey()
Return:
type: string
Connect¶
Wrapper function used by Python API functions to connect to the NIM Web API
def connect( method='get', params=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
method Connection method string get, post get YES
params Array containing the API query array YES
param['q'] The NIM Web API query string YES
Example:
params = {}
params['q'] = 'getShots'
params['showID'] = '100'
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
example: [{"version":"2.5.15.161123","keyValid":"false","keyRequired":"false","error":""}]
Upload¶
Wrapper function used by Python API commands that require a file to be uploaded to the NIM Web API
To upload a file params[‘file’] must be passed a file using open(myFile,’rb’)
def upload( params=None, nimURL=None, apiUser=None, apiKey=None)
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
params Array containing the API query array YES
params['q'] The NIM Web API query string YES
Example:
params = {}
params['q'] = 'uploadDailiesNote'
params['dailiesID'] = '100'
params['name'] = 'note name'
params['file'] = open(imageFile,'rb')
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
type: boolean
values:
True - The upload was successful
False - The upload failed. ( Error messages will be printed. )
Get Culture Codes¶
Retrieves a list of currency codes used for setting the currency type of an item
def get_cultureCodes(nimURL=None, apiUser=None, apiKey=None)
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
example: {"success":true,"error":"","rows":[{"cultureCode":"en-US","currency":"United States Dollar","currencyCode":"USD"},{"cultureCode":"en-IE","currency":"Euro (Ireland)","currencyCode":"EUR"},...,"totalRows":44}
Returns json as an associative array in the format
result->success True/False
result->error Includes any error or security messaging
result->rows An array of returned data
result->totalRows The total count of returned rows in the array
Users¶
Get User ID¶
Retrieves the current user's ID
def get_userID( user='', nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
user The username to retrieve the ID integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
int
Get All Users¶
Returns the full list of NIM Users
def get_userList( nimURL=None, apiUser=None, apiKey=None )
Parameters Type Description
_____________________________________________________________________________________________________________________________________________
Optional:
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
dictionary
Locations¶
Get All Locations¶
Retrieves all defined locations
def get_locations( nimURL=None, apiUser=None, apiKey=None )
Parameters Type Description
_____________________________________________________________________________________________________________________________________________
Optional:
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
List of locations in the format:
{
ID
name
description
}
Contacts¶
Get Contacts¶
Get Contacts based on search parameters. Query will return all contacts the requesting user has access to.
Note
This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.
def get_contacts( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_____________________________________________________________________________________________________________________________________________
Optional:
ID integer The ID of a contact item to query
first_name string Will return all contact items matching the first name
last_name string Will return all contact items matching the last name
email string Will return all contact items matching the email
title string Will return all contact items matching the title
company string Will return all contact items matching the company name
website string Will return all contact items matching the website
work_phone string Will return all contact items matching the work phone number
work_fax string Will return all contact items matching the work fax number
mobile_phone string Will return all contact items matching the mobile phone number
home_phone string Will return all contact items matching the home phone number
address1 string Will return all contact items matching the address1 field
address2 string Will return all contact items matching the address2 field
city string Will return all contact items matching the city
state string Will return all contact items matching the state
zip string Will return all contact items matching the zip
description string Will return all contact items partially matching the description
keywords string A comma separated list of keywords
Will return all contact items matching the keywords
groups string A comma separated list of groups
Will return all contact items matching the groups
customKeys dictionary A dictionary of custom field names and values
Will return all contact items matching the custom field value
limit integer Specifies the maximum number of rows to return
Default 0 (no limit)
offset integer Specifies the number of rows to skip before starting to return rows.
Default 0
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
result->total_count The total number of rows that match the search criteria
result->data An array of returned data
Add Contact¶
Creates a new contact in NIM
Note
add_contact( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Optional:
is_company bool 0/1
first_name string The first name of the contact
last_name string The last name of the contact
email string The email of the contact
title string The title of the contact
company string The company name for the contact
website string The website of the contact
work_phone string The work phone number of the contact
work_fax string The fax number of the contact
mobile_phone string The mobile phone number of the contact
home_phone string The home phone number of the contact
address1 string The first address line of the contact
address2 string The second address line of the contact
city string The city for the contact
state string The state for the contact
zip string The zip code for the contact
description string The description for the contact
keywords string Format ["keyword1","keyword2"]
groups string Format ["group1","group2"]
contact_link_IDs string Format 1,2,3 - a comma separated list of contact IDs
Will replace all linked contacts for this contact
customKeys dictionary A dictionary of custom field names and values
{"My Custom Key Name":"Some text"}
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
result->ID The ID of the newly created item
Update A Contact¶
Update an existing contact by ID If an optional field is not passed, the value for that field will remain unchanged.
Note
update_contact( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
ID integer The ID of the contact to update
Optional:
first_name string The first name of the contact
last_name string The last name of the contact
email string The email of the contact
title string The title of the contact
company string The company name for the contact
website string The website of the contact
work_phone string The work phone number of the contact
work_fax string The fax number of the contact
mobile_phone string The mobile phone number of the contact
home_phone string The home phone number of the contact
address1 string The first address line of the contact
address2 string The second address line of the contact
city string The city for the contact
state string The state for the contact
zip string The zip code for the contact
description string The description for the contact
keywords string Format ["keyword1","keyword2"]
groups string Format ["group1","group2"]
contact_link_IDs string Format 1,2,3 - a comma separated list of contact IDs
Will replace all linked contacts for this contact
customKeys dictionary A dictionary of custom field names and values
{"My Custom Key Name":"Some text"}
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
Delete A Contact¶
Delete an existing contact by ID
delete_contact( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
ID integer The ID of the contact to delete
Optional:
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
Schedule Events¶
Get Schedule Events¶
Get Schedule Events based on search parameters
Note
This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.
def get_scheduleEvents( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
none Will return all schedule events the requesting user has access to
Optional:
ID integer The ID of a schedule event to query
title string Will return all schedule events matching the title
description string Will return all schedule events partially matching the description
statusName string Will return all schedule events matching the statusName
locationName string Will return all schedule events matching the locationName
jobName string Will return all schedule events matching the jobName
jobNumber string Will return all schedule events matching the jobNumber
userIDs string Will return all schedule events matching the userIDs (comma separated list of IDs)
users string Will return all schedule events matching the users (comma separated list of names)
resourceIDs string Will return all schedule events matching the resourceIDs (comma separated list of IDs)
resources string Will return all schedule events matching the resources (comma separated list of names)
start datetime Will return all schedule events matching the start
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
end datetime Will return all schedule events matching the end
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
startRange datetime Will return all schedule events (and event recurrences) AFTER the startRange
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
endRange datetime Will return all schedule events (and event recurrences) BEFORE the endRange
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
startTimezone string Will return all schedule events matching the startTimezone
endTimezone string Will return all schedule events matching the endTimezone
isAllDay bool Will return all schedule events matching the isAllDay (0/1)
recurrenceId integer Will return all schedule events matching the recurrenceId
recurrenceRule string Will return all schedule events matching the recurrenceRule
recurrenceException string Will return all schedule events matching the recurrenceException
userUtilizationTypeID integer Will return all schedule events matching the userUtilizationTypeID
userUtilizationType string Will return all schedule events matching the userUtilizationType
userUtilizationValue string Will return all schedule events matching the userUtilizationValue
resourceUtilizationTypeID integer Will return all schedule events matching the resourceUtilizationTypeID
resourceUtilizationType string Will return all schedule events matching the resourceUtilizationType
resourceUtilizationValue string Will return all schedule events matching the resourceUtilizationValue
limit integer Specifies the maximum number of rows to return
Default 0 (no limit)
offset integer Specifies the number of rows to skip before starting to return rows.
Default 0
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns an associative array in the format
result->success True/False
result->error Includes any error or security messaging
result->total_count The total number of rows that match the search criteria
result->data An array of returned data
Notes:
yyyy: 4-digit year (2024)
mm: 2-digit month (07 for July)
dd: 2-digit day of the month (10)
T: A delimiter separating the date and time components
hh: 2-digit hour in 24-hour format (07)
mm: 2-digit minutes (00)
ss: 2-digit seconds (00)
.sss: Milliseconds (000), representing fractions of a second
Z: Indicates that the time is in Coordinated Universal Time (UTC)
Examples:
https://hostname:portnumber/nimAPI.php?q=getScheduleEvents&title=MyEvent
Examples of valid datetime strings:
2024-07-10T07:00:00.000Z
Represents July 10, 2024, 7:00:00 AM UTC
2024-07-10 07:00:00.000 America/Los_Angeles
Represents July 10, 2024, 7:00:00 AM in the America/Los_Angeles timezone
Add Schedule Event¶
Creates a new event on the schedule.
Note
def add_scheduleEvent( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
start datetime Date if isAllDay = 1; datetime otherwise
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
end datetime Date if isAllDay = 1; datetime otherwise
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
At least one of:
jobID integer A job ID to associate with the event
userIDs string Comma-separated list of user IDs
resourceIDs string Comma-separated list of resource IDs
Optional:
title string The title of the event
description string The description of the event
statusID integer The ID of the status to associate with the event
statusName string The name of the status to associate with the event
locationID integer The ID of the location to associate with the event
jobID integer The ID of the job to associate with the event
userIDs string Comma-separated list of user IDs
resourceIDs string Comma-separated list of resource IDs
startTimezone string A valid timezone identifier; example: America/Los_Angeles
endTimezone string A valid timezone identifier; example: America/Los_Angeles
isAllDay bool 0 or 1
recurrenceId integer ID of this schedule event's parent; this should only exist if this event is an EXCEPTION to a recurring event's ruleset
recurrenceRule string Recurring event ruleset string; see https://datatracker.ietf.org/doc/html/rfc5545
recurrenceException string A list of comma-separated start datetimes for all exceptions to this recurring event's rules
userUtilizationTypeID integer The ID of the user utilization type to associate with the event
userUtilizationType string The name of the user utilization type to associate with the event
Possible values are: "hours per day", "percent per day", "total hours"
userUtilizationValue string The value of the user utilization type to associate with the event
resourceUtilizationTypeID integer The ID of the resource utilization type to associate with the event
resourceUtilizationType string The name of the resource utilization type to associate with the event
Possible values are: "units per day", "percent per day"
resourceUtilizationValue string The value of the resource utilization type to associate with the event
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
result->ID The ID of the newly created item
Update Schedule Event¶
Updates an existing schedule event by ID
Note
def update_scheduleEvent( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
ID integer The ID of the schedule event to update
Optional:
title string The title of the event
description string The description of the event
statusID integer The ID of the status to associate with the event
statusName string The name of the status to associate with the event
locationID integer The ID of the location to associate with the event
jobID integer The ID of the job to associate with the event
userIDs string Comma-separated list of user IDs
resourceIDs string Comma-separated list of resource IDs
start datetime Date if isAllDay = 1; datetime otherwise
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
end datetime Date if isAllDay = 1; datetime otherwise
(yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone)
startTimezone string A valid timezone identifier; example: America/Los_Angeles
endTimezone string A valid timezone identifier; example: America/Los_Angeles
isAllDay bool 0 or 1
recurrenceId integer ID of this schedule event's parent; this should only exist if this event is an EXCEPTION to a recurring event's ruleset
recurrenceRule string Recurring event ruleset string; see https://datatracker.ietf.org/doc/html/rfc5545
recurrenceException string A list of comma-separated start datetimes for all exceptions to this recurring event's rules
userUtilizationTypeID integer The ID of the user utilization type to associate with the event
userUtilizationType string The name of the user utilization type to associate with the event
Possible values are: "hours per day", "percent per day", "total hours"
userUtilizationValue string The value of the user utilization type to associate with the event
resourceUtilizationTypeID integer The ID of the resource utilization type to associate with the event
resourceUtilizationType string The name of the resource utilization type to associate with the event
Possible values are: "units per day", "percent per day"
resourceUtilizationValue string The value of the resource utilization type to associate with the event
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
Delete A Schedule Event¶
Deletes an existing event from the schedule.
def delete_scheduleEvent( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters need to be passed as keyword arguments
Example:
update_scheduleEvent( ID=3391, statusName='1st Hold' )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
ID integer The ID of the schedule event to delete
Optional:
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
Get Schedule Event Statuses¶
Get all schedule event statuses.
def get_scheduleEventStatuses( nimURL=None, apiUser=None, apiKey=None )
Parameters need to be passed as keyword arguments
Example:
get_scheduleEventStatuses()
Parameters Type Description
_________________________________________________________________________________________________________________________________
Optional:
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns an associative array in the format
result->success True/False
result->error Includes any error or security messaging
Resources¶
Get Resources¶
Get Resources based on search parameters. The query will return all resources the requesting user has access to.
Note
This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.
def get_resources( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
none Will return all resources the requesting user has access to
Optional:
ID integer The ID of a resource to query
name string Will return all resources matching the name
description string Will return all resources partially matching the description
color string Will return all resources matching the color
locationID integer Will return all resources matching the location ID
locationName string Will return all resources matching the locationName
keywordIDs string Will return all resources matching the keywordIDs (comma separated list of IDs)
keywords string Will return all resources matching the keywords (comma separated list of names)
resourceGroupIDs string Will return all resources matching the resourceGroupIDs (comma separated list of IDs)
resourceGroups string Will return all resources matching the resourceGroups (comma separated list of names)
limit integer Specifies the maximum number of rows to return
Default 0 (no limit)
offset integer Specifies the number of rows to skip before starting to return rows.
Default 0
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
result->total_count The total number of rows that match the search criteria
result->data An array of returned data
Add A Resource¶
Creates a new resource in NIM
Note
def add_resource( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
name string The resource name
Optional:
description string The resource description
color string The resource color
locationID integer The location ID
keywords string Comma-separated list of keywords
keywordIDs string Comma-separated list of keyword IDs
resourceGroups string Comma-separated list of resource groups
resourceGroupIDs string Comma-separated list of resource group IDs
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
result->ID The ID of the newly created item
Update A Resource¶
Updates an existing resource based on the resource ID
Note
def update_resource( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
ID integer The ID of the resource to update
Optional:
name string The resource name
description string The resource description
color string The resource color
locationID integer The location ID
keywords string Comma-separated list of keywords
keywordIDs string Comma-separated list of keyword IDs
resourceGroups string Comma-separated list of resource groups
resourceGroupIDs string Comma-separated list of resource group IDs
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
Delete A Resource¶
Deletes an existing resource based on the resource ID
def delete_resource( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
ID integer The ID of the resource to delete
Optional:
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
Jobs¶
Get User Jobs¶
Builds a dictionary of all jobs for a given user
def get_jobs( userID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
userID The users ID integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Get Crew¶
Returns an array of users for the crew of the corresponding job(s)
Note
This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.
def get_crew( jobID=None, getData=None, limit=None, offset=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Required:
jobID string single ID or comma separated list of IDs
Optional:
getData 0 / 1 0 or not included - only returns IDs
1 - returns full data for items
limit integer Specifies the maximum number of rows to return
Default 0 (no limit)
offset integer Specifies the number of rows to skip before starting to return rows.
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return:
Returns a dictionary in the format
result->success True/False
result->error Includes any error or security messaging
result->total_count The total number of rows without the LIMIT
result->data An array of the data requested
- job_id
- crew
- user_id
- first_name
- last_name
- email
Add Job¶
Creates a new job.
If no default job number template is set, either number or numberTemplate must be included.
def add_job( name=None, number=None, numberTemplate=None, description=None, client_details=None, agency=None, producer=None, agency_producer=None, \
phone=None, email=None, prod_co=None, prod_director=None, prod_contact=None, prod_phone=None, prod_email=None, \
prod_shoot_date=None, prod_location=None, prod_supervised=None, editorial=None, editor=None, grading=None, colorist=None, \
music=None, mix=None, sound=None, creative_lead=None, projectStatus=None, folder=None, projectStructureID=None, projectStructure=None, \
jobStatusID=None, jobStatus=None, biddingLocationID=None, biddingLocation=None, \
assignedLocationID=None, assignedLocation=None, startDate=None, endDate=None, currency=None, cultureID=None, customKeys=None, \
contactIDs=None, nimURL=None, apiUser=None, apiKey=None)
Parameters Type Values Default Required
________________________________________________________________________________________________
name string YES
number string
numberTemplate string
description string
client_details string
agency string
producer string
agency_producer string
phone string
email string
prod_co string
prod_director string
prod_contact string
prod_phone string
prod_email string
prod_shoot_date date YYYY-mm-dd
prod_location string
prod_supervised boolean 0/1 0
editorial string
editor string
grading string
colorist string
music string
mix string
sound string
creative_lead string
projectStatus string ACTIVE / INACTIVE ACTIVE
Providing a "projectStatus" will override any job status associated activity status.
folder string
projectStructureID OR projectStructure
projectStructureID integer
projectStructure string
jobStatusID OR jobStatus Including the job status will set the project status based on the associated activity status.
jobStatusID integer
jobStatus string
biddingLocationID OR biddingLocation
biddingLocationID integer
biddingLocation string
assignedLocationID OR assignedLocation
assignedLocationID integer
assignedLocation string
start_date date YYYY-mm-dd
end_date date YYYY-mm-dd
currency string 3 digit currency code DEPRECATED
cultureID should be used instead of currency
If currency is set instead of cultureID, NIM will use the first matching cultureID
cultureID integer The ID of the currency culture to use for the job
contactIDs string A comma separated list of contact IDs to link to the job
Example: 1,2,3
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Update Job¶
Updates an existing job based on the jobID.
- The following values will only be updated if the job is offline:
folder projectStructureID projectStructure
def update_job( jobID=None, name=None, number=None, description=None, client_details=None, agency=None, producer=None, agency_producer=None, \
phone=None, email=None, prod_co=None, prod_director=None, prod_contact=None, prod_phone=None, prod_email=None, \
prod_shoot_date=None, prod_location=None, prod_supervised=None, editorial=None, editor=None, grading=None, colorist=None, \
music=None, mix=None, sound=None, creative_lead=None, projectStatus=None, folder=None, projectStructureID=None, projectStructure=None, \
jobStatusID=None, jobStatus=None, biddingLocationID=None, biddingLocation=None, \
assignedLocationID=None, assignedLocation=None, startDate=None, endDate=None, currency=None, cultureID=None, customKeys=None, \
contactIDs=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string
number string
description string
client_details string
agency string
producer string
agency_producer string
phone string
email string
prod_co string
prod_director string
prod_contact string
prod_phone string
prod_email string
prod_shoot_date string YYYY-mm-dd
prod_location string
prod_supervised boolean 0 / 1 0
editorial string
editor string
grading string
colorist string
music string
mix string
sound string
creative_lead string
projectStatus string ACTIVE / INACTIVE ACTIVE
Providing a "projectStatus" will override any job status associated activity status.
folder string
projectStructureID OR projectStructure
projectStructureID integer
projectStructure string
jobStatusID OR jobStatus Including the job status will set the project status based on the associated activity status.
jobStatusID integer
jobStatus string
biddingLocationID OR biddingLocation
biddingLocationID integer
biddingLocation string
assignedLocationID OR assignedLocation
assignedLocationID integer
assignedLocation string
start_date date YYYY-mm-dd
end_date date YYYY-mm-dd
currency string 3 digit currency code DEPRECATED
cultureID should be used instead of currency
If currency is set instead of cultureID, NIM will use the first matching cultureID
cultureID integer The ID of the currency culture to use for the job
contactIDs string A comma separated list of contact IDs to link to the job
Example: 1,2,3
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Delete Job¶
Deletes a job based on jobID.
This is a soft delete and these jobs can be recovered or permanently deleted from the Admin UI.
def delete_job( jobID=None, nimURL=None, apiUser=None, apiKey=None)
Parameters Type Values Default Required
________________________________________________________________________________________________________________________________
jobID integer YES
nimURL string
apiUser string ---
apiKey string ---
Upload Job Icon¶
Uploads a new job icon for a specified job ID and path to the image file.
def upload_jobIcon( jobID=None, img=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________________________________________
jobID integer YES
img string YES
nimURL string
apiUser string ---
apiKey string ---
Return: (dictionary)
ID
number
jobname
folder
Get Job Info¶
Retrieves information for a given job Returns limited data if user does not have permission to view job details.
def get_jobInfo( jobID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________________________________________
jobID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return: (dictionary)
ID
number
jobname
folder
Find Jobs¶
Retrieves job IDs or full job data based on search parameters.
Note
This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your return data.
def find_jobs( nimURL=None, apiUser=None, apiKey=None, **kwargs )
Parameters Type Description
_________________________________________________________________________________________________________________________________
Optional:
getData 0 / 1 0 - returns IDs (default)
1 - returns full data for items
Returns limited data if user does not have permission to view job details
ID int Allows comma separated list
name string Will partially match the job name
number string Will match the job number
description string Will partially match the job description
startDate date YYYY-MM-DD
endDate date YYYY-MM-DD
jobStatusID int Job Status ID
jobStatus string Job Status Name
folder string The job folder name
client_contactID int The ID of a linked contact
Allows comma separated list
client_details string Will partially match the client details
biddingLocationID int ID of the corresponding locations
Allows comma separated list
biddingLocation string Name of the bidding location
assignedLocationID int ID of the corresponding locations
Allows comma separated list
assignedLocation string Name of the assigned location
currency string Currency code (USD, EUR, etc)
is_private int (0, 1)
agency string Agency
agency_producer string Agency Producer
agency_phone string Agency Phone
agency_email string Agency Email
production_company string Production Company
director string Directory
prod_contact string Production Contact
prod_phone string Production Phone
prod_email string Production Email
producer string Producer
creative_lead string Creative Lead
grading string Grading
colorist string Colorist
editorial string Editorial
editor string Editor
mix string Mix
music string Music
sound_design string Sound Design
shoot_date date YYYY-MM-DD
shoot_location string Shoot Location
supervised int (0, 1)
proj_status string (ONLINE, OFFLINE)
activity string (ACTIVE, INACTIVE)
keywords array Allows comma separated list
Example: keyword1,keyword2
customKeys dictionary A dictionary of custom key names and values
Example: {"My Custom Key Name":"Some text","Another Custom Key":"Some other text"}
include_deleted 0/1 1 - include deleted jobs
limit integer specifies the maximum number of rows to return
default 0 (no limit)
offset integer specifies the number of rows to skip before starting to return rows.
default 0
nimURL string Override for nimURL setting in prefs
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser string Required if nimURL is set
and Require API Keys is enabled in NIM
apiKey string Required if nimURL is set
and Require API Keys is enabled in NIM
Return :
Returns an associative array in the format
result->success True/False
result->error Includes any error or security messaging
result->total_count The total number of rows without the limit
result->data An array of the data requested
Get Job Statuses¶
Returns the list of available job statuses
def get_jobStatuses( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return: (dictionary)
success - true or false
error - any associated error message
data - a list of dictionaries
- ID
- name
- priority
- bgcolor
- textcolor
Servers & Project Structure¶
Get All Servers¶
Retrieves all servers optionally filtered by locationID
def get_allServers( locationID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
______________________________________________________________________________________________________________________________
locationID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Job Servers¶
Retrieves servers associated with a specified job ID
def get_jobServers( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________________________________________
ID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Server Info¶
Retrieves servers information from server ID
def get_serverInfo( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
______________________________________________________________________________________________________________________________
ID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Server OS Path¶
Retrieves server path based on server ID and OS type.
def get_serverOSPath( ID=None, os=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________________________
ID ID of the server integer YES
os OS Type string win,Windows,osx,mac, Linux YES
Darwin, Linux
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get OS Path¶
Retrieves file path based on file ID and OS type.
def get_osPath( fileID=None, os=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________________
ID ID of the server integer YES
os OS Type string win,Windows,osx,mac, Linux YES
Darwin, Linux
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Paths¶
Retrieves the NIM path for a project structure given the item ID and the path item to look for.
- Item Options:
job (PROJECT ROOT) asset (ASSET ROOT, ASSET COMPS, ASSET RENDERS) show (SHOW ROOT) shot (SHOT ROOT, SHOT PLATES, SHOT COMPS, SHOT RENDERS)
def get_paths( item='', ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
_____________________________________________________________________________________________________________________________
ID integer YES
item string job, show, shot, asset YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Can Bring Online¶
Tests item against project structure to see if it can be brought online.
- Item types can be asset or shot
If asset, jobID OR assetID must be passed
If shot, showID or shotID must be passed
def can_bringOnline( item='shot', jobID=0, assetID=0, showID=0, shotID=0, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
_____________________________________________________________________________________________________________________________
item string shot, asset shot YES
jobID integer ---
assetID integer ---
showID integer ---
shotID integer ---
nimURL string
apiUser string ---
apiKey string ---
Return:
1 if the item can be brought online or 0 if not.
Bring Online¶
Brings assets and shots online creating folders from project structure
- Item types can be asset or shot
If asset, assetID must be passed
If shot, shotID must be passed
def bring_online( item='shot', assetID=0, shotID=0, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
______________________________________________________________________________________________________________________________
item string shot, asset shot YES
assetID integer
shotID integer
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Assets¶
Get Assets¶
Builds a dictionary of all assets for a given job
def get_assets( jobID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Add Asset¶
Adds a new asset to a job and returns the new assetID.
If an asset with the specified name already exists, NIM wil update the existing asset instead of creating a new one with a duplicate name.
An asset status can be passed by either name or ID.
If both are passed the ID will be used.
def add_asset( jobID=None, name=None, assetStatusID=None, assetStatus=None, description=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string YES
assetStatusID integer
assetStatus string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Update Asset¶
Updates an existing asset based on the assetID.
An asset status can be passed by either name or ID. If both are passed the ID will be used.
def update_asset( assetID=None, assetStatusID=None, assetStatus=None, description=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
assetStatusID integer
assetStatus string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Delete Asset¶
Deletes an asset based on assetID.
def delete_asset( assetID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Upload Asset Icon¶
Uploads an image from a file path to the supplied asset ID.
def upload_assetIcon( assetID=None, img=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
img string YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Asset Info¶
Retrieves information for a given asset from the asset ID.
def get_assetInfo( assetID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Asset Icon¶
Retrieves the path to the asset’s icon for a given assetID
def get_assetIcon( assetID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Asset Statuses¶
Returns the list of available asset statuses
def get_assetStatuses( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return: (dictionary)
success - true or false
error - any associated error message
data - a list of dictionaries
- ID
- name
- priority
- bgcolor
- textcolor
- task_status_ID - the task status ID associated with the asset status
Shows¶
Get Shows¶
Builds a dictionary of all shows for a given job ID
def get_shows( jobID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Show Info¶
Returns all show information for a given show id
def get_showInfo( showID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Add Show¶
Adds a new show to a job and returns the new showID
def add_show( jobID=None, name=None, trt=None, has_previs=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string YES
trt string 00:00:00:00
has_previs boolean 0/1 (a value of 1 will create an associated previs show)
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Update Show¶
Updates an existing show based on the showID.
Show name will only be updated if the show is offline.
def update_show( showID=None, name=None, trt=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
name string
trt string 00:00:00:00
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Delete Show¶
Deletes an existing show based on the showID.
def delete_show( showID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Shots¶
Get Shots¶
Builds a dictionary of all shots for a given show id
def get_shots( showID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Add Shot¶
Adds a shot to a show and returns the new ID.
If a shot with the specified name already exists, NIM will update the existing shot instead of creating a new one with a duplicate name.
A shot status can be passed by either name or ID. If both are passed the ID will be used.
def add_shot( showID=None, shotName=None, name=None, shotStatusID=None, shotStatus=None, description=None, vfx=None, fps=None, frames=None, shotDuration=None, \
handles=None, heads=None, tails=None, height=None, pan=None, tilt=None, roll=None, lens=None, fstop=None, filter=None, \
dts=None, focus=None, ia=None, convergence=None, cam_roll=None, stock=None, format=None, crop=None, protect=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
shotName/name string YES
shotStatusID integer
shotStatus string
description string
vfx string
fps string
frames/shotDuration string
handles string
heads string
tails string
height string
pan string
tilt string
roll string
lens string
fstop string
filter string
dts string
focus string
ia string
convergence string
cam_roll string
stock string
format string
crop string
protect string
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Update Shot¶
Updates an existing shot based on the shotID.
A shot status can be passed by either name or ID. If both are passed the ID will be used.
def update_shot( shotID=None, shotStatusID=None, shotStatus=None, description=None, vfx=None, fps=None, frames=None, duration=None, \
handles=None, heads=None, tails=None, height=None, pan=None, tilt=None, roll=None, lens=None, fstop=None, filter=None, \
dts=None, focus=None, ia=None, convergence=None, cam_roll=None, stock=None, format=None, crop=None, protect=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID integer YES
shotStatusID integer
shotStatus string
description string
vfx string
fps string
frames/duration string
handles string
heads string
tails string
height string
pan string
tilt string
roll string
lens string
fstop string
filter string
dts string
focus string
ia string
convergence string
cam_roll string
stock string
format string
crop string
protect string
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Delete Shot¶
Deletes a shot based on shotID.
def delete_shot( shotID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Upload Shot Icon¶
def upload_shotIcon( shotID=None, img=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID The ID of the shot to upload to integer YES
img The path to the image to upload string YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Shot Info¶
Retrieves information for a given shot
def get_shotInfo( shotID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID shot ID to retrieve information integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Shot Icon¶
Retrieves the path to the shot’s icon for a given shotID
def get_shotIcon( shotID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID shot ID to retrieve icon integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Shot Statuses¶
Returns the list of available shot statuses.
def get_shotStatuses( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
Dictionary
success - true or false
error - any associated error message
data - a list of dictionaries
- ID
- name
- priority
- bgcolor
- textcolor
- task_status_ID - the task status ID associated with the shot status
Tasks¶
Get Tasks Types¶
Retrieves the dictionary of available task types from the API optionally including all in-use tasks on an asset or shot.
def get_taskTypes( app='all', userType='artist', assetID=None, shotID=None, onlyWithFiles=None, \
nimURL=None, apiUser=None, apiKey=None ) :
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________
app Optional filter by application string MAYA, C4D, AE, NUKE, all
HIERO, PHOTOSHOP, 3DSMAX,
HOUDINI, FLAME, all artist
userType Optional filter by role type string artist, producer, management
all
assetID Include tasks used on assetID integer
shotID Include tasks used on shotID string
onlyWithFiles Flag to return only task types that are associated integer 0 or 1 0
with files on provided shot or asset
pub Optional filter for the onlyWithFiles flag to integer 0 or 1 0
return only task types with published files
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Add Task¶
Adds a new task to an asset or shot.
AssetID or shotID can be passed. If both are passed, assetID will be used.
The task type can be determined by passing taskTypeID or taskTypeName. If both are passed, taskTypeID will be used.
A user can be attached to the task by passing either userID or username. If both are passed, userID will be used.
def add_task( assetID=None, shotID=None, taskTypeID=None, taskTypeName=None, userID=None, username=None, \
taskStatusID=None, taskStatus=None, description=None, estimatedHours=None, startDate=None, endDate=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
__________________________________________________________________________________________________________
assetID or shotID YES
assetID integer
shotID integer
taskTypeID or taskTypeName YES
taskTypeID integer
taskTypeName string
userID OR username
userID integer
username string
taskStatusID OR taskStatus
taskStatusID integer
taskStatus string
description string
estimated_hours float
startDate UTC datetime string "2017-01-01 08:00:00"
endDate UTC datetime string "2017-01-01 08:00:00"
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Update Task¶
Updates an existing task based on taskID.
The task type can be determined by passing taskTypeID or taskTypeName. If both are passed, taskTypeID will be used.
A user can be attached to the task by passing either userID or username. If both are passed, userID will be used.
def update_task( taskID=None, taskTypeID=None, taskTypeName=None, userID=None, username=None, \
taskStatusID=None, taskStatus=None, description=None, estimatedHours=None, startDate=None, endDate=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
__________________________________________________________________________________________________________
taskID integer YES
taskTypeID or taskTypeName
taskTypeID integer
taskTypeName string
userID OR username
userID integer
username string
taskStatusID OR taskStatus
taskStatusID integer
taskStatus string
description string
estimated_hours float
startDate UTC datetime string "2017-01-01 08:00:00"
endDate UTC datetime string "2017-01-01 08:00:00"
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Delete Task¶
Deletes a task based on taskID.
def delete_task( taskID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
_____________________________________________________________________________________________________________
taskID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Task Info¶
Retrieves a dictionary of task information.
Given the taskID passed as ID, this function will return the information for a single task.
Given the itemID for an asset or shot and setting the itemClass will return information for all tasks for the respective item.
def get_taskInfo(ID=None, itemClass=None, itemID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
__________________________________________________________________________________________________________
ID integer ---
itemID integer ---
itemClass string asset/shot ---
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Task Statuses¶
Returns the list of available task statuses.
def get_taskStatuses( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
Dictionary
success - true or false
error - any associated error message
data - a list of dictionaries
- ID
- status
- type
- priority
- bgcolor
- textcolor
Files¶
Get Basenames¶
Retrieves the dictionary of basenames for a show, shot or asset.
def get_bases( shotID=None, assetID=None, showID=None, task='', taskType=None, taskID=None, taskTypeID=None, pub=False, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID, assetID, or showID YES
shotID The shot ID to find basenames integer ---
assetID The asset ID to find basenames integer ---
showID The show ID to find basenames integer ---
task / taskType Task Type Name to filter results string
taskID / taskTypeID Task Type ID to filter results integer
pub Filter to return published basename files boolean True/False False
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Published Basename¶
Retrieves the dictionary of the published file for a given basename. The optional username is used to return the date information in the users selected timezone.
def get_basesPub( shotID=None, assetID=None, basename='', username=None, nimURL=None, apiUser=None, apiKey=None ) :
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID OR assetID YES
shotID integer ---
assetID integer ---
basename string YES
username string
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get All Published Basenames¶
Retrieves the dictionary of all available published basenames for a given asset or shot filtered by task type.
The “task” parameter is the task type name.
The “taskID” parameter is the task type ID.
The optional username is used to return the date information in the users selected timezone.
def get_basesAllPub( shotID=None, assetID=None, task=None, taskID=None, username=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID OR assetID YES
shotID integer ---
assetID integer ---
task OR taskID YES
task string ---
taskID integer ---
username string
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Basename Info¶
Retrieves all basenames and their max version for given asset, shot, or show based on ID
def get_baseInfo( shotID=None, assetID=None, showID=None, taskTypeID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID, showID, or assetID YES
shotID integer ---
showID integer ---
assetID integer ---
taskTypeID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Basename Version¶
Retrieves the highest version number for a given basename in an asset or shot.
def get_baseVer( shotID=None, assetID=None, basename='', nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID OR assetID YES
shotID integer ---
assetID integer ---
basename string YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Versions¶
Retrieves the dictionary of available versions from a basename.
The optional username is used to return the date information in the users selected timezone.
def get_vers( shotID=None, assetID=None, showID=None, basename=None, pub=False, username=None, \
nimURL=None, apiUser=None, apiKey=None ) :
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID OR assetID OR showID YES
shotID Shot ID to find basenames integer ---
assetID Asset ID to find basenames integer ---
showID Show ID to find basenames integer ---
basename The basename in which to find versions string YES
pub Filter to only return published basenames boolean True/False False
username User to set timezone string
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Version Info¶
Retrieves the information for a given version ID.
The optional username is used to return the date information in the users selected timezone.
def get_verInfo( verID=None, username=None, nimURL=None, apiUser=None, apiKey=None ) :
Parameters Type Values Default Required
________________________________________________________________________________________________
verID integer YES
username string
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Clear Published Flags¶
Run before publishing to clear previous basename published flags.
ShotID is required when clearing publish for a shot. AssetID is require when clearing publish for an asset.
def clear_pubFlags( shotID=None, assetID=None, basename='', nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID or assetID integer YES
shotID integer ---
assetID integer ---
basename string YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Publish SymLink¶
Creates the symbolic link for a published file based on the file ID
Force Link creates a symbolic link even if the source location is invalid.
def publish_symLink( fileID=None, forceLink=1, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
fileID integer YES
forceLink boolean True/False True
nimURL string
apiUser string ---
apiKey string ---
Return:
boolean (true/false)
Success returns true
Save File¶
Saves a file to the NIM database
def save_file( parent='SHOW', parentID=0, task_type_ID=0, task_folder='', userID=0, basename='', \
filename='', path='', ext='', version='', comment='', serverID=0, pub=False, forceLink=1, \
work=True, metadata='', customKeys=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
parent Type of parent for the file string show, shot, or asset show YES
parentID ID of the parent integer YES
task_type_ID Task type ID to associate with the file integer YES
task_folder Task folder to use for the file string YES
userID ID of the user who owns the file integer YES
basename Basename for the file string YES
filename File name of the file being saved string YES
path Path to the file string YES
serverID ID of the server where file exists integer YES
ext File extension string
version Version of the file integer
comment Comment to add to the file entry string
pub Value of True will publish the file boolean True/False False
forceLink Force the symbolic link creation boolean True/False True
work Mark file as a working file boolean True/False True
customKeys Dictionary of custom keys dictionary {"Custom Key Name" : "Value"}
metadata Dictionary of metadata (Internal Use) dictionary {"Key" : "Value"}
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
Array in the format {success, error, ID} where the ID is the NIM ID of the newly created file.
Update File¶
Updates an existing file in the NIM database
def update_file( ID=0, task_type_ID=0, task_folder='', userID=0, basename='', filename='', path='', \
ext='', version='', comment='', serverID=0, pub=False, forceLink=1, work=True, \
metadata='', customKeys=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID ID of the file to update integer YES
task_type_ID Task type ID to associate with the file integer
task_folder Task folder to use for the file string
userID ID of the user who owns the file integer
basename Basename for the file string
filename File name of the file being saved string
path Path to the file string
ext File extension string
version Version of the file integer
comment Comment to add to the file entry string
serverID ID of the server where file exists integer
pub Value of True will publish the file boolean True/False False
forceLink Force the symbolic link creation boolean True/False True
work Mark file as a working file boolean True/False True
customKeys Dictionary of custom keys dictionary {"Custom Key Name" : "Value"}
metadata Dictionary of metadata (Internal Use) dictionary {"Key" : "Value"}
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
Array in the format {success, error, ID} where the ID is the NIM ID of the newly created file.
Find Files¶
A search function for files.
Any provided parameters will filter the returned list.
def find_files( name='', path='', metadata='', nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
name Find matching name string
path Find matching path string
parent Used with parentID to set the parent type string ASSET / SHOT
parentID The ID of the parent item integer
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Elements¶
Get Element Types¶
Retrieves a dictionary of global element types
def get_elementTypes( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Element Type¶
Retrieves a dictionary of element type info
def get_elementType( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Find Elements¶
A more robust search function for elements.
All parameters are optional.
Any provided parameters will filter the returned list.
def find_elements( name='', path='', jobID='', showID='', shotID='', assetID='', taskID='', renderID='', elementTypeID='', ext='' ,metadata='', \
nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
name Element name string
path Element path string
jobID Job ID integer
showID Show ID integer
shotID Shot ID integer
assetID Asset ID integer
taskID Task ID integer
renderID Render ID integer
elementTypeID Element type ID integer
ext File extension string
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Get Elements¶
Retrieves a dictionary of elements for a particular type given parentID.
If no elementTypeID is given will return elements for all types.
def get_elements( parent='shot', parentID=None, elementTypeID=None, getLastElement=False, isPublished=False, nimURL=None, apiUser=None, apiKey=None ):
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
parent Parent of the element string shot, asset, task, or render shot YES
parentID ID of the parent object integer YES
elementTypeID ID of the element type integer
getLastElement Return on the last published element boolean True/False False
isPublished Return only the published elements boolean True/False False
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Add Element¶
Adds an element to an asset, shot, task, or render
def add_element( parent='shot', parentID=None, userID=None, typeID='', path='', name='', \
startFrame=None, endFrame=None, handles=None, isPublished=False, \
nimURL=None, apiKey=None, metadata='', nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
parent Parent of the element string shot, asset, task, or render shot YES
parentID ID of the parent object integer YES
typeID Element Type ID integer YES
path Path to the file string YES
name Name of the file string YES
startFrame If a sequence, this is the start frame integer
endFrame If a sequence, this is the end frame integer
handles If a sequence, this is the handle length integer
isPublished Should element be flagged as published boolean True/False False
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Update Element¶
Updates an existing element by element ID
def update_element( ID=None, userID=None, jobID=None, assetID=None, shotID=None, taskID=None, \
renderID=None, elementTypeID=None, name=None, path=None, startFrame=None, \
endFrame=None, handles=None, isPublished=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
userID User ID integer
jobID Job ID integer
assetID Asset ID integer
shotID Shot ID integer
taskID Task ID integer
renderID Render ID integer
elementTypeID Element Type ID integer
name Name of the file string
path Path to the file string
startFrame If a sequence, this is the start frame integer
endFrame If a sequence, this is the end frame integer
handles If a sequence, this is the handle length integer
isPublished Should element be flagged as published boolean True/False False
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Delete Element¶
Deletes an existing element by element ID
def delete_element(ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Render¶
Add Render¶
Logs a render to a given taskID.
def add_render( jobID=0, itemType='shot', taskID=0, fileID=0, \
renderKey='', renderName='', renderType='', renderComment='', \
outputDirs=None, outputFiles=None, elementTypeID=0, start_datetime=None, end_datetime=None, \
avgTime='', totalTime='', frame=0, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
______________________________________________________________________________________________________________________________________________________
taskID ID of the task to log the render integer YES
jobID ID of job to log the render integer
itemType Is this an asset or shot render string asset, shot shot
fileID ID of a file to associate with render integer
renderKey Unique Key for render to link to external string
database / render management software
renderName Name of the render string
renderType Type of render string
(example: Deadline will pass "mayaPlugin", "nukePlugin", etc...)
renderComment Comment to add to the render string
outputDirs Array out output directories from the render array
outputFiles Array of output files from the render array
elementTypeID ID of the element type to use for the render integer
start_datetime Datetime value for the start of the render datetime
end_datetime Datetime value for the end of the render datetime
avgTime Average time of the render string
totalTime Total time of the render string
frame The total frame count of the render integer
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Upload Render Icon¶
Upload Render Icon
def upload_renderIcon( renderID=None, renderKey='', img=None, nimURL=None, apiUser=None, apiKey=None ) :
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
renderID ID of the render to add the icon integer YES if renderKey is not passed
renderKey RenderKey of the render to add the icon string YES if renderID is not passed
img Full path to the image string YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Last Shot Render¶
Retrieves the last render added to a shot.
def get_lastShotRender( shotID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
shotID ID of the shot to retrieve last render integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Review¶
Get Review Item Types¶
Retrieves the ID and name for all possible review items types
def get_reviewItemTypes( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
JSON Array of review item types:
ID - The ID of the review item type
name - The name of the review item type
Get Task Review Items¶
Retrieves the dictionary of review items for the specified taskID
def get_taskReviewItems( taskID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
taskID ID of the task to retrieve dailies integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Get Review Items¶
Returns the child review items and details for the given parent item
def get_reviewItems( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
parentType string user YES
job
dev
asset
show
shot
task
render
parentID ID of the parent; jobID if value is "dev" integer YES
allChildren 0 or 1, determines if we return review items associated with child items or not;
for example, if parent is show, would return review items on the show as well as
children shots, tasks, and renders
name Filters the returned review items by the given name
description Filters the returned review items to items that contain the given string
date Filters the returned review items by the given date in the format: yyyy-mm-dd
typeID OR type Filters the returned review items by the given typeID OR type name
statusID OR status Filters the returned review items by the given statusID OR status name
keywordID OR keyword Filters the returned review items by the given keywordID OR keyword name
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Get Review Item Info¶
Retrieves the dictionary of details for the specified review item ID
def get_reviewItem( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Get Review Item Notes¶
Retrieves the dictionary of notes for the specified review item ID
def get_reviewItemNotes( ID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Upload Review Item¶
Upload Review Item
def upload_reviewItem( taskID=None, renderID=None, renderKey=None, itemID=None, itemType=None, path=None, submit=None, \
name=None, description=None, reviewItemTypeID=0, reviewItemStatusID=0, keywords=None, nimURL=None, apiUser=None, apiKey=None ) :
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
itemID ID of the parent item integer YES
itemType The type of parent item string user, job, show, shot, task, render YES
name The name of the review item string
description The description of the review item string
reviewItemTypeID The ID for the reviewItemType integer
reviewItemStatusID The ID for the reviewItemStatus integer
keywords An array of keywords to associate array string Format: ["keyword1","keyword2"]
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
RETURN:
dictionary
Upload Review Note¶
Uploads a note to an existing review item in NIM along with an associated image
def: upload_reviewNote( ID=None, name='', img=None, note='', frame=0, time=-1, userID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
dailiesID ID of the review item to add note integer YES
name Name of the note string
img Full path to the image to attach to note string
note Text of the note string
frame Frame number to associate note integer
time Time in the movie to associate note. string
If this is not frame specific, -1 can be used.
userID NIM user ID of the note owner integer YES
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
dictionary
Get Review Item Statuses¶
Returns the list of available review item statuses
def get_reviewStatuses( nimURL=None, apiUser=None, apiKey=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
nimURL Override for nimURL setting in prefs string
Including nimURL will override the default
NIM API url and skip the reading of saved
user preferences.
apiUser Required if nimURL is set string ---
and Require API Keys is enabled in NIM
apiKey Required if nimURL is set string ---
and Require API Keys is enabled in NIM
Return:
Dictionary
success - true or false
error - any associated error message
data - a list of dictionaries
- ID
- name
- priority
- bgcolor
- textcolor
Get Review Bins¶
get_reviewBins
(context: str, contextID: int, limit: int = 0, offset: int = 0) → dict¶Returns all review bins and their items within a specific context.
ARGUMENTS¶ context
string
REQUIRED
The context of the review for which you want to retrieve bins. Valid options are user, job, dev, asset, show, and shot.
user sets the context to the user dashboard review. When API Keys are required, contextID must be the same as the API user’s userID, and the user must have the viewDashboardReview permission unless they are a root user.
When the dev context is used, set the contextID to the corresponding job ID.
contextID
integer
REQUIRED
The ID of the context item.
limit
integer
OPTIONAL
default: 0
Maximum rows to return. A value of 0 means no limit.
offset
integer
OPTIONAL
default: 0
Number of rows to skip before returning.
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
total_count
integer
The total number of rows that match the search criteria.
data
dict
A dictionary containing details of review bins. Each bin is a dictionary with the following keys:
ID : The unique identifier of the bin
name : The name of the bin
creationDate : Timestamp when the bin was created
createdByUserID : ID of the user who created the bin
createdByFullName : Full name of the user who created the bin
modifiedDate : Timestamp of the bin’s most recent update
modifiedByUserID : ID of the user who most recently updated the bin
modifiedByFullName : Full name of the user who most recently updated the bin
autoUpdateVersions : A flag indicating if version updates happen automatically. 1 for true, 0 for false.
reviewItems : A list of review items within the bin. Each item is a dictionary containing:
ID : Unique item identifier
name : Name or label for the review item
creationDate : Timestamp when the review item was created
createdByUserID : ID of the user who created the item
createdByFullName : Name of the user who created the item
position : The item’s position in the bin
Example Usage:
from nim_core.nim_api import get_reviewBins response = get_reviewBins(context="job", contextID=1, limit=10, offset=0) if response["success"]: for bin_data in response["data"]: print(f"Bin Name: {bin_data['name']}, Created By: {bin_data['createdByFullName']}") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "", "total_count": 1, "data": [ { "ID": 10, "name": "Test Bin", "creationDate": "2025-02-03 12:00:00", "createdByUserID": 2, "createdByFullName": "John Doe", "modifiedDate": "2025-02-04 15:30:00", "modifiedByUserID": 3, "modifiedByFullName": "Jane Smith", "autoUpdateVersions": 0, "reviewItems": [ { "ID": 100, "name": "First Review Item", "creationDate": "2025-02-03 12:30:00", "createdByUserID": 2, "createdByFullName": "John Doe", "position": 1 } ] } ] }
Add Review Bin¶
add_reviewBin
(context: str, contextID: int, name: str, autoUpdateVersions: int = 0) → dict¶Creates a new review bin for a specific context and returns the ID of the newly created bin.
ARGUMENTS¶ context
string
REQUIRED
The context in which to create a new review bin. Valid options are user, job, dev, asset, show, and shot.
user sets the context to the user dashboard review. When API Keys are required, contextID must be the same as the API user’s userID, and the user must have the viewDashboardReview permission unless they are a root user.
When the dev context is used, set the contextID to the corresponding job ID.
contextID
integer
REQUIRED
The ID of the context item.
name
string
REQUIRED
The name of the review bin.
autoUpdateVersions
integer
OPTIONAL
default: 0
Flag to automatically update versions in the bin when new versions are added.
1 = Automatically update versions
0 = Do not update versions
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
data
dict
A dictionary containing the ID of the newly created bin:
ID : The unique identifier of the new bin
Example Usage:
from nim_core.nim_api import add_reviewBin response = add_reviewBin(context="job", contextID=1, name="Test Bin") if response["success"]: print(f"New Review Bin ID: {response['data']['ID']}") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "", "data": { "ID": 10 } }
Update Review Bin¶
update_reviewBin
(ID: int, name: str = None, autoUpdateVersions: int = None) → dict¶Updates an existing review bin with new values for name and/or auto-update settings.
ARGUMENTS¶ ID
integer
REQUIRED
The ID of the review bin to update.
name
string
OPTIONAL
The new name of the review bin.
autoUpdateVersions
integer
OPTIONAL
Flag to automatically update versions in the bin when new versions are added.
1 = Automatically update versions
0 = Do not update versions
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
Example Usage:
from nim_core.nim_api import update_reviewBin response = update_reviewBin(ID=1, name="Test Bin", autoUpdateVersions=1) if response["success"]: print("Review bin updated successfully.") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "" }
Delete Review Bin¶
delete_reviewBin
(ID: int) → dict¶Deletes an existing review bin.
ARGUMENTS¶ ID
integer
REQUIRED
The ID of the review bin to delete.
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
Example Usage:
from nim_core.nim_api import delete_reviewBin response = delete_reviewBin(ID=1) if response["success"]: print("Review bin deleted successfully.") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "" }
Add Review Bin Item¶
add_reviewBinItem
(binID: int, itemID: int, position: int = None) → dict¶Adds an existing review item to a review bin.
ARGUMENTS¶ binID
integer
REQUIRED
The ID of the review bin to update.
itemID
integer
REQUIRED
The ID of the review item to add to the bin.
The review item must be associated with the same context as the review bin.
position
integer
OPTIONAL
The position to place the review item in the bin.
Valid values are 1 or greater.
If the position is greater than the number of review items in the bin, the review item is placed at the end of the bin.
If not provided, the review item is added to the end of the bin.
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
Example Usage:
from nim_core.nim_api import add_reviewBinItem response = add_reviewBinItem(binID=1, itemID=1, position=1) if response["success"]: print("Review item added successfully.") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "" }
Position Review Bin Item¶
position_reviewBinItem
(binID: int, itemID: int, position: int) → dict¶Moves a review item to a new position in a review bin.
ARGUMENTS¶ binID
integer
REQUIRED
The ID of the review bin to update.
itemID
integer
REQUIRED
The ID of the review item to move.
position
integer
REQUIRED
The position to place the review item in the bin.
Valid values are 1 or greater.
If the position is greater than the number of review items in the bin, the review item is placed at the end of the bin.
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
Example Usage:
from nim_core.nim_api import position_reviewBinItem response = position_reviewBinItem(binID=1, itemID=1, position=2) if response["success"]: print("Review item repositioned successfully.") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "" }
Remove Review Bin Item¶
remove_reviewBinItem
(binID: int, itemID: int) → dict¶Removes a review item from a review bin. This does not delete the review item; it is simply removed from the bin.
ARGUMENTS¶ binID
integer
REQUIRED
The ID of the review bin containing the review item.
itemID
integer
REQUIRED
The ID of the review item to remove.
RETURN¶ success
boolean
Indicates whether the operation was successful.
Possible values: true or false.
error
string
Contains any generated error messages if success is false.
If success is true, this field is typically an empty string.
Example Usage:
from nim_core.nim_api import remove_reviewBinItem response = remove_reviewBinItem(binID=1, itemID=1) if response["success"]: print("Review item removed successfully.") else: print(f"Error: {response['error']}")Example Response:
{ "success": True, "error": "" }
Timecards¶
Get Timecards¶
Retrieves a timecard, or array of timecards based on search criteria
A user can be passed by either username or userID. If both are passed the userID will be used. A taskType can be passed by either the name using taskType or ID with taskTypeID. If both are passed the taskTypeID will be used. A location can be passed by either the name using location or ID with locationID. If both are passed the locationID will be used.
def get_timecards( startDate=None, endDate=None, jobID=None, userID=None, username=None, \
taskTypeID=None, taskType=None, taskID=None, locationID=None, location=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
startDate date format: 2017-11-30 not required if jobID provided
endDate date format: 2017-11-30 not required if jobID provided
jobID integer ---
userID integer
username string
taskTypeID integer
taskType string
taskID integer
locationID integer
location string
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Add Timecards¶
Adds a new timecard
A user can be passed by either username or userID. If both are passed the userID will be used. A taskType can be passed by either the name using taskType or ID with taskTypeID. If both are passed the taskTypeID will be used. A location can be passed by either the name using location or ID with locationID. If both are passed the locationID will be used.
If a taskID is passed, the tasks values will override userID, jobID, and taskTypeID
def add_timecard( date=None, userID=None, username=None, jobID=None, taskTypeID=None, taskType=None, taskID=None, \
startTime=None, endTime=None, hrs=None, breakHrs=None, ot=None, dt=None, \
locationID=None, location=None, description=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
date date format: 2017-11-30 YES
userID integer
username string
jobID integer
taskTypeID integer
taskType string
taskID integer
startTime string range: 00:00:00 to 23:59:59
endTime string range: 00:00:00 to 23:59:59
hrs decimal hours between start_time and end_time, including break_hrs, ot, and dt; max 24
breakHrs decimal must fit within hrs
ot decimal must fit within hrs - break_hrs
dt decimal must fit within hrs - (break_hrs + ot)
locationID integer
location string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Update Timecard¶
Updates an existing timecard
A user can be passed by either username or userID. If both are passed the userID will be used. A taskType can be passed by either the name using taskType or ID with taskTypeID. If both are passed the taskTypeID will be used. A location can be passed by either the name using location or ID with locationID. If both are passed the locationID will be used.
If a taskID is passed, the tasks values will override userID, jobID, and task_types_ID
def update_timecard( timecardID=None, date=None, userID=None, username=None, jobID=None, taskTypeID=None, taskType=None, taskID=None, \
startTime=None, endTime=None, hrs=None, breakHrs=None, ot=None, dt=None, \
locationID=None, location=None, description=None, customKeys=None, \
nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
date date format: 2017-11-30
userID integer
username string
jobID integer
taskTypeID integer
taskType string
taskID integer
startTime string range: 00:00:00 to 23:59:59
endTime string range: 00:00:00 to 23:59:59
hrs decimal hours between start_time and end_time, including break_hrs, ot, and dt; max 24
breakHrs decimal must fit within hrs
ot decimal must fit within hrs - break_hrs
dt decimal must fit within hrs - (break_hrs + ot)
locationID integer
location string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Delete Timecard¶
Deletes an existing timecard
def delete_timecard( timecardID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary
Get Timecard Info¶
Retrieves information for an existing timecard
def get_timecardInfo( timecardID=None, nimURL=None, apiUser=None, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
nimURL string
apiUser string ---
apiKey string ---
Return:
dictionary