User's Manual

REST Client

Page Content

  1. Introduction
  2. REST Client API Documentation
  3. Requirements
  4. Simple use cases
  5. Advanced use cases
  6. FAQ / Troubleshooting

Introduction

With the REST Server started, the user can create a custom integration, using any programming language they desire, communicating with ROB-EX through the REST Server.

In the following we will give some requirements for implementing a custom REST Client, as well as some simple use cases.

To provide a little background about how REST calls work, then consider the service "/scheduler/v1/plan/order/{id}". This URL behaves differently depending what kind of HTTP request is made;

  • On HTTP GET, the call will return information about an order with the specified id
  • on HTTP POST, the call will create a ProductionOrder object with the specified id (additional parameters for the order may be provided as part of the Request Body)
  • on HTTP PUT, the call with create or update an existing ProductionOrder object with the specified id (additional parameters for the order may be provided as part of the Request Body)
  • on HTTP DELETE, the call will delete the order with the specified id.

The details about this service may be looked up in the REST Client API Documentation, by looking below “ProductionOrderResource” – see below on how to open the REST Client API Documentation.

REST Client API Documentation

The details about the different available REST services (termed resources in the REST world) are documented in two different ways

  • The interactive Swagger based API available at http://localhost:9998/apiexplorer/ once the REST server is running (change host and port number according to your local configuration). With this option you are able to interact directly with the interface. I.e. there are options to send test calls and immediately view the response.

Requirements

The requirements for implementing a custom REST Client are listed below:

  1. The same requirements as the REST Server (See the REST Server requirements)
  2. Some basic knowledge of how REST works.

Simple use cases

The following simple use cases, are based upon an example system where the REST Server is running on a host machine named “PC-REST” with port number “9998”.

For more info regarding the use of the REST API methods, please consult the REST Client documentation.

Get an Operation

Using the following URL
http://PC-REST:9998/scheduler/v1/plan/operation/R10 and change the method to GET.

This returns a JSON representation of the Operation (see the .NET API documentation) with id “R10”.

Get a unique field from an operation

Using the following URL
http://PC-REST:9998/scheduler/v1/plan/operation/R176/item/opr_state_level and change the method to GET.

This returns a JSON representation of the field “opr_state_level” for the Operation with id “R176”

Filter and sort operations on a specific resource

This is an example of how to lookup operations assigned to a specific resource – according to certain filter criteria’s

Using the following URL:

http://PC-REST:9998/scheduler/v1/plan/resource/R26/operations?filter=opr_state_level lt 40&filter=opr_start_time gt 2015-02-23T10:34:00Z&sort=asc opr_start_time

setting the method type to GET.

This will return a JSON representation of the sorted list of operations that meets the filter criteria’s

  • Operation state is less than 40
  • The operation start time is greater than specified date and time (note that the date is in the time-zone of the ROB-EX client hosting the REST server)
  • The list is sorted ascending according to operation start time

The variable names used (e.g. opr_state_level) may be looked up in the Variable list.

Additional filter criteria’s may be added as needed, just separate each filter by a ‘&’ sign. Note that each filter added is added with a logical AND, i.e. all filters must

The following filter comparisons keywords are supported

Operator name Keyword
Equal eq
Not equal not eq
Less than lt
Greater than gt
Contains contains

The following sort keywords are supported

Operator name Keyword
Ascending asc
Descending desc

Filter and sort operation and get specific variables (layout items)

Using the following URL:

http://PC-REST:9998/scheduler/v1/plan/operations/layoutItems?sort=asc opr_start_time&filter=opr_state_level gt 10&filter=opr_state_level lt 90&layoutItems=opr_resource,opr_name,opr_start_time,opr_end_time

Will get:

  • The fields: Resource name, operation name, start and end: layoutItems=opr_resource,opr_name,opr_start_time,opr_end_time
  • Filtered by operation state > 10 and < 90: filter=opr_state_level gt 10&filter=opr_state_level lt 90
  • Sorted by operation start: sort=asc opr_start_time

The *variable names*(layoutItems) used (e.g. opr_name, opr_start_time) may be looked up in the Variable list.

Delete an Operation

Using the following URL, http://PC-REST:9998/scheduler/v1/plan/operation/R10 and change the method to DELETE.

This will delete the Operation with the id “R10”.

Create production order based on existing master route

Use the following URL, http://PC-REST:9998/scheduler/v1/plan/order/master and change the method to POST.

Add the following parameters to the post data to specify order and master route information. Note that you may leave out order id and name, in which case ROB-EX will automatically assign the next id and name to the order

{
  "masterRouteName": "JobType1",
  "masterRouteAltName":  ",
  "productName": "Test drive",

  "order": {
    "id": "2000",
    "name": "2000",
    "quantity": 20,
    "deliveryCalendar": "2016-1-13T23:00",
    "materialCalendar": "2016-1-5T15:00",
    "customer": "customerName",
    "description": "description text",
    "priority": 8,
    "customText1": "custom text 1",
    "customText2": "custom text 2",
    "customText3": "custom text 3",
    "customText4": "custom text 4",
    "state": 20
  },

  "schedulingSettings": {
    "strategyName": "ForwardFromMaterialDate",
    "externalDependencies": "Ignore"
  }
}

Create production order by supplying route and operations

Use the following URL, PC-REST:9998/scheduler/v1/plan/order/helper and change the method to POST.

Add the following parameters to the post data to specify order, production order route and operation information (note that additional operations may be specified with the square brackets [ ] using standard JSON array notation). Note in this example order id and name is not specified, in which case ROB-EX will automatically assign the next id and name to the order

{
  "order": {
    "quantity": 20.0,
    "deliveryCalendar": "2015-1-1T23:00",
    "materialCalendar": "2015-1-1T23:00",
    "customer": "customerName",
    "description": "description text",
    "priority": 8,
    "customText1": "custom text 1",
    "customText2": "custom text 2",
    "customText3": "custom text 3",
    "customText4": "custom text 4",
    "state": 20
  },

  "routeHelper": {
    "route": {
      "name": "TestRoute"
    },
    "operations": [
      {
        "name": "TestOpr",
        "selectedResourceId": "R8",
        "workload": 20.0
      }
    ]
  },

  "schedulingSettings": {
    "strategyName": "ForwardFromNow",
    "externalDependencies": "Ignore"
  }
}

Advanced use cases

Get an AnalysisResult

Using the following URL, http://PC-REST:9998/scheduler/v1/plan/analysis and change the method to POST.

Add the following analysis parameters to the post data, will yield a resource analysis result, for all resource on a daily basis starting from 2014-06-16 and ranging 3 days. Customization of the analysis result is done by changing these parameters. See the REST Client documentation of a complete overview of the available parameters.

For a overview of the data model for the AnalysisResult, see the .NET client under advanced use cases.

{
  "resolution": {
    "start": "2014-06-16T00:00:00",
    "count": 3,
    "resolutionStep": "DAY"
  },
  "resultTypesToInclude": [
    "RESOURCE"
  ],
  "includeMasterData": "false"
}

FAQ / Troubleshooting

As a rule of thumb, standard HTTP error codes are returned. These can be looked up to give an indication of what the problem might be. Further more, the log might contain indication to the error as well.

In the following, common problems and their solutions are described.

Webpage not available

If you see the “This webpage is not available” or similar error, then it is most likely due to a malformed url or the REST server is not running.

Check that the REST server is running, that the hostname and port number are correct and that the URL you are trying to reach is spelled correctly.

204 No content

The 204 error indicates that the request to the server was successful, but it did not return any content. This can happen e.g. when trying to get a resource using an id that does not exist.

Check that the basemodel object that you are trying to reach actually exists.

400 Bad request

The 400 error indicates a bad request to the server.

Check the ROB-EX client log for further indication of what the cause could be. Typically, this will be cause by missing parameters.

404 Not found

The 404 is a standard HTTP error code that indicates that the client was able to communicate with the server, but the requested page could not be reached.

Check that the URL you are trying to reach is spelled correctly.

405 Method not allowed

The 405 is a standard HTTP error code which indicates that the method used was not allowed. This could be a POST call to a resource that only allows GET calls.

Check what the resource you are trying to call has of available HTTP method calls.

Feedback

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.

Post your comment on this topic.

Post Comment