8Integration With Oracle Digital Assistant

About Oracle Digital Assistant Integration

You can now integrate Oracle Field Service with Oracle Digital Assistant (ODA). ODA is an environment for creating chatbots and then deploying them on the channel of your choice. Chatbots help engage technicians in their day to day activities and allows them to work smarter and more productively.

Note: Oracle Digital Assistant is a separate Oracle product distinct from Oracle Field Service. You must have a valid subscription to the Oracle Digital Assistant service to use the integration between the two applications.

After an integration, a chatbot acts as a personal assistant or a virtual help desk that can assist a technician with their day to day jobs, by answering questions from technicians or by notifying predefined events in Oracle Field Service, Technicians can take appropriate actions when they receive the right data at the right time.


Here are the prerequisites for chatbot integration:

  • Oracle Digital Assistant: Chatbot functionality is offered to Oracle Field Service users by the integration of Oracle Digital Assistant (ODA). Users must purchase Oracle Digital Assistant separately to get the chatbot service in Oracle Field Service.

  • Oracle Field Service Chatbot Sample App: This sample app consists of: Sample service that will relay messages between Oracle Field Service Cloud Collaboration channel and Oracle Digital Assistant by making use of Oracle Field Service public REST APIs, Configuration files that will integrate Oracle Field Service with Oracle Digital Assistant.

    Note: You can download this application from OTN and can make use this as a reference for creating sample application or directly use this by hosting this service to connect with ODA & Field collaboration.
  • Oracle Field Service Pre-built Skills: The pre-built skills will be posted in OTN as a reference, you can download the skills from OTN and can use it as a skill chatbot or as a reference for building new skills based on your specific requirements.

Prebuilt Skills

You can download the pre-built skills after they are posted in OTN as a reference. You can use them as skill chatbots or a reference for building new skills based on your specific requirements.

Oracle Field Service chatbot is configured with these skills:

Usecase Description Chatbot Conversation

Chatbot acts as an assistant to technician during the activity

Technician Started this an activity and opens Helpdesk to start conversation with chatbot:

Tech1: Show service history

Bot : Here is the service history 02 Oct 2018 Installation: HD-DVR installation completed 16 Nov 2018 HD-DVR Upgrade: cables replaced

Technician performs trouble shooting steps and asks the bot about the signal strength:

Tech1: what is the signal level?

Bot: Signal level looks bad (Rx -17 dBmV, SNR 21.3 dB, Tx 58 dBmv) I do not see an Outage with Network Node AD4056

Tech1: Who is working with the node?

Bot: Tech3. He is online now, do you want me to connect him?

Tech1: yes.

Bot: Sure. Connecting

Tech 2 and Tech 1 collaborate and resolve the issue.

Chatbot helps the technician when activity is not started on time

Bot finds that the technician is near to User site but he has not started the activity

Bot initiates a chat with that technician

Bot: I see that you have been at a User location for a while and you have not started an activity. Do you need help to start the activity?

Tech1 : User is not at home

Bot: Ok. Let me try and contact the User for you. Please stand by ...

Bot: Ok. I was able to contact the User. They said "I will be home in 5 minutes, Please wait!"

Other Conversations in Bot

Category Chatbot Conversation


Tech: Hi

Bot: Hi, How may I help you?

Unresolved questions

Tech: nearby technicians?

Bot: I’m sorry, I don’t understand.

Enable Oracle Digital Assistant Integration

Bot connector is a NodeJS based sample app available in OTN. This service connects Oracle Field Service field collaboration and Oracle Digital Assistant. This service enables transferring of messages between Oracle Digital Assistant and Oracle Field Service Cloud.

To enable this integration:

  1. Download the bot connector sample app from OTN site.

  2. Run the service at the customer environment.

Enable Helpdesk with Oracle Digital Assistant

Helpdesks can enable Oracle Digital Assistant (ODA). Once enabled, ODA can act as a virtual operator in the helpdesk and can answer technicians' queries.

You can train the Oracle Digital Assistant based on your business requirements and can equip ODA by adding skills to learn, engage, suggest and recommend resolutions for technician's key problems.

Note: You must have a valid subscription to the Oracle Digital Assistant service, for example Oracle Digital Assistant Platform for SaaS.

To do this, the application uses ODA web hook channel for connecting with ODA. Below steps detail on how to set up connectivity between Collaboration helpdesk & ODA.

  1. Navigate to Configuration, Collaboration.

  2. In the Collaboration page, select Helpdesks in the left pane.

  3. In the Helpdesk configuration page, click the Enable Oracle Digital Assistant check box.

  4. Once enabled, the Oracle Digital Assistant field shows a set of related fields.

    Complete these webhook endpoint details:

    • Webhook secret key
    • Webhook URL
    Note: The webhook endpoint details are available in ODA.
  5. You should configure these endpoints from ODA so that ODA can use the Webhook URL endpoint for all communication with field collaboration

Configure Oracle Digital Assistant for Connecting With Helpdesk

This section discusses how to configure Oracle Digital Assistant (ODA) for connecting with helpdesk.

Review these requirements before you create a webhook-based channel:

  • Channel has to route to specific skill/DA

  • Channel has to be in enabled state

  1. Navigate to the ODA dashboard.

  2. Select Development, Channels to open the Channels page.

  3. Create new channel type as Webhook

  4. Use Outgoing webhook URI obtained from OFS help desk configuration screen.

  5. After successful creation of the channel, use the ODA webhook URL and Webhook secret to complete the OFS help desk configuration.

  6. Update OFS help desk configuration with the generated secret key and Webhook URL from ODA.

Conversation Between Field Technician and ODA

Field Technician can search for a helpdesk (Enabled with ODA) in field collaboration and can initiate a conversation with that helpdesk, on receiving a new chat message ODA can proactively address the question and keep the technician engaged by initiating interaction based on the skills defined in the ODA. Skills are treated as individual chatbots in ODA and each chatbot is designed to interact with users and fulfill the specific type of task such as rescheduling a job for field tech or sharing service history of the job. For more details about skills, see Using Oracle Digital Assistant documentation.

For this, you must follow these steps:
  • Request payload from field collaboration
  • Sharing of inventory, activity or resource details as an attachment

Request Payload from Field Collaboration

This is a sample payload from OFS to ODA skill.

While developing skills at ODA side, you can expect a similar request format from field collaboration.

Payload Schema:

  "userId": (String | mandatory | unique conversation id to maintain the session),
  "messagePayload": {
      "type": (String | mandatory | type of message from ODA),
      "text": (String | mandatory | response message from ODA)
  "userLoginName": (String | mandatory | unique user login identifier)

The above code includes:

  • userLoginName will share the current chat user, which can be used to query OFS REST APIs from the custom component level.
  • User information: OFS Collaboration payload sends only the user login name to ODA. Customer can make use of OFS REST endpoints /rest/ofscCore/v1/users/{login} to get the resource ID and more information about the resource.
  • Custom Component: Field Collaboration expects these components in the response from skill/DA:
  • System.Output
  • System.Text

    Field collaboration will not process responses from components other than these custom components. You must use them while developing skills for connecting with field collaboration.

  • Helpcard: Collaboration will not process DA-level help card, hence, you must use custom skills to manage use cases with help cards.

Sharing of Inventory, Activity or Resource Details as an Attachment

You can develop skills to share activity/inventory/resource information as an attachment in collaboration.

Sending attachment from the skill. You can send attachments by using custom components within the skill. Here is a Sample custom component invocation:

Sample Custom Component for Inventor, activity or Image:
  component: "OFS.Collaboration"
      action: "share"
          type: "activity"
          id: "4545454"
          desc: "Upgrade"

Field Collaboration expects a payload in the below format for attachments (Inventory / Activity/ User). This table displays the properties of the payload:


Key Value Description Required
Action Share

tell what kind of action should be done at collaboration.

supported values: share, helpDeskTransfer

metaData Object only required for share action Optional
This table displays the metadata of the payload:


Table metaData

Key Value Description Required
type Activity type of attachments supported values: activity, inventory, resource Mandatory
id ID of the activity, resource OR inventory unique ID of the respective entity Mandatory
desc description or note description or note Mandatory
Field Collaboration expects a payload in below format for attachments (Inventory / Activity/ User)

Payload for Inventory , activity or resource share:

{"messagePayload":{"payload": {                   "action": "share",     "metaData": {
         "type": "activity"                             "id": 4545454,                             "desc": "Upgrade",                         }                   },                     "type": "raw"                     },                     "userId": "ad3jgo7s79dddgadffdasf9"                

Transfer of Conversation from ODA to Helpdesk Operator

When ODA is not trained to answer any specific quires, the conversation can be transferred to a human helpdesk operator. This will be shared as a new chat in that helpdesk. When a helpdesk operator accepts this chat ODA will leave the conversation, the operator can view previous chat messages between field tech and ODA to get the context of the conversation and can continue the conversation.

While defining the skill, you should make sure that the logic of transfer is implemented in the skill-based on the business requirement.

Transfer chat sample custom component:

  component: "OFS.Collaboration"
      action: "helpDeskTransfer"

Field Collaboration expects a payload in below format in case of the transfer request from a custom component

Sample Payload for Transfer chat to helpdesk

{ "messagePayload": { "payload": { "action": "helpDeskTransfer" }, "type": "raw" }, "userId": "ad3jgo7s79dddgadffdasf9"}

Sample Custom Component for attachment and transfer of conversation

Sample Custom Component

'use strict';
const { MessageModel } = require('@oracle/bots-node-sdk/lib');
module.exports = {
 metadata: () => ({
 name: "OFS.Collaboration",
 properties: {
 action: { required: true, type: 'string' },
 metaData: { required: false, type: 'object' }
 supportedActions: []
 invoke: (conversation, done) => {
 conversation.logger().debug("OFS.Collaboration component invoked");
 const message = MessageModel.rawConversationMessage(this.conversation.properties());
 conversation.logger().debug("OFS.Collaboration action finished");

Use Custom Components

You can use the Core API REST interface to access the Daily Extract files.

Things to consider while writing custom components.

To access Daily Extract files using the Core API, you must install:
  • Create application within Oracle Field Service with the relevant API permissions.
  • Use the application credentials within the custom component to make REST API calls.
  • Use skill configuration for sharing credentials to custom component.