Setting Up Custom Command Line Parameters

Problem

If you are re-using the same code in all your templates to fetch some extra information, it might be worth considering adding a custom command line parameter to Draft. This is a slightly more advanced technique since it requires making and maintaining changes to some built-in Deadline scripts, but it can potentially save you a lot of work in the long run.

Solution

There are a total of three possible places from where a Draft Job can be submitted to Deadline:

  1. The independent Draft Submission Script in the Monitor
    • Relevant Script: scripts/Submission/DraftSubmission/DraftSubmission.py

  2. The Job right-click Draft script in the Monitor
    • Relevant Script: scripts/Jobs/JobDraftSubmission/JobDraftSubmission.py

  3. The Draft Event Plugin
    • Relevant Script: events/Draft/Draft.py

The three different scripts listed above do slightly different things throughout, but the creation of the Draft job itself is more or less the same across all of them. The area of interest for this particular Recipe is near the end of the script, where the Draft arguments are being created. It should look something like this (keep in mind variable names might be slightly different):

#prep the script arguments
args = []
args.append( 'username="%s" ' % scriptDialog.GetValue( "UserBox" ) )
args.append( 'entity="%s" ' % scriptDialog.GetValue( "EntityBox" ) )
args.append( 'version="%s" ' % scriptDialog.GetValue( "VersionBox" ) )

To add another argument to Draft, add another line similar to the args.append( ... ) lines in this section, and supply it with the value you wish to pass to your template:

#prep the script arguments
args = []
args.append( 'username="%s" ' % scriptDialog.GetValue( "UserBox" ) )
args.append( 'entity="%s" ' % scriptDialog.GetValue( "EntityBox" ) )
args.append( 'version="%s" ' % scriptDialog.GetValue( "VersionBox" ) )

#New custom Draft parameter!
newArgValue = "Hello World!"
args.append( 'argumentName="%s" ' % newArgValue )

Now, whenever a new Draft job is submitted through this particular script, Deadline will pass another parameter to your scripts named 'argumentName', with the string value "Hello World!". Keep in mind that you will have to modify all three scripts listed above if you want your change to apply to all types of Draft submissions.

Discussion

Note that even though many other (non-Draft) submitters have Draft sections in them, all of these use the Draft Event Plugin to actually do the submission to Deadline.

Argument Types

While you could technically pass any arbitrarily formatted string to Draft as a parameter, if you’re making use of the DraftParamParser utility functions, Draft will expect parameters to be formatted as 'argumentName=<argumentValue>'.

The argument’s value can only be of the following types:

  • String
    • Format Code '%s'

    • Be sure to add quotes around the value

  • Integer
    • Format Code '%d'

    • No quotes needed

  • Float (decimal value)
    • Format code '%f'

    • No quotes needed

  • A list combining multiple of the above types
    • Lists are to be enclosed in parentheses, and elements should be separated by commas

    • E.g.: (1, "string value", 3.5, "another string")

Here is some code to show what each of these might look like, in the context of the example above:

(NOTE: Pay special attention to how the ‘%’ format codes change based on the type of value it is!)

#String value
strValue = "Hello World!"
args.append( 'stringValue="%s" ' % strValue )

#Integer value
intValue = 25
args.append( 'intValue=%d ' % intValue )

#Float value
floatValue = 3.141593
args.append( 'floatValue=%f ' % floatValue )

#List of values
args.append( 'listValues=(%s,%d,%f) ' % (strValue,intValue,floatValue) )