To use the API, integrator's will need to submit a request for creation of a Orien account with API access to all client data databases.
To generate an API key:
- Log into Orien with your user that has been granted permissions to access API Key Manager.
- Click on the top level hierarchy node for any client data and select Integration Config. Afterwards, click on the API Key Management option.
- In the following menu, click on the Create New option.
- Enter the details for your new API key and then select Save.
- Make sure to copy/paste the API key and store it somewhere as you will not be able to copy again after saving.
Orien Deployments & Endpoint URLs
Ausenco maintain several deployments of Orien that might run in a different version potentially with different customisations enabled. Each deployment of Orien will have a different endpoint with separate documentation.
Ausenco also mange several dedicated deployments for certain clients. Please contact support@orien.zendesk.com to find the correct deployment URL to use before implementing any integration solution.
Endpoint Basics
Ausenco will make best efforts to ensure no breaking changes are made to any existing API endpoint. In the case where changes are required a new endpoint will be created with a different version in the URL. Legacy endpoint versions will be maintained for as long as deemed necessary. Where multiple versions are available please try to use the latest version only.
All endpoints require the Content-Type header to be application/json. Any data from any endpoint will also be returned in json format. Apart from login all endpoints will require an authorisation token to be passed in an x-auth header.
Authenticating with Orien
All API routes require an authorisation token to be passed either as a http header or query parameter named x-auth. Authorisation tokens expire and will need to be re-generated as the first step in any integration project.
Authorisation tokens can be retrieved by passing the api key into the login route.
Orien Client Data & Location Tokens
Most Orien API routes will take either a location or client data token as parameters. Within Orien we recommend separation of data from different sites to different client data. Integrators will only have access to the client data(s) for the user that created the API key within Orien.
There are two ways to obtain a client data or location token to use as a parameter:
- Use the Client-Data-List Route: This will return all client data descriptions and tokens for which the API key has access. This could be used for example if an integrator wishes to download all the data they have access to.
- Retrieve the token from the Orien application URL: Within Orien browse to the required location in the application and you will notice the last part of the url is the location or client data token (e.g. https://au.orien.app/hierarchy/123). As an example, this could be used if the integrator wishes to upload measurement data for only a certain fleet within a client data.
Uploading Data to Orien - General Integrations
There are API routes available to upload data into Orien. These API routes are aligned to their respective GET routes within the swagger documentation. Swagger Docs can be accessed by adding '/api-docs' to the end of your server name: https://yourserverhere.orien.app/api-docs.
These APIs enable external systems and users to extract data, modify the payload, and post it back to Orien. Each API can be interacted with independently and can post data that doesn't originate from Orien. A Data Sync or integration session isn't required to post data through this route - only an auth Token.
{
"ignoreErrors": true/false,
"data": {
"integrationActionType": "create/update/delete (required)",
"hierarchyType": "components/assemblies/external/working (required)",
"description": "string (required)",
"removeReference": true/false,
"code": "string",
"type": "location/component/assembly/reference (required)",
"sortPosition": ,
"assetLibraryEnabled": true/false,
"opexEnabled": true/false,
"emissionsEnabled": true/false,
"custom": {
"customField1": "string",
"customField2": "string"
},
"make": "string",
"model": "string",
"costCentreCode": "string",
"inServiceDate": epoch,
"decommissionDate": epoch,
"accountableDate": epoch,
"meterReadingDate": epoch,
"meterReading": number,
"meterReadingUnit": "string",
"locationCategory": "string",
"hourlyDowntimeCost": number,
"token": "string",
"parentToken": "string",
"parentDescription": "string",
"parentCode": "string",
"constructionToken": "string",
"externalId": "string",
"externalParentId": "string",
"externalConstructionId": "string"
}
}{
"ignoreErrors": true/false,
"data": [
{
"integrationActionType": "create/update/delete (required)",
"locationToken": "string (required)",
"constructionToken": "string",
"description": "string (required)",
"code": "string",
"structureRevisionToken": "string",
"finalised": true/false,
"revision": number,
"working": true/false,
"approved": true/false,
"isRestricted": true/false,
"restrictedDate": epoch,
"restrictedBy": "string",
"createNewRevision": true/false,
"notes": "string",
"structureNodes": [
{
"integrationActionType": "create/update/delete (required)",
"parentNodeToken": "string",
"parentNodeDescription": "string",
"structureNodeMasterToken": "string",
"structureNodeToken": "string",
"structureNodeType": "string",
"componentRevisionMasterToken": "string",
"componentRevisionToken": "string",
"replacementInterval": number,
"replacementIntervalUnit": "string",
"budgetType": "opex/capex/non",
"description": "string (required)",
"replacementActivityDescription": "string",
"make": "string",
"model": "string",
"revision": number,
"finalised": true/false,
"working": true/false,
"finalisedAt": number,
"isRestricted": true/false,
"restrictedDate": epoch,
"restrictedBy": "string",
"activities": [
{
"integrationActionType": "create/update/delete (required)",
"activityToken": "string",
"description": "string",
"code": "string",
"acceptableLimits": "string",
"conditionalComments": "string",
"activityType": "string",
"constraint": "string",
"consequences": "string",
"origin": "string",
"accessTime": number,
"unscheduledOverheadHours": number,
"criticalActivity": true/false,
"performTacticReviewOnActivity": true/false,
"reviewPeriod": number,
"taskColour": "string",
"materials": [
{
"integrationActionType": "create/update/delete (required)",
"materialToken": "string",
"description": "string",
"code": "string",
"partNumber": "string",
"stockCode": "string",
"plantCode": "string",
"expenseElement": "string",
"stockClass": "string",
"unitOfIssue": "string",
"supplier": "string",
"manufacturer": "string",
"cost": number,
"quantity": number,
"currency": "string",
"isConsumable": true/false,
"isTrackable": true/false,
"isSapMaterial": true/false
}
],
"labours": [
{
"integrationActionType": "create/update/delete (required)",
"labourToken": "string",
"description": "string",
"code": "string",
"hourlyRate": number,
"work": number,
"required": number,
"currency": "string",
"expenseElement": "string",
"labourCategory": "string",
"productivityPercent": number,
"unplannedMaintenancePercent": number,
"notes": "string"
}
]
}
],
"functionFailures": [
{
"integrationActionType": "create/update/delete (required)",
"functionFailureToken": "string",
"function": "string",
"functionCategory": "string",
"functionType": "string",
"failure": "string",
"failureModes": [
{
"integrationActionType": "create/update/delete (required)",
"failureModeToken": "string",
"what": "string",
"mechanism": "string",
"cause": "string",
"strategyType": "string",
"redundant": "boolean;",
"beta": number,
"eta": number,
"gamma": number,
"unit": "string",
"notes": "string",
"failureModeActivities": [
{
"integrationActionType": "create/update/delete (required)",
"activityToken": "string",
"description": "string",
"actionType": "string",
"budgetType": "string",
"activityInterval": number,
"activityIntervalUnit": "string"
}
]
}
]
}
]
}
]
}
]
}{
"ignoreErrors": true/false,
"data": {
"integrationActionType": "create/update/delete (required)",
"hierarchyType": "components/assemblies/external/working (required)",
"description": "string (required)",
"removeReference": true/false,
"code": "string",
"type": "location/component/assembly/reference",
"sortPosition": number,
"assetLibraryEnabled": true/false,
"opexEnabled": true/false,
"emissionsEnabled": true/false,
"custom": {
"customField1": "string",
"customField2": "string"
},
"make": "string",
"model": "string",
"costCentreCode": "string",
"inServiceDate": epoch,
"decommissionDate": epoch,
"accountableDate": epoch,
"meterReadingDate": epoch,
"meterReading": ,
"meterReadingUnit": "string",
"locationCategory": "string",
"hourlyDowntimeCost": number,
"token": "string",
"parentToken": "string",
"parentDescription": "string",
"parentCode": "string",
"constructionToken": "string",
"externalId": "string",
"externalParentId": "string",
"externalConstructionId": "string"
}
}{
"ignoreErrors": true/false,
"data": [ {
"integrationActionType": "create/update/delete (required)",
"meterReadingToken": "string",
"locationToken": "string (required)",
"description": "string (required)",
"code": "string",
"meterReading": number ,
"meterReadingDate": epoch,
"lastReplaceDate": epoch,
"costCenterCode": "string",
"unit": "Cycles",
"custom": {
"customField1": "string",
"customField2": "string"
}
}
]
}{
"ignoreErrors": true/false,
"data": [
{
"integrationActionType": "create/update/delete (required)",
"operationLastPerformedToken": "string",
"operationMasterToken": "string",
"locationToken": "string (required)",
"locationDescription": "string",
"locationCode": "string",
"parentLocationDescription": "string",
"parentLocationCode": "string",
"description": "string (required)",
"number": "string",
"lastCompletedDate": epoch (required)
}
]
}{
"ignoreErrors": true/false,
"data": [ {
"integrationActionType": "create/update/delete (required)",
"productionToken": "string",
"productionDescription": "string (required)",
"productionPerHour": number,
"productionPerYear": number (required),
"unit": "string (required)",
"productionIntervals": [
{
"integrationActionType": "create/update/delete (required)",
"productionIntervalToken": "string",
"productionIntervalStartDate": epoch,
"productionIntervalEndDate": epoch,
"productionAmount": number
}
],
"locationUsage": [
"locationToken", "locationToken"
],
"structureNodeUsage": [
"structureNodeMasterToken", "structureNodeMasterToken"
]
}
]
}How to use the APIs - General Integrations
Orien's General APIs follow some general requirements and behaviours to maintain data integrity and to improve the speed of data processing. They are designed to be generic and easy to import data. By using the structures above, assets can be created and managed in bulk without users manually importing files and without a customised integration. Below is a table outlining the field and an explanation of its behaviour or specific fields:
| Field Name | Type | Reason |
|---|---|---|
| ignoreErrors | Boolean |
The entire payload will continue processing even if an error occurs. The incorrect payloads will not be uploaded to Orien. A list of error messages will be shown in the Data Sync module. |
| integrationActionType | Collection (create, update, delete) |
Defines whether the payload is creation of new data, update of existing data, or deleting existing data. This can determine what fields would be required for the payload. For Updates/Deletes, the token of the existing data is generally required. For Creates, as a token hasn't been generated yet, it's not required. |
| externalId / externalParentID | Identifier |
These External IDs are used as a identifier when there could be duplicate objects. These fields aren't stored in Orien after the data has been processed. |
| Epoch | Date |
Epoch dates are used for all date fields as they're understood and implemented the same universally. Negative Epoch times are also appropriate. |
Webhooks
Orien has many webhooks available to assist with Integrations. Webhooks are allocated to a Location - the Webhook is also applied to that allocated Location's children.
The Webhooks can be triggered by several actions in Orien depending on the type of Webhook. Below are each of the Webhooks and how they are triggered:
- Location Change - When a Location is created, updated, or deleted in Orien
- Tactics Finalisation - When a Tactics revision is finalised
- Packaging Finalisation - When a packaging revision is finalised
- Operation Work Instruction - When a Digital Work Instruction Payload is generated
- Opex Generation - When a location's Opex has been generated
- End data sync session - Whenever the specified Data Sync session is completed
Uploading Data to Orien (Data Sync)
Several data sync routes are provided for upload of data into Orien. The intention is that anyone performing an upload will create a data sync session for the upload. Orien users can inspect a history of data uploads from within the Orien application.
The design is such that the data sync session is separated from any upload process. It is intended that a session will start even before any data is prepared for upload. For example when uploading data from a CMMS if the integration tool was to crash Orien users would have details of a session that started but never ended.
The general recommended process is as follows:
- Call API to create session
- Prepare data for upload
- Send message to data sync session
- Upload data
- End data sync session
Work Instruction Data Export
For work instructions the Orien API has several specially designed routes. In Orien work instructions are generated for an operation.
Firstly, work instructions are retrieved using the "work-instructions" route. There is a lot of data associated with a work instruction so the number of results returned will be limited. Consumers of the API must take the "updatedAt" number of the last record and make subsequent calls to the API with this as the last parameter on the next call. When no more results are retrieved the consumer can keep the "updatedAt" and use it to load additional newly created data at a later date.
Secondly, the consumer should make a single call to "work-instructions-meta" which will return all locations for each operation. The consumer can then align the token from this route with the token from the work instruction route of previously downloaded operation work instructions.
For example, an inspection work instruction might have previously been created for five trucks. If a new truck is added to the fleet the work instruction will not have changed but the consumer will need the data from work-instruction-meta to able to identify that truck is relevant for the new location.
Exporting Data from Orien
As well as work instruction data, Orien also has several routes for download of other data. These routes will only return a limited result set and multiple must be made incrementing the "pageNumber" parameter until no more data is retrieved.
Dates & Times Within Orien
The Orien API uses the epoch unix time stamp for all dates and times in the API. This is a number representing the how many milliseconds have passed since January 1st, 1970 at UTC.
Orien has a few date/time concepts:
- Timestamp: The date/time something occurred within the system (for example, the date/time for update or creation of a record in the database).
- Date: Most dates within the application are date only fields (for example. meter reading date, budget period start date, etc.). Although the date will be a epoch unix time stamp in UTC, it is expected the date is to represent an event that occurred sometime within that day in the client data time zone.
- Date Ranges: - Again we use an epoch unix time stamp in UTC for both values however only the date portion will be used (for example, a report loading data with parameters start date of 0 and end date of zero would give all data for January 1st, 1970 within the client data time zone).