Orien provides industry standard Self-Service RESTful endpoints to facilitate the consumption of work instructions for display in third party Digitalised Work Instruction Platforms (DWIP). This document will provide the basic configuration, call procedures and technical objects required for seamless integration.
Current implementation facilitates a polling methodology.
Technical Resources
Swagger API Documentation can be located at https://dev.orien.app/api-docs/
Prerequisites
Users will require:
- Access and API permissions to authorised Orien deployment.
- Orien Self-Service API Key. For details on configuring an API key please refer to the article on Self Service API Documentation.
API Workflow
The flowchart below provides an overview of the API workflow.
Core API's
Please refer to swagger documentation (listed above in the Technical Resources section) for further options and technical details.
Login (/api/ss/v1/login)
Requires a valid, non-expired Orien Self-Service API key to be passed in the body JSON payload.
Returned payload contains a JWT token required for all future communications with RESTful API. Note: this token has an expiry period.
List of client data databases (/api/ss/v1/client-data-list)
Provides a list of all accessible client databases that associated API user has access to. The associated token value within the return payload is used for all future calls to API. There is no ability to query from all client databases at the same time. Individual calls must be made to each. JWT token must be passed via header variables for authentication.
Work Instructions (/api/ss/v1/work-instructions/{clientDBToken})
Orien’s representation of the JSON Work Instruction Document Data generated from the activities and details of an Operation. Orien Operations align to the SAP structure of a Task List Operation. However, Orien extends the implementation to associate the Activities performed on these operations to facilitate the generation of paper-based or digital work instruction documents.
For data to be made available to the API, a functional location must have “Finalised” packaging and either Integration Steps (see section below) configured or paper-based exports have been performed for each Operation. For further information on package finalisation please refer to the Orien User Guide.
This API requires the client database token to be passed in the route. There are three ways this route can be called to customise the data returned. All routes are restricted to 1000 records returned unless a limit value is provided in query parameters.
- Base route (no additional parameters or path options): Returns all Finalised and generated Work Instructions from desired database.
- Base route plus additional JavaScript date number: Returns all work instructions that have been modified after the date provided.
- Base route plus query parameters to filter by Operation Name or Token: Returns all work instructions matching name or token provided.
For further detail refer to the section below on Work Instruction Payload.
Work Instruction Meta (/api/ss/v1/work-instructions-meta/{clientDBToken})
Orien provides users the ability to define “Assembly” assets and reference them throughout the system. These references can contain Operations, providing a similar concept to SAP General Task Lists. Thereby this route will provide the list of available Work Instructions and their associated functional locations.
Example: For a fleet of referenced assembly trucks, their operations will only appear once in the previous route due to it being associated with an assembly. However, each truck will have its functional location listed in this route against that operation. Link between work instruction and work instruction meta routes is the “token” property.
Data Capture Points
Data Capture provides the facility for users to define additional data metrics for consumption by Digitalised Work Instruction Platforms (DWIP’s). These metrics will define the questions within the DWIP’s presented to users while executing a work instruction document per activity (e.g. check engine oil)
Orien provides a very flexible implantation allowing for easy integration but also standardisation across the system. Facilitating more accurate data with less variance or corruption.
Data Capture Flags
- Define properties of a specific data capture definition type.
- Values are provided at the data definition level.
- Special flags for data capture definition “options”
- Allowed value types: Text, Numeric, Dropdown, Boolean
- Example: Image Capture Type (Dropdown: Image, Photo, Drawing)
Data Capture Customisations
- Define properties for user entry at the Activity Level.
- Allocated to Data Capture Definitions
- Allowed value types: Text, Numeric, Dropdown, Boolean
- Example: Range – Max number value (Numeric)
Data Capture Definitions
- Define properties for user entry at the Activity Level.
- Links Flags and Customisations together to form a “template” users can allocated against activities.
- Standardises the user input allowing for accurate data is self service API
- Ability for site to define an “approved” list of data captures that will be rolled out throughout the system.
- Define multiple “steps” of required data to complete activity.
- Has an “Option” type which is captured at the DWIP layer. Example of this is standard “1 | 2 | 3 | 4” response found on existing work instruction documents. These options have a description, code and any special “Option Flag Only” Data Capture Flag values.
- A code field to identify the same Data Capture Definition in different languages or to enable the same Description to be used for multiple definitions
- Types available: Checkbox, Date, Image, Numeric, Option, Text and Time. For example:
-
-
Definition: Temperature
-
- Step 1: Take oil Temp.
- Type: Numeric Type
- Customisations: Upper Range, Lower Range, Precision (provided per activity)
- Flags: Mandatory (true)
-
-
Definition: Temperature
-
User Guide for Data Capture Points
While viewing the Data Capture Definitions, you are able to view the Steps and to see what activities these Definitions are Used In. The Used In button shows each location where the data capture is currently being used. This can be used to identify where a Data Capture point is used database-wide.
Steps
The steps assigned to each data definition are the stages of each data capture point that need to be completed.
Each step can be allocated to be one of the selected capture types. These are:
- Check Box
- Date
- Image
- Numeric
- Option
- Text
- Time
Customisations
Once the Capture type has been defined, you'll be able to apply any customisations that have been set previously to the data capture definition. These customisations can be configured to only appear for specific data capture types e.g. Lower Limit on a Numeric Capture Type.
Flags
Once the customisations have been selected, you'll need to fill in the Data Capture Flags that have been assigned to the Data Type. In the example below we have a 3 flags assigned to the data capture type of Image: Forced Criticality (Dropdown), Forced Required (Checkbox) and Image Capture Type (Dropdown).
Output in API
Data capture points will appear in the JSON payload of the work instruction against each Work Package Task object. Below is an example.
Note
Boolean Data Capture flags will remain as a false value when removed from Data Capture Definitions. All other flags will be removed entirely from the JSON payload.
Integration Steps
Integration Steps are a post packaging approval process that can facilitate a selected set of operations depending on the clients needs. With respect to Work Instruction API and DWIP’s, Integration steps can be utilised to generate all JSON documents post approval allowing for exposure to API. Additionally, proves the function to create DIR record numbers within SAP if SAP endpoint has been configured.
Currently there are three available integration steps on offer:
-
Email Notification:
- Send Email to fixed email address upon finalisation.
-
Work Instruction Generation:
- Builds all work instruction json payloads for approved location.
- Integration step parameter "location" restricts the automatic json payload generation to that provided location and children.
-
DIR Key Creation:
- If SAP route configured on client side, will send a request per Orien Operation with a fixed payload and expected response of either a new DIR number or existing DIR number.
- For further details please contact Orien Technical Team.
- Refer to the section below on Integration Step - SAP DIR Creation for technical data.
Note
Additional web-hooks could be created at client request and as a scoped project.
Work Instruction Payload
Instructions (Root)
| PROPERTY | DESCRIPTION |
|---|---|
| instructions | Collection of all work instructions returned from API route. |
| token | Orien Token to link directly to the associated Operation. Can be used as a parameter in API filters to return that specific operation. |
| workInstruction | Work Instruction JSON payload with all details provided for digitalisation. |
| updatedAt | Date JSON payload was last updated. |
| active |
Whether Operation still exists in Orien. If Operation or Packaging is deleted then active will be set to 0.
|
Work Instruction (Orien Operation)
| PROPERTY | DESCRIPTION |
|---|---|
| Tools | Operation Custom Costs that are flagged with a cost type of “Tool” and associated details. |
| Labours | Operation Labour and associated details. |
| Materials | Operation Materials and associated details. |
| TaskEquipments | Operation Custom Costs that are flagged with a cost type of “Task Equipment” and associated details. |
| WorkpackageTasks | Operation Activities and associated details defining the actions to be performed to complete this Work Instruction. E.g. Check Engine Oil. |
| Symbols | Distinct list of Symbols and their Base64 image. This is the master collection that is referenced by “Id” within the “WorkpackageTask” object. |
| WorkpackageGroups | Distinct List of Activity Groups assigned to “WorkpackageTask”. Orien facilitates the ability to group allocated activities together into sub-groups. Note: Activity groups does not mean all tasks appear next to each other, it is just an activity association to a group. The Id property can be used to link with “WorkpackageTask.TaskGroupId”. |
| EquipmentEntities | Distinct List of Functional locations that have Activities allocated to the Operation. The Id property can be used to link with “WorkpackageTask.EquipmentEntityId”. |
| WorkpackageDetails |
Operation and associated details.
|
Work Package Tasks (Orien Operation Activities)
| PROPERTY | DESCRIPTION |
|---|---|
| Id | Orien Token Id Operation Activity Record. |
| Name, Code, AcceptableLimits, ConditionalComments, Justification, Constraint, Consequence, Origin, Notes, TaskColour, TaskType, ConstraintObject, TaskMetaFields | Details of Orien Activity. Note: Meta Fields represent “Orien Custom Fields” and their assigned values. |
| RowOrder | Order this activity appears in the work instruction document. |
| TaskGroupName and TaskGroupId | The sub-group of allocated Orien Activity. Can be linked back to “WorkpackageGroups” as defined earlier. |
| EntityId, EntityName, EntityCode, EntityPath, EntityNotes, EntityComments, EntityCostCentreCode, ComponentMetaFields | Orien Structure Node (Component) details that are associated with the allocated Activity. Note: Meta Fields represent Orien Custom Fields and their assigned values. |
| ParentEntityId, ParentEntityName, ParentEntityCode, ParentEntityPath, ParentEntityNotes, ParentEntityComments, ParentEntityCostCentreCode, | Not populated at present. |
| EquipmentEntityId, EquipmentEntityName, EquipmentEntityCode, EquipmentEntityPath, EquipmentEntityNotes, EquipmentEntityComments, EquipmentEntityCostCentreCode, EquipmentMetaFields | Orien Functional Location details associated with Orien Structure Node. Note: Meta Fields represent Orien Custom Fields and their assigned values. |
| ExcludeFromWorkpackage | Flag to indicate whether this specific activity should be displayed in work instruction export or ignored. When set to “false” activity should appear for users to provide detail. |
| Critical | Flag to define if Orien Activity is considered critical. |
| TaskImages | List of assigned Orien Activity Images and their associated Base64 encoding. |
| Symbols | List of assigned Orien Symbols and their identifiers. These are used to link back to master list to retrieve Base64 encoding. |
| DataCaptures |
List of Orien Data Capture Points and associated details.
|
Key Points - Activity Ordering
Activities associated with an operation within Orien can be ordered by users manually. This ordering comes out in the “RowOrder” property of the JSON object. This is the driving order of activities irrespective of any additional data like “TaskGroupName”.
Even though activities can belong to the same group, same entity or same equipment they can be ordered completely independently. It is recommended that DWIP’s provide the facility to match the activity orders according to “RowOrder” and not alpha numeric sorting of other fields.
Workpackage Details (Orien Operation Details)
| PROPERTY | DESCRIPTION |
|---|---|
| Id | Orien Token to link directly to the associated Operation. Can be used as a parameter in API filters to return that specific operation. |
| Name, Code, PostShutdown, TaskPreparation, JobDescription, SequenceNumber, AccessTime, OperationNumber, JobDescriptionNewLine, Frequency, FrequencyUnits, Constraint, WorkPackageMetaFields, AdditionalData, ConstraintObject | Orien Operation and associated details. |
| EntityId, EntityName, EntityCode, EntityNotes, EntityComments, EntityCostCentreCode, EntityMetaFields | Orien Functional Location details associated with Orien Operation. Note: Meta Fields represent Orien Custom Fields and their assigned values. |
| Signatories | List of signatories required for signing off Operation. |
Integration Step - SAP DIR Creation
SAP DIR Creation integration step provides third party clients the ability to configure an SAP API endpoint to automatically create or validate DIR records of Finalised Orien Operations. The following integration step if configured is executed upon “Packaging Finalisation” and endpoint hit for each operation accordingly, irrespective of existing DIR value or not.
Request payload to external API
Request is made through a POST request with JSON body data.
| PROPERTY | DESCRIPTION |
|---|---|
| clientDataToken, clientDataDescription | Orien Token to link directly to the associated client database. Can be referenced against Client Data API. |
| description, requestToken | Orien Operation description and token. Can be referenced against Work Instruction API and Work Instruction Meta API. |
| documentIdentifier | DIR number stored within Orien Custom Field if provided to step configuration. |
| maintenancePlanningPlant | Orien Custom Field value if provided to step configuration. |
| locationCode | Orien Functional Location Code. |
| revision | Orien Packaging Revision Number. |
| documentOwner | Creator of packaging revision. |
| externalRequestSystem | Orien name plus version number. |
Expected Response
| PROPERTY | DESCRIPTION |
|---|---|
| documentIdentifier | DIR number to be stored within Orien Custom Field if provided to step configuration. |
| requestToken | Orien Operation Token. Can be referenced against Work Instruction API and Work Instruction Meta API. |
Error handling
If an error occurs in the request call or response it will trigger that packaging revision to fail and roll back to a working state with error message stored against packaging notes. It is the responsibility of the user to re-submit that packaging for finalisation and communicate with any third-party provider if process continually fails.