Web Service

Overview

The deadlinewebservice application is a command line application for the Deadline render farm management system. It allows you to get query information from Deadline over an Internet connection, which you can view with the Mobile application, or you can write custom Web Service Scripts to display this information in a manner of your choice, such as a web page.

You can find the deadlinewebservice application in the Deadline bin folder (Windows or Linux) or the Resources folder (Mac OS X).

Setup

Before you can use the web service, you need to configure the general Web Service settings in the Repository Configuration.

../_images/cro_web_service.png

RESTful HTTP API

The RESTful API in the web service can be used to request information from the database, store new data, alter existing data or remove entries from the database.

See the REST Overview documentation for more information.

Additional Web Service Functionality

This additional web service functionality is still supported, but is now deprecated in favor of the new RESTful HTTP API.

Connecting to the Web Service

You can connect to the web service using a URL containing the host name or IP address of the machine that is hosting the web service application, as well as the port, which we will assume to be 8082 for now (this can be configured in the Web Service Settings). Note that if port 8082 is being blocked by a firewall, the web service will not be able to accept web requests. An example URL will look like the following:

http://[myhost]:8082/[command][arguments]

Where:

  • myhost is your web service server’s IP address or host name.
  • command is the command you want to execute. The web service can support two different types of commands, which are explained below.
  • arguments represents the arguments being passed to the command. This can be optional, and depends on the command.

To confirm that you can at least connect to the web service, try the following URL.

http://[myhost]:8082/

You should see the following if you connect to the web service successfully:

This is the Deadline web service!

Windows Namespace Reservation

If the web service is running on Windows, you may also need to add a namespace reservation for the current user that the web service is running under, so that it can reserve namespaces for the URL connection. See the Configuring Namespace Reservations section in this MSDN Article for more information. Note, Windows XP users require SP2 to be installed and XP 64bit does NOT support namespace reservation. It is recommended to use a server based Windows OS such as Windows 2003, 2008 R2, 2012 or newer.

Note that by default, the web service listens on http://*:8082/, so make sure you set the port number correctly in the URL you use when reserving the namespace. For example:

netsh http add urlacl url=http://*:8082/ user=USERNAME

Ensure you have correctly elevated permissions when executing the above in a command prompt and replace USERNAME with the appropriate %USERNAME% that the web service is running under. Depending on your local security policy, the user account may need to have local administrator rights temporarily for you to initially reserve the namespace. The namespace reservation will also need updating if you ever modify the port number or user account used. Use the following command in a command prompt to help list what namespace reservations are currently present on your machine:

netsh http show urlacl

Note that this is NOT the same reservation that is required for the Proxy Server.

Running Commands

The first set of commands are the same commands that you can use with the Command application. However, these commands are disabled by default. To enable them, you need to enable the Allow Non-Script Commands setting in the Web Service settings. If left disabled, you will see the following results when trying to call one of these commands:

Error - Non-Script commands are disabled.

Here is an example of how you would use the web service to call the -GetSlaveNames command:

http://[myhost]:8082/GetSlaveNames

Here is an example of the results that would be displayed:

Jupiter
Rnd-vista
Slave-29
Monkeypantswin7
Electron.franticfilms.com
Test3
Monkeypants
Slave-27d
Proton.franticfilms.com
Atom.franticfilms.com
Rnd-suse
Opensuse-64
Pathos
Neutron.franticfilms.com

Some commands can take arguments. To include arguments, you need to place a ‘?’ between the command name and the first argument, and then a ‘&’ between additional arguments. Here is an example of how you would use the web service to call the -GetSlaveNamesInPool command, and pass it two pools as arguments:

http://[myhost]:8082/GetSlaveNamesInPool?show_a&show_b

Here is an example of the results that would be displayed:

Monkeypants
Pathos

Calling Python Scripts

The second set of commands are actually Python scripts that you can create in the Repository. These scripts use Pulse’s Python API to get data, and then return the data in a readable manner. So basically, you can create scripts to access any type of data and display it in any way you want. See the Web Service Scripts documentation for more information on how to create these scripts.

Once a script has been created, you can call it by using the name of the script, without the .py extension. For example, if you have a web service script called GetFarmStatistics.py, you would call it using:

http://[myhost]:8082/GetFarmStatistics

Some scripts can take arguments. To include arguments, you need to place a ‘?’ between the command name and the first argument, and then a ‘&’ between additional arguments. Here is an example of how you would pass arg1, arg2, and arg3 as separate arguments to the GetFarmStatistics.py script:

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

The way the results are displayed depends on the format in which they are returned. Again, see the Web Service Scripting documentation for more information.

FAQ

Is Pulse required for the Standalone WebService to work?

No.