Interface Methods¶

Our recommended method for sending data to the Scheduling system is to use the Scheduling RESTful Gateway (SRG). Alternatively, it is possible to use the (WCF) Scheduling Gateway (GWY), however, the WCF version of the Gateway is now deprecated so we strongly advise that the SRG is used instead. It is also possible to use a file based method, but this is not recommended for production systems. Details of each of these methods are given in the corresponding sections below.

Schedule Input Manager File Interface¶

The software also includes the ability to process input XML documents stored in a defined folder. See the software installation notes for details on this file based interface.

PSO Workbench Methods¶

An external application can launch the PSO Workbench by sending a POST request to the /api/session page. The request body is a JSON object and the account id, username and password are specified in the "account_id", "user_id" and "password" properties.

If the request is successful, it returns an "access_token" property in the JSON object response body. This access token is specified on the query string to the PSO Workbench login page to automatically login, e.g. /Default/login?access=abcd12345678abcd for the Default account id. For further details ask an IFS consultant.

This access token is no longer restricted to the login page, it can now be used to start on any page in the application just by specifying the url e.g. /Default/scheduling/activity?access=abcd12345678abcd.

We prevent PSO Workbench from appearing in a frame from a remote host server without explicitly allowing the URL of the host on the PSO side. This is done by adding server URLs to the ‘system’ parameter called ‘WorkbenchHostURL’ in the head organisation. This parameter only needs to cover the server which hosts the calling application, not each client workstation that will be accessing the system. Multiple server URLs can be included separated by spaces, e.g. "https://server1/ http://domain/server2:port/" and "*" wildcards can be used for example "https://mydomain.com/*".

A token from the PSO Workbench cannot be used to access the Scheduling Workbench.

Other Workbench Url Parameters¶

When opening the PSO Workbench, the url can also contain for example:

• ?datasetId=MyData - to select dataset called "MyData" while opening any page in the scheduling or planning workspaces.
• ?localeCode=en-GB - to set the language to English after login while opening any page in the scheduling or planning workspaces.
• ?timezoneId=Europe/Lisbon - to set the timezone after login while opening any page in the scheduling or planning workspaces. IANA Timezones are supported

These URL Parameters are supported in any page in the scheduling and planning workspace.

When specifying multiple parameters, use ? before the first and & before each subsequent parameter, e.g. /Default/scheduling/activity?localeCode=sv&dataSetId=myData

OpenID Connect¶

If OpenID Connect is configured for the account, the external application must first obtain an OpenID access token from the OpenID provider. The OpenID access token is sent to the /api/session page in the "openid_access_token" property of the JSON request instead of the "user_id" and "password" properties. Username and password authentication is not possible unless the AllowAuthenticationGateway parameter is set.

Authentication Gateway¶

If OpenID Connect is configured for the account and the AllowAuthenticationGateway parameter is set, both OpenID and username/password authentications are possible. To perform a username/password authentication. the JSON request object specifies "account_id", "user_id" and "password" properties and must also set the "auth_gateway" property true.

Broadcast Workbench Changes¶

Broadcasting workbench data to an external endpoint can be used to add a intermediary layer between making manual changes on the workbench and that change being submitted to the PSO system to be processed. This may be required if all manual changes made on the workbench need to also inform an external service (outside of PSO).

This can be achieved by including a broadcast request of type 'WORKBENCH' in the input data. It is recommended to use the 'REST' broadcast type for this, and there is an example included in the next section.

The external service would then be expected to send the data received in the broadcast back into the PSO system. When doing so the PSO system will return an Input Id for the data, and this ID should be returned in the response message to the workbench broadcast. The change can also be rejected by the external system, and an error message returned which will be displayed to the user.

Broadcast PSO to external RESTful endpoint¶

The Schedule Broadcast Manager can be configured to post data out from PSO to a external RESTful endpoint. If required, set the 'broadcast_type_id' to 'REST' on the 'Broadcast' entity and continue to configure your requirements. The REST broadcast type can be used with all plan types, for instance broadcasting manual changes made by the Workbench or plans produced by the Dynamic Scheduling Engine. See the Scheduling Schema guide for more details on setting up broadcasts.

Broadcast parameters¶

The broadcast type 'REST' has parameters that will need configuring. PSO supports HTTP basic authentication which is secure when used with HTTPs. Authentication is not required and this broadcast type can be used without it.

Broadcast PSO Data¶

Allowed plan types; CHANGE, COMPLETE, INTERNAL, ADMIN

An endpoint is required for PSO to POST to, PSO will send the required data in the body of the request either as JSON or XML.

Example Request

JSON¶

POST https://MyHost/ReceivePSOData
Content-Type: application/json; charset=utf-8

{
    "ScheduleData" : {
        ...
    }
}

XML¶

POST https://MyHost/ReceivePSOData
Content-Type: application/xml; charset=utf-8

<dsScheduleData xmlns="http://360Scheduling.com/Schema/dsScheduleData.xsd">
    ...
</dsScheduleData>

Broadcast Workbench Data¶

Allowed plan types; WORKBENCH

An endpoint is required for PSO to POST to, PSO will send the workbench language id within the query string and the required data in the body of the request as either JSON or XML.

The external service would then be expected to send the data received back into the PSO system, returning the Input Id in the response message to the post request. See the previous section for further details relating to this process.

Example Request

JSON¶

POST https://MyHost/ReceivePSOData?languageid=en
Content-Type: application/json; charset=utf-8

{
    "ScheduleData" : {
        ...
    }
}

XML¶

POST https://MyHost/ReceivePSOData?languageid=en
Content-Type: application/xml; charset=utf-8

<dsScheduleData xmlns="http://360Scheduling.com/Schema/dsScheduleData.xsd">;
    ...
</dsScheduleData>

Example Response - Success

Return input reference id, the Scheduling Workbench will then display that the broadcast was successful.

JSON¶

Content-Type: application/json; charset=utf-8

{
    "result":1,
    "errorMessage":""
}

XML¶

Content-Type: application/xml; charset=utf-8

<BroadcastResponse>
    <Result>1</Result>
    <ErrorMessage></ErrorMessage>
</BroadcastResponse>

Example Response - Error

Return result of -1 and error message to be displayed on the Scheduling Workbench.

JSON¶

Content-Type: application/json; charset=utf-8

{
    "result":-1,
    "errorMessage":"example error message"
}

XML¶

Content-Type: application/xml; charset=utf-8

<BroadcastResponse>
    <Result>-1</Result>
    <ErrorMessage>example error message</ErrorMessage>
</BroadcastResponse>

Response Model

BroadcastResponse:
    Result : Int64,
    ErrorMessage : string

Modelling Interface¶

The Modelling Database holds data used by applications such as the Advanced Resource Planner (ARP). Data is input into the Modelling Database using the schema described in the Modelling Schema guide. The Modelling Database is a transaction database and updates may also need to be fed back to the external system. This ability is included in the Resource Planning service, which is able to extract data from the Modelling Database and pass it to the external application.

Modelling Data Broadcast Options¶

There are a number of options as to how and when changes made in the modelling database will be sent to an external system.

There are two options for the method of broadcasting the data. This is set using the parameter 'BroadcastARPDataOptions'.

• File - the data will be written to a file. The parameter 'BroadcastDirectory' must be set.
• Web service - the data will be sent to an external web service. This works in the same way as broadcasting scheduling data to a web service, except that the broadcast parameters are system parameters. The parameters 'WebServiceID' and 'WebServiceURL' must be set.

There are two options for the type of data sent - either COMPLETE or CHANGE. If complete data is selected then a complete copy of the dataset is broadcast every time. If change is selected then the data broadcast will detail the changes since the previous broadcast.

There are two options for when data is broadcast - either continuously or once per day. If broadcasting continuously the RPL service will check for changes on a regular basis (based on the parameter 'CheckForUpdateSeconds'), and send updated data if any changes are detected. If broadcasting once per day then the parameter 'BroadcastARPDataTimeOfDay' will be used to decide the exact time, and at this time the latest data will be broadcast (even if no changes have occurred since the previous day).

Update Poll¶

The update poll will check for any previously unreported updates. Updates to a dataset that occur before a LOAD of that dataset are ignored. Updates to a WORKINGSET Rota are ignored.

Modelling Data Input Example¶

A RAM_Update entity must be present in the data for it to be loaded. This applies to new loads or changes. For details on how to make changes to a record see RAM_Update in the Modelling Schema guide.

See training materials for full example.

<?xml version="1.0" standalone="yes" ?> 
<DsModelling xmlns="http://360Scheduling.com/Schema/DsModelling.xsd">

<!-- One RAM_Update row must be included -->
  <RAM_Update>
      <external_id>ABC</external_id> 
    <dataset_id>Default</dataset_id> 
    <organisation_id>1</organisation_id> 
    <ram_update_type_id>CHANGE</ram_update_type_id> 
  </RAM_Update>

<!-- This will either insert the row specified, or update the entire row if it already exists -->
  <RAM_Division_Type>
    <id>2</id> 
    <description>Region</description> 
  </RAM_Division_Type>

<!-- This will update a single column in a single row -->
  <RAM_Data_Update>
    <object_type_id>RAM_Location</object_type_id>
    <object_pk_name1>id</object_pk_name1>
    <object_pk1>1</object_pk1>
    <column_name>name</column_name>
    <column_value>new name</column_value>
  </RAM_Data_Update>

<!-- This will delete the specified row -->
  <RAM_Data_Update>
    <object_type_id>RAM_Location</object_type_id>
    <object_pk_name1>id</object_pk_name1>
    <object_pk1>100</object_pk1>
    <delete_row>true</delete_row>
  </RAM_Data_Update>

<!-- further updates -->

</DsModelling>