Before you Begin

In Oracle Cloud HCM, it's now possible for users to access HCM services through a conversational interface (a chatbot) called a digital assistant. Digital assistants can be developed and deployed through the Oracle Digital Assistant cloud service. A digital assistant serves as a unified interface for skills, each of which are designed to handle inquiries and request in a given subject area.

If you have an Oracle Cloud HCM account that comes with a pre-provisioned instance of Oracle Digital Assistant, you also get an out-of-the-box digital assistant (called FADigitalAssistant) that includes a variety of skills for Oracle Cloud Applications. Among the skills in FADigitalAssistant is a skill for HCM, which enables users to handle various employee and manager tasks through a chat window, thus saving time for HR representatives. You can use that skill as is or you can extend it to answer more questions and handle company-specific terms and phrasing.

Here are some examples of requests you can try with this skill:

  • Find someone in the company directory.
  • Check on your last paycheck.
  • View your benefits.
  • View your available vacation/PTO balance.
  • Ask about manager functions such as Approvals, My Team or Promotion.

This tutorial guides you through the process of:

  • Setting up your users to access Oracle Digital Assistant.
  • Configuring the digital assistant so that it can be exposed in your Oracle Cloud HCM instance.
  • Activating the Fusion Applications digital assistant in your HCM instance.

What Do You Need?

Before continuing with these steps, you need:

  • An Oracle Cloud Human Capital Management (HCM) instance.
  • An Oracle Digital Assistant instance that has been provisioned as part of your Oracle Cloud HCM account.

    This pairing of Digital Assistant with Oracle Cloud HCM ensures that the HCM skills are available in Digital Assistant's Skill Store and authentication between Oracle Cloud HCM and the FADigitalAssistant is handled correctly. Speak with your Oracle Cloud sales representative if you are unsure about your setup.

  • Administrative access to Oracle Cloud HCM.

    Confirm that the administrator is correct and available to work on the activation. If the administrator account is incorrect or inaccessible, you will need to file a Service Request (SR) to request the change.

Access Your Pre-Provisioned Digital Assistant Environment

In this section of the tutorial, you will set up access privileges for yourself and your team to the Oracle Digital Assistant that has been pre-provisioned for you.

Access the IDCS Application for HCM

You set up your team members' access to Digital Assistant through Oracle Identity Cloud Service (IDCS). To get to the IDCS Application for HCM:

  1. Get the Admin Console URL to your IDCS account.

    This URL is provided in an email that is sent to your primary administrator with a subject line similar to the following:

    Action Required: Your new Oracle Identity Cloud Service instance in Cloud Account <account name> is ready

    If you don't have your cloud administrator account credentials, ask your help desk to create a technical service request.

  2. Open the URL in your browser and do one of the following tasks:
    • Sign in using your credentials.

      Note: If you're signing in to the Identity Cloud Service application for the first time, you must create a new password. To do so, on the Oracle Cloud Account Sign In page, click the link for Need help signing in, and then follow the instructions.

    • Sign in with the available Oracle Identity Cloud instance using your SSO credentials.

      This image shows the Oracle Cloud Account Sign In page with the link that you can use if you're signing in for the first time (1) and an Identity Cloud Service instance, for example, Oracle Applications Cloud (2).

      This image shows the Oracle Cloud Account Sign In page with the link that you can use if you're signing in for the first time (1) and an Identity Cloud Service instance, for example, Oracle Applications Cloud (2).

Confirm that Synchronization is Enabled Between Your HCM and Digital Assistant Instances

An IDCS application is set up to represent your Cloud HCM instance. This IDCS application is essentially an intermediary to synchronize your user accounts between HCM and Digital Assistant. In this section, you'll confirm that the user accounts are indeed synchronized.

Confirm that User Synchronization is Enabled

  1. In IDCS, click main menu icon to open the side menu and then select the Oracle Cloud Services link.
  2. Find the entry for the Oracle Applications Cloud (Fusion) application and click it to open it.
  3. In the application, click the Provisioning tab.
  4. If Enable Provisioning switch is in the OFF position, switch it ON.
  5. Scroll down to the Select Provisioning Options section of the page and select the Authoritative Sync checkbox.
  6. Scroll down to the bottom of the page and make sure the Enable Synchronization switch is set to the ON position.
  7. Scroll back to the top of the page and click Save.

Confirm that the IDCS Application Contains Your Users

  1. In the application, click the Users tab.
  2. If the users that you want to access Digital Assistant are not listed there, click Import and proceed with importing of those users.

An Oracle Identity Cloud Service (IDCS) application is also set up for you to manage access to Digital Assistant.

You use this application to assign your team members roles to access Digital Assistant.

  1. In IDCS, click main menu icon to open the side menu and then select the Oracle Cloud Services link.
  2. Find the application that has idcs-oda at the beginning of its name.

    This is the IDCS application for your Digital Assistant instance.

  3. Click the application name to open the application.

Assign Yourself and Other Admins the ServiceAdministrator Role

You'll want to assign the ServiceAdministrator role to yourself and possibly a few other people. This will grant you full privileges within the Digital Assistant, including a number of capabilities (such as viewing detailed audit information and purging data) that developers and business users don't need.

  1. In the IDCS application, click the Application Roles tab.
  2. In the tile for the ServiceAdministrator role, click role menu icon) and select Assign Users or Assign Group.
  3. Select the users or groups that you want to assign the role to and click OK.

Assign Your Developers the ServiceDeveloper Role

Assign the ServiceDeveloper role to users that will be working with the Digital Assistant instance to extend and customize the FADigitalAssistant and any of the skills that it encompasses.

The ServiceDeveloper contains a subset of the permissions of the ServiceAdministrator role.

To assign the ServiceDeveloper role:

  1. In the IDCS application, click the Application Roles tab.
  2. In the tile for the ServiceDeveloper role, click role menu icon) and select Assign Users or Assign Group.
  3. Select the users or groups that you want to assign the role to and click OK.

(Optional) Assign Business Users the ServiceBusinessUser Role

The ServiceBusinessUser role is available for users who need to evaluate the digital assistant and skills and evaluate how they are being used (via Insights reports).

The ServiceBusinessUser contains a subset of the permissions of the ServiceDeveloper role.

To assign the ServiceBusinessUser role:

  1. In the IDCS application, click the Application Roles tab.
  2. In the tile for the ServiceBusinessUser role, click role menu icon) and select Assign Users or Assign Group.
  3. Select the users or groups that you want to assign the role to and click OK.

Get the Digital Assistant Instance URL

Next, get the URL for Digital Assistant so that you can bookmark it and share it with your developers.

  1. In the IDCS application for Digital Assistant, click the Configuration tab.
  2. Expand the Resources section of the page.
  3. Copy the value of the Primary Audience field and paste it to a text file.
    A screenshot of IDCS. In the left navigation, there are 7 menu items, the third of which is 'Applications' and which is selected. In the main content area, there are 5 tabs, the second of which is called 'Configuration' and which is selected. Within that page are sections for General Information, Client Configuration, and Resources. The Resources section is expanded and contains several fields, the fourth of which is Primary Audience.
  4. This is the URL for the instance's user interface. Distribute this URL to team members that you want to have access to Digital Assistant.

Create a Web Channel in Digital Assistant

In this section, you create a channel in Oracle Digital Assistant that exposes your digital assistant in the Oracle Cloud HCM user interface.

Get the Updated FADigitalAssistant

When an instance of Oracle Digital Assistant that is paired with an Oracle Cloud HCM instance is provisioned, it is automatically populated with the out-of-the-box digital assistant named FADigitalAssistant.

Since this digital assistant is periodically updated, do the following to make sure that you have the most up-to-date version:

  1. In your browser, navigate to the Oracle Digital Assistant user interface using URL that you assembled in the previous section.
  2. Sign in using your Oracle Cloud single sign-on credentials.
  3. In Digital Assistant, click main menu icon to open the side menu and then select Development > Digital Assistants.
  4. In the tile for FADigitalAssistant, click Options menu icon, select Install Update, and then confirm by clicking the Update button.

    (If there is not a more recent version, the Install Update option won't appear.)

Note: If the version of FADigitalAssistant is from 2019, an Install Update button may not appear for the digital assistant. In that case, you need to pull the latest version of the digital assistant from the Skill Store by doing the following:

  1. In Digital Assistant, click main menu icon to open the side menu and then select Development > Store.
  2. In the tile for FADigitalAssistant, click Options menu icon, select Pull, and then confirm by clicking the Pull button.

Train the Digital Assistant

For the updated digital assistant to work, it needs to be trained.

  1. Click main menu icon to open the side menu and then select Development > Digital Assistants.
  2. Open the digital assistant by clicking its tile.
  3. In the top navigation for the digital assistant, click the Training needed icon button.

    Note: If you see the No training needed now icon button instead of the Training needed icon button, that means that it is already trained and that you don't need to complete this step.

  4. In the Train dialog, leave Trainer Tm as the default, click Submit, and wait for the training to complete.

This might take a few minutes. You'll be informed when the training is completed with a popup confirmation message.

If you miss that message, you can confirm that the training has finished when the Training needed icon button button has been replaced with the No training needed now icon button.

Configure a Web Channel and Connect it to FADigitalAssistant

  1. In Oracle Digital Assistant, click main menu icon to open the side menu and then select Development > Channels.
  2. Click + Channel.
  3. In the Create Channel dialog box:
    • Enter a Name for the channel.
    • From the Channel Type list, select Oracle Web.
    • In the Allowed Domains field, enter an asterisk: *
    • Make sure that the Client Authentication Enabled switch is in the OFF position.
    • Click Create.
  4. In the Route To dropdown, select the most recent version of FADigitalAssistant that is listed.
  5. Move the Channel Enabled switch to the On position.
  6. Copy the Channel Id value to a text file.

Enable and Configure Access to the Chat Widget in the Oracle Cloud HCM User Interface

In this section of the tutorial, you:

  1. Enable the HCM instance to work with Digital Assistant.
  2. Add the chat widget to the HCM user interface.
  3. Import roles that give users permissions to use the digital assistant's features.
  4. Verify that the roles have been imported.
  5. Grant the imported roles to users.

Caution: If you do these steps in a a test or development environment and then you have the environment refreshed with configuration data from your production environment, the changes you make in this section will be overwritten.

Enable Integration with Digital Assistant in the HCM Instance

  1. Sign in to Oracle Applications Cloud.
  2. Click your user image or name in the global header, and in the Settings and Actions menu, select Setup and Maintenance.
  3. Locate the Tasks icon on the right side of the page.
  4. The Tasks icon
  5. Click the icon and select Search.
  6. In the Search field enter Manage Administrator Profile Values and press Enter.
  7. In the Search Results, click the Manage Administrator Profile Values link to open the Manage Administrator Profile Values page.
  8. In the Profile Option Code field, enter FA_ENABLE_DIGITAL_ASSISTANT and click Search.
  9. In the FA_ENABLE_DIGITAL_ASSISTANT: Profile Values section of the page, click the + icon.
  10. From the Profile Level drop-down list, select Site.
  11. For Profile Value, set the value to Y.
  12. Click Save and Close.
  13. Click Done.

Add the Chat Widget to the HCM User Interface

Next you need to add the chat widget to the HCM UI. You do this by completing these general steps:

  • Create a sandbox in HCM. Sandboxes enable you to configure changes to the user interface and verify them before putting those changes into your production instance.
  • Use HCM Experience Design Studio to add and configure the chat widget in the sandbox environment.
  • Publish the changes in the sandbox to the live HCM instance.

Here are the detailed steps:

  1. Open a new tab in your browser and navigate to your Oracle Cloud HCM instance.
  2. In Oracle Cloud HCM, click main menu icon to open the side menu, click Show More, scroll down to the Configuration section, and select Sandboxes.
  3. Click Create Sandbox.
  4. In the Name field, enter a name indicating that it's a sandbox for Digital Assistant integration.
  5. Select the HCM Experience Design Studio checkbox.
  6. Click Create and Enter.
  7. From the Tools dropdown at the top of the page, select HCM Experience Design Studio.
  8. From the left navigation, select Digital Assistant Configuration.
  9. If it isn't already pre-populated, fill in the Server URL of the ODA Instance field with the URL of your Digital Assistant instance.

    It should look something like this: idcs-oda-1234567890abcdef1234567890-t0.data.digitalassistant.oci.com

  10. In the Web Channel Id field, paste the ID that was generated when you created the web channel in Digital Assistant.

    Important: Make sure there are no leading or trailing spaces in the pasted web channel ID.

  11. In the Features and Functionality Configuration section, specify any other web channel preferences.

    For example, you may wish to turn off the Bot Responses in Audio option.

  12. Click Save and Close.
  13. Click the page's Home icon (Home icon) to verify that the chat widget appears as you expect.

    If the chat widget doesn't appear, carefully go over the previous steps to make sure that you didn't miss a step.

  14. From the dropdown menu with the name of the sandbox (at the top of the page), select Publish.
  15. In the Publish Sandbox dialog, click OK.
  16. On the Sandbox Detail page, click Publish.
  17. In the Warning dialog, click Continue to Publish.
  18. Back on the Sandbox Detail page, click Done.

Upload Roles for Digital Assistant Access

In this step, you'll upload some sample custom roles to your HCM instance. These roles are designed to provide user access to the digital assistant through the chat widget in the HCM user interface.

Note: These roles are provided to simplify initial setup and testing of the chat widget in HCM. When you eventually roll this out to your users you most likely will want to add the Digital Assistant privileges (HRC_ACCESS_DIGITAL_ASSISTANT_PRIV) to the existing abstract roles for employees and managers.

  1. Download this zip file to your system.

    Note: This zip works in both 21A and 21B.

  2. Click the Tasks icon on the right side of the Setup and Maintenance page to open the task list, and then select Manage Configuration Packages.
  3. In the Search Results section of the page, click Upload.
  4. Click Choose File and select the file that you have downloaded.
  5. Click the Get Details button.

    Details of the configuration package should appear, indicating that the package is for exporting Digital Assistant roles.

  6. Click Submit.
  7. In the Information dialog that appears, click OK.
  8. On the Digital_Assistant_Roles_21B_12MAR21: Export and Import Processes section of the page, click Import Setup Data.
  9. Click Submit.

Verify that the Roles Have Been Imported

Now you'll take a look at the roles you have imported.

  1. Click main menu icon to open the side menu, click Show More, scroll down to the Tools section, and select Security Console.
  2. From the left navigation, select Roles.
  3. In the Search field, enter Digital and press Enter.

You should see two roles related to Digital Assistant:

  • Digital Assistant - Employee Role, which enables users to use the chat widget for base employee level functions.
  • Digital Assistant - Manager Role, which enables users to use the chat widget for manager functions. (Managers would also need the employee role for employee functions.)

Grant the Imported Roles to Employee and Manager Users

Now that the HCM roles for using the digital assistant through the chat widget are in the system, you can start applying those roles to your users.

For each employee (including managers), you would grant the role Digital Assistant - Employee Role.

For managers, you would also grant the role Digital Assistant - Manager Role.

Note: For now, you'll probably just want to add a few users so that you can test the integration. Later, when you are ready to roll out the chatbot functionality to all of your users, you'll probably want to add the privileges related to Digital Assistant to your existing roles.

  1. In the Security Console, click the Users tab.
  2. For each user that requires access to the chat widget:
    1. Search for and select the user.
    2. Click Edit.
    3. Click Add Role.
    4. Search for and select the custom role for Digital Assistant access.
    5. Click Add Role Membership.
    6. Click Done to exit the dialog.
  3. Click Save and Close.

Set the da.FARestEndpoint Parameter

For the digital assistant to be able to communicate with the HCM instance, it needs to use the REST endpoint for that instance. That endpoint is specified in a custom parameter.

You will probably also want to specify that paremeter in the skill itself so that you can test the skill outside of the context of the digital assistant.

Set the da.FARestEndpoint Parameter in the Digital Assistant

  1. In Oracle Digital Assistant, click icon to open the side menu to open the side menu, select Development > Digital Assistants, and select your digital assistant.
  2. In the digital assistant's left navigation, click Skills icon.
  3. Select the Hcm skill.
  4. Scroll down to the Parameters section of the page.
  5. Select the da.FARestEndpoint row and click the Edit button above the table.
  6. In the Edit Parameter dialog, make sure that the value of the parameter is the URL for your HCM instance.

    Note: The URL should

    • Start with https://
    • End with .com
    • Not include a port number

  7. Click OK

    The updated parameter value will be applied for all skills that use the parameter.

Set the da.FARestEndpoint Parameter Directly in the Hcm Skill

If you plan to extend the Hcm skill to add your own customizations, you'll likely want to iteratively test the skill without having to re-add it to the digital assistant each time you've made changes. In this case, you will also need to have the da.FARestEndpoint set directly in the skill itself.

To set the parameter directly in the skill:

  1. In Oracle Digital Assistant, click icon to open the side menu to open the side menu, select Development > Skills, and select the Hcm skill.
  2. In the left navigation for the skill, select the Settings icon and then select the Configuration tab.
  3. Scroll down to the Custom Parameters section of the page.
  4. Select the da.FARestEndpoint row and click the Edit button above the table.
  5. In the Edit Parameter dialog, make sure that the value of the parameter is the URL for your HCM instance.

Verify that the Chat Widget Works

In this section, you confirm that end users can converse with the digital assistant by logging in as one of those end users.

  1. Log in to the HCM UI as an HCM user to whom you just granted a Digital Assistant role.

    Note: The HCM URL needs to include /hcmUI after the root of the URL for the chat widget to appear.

    A screenshot of the HCM UI. In the main content area, there is the message 'Good afternoon, VP HR (Richard Macintyre)! Below that are tabs for 'Me' (which is selected, 'My Team', 'Procurement', 'My Client Groups', etc.  There are tiles for Personal Information, Directory, Onboarding, etc. On the lower right of the page is a red icon that depicts a chat bubble.

    On the bottom right of your screen, you'll see a widget. In the screenshot above, it has a red icon.

  2. Click the widget to open the chat window.

    The chat window should open up within the page.

    A screenshot of a chat window. It has the word 'Ask' in the title bar. In the chat area is a message bubble with the text 'Hello Richard, how can I help you today?'.
  3. Type who is my hr rep and press Enter.

    You should see a response similar to the one that is shown in the screenshot below.

    A screenshot of a chat window. In addition to the contents shown in the previous screenshot is the question 'who is my hr rep' and the answer 'Your HR representative is Jack Adamson', followed by contact information.

  4. Next, type who is my manager and press Enter.

    You should get a response that gives your manager's name and contact details.

    A screenshot of a chat window. In chat area, there is the question 'who is my manager' and the answer 'You report to Andrew Hardaker, Vice President', followed by contact information.

This confirms that the HCM widget is correctly set up to use the FADigitalAssistant digital assistant, through which users can access personal and job-related data from the HCM backend.

Want to Learn More?

  • If you want to learn more about how Digital Assistant works with Oracle Cloud HCM and other Fusion-based Cloud Applications, visit the following section of Using Oracle Digital Assistant: Fusion-Based Oracle Cloud Applications and Digital Assistant
  • To learn how to extend and customize your copy of FADigital Assistant, see Extending Skills.
  • To consult with experts on Digital Assistant integration with HCM, attend our Office Hours events. You can find more information through Cloud Custom Connect.