REST Server

Page Content

1. Introduction
2. Requirements
3. Starting the REST server
   1. Test connection
4. FAQ / Troubleshooting

Introduction

When enabled, the REST Server, provides the user with a REST Based Client API (a set of web-services). This allows for custom integration with Proficy Scheduler as well as being the foundation layer for modules like Time Tracker. Some services provide options to create, read, update or delete basic objects in Proficy Scheduler (e.g. Operation, Resource, ProductionOrder etc). Other high level services allows for e.g. the creation and re-scheduling of orders and operations. The input and output from the REST server is using the JSON format . For a complete set of services, see the REST API documentation

The services available from the REST API have also been implemented as a .NET Assembly deployed as Robex.Scheduler.dll (see drawing below). The Robex.Scheduler.dll communicates with the REST Server through the REST API thus hiding all the REST details. For further information, including getting started examples in C#, see the .NET Client documentation.

A third option is to program a client using Proficy Workflow using the supplied Proficy Scheduler Workflow Client. With this service provider installed into Proficy Workflow, all the services are easily available inside Workflow. For further information regarding this, read the Proficy Scheduler Workflow Client documentation and also see the .NET Client documentation, since these have identical services/methods.

!This .NET Client dll and the Workflow Client is no longer being updated and we recommend to directly use the web-service based REST Client API.

For an overview of the architecture, see the image below.

The following is a description of how to get the REST Server started as well as doing doing basic work with the API.

DLL files

The DLL files are located in

<sch_client_dir>\plugins\rest\dotnet\bin

RestSharp.dll
Robex.Scheduler.dll  (requires RestSharp.dll)
Robex.Workflow.dll   (requires Robex.Scheduler.dll)

make sure to place these DLL files in a location where they will be located by your .NET IDE and during execution of your .NET deployment.

Requirements

The requirements for using the REST Server are listed below.

1. Proficy Scheduler version 5.2 or newer
2. License to Proficy Scheduler REST Server (menu Help->Register)

Starting the REST server

The REST Server is incorporated as a module build into the Proficy Scheduler Planner Client. In production is it best practice start the REST Server on a client that runs using the Client run as service option. Note that the REST Server is automatically started when the client is configured to run as an Integration Client service.

Alternatively, to start the REST Server on any Desktop Planner Client, add the following parameters on the Proficy Scheduler exe shortcut (for info on adding parameters on the shortcut see Starting up the client)

-Dgantt.rest=true

For enabling Basic Authentication, the following parameters may be added

-Dgantt.rest.username=
-Dgantt.rest.password=

The selected <username> and <password> are used for Basic Authentication. See here for supported authentication options.

Optionally, the port number and host to listen on can be changed using the following parameter, i.e. this is needed in case of running multiple Proficy Scheduler REST Server clients on the same PC or the default port number (see Test connection) is already occupied by another application:

-Dgantt.rest.portnumber= (default=9998)
-Dgantt.rest.host= (default="0.0.0.0" = all)

If the REST api is used from browsers the browser will check for “cross domain resource sharing” (http://enable-cors.org/index.html), Per default the rest service will allow rest calls from all domains (“*”) to control which domains to allow calls from use the setting below:

-Dgantt.rest.allowOrigin= (default="*")

If the server has been started properly, the following output should be visible in the log-file:

RestServer init called
Run rest service: true
Rest server scheme=http
Rest server hostname=
Rest server portnumber=

Test connection

For testing purposes we recommend using an App like Postman, see setup instructions below.

To test that the connection to the REST Server is working try accessing the following URL from within the Postman App: http://<*hostname*>:<*portnumber*>/scheduler/v1/service. Where <hostname> is the hostname of the machine where the REST Server is running and <portnumber> is the selected port number (default is 9998).

If the REST server is working, this will now display info regarding the Proficy Scheduler client (e.g. version number, memory consumption, etc.).

Setting up Postman

1. Install the Postman App
2. To access the REST API there are some settings that need to be set in Postman. Select the authentication method that corresponds with how you configured the REST server (see here for supported authentication options). Then click the Refresh headers button. This will add an authorization header to the HTTP calls.
3. Also is it necessary to set the content-type in the HTTP headers to application/json.

FAQ / Troubleshooting

The REST Server did not start

Search in the log for a line similar to: “Unable to start REST Server on http://<hostname>:<portnumber> java.net.BindException: Address already in use: bind”.

If this line is present in the log, then the error is most likely that the provided portnumber is already in use. Select another port number and try again.

I get a “401 Unauthorized” message

This can be caused by one of two things:

1. The username or password was not set. In this case there should also be a message saying “Authentication credentials are required”. Check that the commands added to the shortcut are spelled properly.
2. The username or password was wrong. In this case there should also be a message saying “Invalid username or password”. Check that the username and password chosen during startup of the REST Server are the same as provided to Postman.