2 Order the Service and Provision an Instance

To get your team set up with Oracle Digital Assistant, you order the service, give users appropriate permissions, and then provision the instance.

Digital Assistant Product Types

Oracle Digital Assistant is available through a variety of pricing and subscription models. How you set up your instance depends on which of these models you select when you order the service.

The pricing models break down into the following general types:

  • Individual service. When you order Digital Assistant as an individual service, you typically provision such instances yourself. See Set Up Digital Assistant as an Individual Service.
  • Paired with Fusion-based Cloud applications. You can get Digital Assistant in this way when you have Fusion-based Oracle Applications Cloud services (such as Sales Cloud or HCM Cloud) and purchase one of the out-of-the-box skills (chatbots).

    When you get ODA in this form, it is automatically provisioned for you. You give team members access to the instance in the IDCS application for the instance. See Fusion-Based Oracle Cloud Applications and Digital Assistant.

    Note:

    This type of Digital Assistant order is specifically designed for you to be able to extend those out-of-the-box skills for your business. If you also want to create custom skills or integrate with backends other than the service that the out-of-the-box skills are tied to, you need to get a separate individual subscription to Digital Assistant.

Place an Order for Oracle Digital Assistant

You can place an order in one of these ways:

After you place an order for Oracle Digital Assistant as in individual service, you receive an email with instructions on accessing your Cloud account with a temporary password. Once you log in with that password, you are prompted to enter a new password. After that, you can go ahead and set up your users and provision your instance.

Set Up Digital Assistant as an Individual Service

To set up a an individual instance of Oracle Digital Assistant (in other words, an instance that is not paired with an order of Oracle Cloud Applications and thus not provisioned automatically for you), you need to go into the Oracle Cloud Infrastructure Console and do the following:

  1. Set up a compartment for the Digital Assistant in your tenancy.
  2. Set up users and groups for the users.
  3. Set up policies that govern the permissions for the user groups.
  4. Provision the instance.

The following topics provide a thorough description of the concepts and considerations behind these tasks and how to complete them. If you'd like to quickly get an instance up and running and configure a basic set of user permissions, you can follow this Recipe for Quick Setup and Provisioning.

Users, Groups, and Policies

Oracle Digital Assistant uses Oracle Cloud Infrastructure Identity and Access Management (IAM) as its base service for authentication and authorization. (Through IAM, you can also set up federation to other identity providers, such as Oracle Identity Cloud Service (IDCS).)

IAM is a policy-based identity service. The tenancy administrator for your organization needs to set up compartments, groups, and policies that control which users can access which resources and how. For an overview of this process, see Setting Up Your Tenancy.

In Digital Assistant, policies control who can develop skills and digital assistants, access Insights data, and call the service's APIs. For details on how policies work, see Getting Started with Policies. For specific details about writing policies, see Policy Reference.

Digital Assistant Policies

Before you start organizing your users into groups, you should learn the basics on how policies work and decide on what policies you want to apply to which groups of users.

Policies are created with statements that specify resource-types, verbs (which describe the level of access to those resource types), and locations (typically the names of compartments).

For example, you could create a policy statement that enables a group named ServiceDevelopers to be able to use the resource type oda-design in a compartment named MyDigitalAssistantTest.

Resource-Types

This table shows the resource types that are available for Oracle Digital Assistant.

Resource-type Description
oda-instance-resource Enables use of Oracle Digital Assistant APIs. There are three permissions levels (verbs) that you can apply. For details on which endpoints are covered in each permission level (inspect, read, and use), see REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure and click Permissions in the left navigation of the page.
oda-design Enables access to the user interface for skills, digital assistants, and channels. At the read permission level, users can see the artifacts that have been created. At the use level, users can actively develop, test, and deploy these artifacts.
oda-insights Enables access to the user interface for skill and digital assistant Insights.
oda-instances Enables access to the console for Oracle Digital Assistant instances. At the manage permission level, you can create and delete instances.
oda-family This resource type is a superset of the Oracle Digital Assistant resource types. For each verb (inspect, read, use, and manage) that you use with this resource-type in a policy definition, all operations covered by that verb are included. For example, if you have a policy using this resource type and the manage verb, the user(s) that are covered by this policy will have all possible Oracle Digital Assistant permissions.
Verbs

You use verbs in policy definitions to set the permission levels that given user groups have for given resource-types. For example, you would use the read verb to allow read-only access.

Here are the verbs have been defined for the set of Oracle Digital Assistant resource-types.

Verb Description
inspect Generally covers operations that list contents of a resource. This is the verb that provides the most limited access.
read In user interface terms, this generally means read-only access. In API terms, it generally applies to GET operations.
use When applied to resources in the service's user interface, this generally allows developing, testing, and deploying of these resources. At the API level, it generally allows GET, PUT, POST, PATCH, and DELETE operations, with the exception of more high-impact operations (such as creating instances and purging data).
manage Generally allows the user to perform the whole set of a resource type's operations, including high-impact operations such as creating instances and purging data.
Example Set of Policies

The following table illustrates the patterns for IAM policies and provides typical examples for Oracle Digital Assistant.

IAM Policy Pattern for Policy Statement
Policy for Service Administrators
  • Allow group <name_of_your_Service_Administrators_Group> to manage oda-family in compartment <your_digital_assistant_compartment>
Policy for Service Developers
  • Allow group <name_of_your_Service_Developers_Group> to use oda-design in compartment <your_digital_assistant_compartment>
  • Allow group <name_of_your_Service_Developers_Group> to use oda-insights in compartment <your_digital_assistant_compartment>
Policy for Service Business Users
  • Allow group <name_of_your_Service_Business_Users_Group> to read oda-design in compartment <your_digital_assistant_compartment>
  • Allow group <name_of_your_Service_Business_Users_Group> to use oda-insights in compartment <your_digital_assistant_compartment>
Policy for Digital Assistant API Users
  • Allow group <name_of_your_Digital_Assistant_API_Users_Group> to use oda-instance-resource in compartment <your_digital_assistant_compartment>

Note:

This statement provides access to all of the Oracle Digital Assistant endpoints. You can also create policies using the inspect and read verbs for more limited access. To see which endpoints are covered by which verbs, see REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure.
Create a Compartment

Compartments enable you to partition resources in Oracle Cloud Service so that you can better control access to those resources. When you write policies to give users access to a Digital Assistant instance, the compartment name is one of the parts of the policy statement.

Note:

You can also write policies that give users access to the resources in the entire tenant, but that is best for very simple setups (such as if you never intend to have more than one Digital Assistant instance.

To create a compartment:

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Compartments.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. Click Create Compartment.
  3. Fill in the required values and click Create Compartment.
Create New IAM Users

If any of your users don't have user accounts yet, create them in IAM.

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Users.

  2. Click Create User.

  3. In the Create User dialog, fill in the necessary details, with special attention to the following:

    • The Name value can be an email address or a unique name. This will be the name that the user uses to log in to the instance.
    • The Email value, which is used for password recovery.
  4. Click Create.

  5. Once the user is created, select the user and click Create/Reset Password.

  6. Click Copy.

  7. Paste the password in a secure place, and then provide it to the user.

    The user will need to log in with that password and then immediately change it.

Create Groups

Groups are collections of users that can be referenced in policies. You create groups to help manage which users get access to what.

Here is an example set of user groups that you could set up.

User Group Description and Purpose
Service Administrators Has complete unfettered access to manage, administer, and develop with the Oracle Digital Assistant service instance.
Service Developer Has privileges to develop and train digital assistants. However, can't delete published digital assistants or skills nor purge data. These privileges are a subset of service administrator privileges.
Service Business Users Mostly read-only access. Can use the skill and digital assistant tester, view Insights reports, and also enhance the training corpus by adding sample utterances (retraining). These privileges are a subset of service developer privileges. Intended for line-of-business users and analysts.
External Service Users Has permissions to call Oracle Digital Assistant REST APIs. There are three different permission levels (the inspect, read, and use verbs) for Oracle Digital Assistant APIs. As such, you may want to create a separate group for two or three of those permission levels.

To create a group:

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity, and then select Groups.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

    A list of the groups in your tenancy is displayed.

  2. Click Create Group.

  3. Enter the following:

    • Name: A unique name for the group. The name must be unique across all groups in your tenancy. You cannot change this later.
    • Description: A friendly description. You can change this later if you want to.
    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  4. Click Create Group.

Add IAM Users to a Group

You'll need to add each user to a group in order to give them access to the service.

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Groups.

    A list of the groups in your tenancy is displayed.

  2. Locate the group in the list.

  3. Click the group.

  4. Click Add User to Group.

  5. Select the user from the drop-down list, and then click Add User.

Map IDCS Users to an IAM Group

If the user accounts for the team members that need to access Digital Assistant have been set up in Oracle Identity Cloud Service (IDCS), you can map those users to an IAM group.

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Federation.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. Click the OracleIdentityCloudService link.

  3. In the left navigation, click Group Mappings.

  4. Click Edit Mapping.

  5. Click Add Mapping.

  6. In the Identity Provider Group field, select the IDCS group for the users that you want to give access to Digital Assistant.

  7. In the OCI Group field, select the IAM group that corresponds with the access that you want to provide for those users.

  8. Click Submit.

Create Policies

You define IAM policies to apply to your user groups.

To create a policy:

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Policies.

    A list of the policies in the compartment you're viewing is displayed.

  2. If you want to attach the policy to a compartment other than the one you're viewing, select the desired compartment from the list on the left. Where the policy is attached controls who can later modify or delete it (see Policy Attachment).

  3. Click Create Policy.

  4. Enter the following:

    • Name: A unique name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later.
    • Description: A friendly description. You can change this later if you want to.
    • Policy Versioning: Select Keep Policy Current if you'd like the policy to stay current with any future changes to the service's definitions of verbs and resources. Or if you'd prefer to limit access according to the definitions that were current on a specific date, select Use Version Date and enter that date in format YYYY-MM-DD format. For more information, see Policy Language Version.
    • Statement: A policy statement. For the correct format to use, see Policy Basics and also Policy Syntax. If you want to add more than one statement, click +.
    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  5. Click Create.

The new policy will go into effect typically within 10 seconds.

For an example of how you might define your Oracle Digital Assistant policies, see Example Set of Policies.

For more background on IAM policies, see How Policies Work.

Create an Oracle Digital Assistant Service Instance

  1. Sign in to your Oracle Cloud account.
  2. From the Infrastructure Console, click the navigation menu Navigation menu icon in the top left corner, scroll down to and expand Data and AI, and select Digital Assistant.
  3. From the Compartments panel, select a compartment.

    If you haven't yet created a compartment, see Understanding Compartments and Managing Compartments.

  4. Click Create Instance.
  5. On the Create Instance page, fill in the following details:
    • Compartment.
    • Name. Enter a name that reflects usage of the instance. For example, for a development environment, you might use oda-dev1.

    • Instance shape. Select between the following shapes:

      • Development. This is a lightweight option that is geared toward development work.
      • Production. This option should be selected for production instances of Digital Assistant. In comparison with the Development shape, this option has greater database capacity, which enables more Insights data to be collected.
    • Tag Namespace. (Optional) To learn how this works, see Managing Tags and Tag Namespaces.

  6. Click Create.

    After a few minutes, your instance will go from the status of Creating to Active, meaning that your instance is ready to use.

Note:

If provisioning of the instance fails, it could be because you have reached the service limit for Digital Assistant instances on your account. For an explanation of service limits and the possibility of requesting a higher limit, see Service Limits.

Access the Service Instance from the Infrastructure Console

Once you have provisioned an instance, you can access it from the Infrastructure Console by following these steps:

  1. In the console page for the instance, click the Service Console button.

    You will be redirected to another login page.

  2. Click the Change tenant link.

  3. In the Cloud Tenant field, enter the value of the Cloud Account field from the Access Details section of your welcome email.

  4. Sign in to the instance.

    As the tenant administrator, you can always log in with your single-sign on credentials (on the left side of the page). Similarly, any users that have been federated through IDCS can log in with these credentials.

    Any users that have been provisioned with IAM user accounts can log in on the right side.

    Once you have signed in, you should be directed to your Oracle Digital Assistant service instance.

    Note:

    If your new password doesn't work, it may be because it hasn't taken effect yet. If that is the case, try entering the temporary password you received from your welcome email.

Get the Service Instance URL

You can retrieve the URL for your service instance on the console page for the instance. You will then need to share that URL with your team, since they will not be otherwise notified, even when they are granted permissions for Digital Assistant.

  1. In the Instance Information tab, click the Copy link that appears to the right of the Base Web URL field.

    This will copy the URL to your system's clipboard.

  2. Paste the URL to a convenient location.

  3. Share this URL with members of your team.

Sign-In Options

When you enter the URL for your Oracle Digital Assistant instance in your browser, you are presented with two login options:

  • Oracle Cloud Infrastructure (IAM): IAM is the native identity service for Oracle Cloud Infrastructure. If all of your Oracle Cloud services fall under Oracle Cloud Infrastructure (Gen 2), you should set up your user accounts in IAM and use this as your primary sign-in option.
  • Single Sign-On (SSO): With this option, you can log in if you have a user account with an identity provider that is federated with IAM. For example, Oracle Identity Cloud Service (IDCS) is a service used by many Oracle Cloud services, including ones that are not part of the Oracle Cloud Infrastructure (Gen 2) architecture. Once such a user account is federated and assigned to groups with appropriate permissions, that user account can be used as a single sign-on option for all of that user's Oracle Cloud services.

    Note:

    If you are the Cloud account administrator, you can log in to Digital Assistant with your IDCS account, even if you haven't explicitly added that account to a group with permissions for accessing Digital Assistant.

For more on these options, how they relate to each other, and what it looks like when you sign in with each, see Understanding the Sign-In Options.

Service Limits

Oracle Digital Assistant has limits for the number of instances and embedded custom component services that you can create. Whenever you create a new instance or embedded custom component service, the system ensures that your request is within the bounds of your limit.

For instances, the limit depends on the way you ordered Digital Assistant:

Resource Limit Limit Short Name Limit Description
Digital Assistant instance count instance-count 20 Maximum number of instances of Oracle Digital Assistant.
Embedded custom component service count embedded-custom-component-service-count (View in the Infrastructure Console) Limit per instance on embedded container services that you can create to host custom components.
View Service Limits in the Infrastructure Console

To view your current service limits:

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Governance, then click Limits, Quotas, and Usage.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. In the Service dropdown, select Digital Assistant.

If the limit is too low for your need, you can request an increase. See Requesting a Service Limit Increase.

Service Quotas

You can use quotas to determine how other users allocate resources across compartments in Oracle Cloud Infrastructure. Whenever you create an Oracle Digital Assistant instance or scale up, the system ensures that your request is within the bounds of the quota for that compartment.

For more on how quotas work, see Compartment Quotas.

This table shows the Digital Assistant-related quota that you can apply to compartments

Quota Name Scope Description
instance-count Regional Maximum number of instances of Oracle Digital Assistant for the compartment
Example Quota Policy for Oracle Digital Assistant

Here's an example of a quota statement:

Set digital-assistant quota instance-count to 3 in compartment MyCompartment

In this example, the number of Oracle Digital Assistant instances that can be provisioned in the compartment MyCompartment is limited to 3.

Recipe for Quick Setup and Provisioning

When you set up your instance for your users, you should carefully plan how you organize your tenancy and construct your user groups and policies. However, if you'd like to quickly set up an instance before becoming completely conversant in these concepts, you can follow the "recipe" below.

In this recipe, in addition to provisioning the instance, you set up permissions for developers and administrators using Oracle Cloud Infrastructure's Identity and Access Management (IAM) service. You can later adapt the recipe to your own needs.

  1. Create a compartment in which you'll place your instance.

    Compartments provide logical groupings of service instances and other cloud resources. By creating a compartment for your instance, you can grant users permissions for the instance without granting those permissions for your whole tenancy.

    1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Compartments.

      You might need to use the scroll bar on the left to scroll down to see the menu option.

    2. Click Create Compartment.
    3. In the Name field, enter da_development.

      You can choose another name if you wish. If you do so, remember to adjust the policy definitions below accordingly.

    4. Fill in the rest of the required values and click Create Compartment.
  2. Create IAM user accounts for any other team members that you want to have access the instance.

    1. In the Identity menu, select Users.

    2. Click Create User.

    3. In the Create User dialog, fill in the necessary details, with special attention to the following:

      • The Name value can be an email address or a unique name. This will be the name that the user uses to log in to the instance.
      • The Email value, which is used for password recovery.
    4. Click Create.

    5. Once the user is created, select the user and click Create/Reset Password.

    6. Click Copy.

    7. Paste the password in a secure place, and then provide it to the user.

      The user will need to log in with that password and then immediately change it.

  3. Create one IAM group for your developers and one for your administrators.

    1. In the Identity menu, select Groups.

    2. Click Create Group.

    3. Complete the fields in the dialog as follows:

      • Name: ServiceDevelopers
      • Description: Developer access to the instance of Digital Assistant in the da_development compartment.
    4. Click Create Group to complete creation of the group.

    5. Again, click the page's Create Group button.

    6. Enter the following:

      • Name: ServiceAdministrators
      • Description: Complete access to the instance of Digital Assistant in the da_development compartment, including the ability to set feature flags and purge data.
    7. Click Create Group.

    Note:

    As with the compartment name, you can name the groups anything that you wish. If you use different names, remember to adjust the policy definitions below accordingly.
  4. Create policies for each group that define the level of access each member gets to the Digital Assistant instance.

    In these steps, you'll create policies to define the access that each group will have. For the developer group, you'll give permissions that allow development of skills and digital assistants, creation of channels, and other functions useful for developers. For the administrator group, you'll provide full permissions for the instance, including the ability to enable features and manage analytics data.

    1. In the Identity menu, select Policies.

    2. From the list of compartments on the left, select da_development.

    3. Click Create Policy.

    4. For Name and Description, enter the following:

      • Name: Policy-for-DA-ServiceDevelopers
      • Description: Policy for developer access to instances of Digital Assistant in the da_development compartment.
    5. For Policy Versioning, select Keep Policy Current.

    6. For Statement, enter the following two statements:

      • Allow group ServiceDevelopers to use oda-design in compartment da_development
      • Allow group ServiceDevelopers to use oda-insights in compartment da_development
    7. Click Create.

    8. Again, click Create Policy.

    9. Enter the following:

      • Name: Policy-for-DA-ServiceAdministrators
      • Description: Policy for complete access to instances of Digital Assistant in the da_development compartment.
      • Policy Versioning: Keep Policy Current.
      • Statement: Allow group ServiceAdministrators to manage oda-family in compartment da_development
    10. Click Create.

  5. Add users to the appropriate IAM groups. (You don't need to add yourself, because you already have access to the instance as the Cloud account administrator.)

    1. In the Identity menu, select Groups.

    2. Locate the group in the list.

    3. Click the group.

    4. Click Add User to Group.

    5. Select the user from the drop-down list, and then click Add User.

  6. Create the Oracle Digital Assistant service instance.

    1. From the navigation menu in the top left corner, scroll down to and expand Data and AI, and select Digital Assistant.
    2. From the Compartments panel, select da_development.
    3. Click Create Instance.
    4. On the Create Instance page, fill in the following details:
      • Compartment: da_development
      • Name: da-dev1 (or another name that reflects usage of the instance)

      • Instance shape: Production

    5. Select the VIEW DIGITAL ASSISTANT INSTANCE DETAILS UPON CREATING checkbox.
    6. Click Create.

      After a few minutes, your instance will go from the status of Creating to Active, meaning that your instance is ready to use.

  7. Get the URL for your users.

    1. On the Instance Information tab of the page for your instance in the Infrastructure Console, click the Copy link that appears to the right of the Base Web URL field.

      This will copy the URL to your system's clipboard.

    2. Paste the URL to a convenient location.

    3. Share this URL with members of your team.

      Since you have set them up with IAM accounts, tell them to sign in on the right side of the login page (under Oracle Cloud Infrastructure).

      However, you will need to log in on the left side of the page with your SSO account (unless you have added your IAM user account to either the ServiceDevelopers or ServiceAdministrator group).

      Note:

      As the Cloud account administrator, you have both SSO (via Oracle Identity Cloud Service) and IAM accounts. And, as Cloud account administrator, you can sign in into Digital Assistant with your SSO account without first having to add yourself to a group with permissions for Digital Assistant.
  8. (Optional) Access the instance from the Infrastructure Console.

    You can also access the service instance from the Infrastructure Console:

    1. In the console page for the instance, click the Service Console button.

      You will be redirected to another login page.

    2. On the login page, where it says Signing in to cloud tenant, make sure that the tenant name matches the name in the Cloud Account field in the Access Details section of your welcome email. Otherwise, click the Change tenant link and enter the name of your cloud account before continuing.

    3. On the left side of the page, under Single Sign-On (SSO), click Continue.

      You should be directed to your Oracle Digital Assistant service instance.

Fusion-Based Oracle Cloud Applications and Digital Assistant

If you have a Digital Assistant instance that is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as HCM Cloud or Sales Cloud, the setup steps are different than if you have ordered Digital Assistant independently.

In this case, Digital Assistant is provided so that you can customize out-of-the-box skills that come with your Cloud Applications service.

The following topics explain how to set up users to be able to use Digital Assistant and get started with the out-of-the-box skills.

Assign Users the ServiceDeveloper Role

For Digital Assistant instances that are linked with Fusion-based Oracle Cloud services, you use an Oracle Identity Cloud Service (IDCS) application to manage access to Digital Assistant.

To access Digital Assistant, your team members need the ServiceDeveloper role. The Cloud Account Administrator on your team (typically, the person who signed up for the service) can grant other team members this role.

To set up users with the ServiceDeveloper role:

  1. As the Cloud Account Administrator, log in to IDCS.

    The URL for your IDCS instance is provided in the welcome email you receive when you sign up for the service (or if and when the service was upgraded to include out-of-the-box skills).

  2. Click the Applications tile.

  3. Navigate to the IDCS application for your Digital Assistant instance.

    This application probably has idcs-oda at the beginning of its name.

  4. In the IDCS application, click the Application Roles tab.

  5. In the tile for the ServiceDeveloper role, click role menu icon) and select Assign Users or Assign Group.

  6. Select the users or groups that you want to assign the role to and click Assign.

    Note:

    If you want to be able to access the Digital Assistant user interface, be sure to assign yourself that role as well.

Get the Digital Assistant Instance URL

For instances of Digital Assistant that come with a Fusion-based Cloud Applications service, here's how you get the URL for the service:

  1. In the IDCS application for Digital Assistant, click the Configuration tab, and find the Primary Audience field.

  2. Copy the value of the Primary Audience field and paste it to a text file.

  3. Append /botsui to the URL that you copied.

    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.

Get the Out-of-the-Box Skills

Out-of-the-box skills that are provided for Fusion-based Cloud Applications services are available in Digital Assistant's Skill Store.

To get a skill from the Digital Assistant Skill Store:

  1. Log in to Digital Assistant.
  2. Click icon to open the side menu to open the side menu and select Development > Store.

  3. In the tile for the skill that you want to add, click icon to open the Options menu and select Pull.

    The skill appears in Skills Catalog in your instance. The next step is to train the skill.

Train the Out-of-the-Box Skills

Before you can use a skill or test its behavior, you need to train it.

To train a skill:

  1. Log in to Digital Assistant.

  2. In Digital Assistant, click icon to open the side menu to open the side menu and select Development > Skills.

  3. Click the tile for the skill that you want to train to open it.

  4. Click the Train button in the upper right corner of the page and then click Submit.

Test the Out-of-the-Box Skills

You can test the behavior of a skill directly within Digital Assistant. See The Skill Tester.

Learn About Extending Out-of-the-Box Skills

Once you have pulled out-of-the-box skills, you can evaluate them, deploy them as is, or extend (customize) them and then deploy them.

Explore these topics to learn what you can do and how to do it:

Learn About Personalizing Digital Assistants

If you deploy your out-of-the-box skills as part of a single digital assistant, here are some things you can do with the digital assistant.

Developing Custom Skills and Digital Assistants

Digital Assistant instances that are paired with subscriptions to a Fusion-based Oracle Applications Cloud service are designed for you to use and extend existing out-of-the-box skills that are provided by that Oracle Applications Cloud service. However, you aren't automatically allowed to develop your own skills and digital assistants in these paired instances. If you have such an instance, you will get warning messages when attempting to create new bots (or importing or cloning existing bots).

To be able to develop your own skills and digital assistants, you need to have a subscription to Digital Assistant as an individual service.

If you have both a paired Digital Assistant instance and an instance of Digital Assistant as an individual service, you can link the instances. Doing so enables you to develop bots in both instances.

Depending on your needs you can subscribe to either Oracle Digital Assistant Cloud Service or one of the Oracle Digital Assistant Platform for Oracle SaaS options.

When you sign up for the subscription, be sure to use the same Oracle Cloud account where you have your paired instance. See Place an Order for Oracle Digital Assistant for getting a subscription to an individual instance.

Once you have a subscription, you need to provision an instance. When you do so, be sure to provision it in the same region as your Oracle Applications Cloud instance. See Set Up Digital Assistant as an Individual Service for details on provisioning an instance.

Once you have an instance of Digital Assistant provisioned, you can link your paired instance to it and develop new bots directly in the paired instance.

Link Digital Assistant Instances

To link a Digital Assistant that is paired with an Oracle Cloud Applications instance to a Digital Assistant instance that allows you the full range of bot development features:

  1. Log in to the paired instance of Digital Assistant with administrator privileges.

  2. Click icon to open the side menu to open the side menu and select Settings > Linked Instance.

  3. Click Set Linked Instance.

  4. In the dialog, select an instance from the Service Instance dropdown and click Link Instance.

    If there are no instances shown in the dropdown, you either:

    • Don't have any instances in the same Oracle Cloud account that your paired instance is in.
    • Don't have any instances in the same region that your paired instance is in.

    For information on subscribing to Digital Assistant as an individual service and provisioning an instance, see Place an Order for Oracle Digital Assistant and Set Up Digital Assistant as an Individual Service.

Administration of Linked Instances

When you have linked Digital Assistant instances, there are some important administrative details to be aware of:

  • You can't unlink a Digital Assistant instance yourself. To unlink it, you need to file a Service Request.
  • In the Infrastructure Console, you can't stop or delete instances that have been linked to.
  • After an instance has been linked, any billable activity related to your custom skills and digital assistants is billed to the linked instance, even if those bots are hosted in the instance that was provisioned for your out-of-the-box Oracle Cloud Applications skills.

Migration from Gen 1 to Gen 2 Infrastructure

If you have instances of Oracle Digital Assistant that were originally provisioned on Oracles's Gen 1 cloud infrastructure and which have since been migrated to Oracle Cloud Infrastructure (Gen 2), most of your work with the migrated instances should proceed without interruption. However, there are some differences. Here's what you need to know.

What Happens When an Instance is Migrated

When an instance of Digital Assistant is migrated from the Gen 1 infrastructure to the Gen 2 infrastructure, the following things happen:

  • A new IDCS application is created to handle user authorization and access to APIs, and it is associated with the instance.

    The name of the IDCS application should begin with idcs-oda.

  • In the IDCS application, a group called OCI_Administrators is created, and the Cloud account administrator is assigned to this group. Members of this group can later access the Gen 2 infrastructure console to provision new instances, manage users in IAM (the Gen 2 infrastructure's access management system).

The following things don't change:

  • The URL to your instance.
  • The way you handle identity management for the instance. (You still use IDCS.)

Differences in Migrated Instances

Here are some differences that you need to note (and possibly take action on) once an instance has been migrated from Gen 1 to Gen 2:

  • There are two new application roles available in the instance's IDCS application (ServiceAdmin and ServiceBusinessUser), in addition to ServiceDeveloper, which was the only role available in Gen 1 instances.

  • Custom component packages that you upload to an embedded custom component service must contain all node module dependencies as described in Prepare the Package for an Embedded Container Service. If the package doesn't contain all its dependencies, then you'll receive an invalid component path error.

  • In the Gen 2 infrastructure, there are service limits for embedded custom components services.

    If you need to raise the limit, you can request an increase. For more information, see View Service Limits in the Infrastructure Console and Requesting a Service Limit Increase.

  • If any of your skills use the OAuth2Client component to access the Oracle Digital Assistant REST APIs, then the authentication service that they rely on must be updated to use the new IDCS confidential app that has been provisioned for the Gen 2 instance. You'll need to update the client ID, client secret, and scope. To learn how to get the new values, see the Send Requests topic in REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure. To learn about updating the authentication service, see Authentication Services.
  • The Sessions API endpoint has changed and now includes the user ID and channel ID in addition to the session ID. For any custom components that call this API to get the conversation log, you need to modify that API call. In addition, the client ID, client secret, and scope that you use to get the access token to authorize the REST call must be updated. For custom components that access the Sessions API, you need to make these changes:

    • Your code must call conversation.channelId() to get the channel ID for the request path.
    • You must change the request path to /api/v1/bots/sessions/{channelId}/{userId}/{sessionId}/log. Note that currently, the user ID has the same value as the session ID.
    • If the custom component retrieves the access token, then the client ID, client secret, and scope must be updated in the REST call to the access token endpoint. To learn how to get the new values, see the Send Requests topic in REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure.

    After you make the changes, re-package the components. Then, for all skills that have a component service for the component package, reload the package.

    For further details about the API, see REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure.

  • For Agent Transfer (Agent Integrations), the customInfo object structure is different for new channels if the target OSvC is 19A or later.

  • The Web, Android, and iOS SDK channel types in Gen 1 instances are replaced by Oracle native versions of those channel types in Gen 2 (with new SDKs for each channel type). If you have any skills or digital assistants that use the old channel types, you should migrate them to use the new Oracle native channel types.

    See Oracle Digital Assistant Web SDK customization and programming examples on the TechExchange blog for concrete examples of how to adapt web app code to the new Web SDK.

  • You can now use Answer Intents to add FAQ functionality to a skill. As opposed to the Q&A functionality, answer intents are resolved with NLP. In addition, you don't need to update the dialog flow to handle answer intents the way you do a Q&A module.
  • There is a variety of other features and enhancements available in Gen 2 instances of Digital Assistant that are not available in Gen 1 instances. For a rundown of these features, see What's New in Oracle Digital Assistant.

Manage User Access in a Migrated Instance

For Digital Assistant instances that have been migrated from the Gen 1 cloud infrastructure to Gen 2, you use an Oracle Identity Cloud Service (IDCS) application to manage access to Digital Assistant.

In Gen 2 instances, the following application roles are available:

  • ServiceAdministrator, which provides full permissions for the instance. In Gen 1 instances, the ServiceDeveloper role provides this level of access.
  • ServiceDeveloper, which provides permissions that are relevant for users who develop skills and digital assistants. It lacks some admin permissions (such as the ability to purge data).
  • ServiceBusinessUser, which provides a subset of the ServiceDeveloper permissions and is primarily focused on the ability to work with Insights reports.

By default, all users of a migrated instance are assigned the ServiceAdministrator role. For users that should not have the full ServiceAdministrator permissions, you can change their roles that better align with their use of the instance.

To assign a user one of these roles:

  1. As the Cloud Account Administrator, log in to IDCS.

  2. Click the Applications tile.

  3. Navigate to the IDCS application for your migrated Digital Assistant instance.

    This application should have a name that matches the first part of your instance's fully-qualified domain name (FQDN). For example, if your instance's FQDN is idcs-oda-abcd1234-p0.digitalassistant.example.com, then the IDCS application should have idcs-oda-abcd1234-p0 at the beginning of its name.

  4. In the IDCS application, click the Application Roles tab.

  5. In the tile for the role that you want to add users to, click role menu icon) and select Assign Users or Assign Group.

  6. Select the users or groups that you want to assign the role to and click Assign.

    Note:

    If you want to be able to access the Digital Assistant user interface, be sure to assign yourself that role as well.

To remove a role assignment for a user, click role menu icon) in the tile for the role and select Revoke Users.

Note:

In the Gen 1 infrastructure, the only available IDCS application role for Digital Assistant is called ServiceDeveloper, but its Gen 2 equivalent is ServiceAdministrator.

IP Addresses for the Allowlist

As Oracle Cloud Infrastructure (Gen 2) is a multi-tenant architecture, Digital Assistant instances that are migrated to Gen 2 will no longer have their own range of IP addresses. Instead, you have a range of public IP addresses that are determined by the region that your instance resides in. If you had previously had an allowlist with a range of IP addresses for your instance when it was on the Gen 1 infrastructure, you'll need to update that list with public IP addresses provided in the Gen 2 infrastructure.

To determine the range of IP addresses for your region, see Public IP Addresses for VCNs and the Oracle Services Network.