API Capabilities - v11 Upgrade

In version 11, OFS introduces a variety of new API capabilities. This article explains each use case with examples of how they can be used.

The Overview

OFS v11 introduces the following API improvements

• Operations State Machine API
• Schedule Integration via API
• API Exports
• Ability to Send Timestamps with Data
• Raise Flow Forms with Pre-Filled Data

 

Operations State Machine API

The Operations State Machine API is a newly introduced API in OFS v11 which is designed to make a significant difference to OFS capabilities to integrate with external systems. In designing new models like our Asset Monitoring capabilities, OFS have dependencies on external systems to provide information via API.

To do this, we have built an ability for external systems to dispatch events to OFS via API. There are new API methods allowing external systems to list all events known to OFS, check which are valid given the current set of states, and action the events known to the state machine, via the 3 endpoints listed below: 

• /server/events/fire/{eventName}
  • Fire the named event
• /server/events/list
  • Return a list of all known events
• /server/events/listValid
  • Return a list of all valid events

---

Schedule Integration via API

For a long time, OFS has been able to ingest schedule information via XML documents exchanged with external systems. The OFS-specific XML format has been ingested and parsed by the receiving OFS server.

To make this integration easier for clients in the API-age of internet connected systems, OFS have made it possible to send OFS formatted XML Schedule information directly to a client's OFS software via HTTP POST API Call:

• /schedule/xml/overwrite
  • POST content to this endpoint to ingest as XML Schedule information

 

---

API Exports

Within OFS Analytics, it is possible to segement data by product or by crew. Some clients have expressed an interest in optionally partitioning the data they review in external systems like Microsoft Excel or Microsoft PowerBI by both product and crew.

Typically this view is expected to be useful only to customers who routinely run the same jobs across multiple different operators, but in this circumstance, there may be valuable insights to be obtained by comparing these highly segemented data sets.

OFS v11 introduces a capability to export data from the OFS Export APIs which is segmented by crew and product. This applies to both reason and productivity data.

These reports must be manually enabled by OFS on a per-client basis as they have an expected performance impact which should be considered, but if you are interested in exporting data partitioned by both product and crew then you should contact your OFS representative or OFS Support.

---

Timestamped Data Endpoints

Many OFS deployments send data over the internet via API calls, and are susceptible to dropouts of connectivity which could impact OFS data-recording performance.

OFS is testing and has introduced in v11 some new capabilities to data ingesting APIs which allows for a timestamp to be associated with the datapoint which is being sent via API.

In the future this may allow for buffering of information in OFS devices, to ensure that no information is lost when devices fall offline, and information can be replayed at the server at a later date/time.

OFS will continue to internally develop and test such solutions and hope to innovate further in this space in the future.

---

Raising an OFS Flow Form with Pre-Filled Data

In the OFS v11.4 release, we are introducing an API which allows for the creation of an OFS-Flow alert which contains pre-filled data populated by the API request itself.

This is motivated by an increased desire to integrate external systems with OFS-Flow, for the digital acquisition of factory data, like checkweigher information. Our new API capability simplifies the workflow for this data acquisition.

Previously, when an external system wanted to provide data into OFS-Flow, the required workflow was to:

• Use the /alertraise API to create a form in its default workstate. 
• Query the OFS Alertstore with the /alertstore/query API, to identify the raised form.
• Add data to the retrieved flow form object, in the correct format.
• Send the flow form object back to the alertstore/submit API.

Using the new Pre-Filled Data Capability

With this new capability, OFS Flow Forms can be seeded with initial data with ease via the OFS APIs.

• The /alertraise/ API after v11.4 supports an optional body content. 
• The supported format is a POST request with a body formatted as
  application/x-www-form-urlencoded data
  • Within the form content, each form field name is matched to OFS-Flow form content. 
  • The form to be raised is specified as the configUID parameter.
  • When the form is raised, the fields of that form are checked for matching content from the request body form.
    • Application Form content consists of a key and value pair. The key is matched to the form field name, and the API tries to use the value as the form field's initial value on form startup.
  • If form field names do not exactly match, no action is taken.
  • An error is raised if your API request contains duplicate form field names in the body content.