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 displayes 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_dailies(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

Connect

Wrapper function used by Python API functions to connect to the NIM Web API

def connect( method='get', params=None, nimURL=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
    apiKey                  Required if nimURL is set and Require        string                                                     ---
                            API Keys is enabled

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, 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
    apiKey                  Required if nimURL is set and Require        string                                                     ---
                            API Keys is enabled

Return:
        type: boolean

        values:
            True - The upload was successful
            False - The upload failed. ( Error messages will be printed. )

Get Application

Returns the current application name.

def get_app()

Return:
    string

Users

Get User

Retrieves the current user’s username

def get_user()

Return:
    string

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

Get All Users

Returns the full list of NIM Users

def get_userList()

Return:
    dictionary

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, 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
    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, 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
    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          job, show, 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 task types only for existing items   integer         0 or 1

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='', taskID=None, pub=False )

    Parameters              Description                                  Type            Values                      Default        Required
_____________________________________________________________________________________________________________________________________________

    shotID, assetID, or shotID                                                                                                      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                                                    ---
    taskID                  Task Type ID to filter results               integer
    pub                     Filter to only return published basenames    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

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
    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
    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 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