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

The Pulse application also has the web service built into it, so if you are already running Pulse, you can just connect to it directly instead of running the standalone deadlinewebservice application. That being said, there are a few benefits to running the standalone deadlinewebservice application if you are already running Pulse:

  • If you make heavy use of the web service, it won’t impact Pulse’s performance.
  • You can run multiple instances of the standalone deadlinewebservice application on different machines.
  • Migrating the web service to another machine doesn’t require you to migrate Pulse as well.

If you would like to use Pulse’s web service feature, you must enable it in Pulse, which can be done from the Web Service tab in the Pulse Settings in the Repository Configuration. Note that if you enable or disable the web service feature while Pulse is running, you must restart Pulse for the changes to take effect.

../_images/cro_pulse_web_service.png

Setup

Before you can use the web service, you need to configure the general Web Service settings in the Repository Configuration. These settings apply to both the standalone deadlinewebservice application, and Pulse’s web service feature.

../_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 8080 for now (this can be configured in the Web Service Settings). Note that if port 8080 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]:8080/[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]:8080/

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 that by default, the web service listens on http://*:8080/, 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://*:8080/ 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

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]:8080/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]:8080/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]:8080/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]:8080/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.