Integrating with Oracle Field Service Cloud using ICS REST adapter

Oracle Field Service Cloud (OFSC) helps transform Customer Experience by building efficient field service solutions. It is built on time-based, self-learning, and predictive technology. Oracle Integration Cloud Service (ICS) provides the Oracle Field Service adapter (OFSC adapter) to create inbound and outbound integrations with OFSC. Refer here for OFSC adapter documentation.

The OFSC adapter can be used to create integrations using OFSC as ‘invoke’(outbound into OFSC) and/or ‘trigger’(events flowing from OFSC into ICS). This native OFSC adapter exposes a rich set of operations(for outbound) and events(inbound) for most commonly used business objects. Refer to the below 2 links for the Business Objects and operations/events provided by the OFSC adapter

  • OFSC Invoke operations – link
  • OFSC Trigger events – link

However, OFSC provides a myriad of other REST operations (refer the REST API doc) that can be used to access data stored in Field Service Cloud and integrate with other systems.

This blog will provide details on how the ICS generic REST adapter can be used to build ICS integrations to OFSC.

Using ICS REST adapter with OFSC

The next 3 sections will walk through the REST connection,  Invoke and Trigger configurations required to connect to OFSC using REST adapter.

It is important to ensure that all OFSC setup to invoke ICS is done. This are the same prerequisites steps mentioned for OFSC adapter. Refer to them in the OFSC ICS prerequisites page here

Before using REST adapter for any OFSC operation, check the operations (Invoke and Trigger operations) that are available using the native OFSC adapter in ICS

 

REST Connection

Create a REST connection to OFSC as follows

The Connection URL is usually https://api.etadirect.com/rest/ofscCore/v1

Use Basic Authentication as the security policy.

Note that OFSC requires the Auth header in the following format.

Authorization: Basic BASE64(‘<USERNAME>@<INSTANCE-NAME>:<PASSWORD>)

Hence, make sure to use the <username>@<company_name> as the Username on REST adapter connection properties. For example – Refer to below screen shot for other a sample REST connection properties page

 

 Use Basic Authentication, username@company_name and password when creating the REST Connection to OFSC

01_REST_ConnPage

OFSC REST Invoke

Drag the OFSC REST connection created in previous step into the invoke side of an ICS integration. Use the following screens as reference while traversing the invoke configuration wizard.

Below examples screen shows the configuration to invoke the Update User REST operation from the OFSC REST API

 

Define the REST resource URI, HTTP Verb and options for the OFSC REST invoke

02_Invoke_page1

Define the query parameters if any

02_Invoke_page2

Define the request and response payload structures as appropriate

02_Invoke_page2-23

Review the summary and finish configuring the invoke OFSC REST invoke

02_Invoke_page3

OFSC REST Trigger

Below screens show the OFSC REST connection for receiving Trigger events from OFSC. The example is for configuring the trigger to receive userCreated event from OFSC.

Define the REST resource URI, HTTP Verb and options for the OFSC REST trigger operation

03_trigger_page0

Define payload structure expected for trigger

03_trigger_page1

03_trigger_page2

Event Payload

The sample payload used for userCreated event is as follows

{
    "eventType": "userCreated",
    "time": "2017-04-28 10:33:17",
    "user": "admin",
    "userChanges": {
        "createdTime": "2017-04-28 10:33:17",
        "language": "en",
        "lastPasswordChangeTime": "2017-04-28 10:33:17",
        "lastUpdatedTime": "2017-04-28 10:33:17",
        "login": "User5",
        "mainResourceId": "Gautham",
        "name": "User5",
        "passwordChanged": true,
        "resources": ["A Team","Asia"],
        "status": "active",
        "timeZone": "(UTC-05:00) New York - Eastern Time (ET)",
        "timeZoneDiff": -240,
        "timeZoneIANA": "America\/New_York",
        "userType": "UT16_DISPLAY_PROFILE",
        "weekStart": "default"
    },
    "userDetails": {
        "login": "User5",
        "mainResourceId": "Gautham",
        "name": "User5",
        "userType": "UT16_DISPLAY_PROFILE"
    }
}

The required event payload for all events may not be obvious.

The event payload structure can be inferred from the ‘event fields’ from the supported events link -> https://docs.oracle.com/cloud/latest/fieldservicecs_gs/CXFSC/OFSC_Supported_Events_Types.html

Also, the event payload structure can be determined using ‘Trace Enabled’ feature of ICS integration. Activate the integration with a draft event payload structure and subscribe to the desired event on OFSC as described above. Then use the Activity Stream file (ics-flow.log) within ICS Diagnostic logs at runtime to inspect the event payloads. Later, deactivate, re-edit the integration with the proper event payload structure. Note that trigger connection properties and mappings may also need to be updated due to changed event payload structure.

Flow Activation

Once the integration using OFSC Event as trigger is complete, activate the integration in ICS and note down the Integration URL.

For example – https://<ics-instance-url>/integration/flowapi/rest/OFSC_USER_CREATE_USER_UPDATE/v01/

Event Subscription

Now this integration should be subscribed on Field Service Cloud instance to receive the desired event

This can be done by making a POST REST call to the OFSC Event – CreateSubscription API defined in the OFSC REST API Doc-> http://docs.oracle.com/cloud/latest/fieldservicecs_gs/CXFSC/op-rest-ofscCore-v1-events-subscriptions-post.html

The resource URI is https://api.etadirect.com/rest/ofscCore/v1/v1/events/subscriptions

Use your favorite REST client to make this one-time event subscription call. The below diagram shows a curl command used to create the event subscription. One can use Postman or SoapUI as well.

 

04_eventSubscribe_page1

Here is the sample eventSubscription payload

{
    "events": [
        "userCreated"
    ],
    "pushTo": {
        "url": "https://<ics-instance-url>/integration/flowapi/rest/OFSC_USER_CREATE_USER_UPDATE/v01/"
    }
}

Here are some points to note before subscribing to events –

  • Ensure that the Event Push Agent is configured on the OFSC instance. If not, the event Subscription call above will not be successful!
  • The Push Event Agent is an internal component and one should raise an SR on OFSC to configure Push Event Agent on the OFSC instance.
  • The basic auth header for event Subscription can be generated using username (=<username>@<company_name>) and password as discussed in previous section.
  • The “events” in the createSubscription payload above can be a list of events that the ICS integration needs to subscribe to. Note that the all events belonging to a given Business Object follow the same payload structure. Hence you can potentially subscribe to multiple events of the same Business Object, as long as the ICS integration is designed to handle all of them meaningfully. An example in this case would be “userCreated”, “userUpdated”
  • The “pushTo” in the event subscription payload should be set to the ICS integration endpoint that was activated in the previous section!

 The pushTo url in the event subscription payload should be set to the ICS integration endpoint that was activated in the previous section!

With the above, ICS integrations are ready to receive events from OFSC and invoke operations on OFSC using the generic REST adapter !

 

Add Your Comment