Our product vision is to make maintenance data available outside of the ERP system, to keep it relevant and updated, while also inspiring and enabling for innovation.

The API is designed and built according to Equinor's API strategy.

The API is documented in OpenAPI 3.0 format and follows REST principles.

A simple way to test the API is through Postman which is accessible through AccessIT.

The APIphany team also do conceptual development together with the consumer. Event Driven architecture is one example. Another example is for Condition Based Maintenance (CBM).

The API will use common terminology used across the Oil&Gas industry for the maintenance process. Norsok standard NS-EN 13306 and ISO 14224 are key resource in the naming of resources in the API.

api-version must be present in all request as part of the query string. Requests without API version will be rejected with a HTTP 404 response code. The latest api-version is v1.

deprecated 2022-08 The subscription key is as of release 1.11.0 phased out and therefore HTTP header ocp-apim-subscription-key is no longer required for requests. This is a non-breaking change and clients are unaffected if the subscription key is still sent.

The Maintenance API will combine information from various business systems in Equinor used in the maintenance area through one common API.

Currently, the majority of endpoints connect to Equinor's ERP system based on SAP.

API Request Limits

A safeguard has been put in place in order to not overload the backend systems. It is set up so that each consumer has a fixed number of concurrent requests that they can execute at the same time. If the amount of requests exceeds the limit, requests may be put into a queue, awaiting execution. If the queue is also filled up, the API will start to respond with 429 - Too Many Requests responses. The consumer will have to back off and reduce the amount of concurrent requests (by waiting for the active requests to finish) before issuing more. The current limits per consumer is:

• Concurrent Requests: 50
• Queue Limit: 0

Using Version Line

In our QA environment (https://api-test.gateway.equinor.com/maintenance-api) you can route your request towards the version line client instead of the default production line. This is helpful in role building scenarios which is typically done in the version line (Q83) or if the production line (Q93) is down due to maintenance or updates.

To route a request towards the version line, include the query parameter use-version-line=true in your request. This parameter will default to false if it is not included.

Using Field Selection as a query parameter

In our API, you can customize the response by specifying which fields to include using the selectFields query parameter on all Lookup endpoints. This allows you to tailor the data returned based on your needs, improving efficiency and reducing unnecessary data transfer.

To include specific fields in your response, add the query parameter select-fields to your request, followed by a comma-separated list of the desired fields. This allows you to limit the data returned to only the fields you need, which can improve performance by reducing the payload size. For example, if a resource has properties id, name, and description, a request with selectFields=id,name will return only those two properties.

If the select-fields parameter is not included, all available fields will be returned by default.

The user executing the API requests will need to authenticate with OAuth 2.0 authorization code flow with Equinor Azure AD as the identity provider.

The user needs to exist and have authorization in Equinor's ERP system. Equinor Azure AD affiliated users are not supported as the user does not exist in Equinor's ERP system. In special cases, system to system integration can be setup; see section Client setup->System to system setup for more information.

Applying for access is handled by the internal AccessIT solution and the following roles are required:

• SAP P05: YO900 - OM Mobile Apps & API (SAPP05)
• SAP P03: General Operation & Maintenance roles for P03

Note: YO900 replaces old role YT105. YO900 is normally only required in SAP P05. For SAP P03, it's in most cases covered by general operation & maintenance roles (as they include YO900/ZO900).

Note: If the user should have only display access through the role YO001 - Display role O&M or YO017 - Display role O&M External, they need the YT105 - OM Mobile Apps & API (SAPP03) role in addition.

General operation & maintenance roles depend on the function of the business users. For employees, it's typically YO001 - Display role O&M and YO002 - Operations & Maintenance Executor. For consultants, it's typically YO017 - Display role O&M External and YO011 External - Support Executor. For contractors, the roles are covered through ACM positions assigned and approved by the vendor company (YO301_01 is an example of a role defined for contractors). More information can be found in governing document GL0446 - SAP roles in operation, maintenance and modifications.

For Maintenance API QA environment, consumers will need to apply for same roles in SAP QA systems Q05, Q93 and Q83 (used during planned downtime for Q93).

SAP ARM

The Access Request Management (ARM) system is used to apply for roles in SAP non production environments. The ARM system is available at the following link

Lotus Notes (deprecated)

The KB0036937 defines the procedure for applying for roles in the SAP QA environment.

The API allows you to get mock response for all endpoints if required. This can be useful in special cases. For example if developers from external companies do not have (and should not have) authorization in Equinor's ERP system, they can still interact with the API to see the possibilities.

Add mock-response=true as a query parameter to the request and the response will be mock data based on the OpenAPI specification.

Maintenance API can be integrated and provide value in solutions such as web applications, mobile apps, Power Apps, commandline scripts and many more. In order to start using Maintenance API, some setup is required. We strive to keep this to a minimum and will assist developers from IT and the business in the necessary setup.

The standard and preferred scenario for using Maintenance API involves OAuth Authorization Code Flow. Here the client application is configured with permission to call the Maintenance API on behalf of the logged on user in Equinor Azure AD. Interaction with the backend ERP system (such as read a failure report or update a work order) is performed with the logged on user and requires that the logged on user has the necessary authorizations.

The following configuration steps needs to be performed for the initial setup:

1. Create client app registration in Equinor Azure AD through portal.azure.com for each environment of your solution. This step requires the Application Developer role in Access IT. See Omnia documentation Application Management in AAD for more information. We recommend one client app registration per client environment such as dev, qa and production.

2. Create client secrets for your client app registrations

3. Add an API permission for the app registrations towards the Maintenance API. The following API names are used with application id in parenthesis: Maintenance API QA (ad711600-154b-4ab0-8945-06cba7f10c4b) and Maintenance API Prod (1aee2186-b5f4-445a-bbf2-d28589ccb59a)

4. Trigger an authentication request through a http client (such as postman, or in a browser) in order to trigger the consent process of the API permission https://login.microsoftonline.com/3aa4a235-b6e2-48d5-9195-7fcf05b459b0/oauth2/v2.0/authorize?client_id=YourClientIdGuid&redirect_uri=RedirectUriOnYourAppReg&response_mode=form_post&response_type=code&scope=MaintenanceAPIGuid/.default

5. Contact us at the #maintenance-api channel on slack or create a Github issue for maintenance-api-docs. We would love to hear how you intend to use the API

We recommend using Postman as a tool for experimenting with the API.

In some scenarios, the standard setup does not cover the requirements and there is a need for system to system communication without user interaction. An example of such a scenario is scheduled background jobs.

For Maintenance API system to system integration requires additional setup both in the ERP system and for the client.

In the ERP system, a role supporting the specific client requirements must be established. In addition, a system user with this role will be need to be created.

The client must use oauth2 client credentials flow with certificates and the client application must be registered in Equinor Azure AD as an app registration. The client must generate a self-signed certificate and upload the public key to their app registration in Equinor Azure AD.

The self-signed certificate with private key will be used to generate the client_assertion property of the request to Equinor Azure AD as described Microsoft identity platform application authentication certificate credentials. We recommend using Microsoft MSAL to assist in the integration.

The APIphany team will assist in the system to system setup when necessary for integration. Contact us at the #maintenance-api channel on slack or create a Github issue for maintenance-api-docs.

Reading user information with system to system setup

It is possible to read user information with system to system setup but the functionality is disabled by default. To enable this functionality, the application must have a Legal Risk Assesment in place, showing that the application is allowed to read limited user information. Contact us for verification and enabling of this functionality for your application.

Microsoft Power Apps is a low-code platform for implementing business functionality. For more information on the usage of Power Apps in Equinor, see the Citizen Development site, Microsoft Power Platform group at Yammer or the Equinor Slack channel #powerplatform.

In order to use Maintenance API within Equinor Power Apps, the relevant DigiTeam should establish a custom connector for the API in their Power platform environment. It is important to keep the custom connector up to date in order the get access to the latest functionality in the API.

The Power Platform enablement team provides some utilities for creating custom connectors in their Github repository.

The latest OpenAPI specification for Maintenance API will always be available at maintenance-api-docs and it adheres to the OpenAPI 3.0.1 standard.

Note: Be aware the OpenAPI support in custom connectors is limited and outdated. For example elements such as allOf or oneOf used in Maintenance API are not directly supported. We have an unsupported generated file which attempts to fix this at maintenance-api-flattened.yaml.

The resource will be named according to common terminology used across the Oil&Gas industry (for example Norsok standard NS-EN 13306 and ISO 14224).

Example of resources are /work-orders/preventive-work-orders and /plants/{plant-id}/tags .

Resources keys will indicate the resource type as part of the name. Example: workCenterId and priorityId.

If there is a common "supertype resource", the supertype will determine the naming standard of the key. Example: FailureReports and ActivityReports are both a type of MaintenanceRecord. Therefore, the key for both is recordId.

Some resources may have multi-line text describing the resource or the contents of it in more detail. This will always have property name text.

ERP Advanced multi-line text

For all Maintenance record- and Work Order-related endpoints, we now expose multi-line text, that gives the consumer greater control of the input and formatting of the text towards the ERP system when creating and updating. In the corresponding lookup request, the formatting can be viewed as it is stored in the source system. A dummy example is provided below:

"text" : "Commands should generally not be inputted, just kept where they are from the lookup \n{{COMMAND INCLUDE Z_110_FLX_BEREDSKAPSGASSMAAL_0001 OBJECT TEXT ID IPRT}}, 
but after that we can do whatever.\n{{LEFT_ALIGNED}}Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.\n{{CENTERED}}Duis aute irure dolor in reprehenderit in voluptate velit 
esse cillum dolore eu fugiat nulla pariatur.\nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui 
officia deserunt mollit anim id est laborum."

With the help of Control Characters, styling such as centering, left-alignment and linefeed can be controlled. These are always surrounded by double curly braces{{ }}. These are the available keys:

Constraints

Any line that is longer than 132 characters will be split up and inserted as extended lines automatically. The exception to this is COMMAND, which will only accept one 132 characters long line, per command.

Display text without control characters

If you want to display text without the control characters, you can remove them with a Regex expression for example. The pattern (\{\{.*?\}\}) can be used to match all control characters for easy removal. Make sure that you test your patterns for your use case before setting them into production. There are online tools that are helpful with both creating and testing, which should be easy to find with a web search.

All date and time information are based on UTC (Universal Time Coordinated) and formatted according to RFC3339. This also applies to durations, such as 1 day or 2 hours.

Example values:

• datetime: 2022-08-24T14:15:22Z
• date: 2019-08-24
• duration: P0Y0M1DT0H0M0S (one day) and P0Y0M0DT2H0M0S (two hours)

These values are easily compatible with libraries such as moment.js library.

It's worth mentioning that in some special cases for maintenance data outside of Norway, datetimes after timezone conversion is not what the end-users would expect. The reason for this is that users may have entered datetimes in their local timezone into the Equinor ERP system, but the Equinor ERP system is configured to treat the input as if it was in the current Norwegian timezone (UTC+1/UTC+2). This causes a discrepancy in the Equinor ERP system which can not be corrected for in Maintenance API. basicStartDateTime and basicEndDateTime for work orders are examples of properties which may have unexpected time conversion.

From some resources there will be a need to provide uri links to other endpoints. This can for example to provide the endpoint for download of a binary attachment from a work order resource it belongs to.

The link will be defined in the data model of the resource and be grouped under the property name _links. The name of the properties for the _links object will taken from Link relations defined through RFC8288 when possible. Typical link relation names are self and enclosure.

The uri will not include query parameters required or supported by the endpoint (such as api-version, include-operations etc).

"attachments": [
{
    "attachmentId": "M3E0d7JwNje2tDQxNzByM3I1NIAARxdLE0MDx5oaEMfQ0MDSwtDYNN7AIt7CwNzC0MDcUiEsNa8kUy_CJ7gGAA"",
    "fileName": "equipment_location.jpg",
    "fileSize": "1636352",
    "mimeType": "image/jpg",
    "_links": {
        "enclosure": "/equipment/11948620/attachments/M3E0d7JwNje2tDQxNzByM3I1NIAARxdLE0MDx5oaEMfQ0MDSwtDYNN7AIt7CwNzC0MDcUiEsNa8kUy_CJ7gGAA"
        "documentEnclosure": "/documents/1097069-C01-000-00/attachments/M3E0d7JwNje2tDQxNzByM3I1NIAARxdLE0MDx5oaEMfQ0MDSwtDYNN7AIt7CwNzC0MDcUiEsNa8kUy_CJ7gGAA"
    }
}

Lookup operations return a single instance for the resource based on the key.

The resource may have related data which may or may not be relevant for a client. In order to indicate which related data to include, the lookup operation provides include-... query string boolean options. Examples: include-operations and include-tasks

Clients need to retrieve a subset of all resources for an endpoint. Usually, the criteria are non-trivial and in many case are not direct properties of the resource. REST does not provide a well-defined pattern for these types of requests.

Our approach, is to provide predefined filters with parameters. Each filter is documented in the OpenAPI specification.

Examples: maintenance-records/failure-reports/?api-version=v1&filter=recent-status-activation&status-id=RIDO&max-days-since-activation=1 and /maintenance-orders/preventive-work-order/?api-version=v1&filter=same-maintenance-plan&work-order-id=12345678&max=5

Update operations for resources will utilize a sub-set of the JSON Patch proposed standard. JSON Patch is described in RFC 6902 with a user-friendly version at https://jsonpatch.com/.

Our goals with using JSON Patch is to focus on the intent of the update and avoid common pitfalls for the client. The common pitfalls we avoid with JSON Patch are:

1. Clients inadvertently resetting properties of a resource to an empty value. This due to the client mistakenly sending all properties of a resource in a HTTP PATCH request with some of them having an initial value.
2. Clients inadvertently overwriting changes made by other users directly in the back-end system. This due to client mistakenly have provided properties which have not been changed in a HTTP PATCH request.

Using JSON Patch is straightforward.

• Set the content-type to application/json-patch+json.
• In the body, send an array of JSON Patch operations. Typically, one element pr property to be update for the resource

As part of the OpenAPI documentation, we will provide concrete examples for all update operation. In addition, the schema definition for the request body defines which resource properties can be updated.

Example of JSON Patch request body which replaces the value of the properties title and text:

[
  {
    "op": "replace",
    "path": "/title",
    "value": "Material failure"
  },
  {
    "op": "replace",
    "path": "/text",
    "value": "OBSERVERT FEILTILSTAND FYLLES UT AV INNMELDER:\nBeskriv feilen så godt som mulig (legg gjerne med bilde):\nMaterial tretthet..\n"
  }
]

HTTP response codes will follow established best practice for REST services and will be documented in the OpenAPI specification.

Below is a list of status codes used in the API which the client should handle. Common:

• 400 Bad Request - The request is invalid. For example missing parameters in the query string
• 401 Unauthorized - The request did not include an authentication token or the authentication token was expired or invalid
• 403 Forbidden - User does not have sufficient permissions
• 405 Method not allowed - HTTP verb not supported for requested resource
• 429 Too many requests - A client has exceeded the rate limit for the API. The client should back off and reduce the amount of requests
• 500 Internal Server Error - Sorry, an unexpected error ocurred on our side. Let's us know and we'll get around to fix it
• 503 Service unavailable - API or a service it depends on is currently not available.

Read - HTTP GET:

• 200 OK - The request completed successfully
• 404 Not Found - The resource does not exist or an non-existing endpoint has been called

Create - HTTP POST:

• 201 Created - Create of resource was successful and resource is returned in body
• 400 Bad Request - The resource provided in the body is not according to specification
• 409 Conflict - The creation of this resource is in conflict with an already existing resources

Create - HTTP PUT

• 204 No Content - Request successful but no resource returned in body
• 400 Bad Request - HTTP Put failed due to file contents
• 413 Payload too large - File too large

Update - HTTP PATCH:

• 204 OK - Update of resource was successful and resource is returned in body
• 400 Bad Request - The resource properties to update is not according to specification
• 409 Conflict - The update of this resource is in conflict with an already existing resources

Delete - HTTP DELETE:

• 204 OK - Delete of resource was successful
• 404 Not Found - The resource does not exist or an non-existing endpoint has been called
• 409 Conflict - The delete of this resource is in conflict with an already existing resources

Endpoints that return multiple items will in some cases support pagination. This helps improve performance by only fetching the data which is necessary for the client.

Parameters page and per-page are used to define which page is fetched and how many records are returned in the current request. per-page will typically have a max limit defined in the endpoint's documentation.

The response of a pagination request will include 3 additional HTTP headers:

• Total-Count: Custom HTTP header which shows total number of items found matching the criteria of the request (not just in the page returned)
• Link: Pagination data in accordance to RFC 5988. This will include a link for the next, previous, first and last page.
• Link-Json: Custom HTTP header for making the information in Total-Count and Link accessible in an easy to read JSON format

Clients are recommended to use Link-Json HTTP header to traverse the pages. Example of the data in this HTTP header:

{
  "totalCount": 49,
  "links": {
      "next": "https://api-test.gateway.equinor.com/maintenance-api/equipment?page=3&api-version=v1",
      "prev": "https://api-test.gateway.equinor.com/maintenance-api/equipment?page=2&api-version=v1",
      "first": "https://api-test.gateway.equinor.com/maintenance-api/equipment?api-version=v1",
      "last": "https://api-test.gateway.equinor.com/maintenance-api/equipment?page=4&api-version=v1"
  }
}

Note: For some endpoints there is a risk that individual items "disappear" between pages if data is updated in ERP system whilst the pages are requested.

The Maintenance API will use the principles of API evolution instead of introducing a new api-version on every breaking change.

In order to achieve this, endpoints, query parameters and resource properties can become deprecated and will be marked so in the OpenAPI specification.

In general, deprecated properties will be removed after 3 months. If a client uses a deprecated endpoint or query parameter, the Maintenance API will in the response provide a Sunset HTTP header Sunset: Sat, 15 May 2021 12:59:59 GMT representing the removal date for the deprecated feature as specified in RFC8594. In addition, a HTTP header Link: <https://equinor.github.io/maintenance-api-docs/#section/Deprecation>; rel="sunset" will be provided to pointing to relevant documentation.

Clients must monitor these messages and take corrective actions.

Rename quantityUnit to quantityUnitId

quantityUnitId is added to differentiate the field from future requirement where a description of quantityUnit might be added.

This deprecates the response in the following endpoints

1. GET /work-orders/corrective-work-orders/{work-order-id}
2. GET /work-orders/preventive-work-orders/{work-order-id}
3. GET /work-orders/sas-change-work-orders/{work-order-id}
4. GET /work-orders/project-work-orders/{work-order-id}
5. GET /work-orders/subsea-work-orders/{work-order-id}
6. GET /work-orders/modification-work-orders/{work-order-id}

Rename plannerGroupPlantId to planningPlantId

planningPlantId is replacing plannerGroupPlantId This deprecates properties of the response in the following endpoints:

1. GET /maintenance-records
2. GET /maintenance-records/modification-proposals/{record-id}

This deprecates HTTP POST request properties for the following endpoints:

1. /maintenance-records/modification-proposals/{record-id}

Updating FailureImpactId on Failure Report

failureImpactId should only be updated through a new dedicated endpoint in order to properly maintain priorityId on the related Corrective WorkOrder.

This deprecates the updating of failureImpactId on the following endpoint.

1. /maintenance-records/failure-reports/{record-id}

For updating failureImpactId, see new endpoint: /maintenance-records/failure-reports/{record-id}/failure-impact-change

Remove cmrIndicator from work orders.

cmrIndicator is removed from the response for all work order types. Please see the STRY0261073 for more information.

The intention of the CMR-indicator is to reflect work orders that will hit different KPI's. However, the KPI definitions have changed over the last decade without the CMR-indicator being updated. This has resulted in a current situation where the CMR-indicator on work orders is misleading. Going forward we will use the priority field on work orders to reflect their criticality. The CMR-indicator is therefore no longer needed and should be removed.

Deprecating filter in specific search endpoints

filter is a parameter used in Search endpoints to define which search criteria are necessary given the backend search query. This has been more restrictive than it needs to be to, so in order to support more query parameters for Search endpoints, better results can be achieved by removing the filter parameter. Additionally this will result in smaller and faster responses with only relevant data.

Please see each given endpoint on which parameters will be required in the future and which can be combined.

This deprecates filter in the following endpoints:

1. GET /work-order-plan/{planning-plant-id}

The API is operated and maintained by the APIphany team, who can be contacted in Equinor slack channels #maintenance-api and #maintenance-api-support

Feature requests are welcomed and can be submitted through:

1. Github issue for maintenance-api-docs
2. Equinor Slack channel #maintenance-api
3. Contact in GBS IT PLA POM department

A list of frequently asked questions (FAQs) along with their answers.

• Q: I got the error status 403 - Forbidden, how may I resolve this?

  • A: 403 Forbidden is related to permissions. Users are advised to verify that the appropriate roles are active. Read more about HTTP Response codes here

Endpoints have been introduced in the current version

Endpoints which have been modified in the current version