Maintenance API Event Driven is a companion solution to Maintenance API. Whilst Maintenance API provides a REST-based synchronous API, this is event driven and publishes maintenance events consumer solution can subscribe and react to.

"Event-driven architecture is a software architecture paradigm promoting the production, detection, consumption of, and reaction to events". The events represent "a signifcant change in state" for a business object and in our case are produced from the Equinor's ERP system.

Examples of maintenance events:

• Corrective work order created from failure report
• Preventive work order created from maintenance program
• Work order of type SAS Change, Project, Modification or Subsea created
• Work order status activation (REL, TECO most important ones)
• Work order modified
  • Work order header fields updated
  • Work order operation fields updated
  • Confirmation of operation
  • Time writing/confirmations
  • Work order component added, updated or removed
  • Equipment reserved/unreserved for Subsea work order
• Work order operation scheduling (planned dates adjusted or added/removed from baseline plan)
• Delay in logistics for parts required for work order (parts of SCM Logistics so outside of Maintenance scope)

Azure Service Bus is a key component in the Maintenance API event driven architecture and runs in Equinor's Azure tenant. This is a mature product with advanced functionality and excellent library support for consumers especially on the .NET platform.

Subscriber setup will be performed by the Maintenance API team.

As part of this, the following will be configured:

• A subscription in Azure Service bus with filter matching the events of interest to the specific consumer
• A consumer specific queue in Azure Service Bus which will receive a copy of all events matching the subscription filter
• A Shared Access Signature the consumer will use for authorization
• Firewall allow rules for the ip-adresses used by the consumer

Client event consumption

Consumers will use typically use libraries such as Azure.Messaging.ServiceBus for reading events from their subscriptions through a persistent TCP/IP connection (Azure Service Bus also provides a synchronous based REST interface for reading events in special cases).

We recommend the consumer uses a Peek-Lock message pattern and actively confirm messages once successfully processed.

Dead-letter-queues can hold failed events and must be monitored by the consumer.

Events

Events originate from Equinor's ERP system. They will use common terminology from across the Oil&Gas and Renewables industry for the maintenance process in the same way as the Maintenance API (Norsok standard NS-EN 13306 and ISO 14224 are key resource).

The events will contain the full state of the modified resource just after the event occured. The full state is identical to what will be returned on a lookup request for the individual resource in Maintenance API

The event data will follow the cloudevents standard.

Due to underlying depdencies, we cannot guarantee the correct ordering of the events and cannot guarantee a event is delivered only once. However, due to the relatively low volume of events published, we expect these two conditions to normally hold true.

Feature requests are welcomed and can be submitted through https://github.com/equinor/maintenance-api-event-driven

Used to report work performed for a maintenance activity against a tag

Used when an equipment fault/degradation is detected or when there is need for work that is not related to equipment fault.

Modification proposal initiates the processing of a modification, replacement or maintenance project. In Equinor for upstream offshore, a modification proposal initiates the business processes 'OM103.01 - Initiate projects on plants in operation' or 'OM103.70.01 - Propose simple modifications in safety and automation systems'.

Used to represent the results of a certification such as PSV or lifting certificate

Used to request for update of technical information or maintenance programs