Web Service Scripts

Overview

Web service scripts allow you to retrieve data from Deadline and display it in any way you see fit. See the Web Service for more information on Deadline’s web service feature and how you can use it to call scripts and commands.

Creating Web Service Scripts

Custom web service scripts can be created in the ‘custom\scripts\WebService’ folder in your repository. See the Scripting Overview documentation for more information on the ‘custom’ folder in the Repository and how it’s used.

Just place any new scripts directly into this folder, and they will be available to the Web Service. Script files names should not contain any spaces, and should end in a ‘.py’ extension (ie, they must be Python scripts).

The __main__ Function

All web service scripts must define a __main__ function that accepts *args (a tuple containing 2 items). This is the function that will be called when the web service executes the script. Note that if you decide not to accept args, and an argument string is passed to your script in the URL, it will result in an exception being thrown. The function should also return a string value, which is used to display the results. The string can be HTML, XML, plain text, etc.

def __main__( *args ):
    results = ""

    #...
    #append data to results
    #...

    return results

It is also possible for the web service script to set the HTTP status code. This can be done by including the status code after the results in the return statement. For example:

def __main__( *args ):
    results = ""
    statusCode = "200"

    #...
    #append data to results, and set statusCode as necessary
    #...

    return results, statusCode

Finally, it is possible for the web service script to set additional headers to be included in the HTTP response. This can be done by including an arbitrary number of “key=value” strings after the status code in the return statement. For example:

def __main__( *args ):
    results = ""
    statusCode = "200"

    #...
    #append data to results, and set statusCode as necessary
    #...

    return results, statusCode, "header1=value1", "header2=value2"

Supporting Arguments

Arguments can be passed to web service scripts as a tuple with 2 items, and can be accepted in two different ways. The first way is to simply accept args, which will be an array of length 2. The other way is to accept the tuple as two separate variables, for instance (dlArgs, qsArgs) for Deadline arguments and query string arguments. In the first case, args[0] is equivalent to dlArgs (Deadline arguments), and args[1] is equivalent to qsArgs (Query String Arguments).

Deadline Arguments

The web service will automatically pass your script a dictionary as the first item in the args tuple. The Dictionary will contain at least one key (“Authenticated”), but may contain more if the user authenticated with the web service. Currently, if the user has not authenticated, the Dictionary will only contain the “Authenticated” key, with a value of ‘False’. However, if the user has authenticated, it will also contain the “UserName” key, with a value of the user executing the script.

Query String Arguments

Arguments are passed to your script by a query string defined in the URL, and can be in one of the following forms:

Key/Value Pairs: This is the preferred method of passing arguments. Arguments in this form will look something like this at the end of the URL:

?key0=value0&key1=value1

List of Values: Arguments in this form will instead look something like this:

?value0&value1

The query string will be passed to the Python script as a NameValueCollection and it will be the second item of the tuple passed to your script’s __main__ function.

Relevant API Functions

For functions that will be relevant to most Web Service scripts, see the ‘Deadline.PulseUtils’ section of the Deadline Scripting Reference documentation. The full Deadline Scripting Reference can be found on the Thinkbox Software Documentation Website. Offline PDF and HTML versions can be downloaded from here as well.

Calling Web Service Scripts

Once the script has been created, you can call it using the web service. See the Web Service Documentation for more information on how to set this up. For example, if you have a Web Service script called ‘GetFarmStatistics.py’, you would call it using the following URL (where [myhost] is the hostname pointing to your web service machine):

http://[myhost]:8080/GetFarmStatistics

Some scripts can take arguments, as detailed in the previous section. To include arguments, you need to place a ‘?’ between the base URL and the first argument, with ‘&’ separating addition arguments. Here is an example of how you would pass ‘arg1’, ‘arg2’, and ‘arg3’ as a list of arguments to the GetFarmStatistics.py script:

http://[myhost]:8080/GetFarmStatistics?arg1&arg2&arg3

Here is an example of how you would pass values for arguments named ‘arg1’, ‘arg2’, and ‘arg3’ in the form of key-value pairs:

http://[myhost]:8080/GetFarmStatistics?arg1=value1&arg2=value2&arg3=value3

The way the results of the script will be displayed is entirely dependent on the format in which the Script returns them.

Migrating Scripts from Deadline 5

Some changes were made to the Scripting API in Deadline 6, which means that Deadline 6 and later are NOT backward compatible with scripts written for Deadline 5. However, migrating your scripts over is relatively straightforward, and this guide will walk you through the API changes so that you can update your scripts as necessary.

The only significant change is that the globally defined functions are no longer available. See the Migrating Scripts From Deadline 5 section in the Scripting Overview documentation for more information, including replacement functions.