1. Sign in to your Oracle Cloud account.
2. In the Infrastructure Console, click on the top left to open the navigation menu, select Analytics & AI, and select Digital Assistant (which appears under the AI Services category on the page).
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 Digital Assistant Instance.
5. On the Create Digital Assistant 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 higher rate limits and greater database capacity, which enables more Insights data to be collected.

     See Instance Shapes and Rate and Storage Limits for information on the rate limits.

   • If you want to enable role-based access to the instance (instead of IAM's default policy-based access), click Show Advanced Options, select Enable Role Based Access, and select an identity domain.

     See Role-Based Access and Identity Domains for information on setting up users and groups and assigning roles.

     Note
     
     The Enable Role Based Access option is disabled if the current tenancy doesn't yet have support for Identity Domains.

   • 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.

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.

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.

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

• Oracle Cloud Infrastructure Direct Sign-In (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.

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:

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

The number of requests per minute that can be made to your instance depends on your instance's shape:

• Development shape: 50 requests per minute
• Production shape: 500 requests per minute

These limits cover requests from user channels (such as Slack, Microsoft Teams, Web, Twilio, Webhook, and so on).

For any requests that occur when the rate limit has been reached, a HTTP 429 (Too Many Requests) response is returned.

In addition, the amount of storage allocated for Insights data is dependent on instance shape:

• Development shape: 40GB
• Production shape: 100GB

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 on the top left to open the navigation menu, select Identity & Security, and select Compartments.

   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. Under the Identity section of the Identity & Security page, 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.

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

   1. Under the Identity section of the Identity & Security page, click 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. Under the Identity section of the Identity & Security page, click 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. Click on the top left to open the navigation menu, select Analytics & 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:

        • Development. This is a lightweight option that is geared toward development work.
        • Production. This option should be selected for production instances of Oracle Digital Assistant. In comparison with the Development shape, the Production shape can accept more requests per minute and has greater database capacity, which enables more Insights data to be collected and stored.
   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.

Digital Assistant instances that are paired with subscriptions to an Oracle Fusion Applications Cloud service are designed for you to use and extend existing out-of-the-box skills that are provided by that Fusion Applications service. By default, these paired instances do not allow you to use the full range of Digital Assistant features, such as creating and cloning skills and digital assistants.

If you want to take advantage of Digital Assistant's full range of features within the paired instance, you can link that paired instance to a subscription to Digital Assistant as an individual service. If your paired instance isn't linked in this way, you will get warning messages when creating skills or digital assistants or performing any other task that is not covered by the terms for the paired instance.

There are two ways that you can link your paired Digital Assistant instance:

• Using the same Oracle Cloud account in which you have your Fusion Applications subscription, purchase an Oracle Digital Assistant Platform for SaaS subscription. Once you have enabled the entitlement for that subscription, the linking should occur automatically.

  You'll know the link has been successfully established if you can do things in the paired instance like create new skills without seeing a warning that you do not have the necessary entitlement to do so.

  Note
  
  When linking to this type of subscription, you don't need to actually provision a new instance for the linking to work. In fact, it is best to keep doing your development work in the paired instance and not provision an instance for the Oracle Digital Assistant Platform for SaaS subscription.

• Using the same Oracle Cloud account in which you have your Oracle Applications subscription, subscribe to Digital Assistant Cloud Service through the Universal Credits program, provision an instance, and then manually link that instance to your paired instance. See Manually Link Digital Assistant Instances.

Each instance of Digital Assistant that has been migrated from the Gen 1 infrastructure to the Gen 2 infrastructure has an IDCS application to handle user authorization and access to APIs. The name of the IDCS application should begin with idcs-oda.

Within that IDCS application is a group called OCI_Administrators. 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 and manage users in IAM.

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.

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 Oracle Cloud Services 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 ) 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 ) in the tile for the role and select Revoke Users.

As Oracle Cloud Infrastructure (Gen 2) is a multi-tenant architecture, Digital Assistant instances that are migrated to Gen 2 do not 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.