Supported Data Flows
All data flows are implemented as REST web services. HTTPS transport is used (by default access over plain HTTP is disabled).
The adapter publishes catalog of available inbound and outbound REST web services. It is accessible at the URL:
https://<server>:<port>/nms-ofs/rest/v1/catalog
Authentication
Basic HTTP authentication or OAuth 2.0 can be used to authenticate incoming and outgoing requests. For outgoing requests these methods are mutually exclusive. For incoming requests they can be used together.
In case of OAuth the Client Credentials Flow is used with 'client_credentials' grant type and JWT tokens.
See
“OAuth Configuration” for details on configuring OAuth support.
Outgoing Flows
Heartbeat
When connection to the Oracle Field Service system is not established the adapter periodically sends out PingURL message. Once such message is sent successfully, the connection is considered established, sending of the PingURL messages stops and the adapter executes synchronization sequence. The purpose of the synchronization sequence is to send out updates for the activities where corresponding trouble event information has changed with the connection was down.
Create/Update Mobile Activity
CreateUpdateMessage message is sent by the adapter whenever new mobile activity needs to be created or an existing activity needs to be updated. The message contains full details of the trouble event associated with the activity as well as details one or more activities associated with the trouble event.
Complete/Cancel Mobile Activity
CompleteOrder message is sent by the adapter when activity is needs to be completed or cancelled. When a trouble event is completed or canceled all the activities associated with the trouble event are completed or canceled. When a crew is released from a trouble event - only the activity associated with that crew is canceled.
Incoming Flows
Create Mobile Activity
Sending CreateActivity message to the adapter creates a new mobile activity for an existing trouble event. Either an index of an existing trouble event or activity id of an existing activity needs to be passed in the request. Activity id of the newly created mobile activity is returned.
Update Mobile Activity
Sending UpdateActivity message to the adapter allows to perform different crew-related actions depending on the state value passed in the request.
• Dispatched – assigns the mobile crew associated with the activity to the trouble event.
• EnRoute – places the mobile crew associated with the activity en-route to the trouble event.
• Started - places the mobile crew associated with the activity onsite for the trouble event.
• Suspended – suspends the mobile crew associated with the activity from working on the trouble event.
• NoCrew – releases the mobile crew associated with the activity from working on the trouble event. The same effect can be achieved by sending crewId in the message. Releasing the crew will cause the activity to be cancelled.
• Complete – completes the activity and releases the crew from the trouble event.
• Cancelled – cancels the activity and releases the crew from the trouble event.
Update Trouble Event
Sending UpdateEvent message to the adapter allows trouble event in the Oracle Utilities Network Management System to be updated. In particular it allows to
• Update Estimated Restoration Time
• Update Event Case Note
• Update Event Details information
• Update Failed Equipment information
• Update crew action steps
• Confirm Outage Device
• Move outage upstream or downstream
• Restore outage
• Cancel trouble event
Query
Query request allows retrieving information from Oracle Utilities Network Management System. The following query types are supported:
• call – returns customer calls for specific trouble event
• customer – returns customer information for specific account number
• device_info – returns device information for specific device name (alias)
Update Crews
Update Crews request allows Oracle Field Service system to create or update one or more crews in the Oracle Utilities Network Management System. Mobile flag is automatically set for crews created or updated this way.
Update Crew Active Status
Update Crew Active Status allows Oracle Field Service system to update active status of a crew in the Oracle Utilities Network Management System.
Update Crew Shift Status
Update Crew Active Status allows Oracle Field Service system to update shift status of a crew in the Oracle Utilities Network Management System.
Admin Data
Admin Data request allows Oracle Field Service system to retrieve administrative/configuration information from the Oracle Utilities Network Management System. Returned data includes:
• Event Details drop-down options
• Crew types
• Crew member classes
• Crew vehicle types
• Control zone information
• Database schema definitions of the PICKLIST_INFO_UPD_TR and PICKLIST_INFO_EQ_FAIL tables
• Names of electrical phases
Asynchronous Message Acknowledgment
The outgoing requests other than PingURL can be processed asynchronously. In such case the receiving side would send back response message containing error code 'DEFERRED'. This is an indication the request is being processed asynchronously. The adapter would wait up to the configured amount of time (mwm.ack_wait_timeout) for the incoming MessageAck message containing result of the earlier request. There are 3 possible outcomes: Success – request was processed successfully; Error – an error occurred while processing the request; Failure – request cannot be delivered to the Oracle Field Service system. Failure response is treated as loss of connection between the system and initiates heartbeat flow followed by synchronization sequence. If MessageAck message is not received during the configured period of time then the Failure outcome is assumed.
Correspondence between the original request message and the MessageAck message is established through the messageId attribute in the message header of the original request. The MessageAck message must contain the same message id.