Oracle Cloud Infrastructure Documentation

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.

Place an Order for Oracle Digital Assistant

You can place an order in one of these ways:

After an order is placed, as the Cloud Account Administrator, 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 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.

Set Up Groups, Users, and Policies

Oracle Digital Assistant uses Oracle Cloud Infrastructure Identity and Access Management (IAM) for authentication and authorization.

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.

Policies control who can create new users, 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

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

Resource-Types

This table shows the resources 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. 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 include verbs in policy definitions to express how a user with a given permission for a resource-type can interact with resources that are encompassed by that permission.

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.
Read Generally applies to GET operations.
Use Generally applies to GET, PUT, POST, PATCH, and DELETE operations, with the exception of more high-impact operations (such as creating instances and purging data).
Manage Usually applies to the whole set of a resource-type's operations.
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 Groups

Create groups to grant access to Digital Assistant instances to multiple users.

Here are the recommended user groups for Digital Assistant

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 (list, read, and use) for Oracle Digital Assistant APIs. As such, you may want to create a separate group for two or three of those permission levels.
  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. 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 Existing Users to a Group
  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.
Create New Users
  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.

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.

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

  7. Once the service is active, click Service Console to get to the instance's login page.
  8. Log in to the instance with your credentials.

Access the Service Instance for the First Time

Once you have provisioned an instance, you can access it for the first time 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 value of the Cloud Account field from the Access Details section of your welcome email.
  4. On the right side of the page, under Oracle Cloud Infrastructure, enter your user name and password, and click Sign 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:

  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.

You can then share this URL with members of your team who have user accounts with permissions to use the service instance.