Service Administration

Note

The information on this page doesn't apply to versions 19.4.1 and earlier of Oracle Digital Assistant. For service administration information for those earlier versions, see the legacy Administering Oracle Digital Assistant guide.

Manage Features

In each release of Oracle Digital Assistant, there are sets of optional features that you can enable or disable. You do so by selecting a profile that contains the features you want to have enabled.

To change the optional features that are enabled:

  1. In Oracle Digital Assistant, click icon to open the side menu to open the side menu and select Settings > Feature Management.
  2. From the Current profile dropdown, select the profile that corresponds with the features that you want enabled and disabled.

Audit Trail

Should you need to see a history of user activity in an instance of Oracle Digital Assistant and you have administrator privileges for the instance, you can view the instance's activity logs.

These logs capture granular detail of user sessions, such as listing, creating, editing, and deleting skills.

To browse the logs:

  1. In the instance, click icon to open the side menu to open the side menu and select Settings > Audit Trail.
  2. If you want to see results for more than the current day, go to the Today dropdown and select a different date range.
  3. Click + Criteria one or more times to create search criteria to home in on the type of activity that you want to view.
  4. Click Search.
  5. To see details for a log entry, click the entry.
Note

This feature is not available on version 19.4.1.

Example: Searching for Delete Operations

Here's an example of how you can use the search feature to see all delete operations:

  1. Click + Criteria.
  2. In the Filter field, select Operation.
  3. In the Operator field, select Starts With.
  4. In the value field, enter Delete.
  5. Click Search.

In the results for that search, you'll see entries for any operations with names beginning with Delete, such as DeleteSkill or DeleteSkillIntent.

Events for Digital Assistant Instances

You can create automation based on state changes for your Oracle Digital Assistant service instances by using event types, rules, and actions.

For information on how events work, see Overview of Events.

Event Types

These are the event types that Oracle Digital Assistant service instances emit:

Friendly Name Event Type
Change Digital Assistant Compartment Begin
com.oraclecloud.digitalassistant.changeodacompartment.begin
Change Digital Assistant Compartment End
com.oraclecloud.digitalassistant.changeodacompartment.end
Create Digital Assistant Instance Begin
com.oraclecloud.digitalassistant.createodainstance.begin
Create Digital Assistant Instance End
com.oraclecloud.digitalassistant.createodainstance.end
Delete Digital Assistant Instance Begin
com.oraclecloud.digitalassistant.deleteodainstance.begin
Delete Digital Assistant Instance End
com.oraclecloud.digitalassistant.deleteodainstance.end
Update Digital Assistant Instance

com.oraclecloud.digitalassistant.updateodainstance

Example Digital Assistant Service Instance Event

This is a reference event for Oracle Digital Assistant service instances.

{
  "id": "ocid1.eventschema.oc1.phx.abyhqljrfajridyag4epdbthdjuhwgkwxxog32ed4e36yx2zotmphyxe3z5q",
  "exampleEvent": {
    "eventID": "unique_id",
    "eventTime": "2019-10-09T13:58:03.575Z",
    "contentType": "application/json",
    "eventType": "com.oraclecloud.digitalassistant.createodainstance.end",
    "cloudEventsVersion": "0.1",
    "source": "DigitalAssistant",
    "extensions": {
      "compartmentId": "ocid1.compartment.oc1..unique_ID"
    },
    "eventTypeVersion": "2.0",
    "data": {
      "resourceName": "example_name",
      "compartmentId": "ocid1.compartment.oc1..unique_ID",
      "availabilityDomain": "all",
      "compartmentName": "example_name",
      "resourceId": "ocid1.odainstance.oc1.phx.unique_ID"
    }
  },
  "serviceName": "Digital Assistant",
  "displayName": "ODA Instance - Create End",
  "eventType": "com.oraclecloud.digitalassistant.createodainstance.end",
  "additionalDetails": [],
  "timeCreated": "2019-10-09T13:58:03.575Z"
}

Metrics, Alarms, Notifications, and Billing

You can monitor the health, performance, and usage of Oracle Digital Assistant service instances in Oracle Cloud Infrastructure by using metrics, alarms, and notifications.

For example, you can:

  • See how many messages have been sent over a given period of time by users to skills and digital assistants in your service instance.
  • See any errors that have occurred over a given period of time.
  • Set alarms to alert you when any of these metrics hit a certain threshold.

For information on how these features work, see Monitoring Overview and Notifications Overview.

Digital Assistant Metrics

Oracle Digital Assistant metrics are emitted with the metric namespace oci_digitalassistant.

Here are the available metrics for Oracle Digital Assistant instances.

Metric Metric Display Name Unit Description Dimensions
RuntimeRequests Runtime Requests count

Number of runtime requests sent to the service.

This includes

  • Messages sent by a user through a skill or digital assistant.
  • Authentication and authorization attempts.
  • Invocations of WebView components.
  • Calls to the Oracle Function Service for Custom Code.
  • Calls through the Skill Tester.
  • Views of individual Insights reports.
  • Notifications sent to users to initiate a conversation (through the Application-Initiated Conversations feature).
resourceIdresourceDisplayNameshape
RuntimeErrorResponses Runtime Error Responses count

Number of runtime error responses returned during conversations with a skill or digital assistant.

This includes API calls that return status codes of 400-499 and 500-599.

Such errors may indicate problem with a channel or its configuration.

resourceIdresourceDisplayNameshapeerrorType
CustomComponentErrorResponses Custom Component Error Responses count Number of error responses received from custom components or from functions from the Functions service. resourceIdresourceDisplayNameshape
CustomComponentRejectedResponses Custom Component Rejected Responses count

Number of invalid responses received from custom components or functions from the Functions service.

For example, this might include responses with a 200 status code but which are wrapped in malformed JSON.

resourceIdresourceDisplayNameshape

You can view metrics by individual service instance or in aggregated form for all instances.

View Metrics for a Single Instance

To view metrics for an individual service instance:

  1. 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.
  2. Select the instance's compartment.
  3. Select the instance.
  4. Scroll down to the Metrics section of the page to view the metrics.

View Metrics for All Instances

To view aggregated metrics for all service instances:

  1. From the Infrastructure Console, click the navigation menu Navigation menu icon in the top left corner, scroll down to and expand Monitoring, and select Service Metrics.
  2. In the Compartments dropdown, select the compartment for which you want to view metrics.
  3. In the Metric Namespace, select oci_digitalassistant.

Monitor Billing

The Infrastructure Console provides various billing and payment tools that make it easy to monitor your Oracle Digital Assistant billing, service costs, and usage.

To view your billing and usage, perform the following steps:

  1. Sign in to Oracle Cloud as the cloud account administrator. You can find your account name and login information in your welcome email.
  2. From the Infrastructure Console, click the navigation menu Navigation menu icon in the top left corner, scroll down to Governance and Administration, expand Account Management, and select one of the following options:
    • Cost Analysis: provides easy-to-use visualization tools to help you track and optimize your spending.

    • Payment Method: easily manage how you pay for your usage.

    • Invoices: view and download invoices for your usage.

    • Budgets: set thresholds for your spending. You can set alerts on your budget to let you know when you might exceed your budget, and you can view all of your budgets and spending from one single place.

    • Usage Report: view comma-separated value (CSV) files that can be used to get detailed breakdowns of resources for audit or invoice reconciliation.

      Note

      The first time you access usage reports, you must create a policy in your root compartment. Follow the instructions on the Usage Report page to create the policy, copying the statements as directed.

For more information on the billing and payment tools, see Billing and Payment Tools Overview.

Stop and Start Instances

You can stop and start instances of Oracle Digital Assistant.

When you stop an instance, the instance's state changes to INACTIVE, which means that the instance can't be accessed and any metering is suspended. Starting an instance returns it to the ACTIVE state, making it available to users and resuming metering.

To stop or start an instance:

  1. 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.
  2. Select the instance's compartment.
  3. Select the instance.
  4. Click the Stop or Start button.

Delete an Instance

To permanently delete an instance of Oracle Digital Assistant:

  1. 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.
  2. Select the instance's compartment.
  3. Select the instance.
  4. From the More Actions menu, select Delete.

Break Glass

Oracle Break Glass for Oracle Digital Assistant enables you to securely restrict Oracle's access to your cloud environment.

The Break Glass for Oracle Digital Assistant feature is enabled if you have a Digital Assistant instance that is paired with a Fusion-based Oracle Cloud Applications subscription that includes Break Glass.

When you use Break Glass, Oracle Support representatives can access your cloud environment only after relevant approvals and authorization to troubleshoot any issues that may arise in your cloud environment.

Break Glass has these primary features:

  • Temporary access approval, in which Oracle personnel can only access instance data through a strict customer approval process. Typically, such a process would only be initiated to help resolve a customer service request.

    Such access is time limited. Any temporary access credentials are automatically reset after the agreed upon time.

    Such access is logged and detailed reports are available.

  • The option to upload your own Transparent Data Encryption (TDE) master encryption key.

    By default, your data in the Oracle Cloud environment is encrypted at rest using TDE.

    With Break Glass, you can upload your own TDE master encryption key and manage its lifecycle. If you provide your own key, your data will also be protected and audited using Data Vault. You can also periodically update the keys.

Temporary Access Approval

If you submit a service request (SR) and Oracle Support determines that it needs access to some of your data for debugging purposes, you can agree to give them temporary access to your service instance data. Here's the general flow of the process:

  1. You submit an SR.
  2. If Oracle Support determines that they need access to any of your data for debugging purposes, they will contact your administrator via email for approval to conduct a Break Glass session. (The email has a link to the Temporary Access Approval page of your Digital Assistant, where your administrator can click Approve or Reject.)
  3. If your administrator approves the request, a temporary password is generated to enable Oracle Support to start a Break Glass session, in which they can access the required data.
  4. Once Oracle support completes its work in the Break Glass session, they terminate the session. If they don't explicitly terminate the session, it expires automatically within the timeframe that you have agreed upon.

Provide Your Own Key

By default, Oracle provides and manages the TDE keys for encrypting the data in your Digital Assistant instance.

If your instance has Break Glass enabled, you can also replace the Oracle-provided private key with your own, which also enables you to rotate the keys as you require.

Note

When you first switch to using your own key, you need to allow some time for your instance to be out of service. You should also back up any key artifacts in your instance.
Create and Import Your TDE Master Key

To provide your own key, follow these steps:

  1. In Oracle Digital Assistant, click icon to open the side menu to open the side menu and select Settings > Break Glass.
  2. On the Provide Your Own Key Page, click + Provide Your Own Key.
  3. Click Public Key to download the Oracle public wrapping key that you will need to encrypt your own transparent data encryption (TDE) master key.
  4. Use OpenSSL to generate and encrypt your key:
    1. Create a new directory for the key and assign it to an environment variable:
      $ mkdir –p dir_of_key
      $ export KEYPATH dir_of_key
    2. Make sure the directory is restricted:
      $ chmod go-rwx $KEYPATH
    3. Generate the TDE master key:
      $ openssl rand 32 > $KEYPATH/clearkey
    4. Encrypt your generated TDE master key with the Oracle public wrapping key that you downloaded in step 3:
      $ openssl pkeyutl -encrypt -in $KEYPATH/clearkey -inkey $KEYPATH/wrappingkey -pubin -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 > $KEYPATH/wrappedkey
  5. In the External Key Data Source field, upload the encrypted TDE master key (e.g. wrappedkey, as in the above example).
  6. In the Email Address field, enter the email address of the person to notify when the reconfiguration of the Digital Assistant instance has finished and the instance is ready to used again.
  7. Click Submit and then Confirm.
Update the Key

If you have previously provided your own TDE key for your Digital Assistant instance, you can update that key.

  1. In Oracle Digital Assistant, click icon to open the side menu to open the side menu and select Settings > Break Glass.
  2. On the Provide Your Own Key Page, click + Update the key.
  3. Click Public Key to download the Oracle public wrapping key that you will need to encrypt your own transparent data encryption (TDE) master key.
  4. Use OpenSSL to generate and encrypt your key:
    1. Create a new directory for the key and assign it to an environment variable:
      $mkdir –p dir_of_key
      $ export KEYPATH dir_of_key
    2. Make sure the directory is restricted:
      $ chmod go-rwx $KEYPATH
    3. Generate the TDE master key:
      $ openssl rand 32 > $KEYPATH/clearkey
    4. Encrypt your generated TDE master key with the Oracle public wrapping key that you downloaded in step 3:
      $ openssl pkeyutl -encrypt -in $KEYPATH/clearkey -inkey $KEYPATH/wrappingkey -pubin -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 > $KEYPATH/wrappedkey
  5. In the External Key Data Source field, upload the encrypted TDE master key.
  6. Click Submit and then Confirm.
Note

Once you create or update your key, you have to wait 16 days or more before you can update it again.

Further Administration Information

Once you have set up your Oracle Digital Assistant instance and its users, you may wish to delve further into setup of your account. Here are some topics containing more details on administering services in Oracle Cloud Infrastructure that you may wish to explore: