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 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.
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
Get Culture Codes¶
Retrieves a list of currency codes used for setting the currency type of an item
def get_cultureCodes()
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
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. )
Users¶
Get User ID¶
Retrieves the current user's ID
def get_userID( user='' )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
user The username to retrieve the ID integer YES
Return:
int
Jobs¶
Get User Jobs¶
Builds a dictionary of all jobs for a given user
def get_jobs( userID=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
userID The users ID integer YES
RETURN:
dictionary
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=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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
name string YES
number string
numberTemplate string
description string
client 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
folder string
projectStructureID OR projectStructure
projectStructureID integer
projectStructure string
jobStatusID OR jobStatus
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 insead of cultureID, NIM will use the first matching cultureID
cultureID integer
customKeys dictionary {"Custom Key Name" : "Value"}
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=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)
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string
number string
description string
client 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
folder string
projectStructureID OR projectStructure
projectStructureID integer
projectStructure string
jobStatusID OR jobStatus
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 insead of cultureID, NIM will use the first matching cultureID
cultureID integer
customKeys dictionary {"Custom Key Name" : "Value"}
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)
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
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, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
img string YES
Return: (dictionary)
ID
number
jobname
folder
Get Job Info¶
Retrieves information for a given job
def get_jobInfo( jobID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
Return: (dictionary)
ID
number
jobname
folder
Servers & Project Structure¶
Get All Servers¶
Retrieves all servers optionally filtered by locationID
def get_allServers( locationID='' )
Parameters Type Values Default Required
________________________________________________________________________________________________
locationID integer
Return:
dictionary
Get Job Servers¶
Retrieves servers associated with a specified job ID
def get_jobServers( ID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
Return:
dictionary
Get Server Info¶
Retrieves servers information from server ID
def get_serverInfo( ID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
Return:
dictionary
Get Server OS Path¶
Retrieves server path based on server ID and OS type.
def get_serverOSPath( ID=None, os='' )
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
Return:
dictionary
Get OS Path¶
Retrieves file path based on file ID and OS type.
def get_osPath( fileID=None, os='' )
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
Return:
dictionary
Get Paths¶
Retrieves the NIM path for a project structure given the item ID and the path item to look for.
- Type 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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
item string job, show, shot, asset YES
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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
item string shot, asset shot YES
jobID integer ---
assetID integer ---
showID integer ---
shotID integer ---
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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
item string shot, asset shot YES
assetID integer
shotID integer
Return:
dictionary
Assets¶
Get Assets¶
Builds a dictionary of all assets for a given job
def get_assets( jobID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string YES
assetStatusID integer
assetStatus string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
assetStatusID integer
assetStatus string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
Return:
dictionary
Delete Asset¶
Deletes an asset based on assetID.
def delete_asset( assetID=None)
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
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, apiKey=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
img string YES
nimURL string
apiKey string
Return:
dictionary
Get Asset Info¶
Retrieves information for a given asset from the asset ID.
def get_assetInfo( assetID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
Return:
dictionary
Get Asset Icon¶
Retrieves the path to the asset’s icon for a given assetID
def get_assetIcon( assetID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
Return:
dictionary
Shows¶
Get Shows¶
Builds a dictionary of all shows for a given job ID
def get_shows( jobID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
Return:
dictionary
Get Show Info¶
Returns all show information for a given show id
def get_showInfo( showID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
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)
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)
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)
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
name string
trt string 00:00:00:00
Return:
dictionary
Delete Show¶
Deletes an existing show based on the showID.
def delete_show( showID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
Return:
dictionary
Shots¶
Get Shots¶
Builds a dictionary of all shots for a given show id
def get_shots( showID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
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 )
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"}
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 )
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"}
Return:
dictionary
Delete Shot¶
Deletes a shot based on shotID.
def delete_shot( shotID=None)
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID integer YES
Return:
dictionary
Upload Shot Icon¶
def upload_shotIcon( shotID=None, img=None, nimURL=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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
Return:
dictionary
Get Shot Info¶
Retrieves information for a given shot
def get_shotInfo( shotID=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID shot ID to retrieve information integer YES
Return:
dictionary
Get Shot Icon¶
Retrieves the path to the shot’s icon for a given shotID
def get_shotIcon( shotID=None )
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
shotID shot ID to retrieve icon integer YES
Return:
dictionary
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 ) :
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
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 )
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"}
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)
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"}
Return:
dictionary
Delete Task¶
Deletes a task based on taskID.
def delete_task( taskID=None)
Parameters Type Values Default Required
__________________________________________________________________________________________________________
taskID integer YES
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)
Parameters Type Values Default Required
__________________________________________________________________________________________________________
ID integer ---
itemID integer ---
itemClass string asset/shot ---
Return:
dictionary
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 )
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
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 ) :
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID OR assetID YES
shotID integer ---
assetID integer ---
basename string YES
username 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 seleted timezone.
def get_basesAllPub( shotID=None, assetID=None, task=None, taskID=None, username=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID OR assetID YES
shotID integer ---
assetID integer ---
task OR taskID YES
task string ---
taskID integer ---
basename string YES
username 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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID, showID, or assetID YES
shotID integer ---
showID integer ---
assetID integer ---
taskTypeID integer YES
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='' )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID OR assetID YES
shotID integer ---
assetID integer ---
basename string YES
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 ) :
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
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 ) :
Parameters Type Values Default Required
________________________________________________________________________________________________
verID integer YES
username 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='' )
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID or assetID integer YES
shotID integer ---
assetID integer ---
basename string YES
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 )
Parameters Type Values Default Required
________________________________________________________________________________________________
fileID integer YES
forceLink boolean True/False True
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 )
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"}
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 )
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"}
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='')
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"}
Return:
dictionary
Elements¶
Get Element Types¶
Retrieves a dictionary of global element types
def get_elementTypes()
Return:
dictionary
Get Element Type¶
Retrieves a dictionary of element type info
def get_elementType( ID=None )
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
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='')
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"}
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):
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
Return:
dictionary
Add Element¶
Adds an element to an asset, shot, task, or render
nimURL and apiKey are optional for Render API Key overrride
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='' )
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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
RETURN:
dictionary
Update Element¶
Updates an existing element by element ID
nimURL and apiKey are optional for Render API Key override
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, 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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
Return:
dictionary
Delete Element¶
Deletes an existing element by element ID
nimURL and apiKey are optional for Render API Key override
def delete_element(ID=None, nimURL=None, apiKey=None)
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
nimURL Override for nimURL setting in prefs string
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
Return:
dictionary
Render¶
Add Render¶
Logs a render to a given taskID.
nimURL and apiKey are optional for Render API Key override
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, 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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
Return:
dictionary
Upload Render Icon¶
Upload Render Icon
nimURL and apiKey are optional for Render API Key overrride
2 required fields:
renderID or renderKey
img
def upload_renderIcon( renderID=None, renderKey='', img=None, nimURL=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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
Return:
dictionary
Get Last Shot Render¶
Retrieves the last render added to a shot.
def get_lastShotRender( shotID=None )
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
shotID ID of the shot to retrieve last render integer YES
Return:
dictionary
Review¶
Get Review Item Types¶
Retrieves the ID and name for all possible review items types
def get_reviewItemTypes()
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 reviem items for the specified taskID
def get_taskDailies( taskID=None)
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
taskID ID of the task to retrieve dailies integer YES
RETURN:
dictionary
Get Review Items¶
Returns the child review items and details for the given parent item
def get_reviewItems( ID=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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
RETURN:
dictionary
Get Review Item Info¶
Retrieves the dictionary of details for the specified review item ID
def get_reviewItem( ID=None)
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
RETURN:
dictionary
Get Review Item Notes¶
Retrieves the dictionary of notes for the specified review item ID
def get_reviewItemNotes( ID=None)
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
RETURN:
dictionary
Upload Review Item¶
Upload Review Item
nimURL and apiKey are optional for Render API Key overrride
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, 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"]
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, 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
apiKey Required if nimURL is set and Require string ---
API Keys is enabled
Return:
dictionary
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 )
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
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)
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"}
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)
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"}
Return:
dictionary
Delete Timecard¶
Deletes an existing timecard
def delete_timecard( timecardID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
Return:
dictionary
Get Timecard Info¶
Retrieves information for an existing timecard
def get_timecardInfo( timecardID=None )
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
Return:
dictionary