OCI Digital Assistant Professional cheat sheet

A digital assistant skill bundles a dialog flow, intents, entities, and backend integrations; a digital assistant is a routing layer that owns one or more skills plus a system-level answer for unresolved input.

Skill routing precedence: the digital assistant evaluates its own intents first, then hands off to skills; explicit skill invocation via the skill name in utterance overrides automatic routing confidence.

Use a versioned digital assistant (1.0, 1.1) for promotion across environments; versions are immutable snapshots, so clone to a new version to change behavior in production.

Draft vs. published: the draft is the editable working copy used by the skill tester; published versions are what channels and other assistants consume.

Interruptions are configured per skill: global interruptions (e.g., cancel, start over) belong to the digital assistant, while skill-scoped interruptions stay inside the skill's flow.

Digital assistant-level variables are shared across skills; skill-level variables are scoped to that skill and are not visible to sibling skills unless explicitly mapped.

The system.intent entity and the built-in unresolvedIntent are mandatory; every dialog flow needs a default transition or the runtime raises a routing error.

Composite bag entities reduce dialog state count by grouping related entity resolution into a single flow node; use them when three or more related fields are collected together.

Intent training utterances should be 10-20 per intent with varied phrasing; utterances that match two intents lower confidence and should be merged or disambiguated.

Confidence threshold defaults: values below the skill's confidence threshold route to unresolvedIntent; raise thresholds to reduce false positives, lower them to reduce unresolved fallbacks.

Entity types: value-list (enumerated), regex (pattern), and derived (computed from other entities); composite bag entities aggregate multiple entity types into one resolution unit.

Entity resolution order in a composite bag is configurable; set the most discriminating entity first so partial matches fail fast.

Dialog flow states: states with an entry action, optional prompt, optional post-action, and transitions; a state with no matching transition throws an error at runtime.

Use Apache FreeMarker expressions (${...}) for dynamic text and conditions; the built-in variable flow is available in all states, and error is populated in error-handler states.

System entities include system.date, system.time, system.number, system.currency, and system.person; they resolve without custom training but may need locale-specific configuration.

Set the entity's maxPrompts and the state's maxAttempts to bound retries; exceeding maxAttempts transitions to the state's next transition or an error handler.

REST integration: define a REST service with a base URL, then create an event-backed custom component whose payload maps dialog variables to request parameters and response properties back to variables.

Custom components extend the built-in component set; each has a name, a version, and a properties schema that the dialog flow must satisfy or validation fails at design time.

Authentication options for REST services: basic auth, OAuth 2.0 (client credentials or authorization code), and API key in header or query parameter.

Use the backend's error response to set the component's error action; map HTTP 4xx/5xx to a transition state rather than letting the flow crash.

Service timeouts: configure connection and read timeouts on the REST service; the default read timeout is short, so long-running backends need explicit tuning.

Custom component packages are exported as .zip and imported into another environment; the package includes the component definition and its service metadata, not the target environment's credentials.

For multi-turn data collection, prefer a composite bag entity over chained custom components to keep state count and error handling manageable.

Entity event handlers can call custom components to validate or transform a resolved entity value (e.g., look up an account ID) before the flow continues.

Channels (web, Slack, Microsoft Teams, Twilio SMS, and generic webhook) are attached to a published digital assistant version; changing the channel requires republishing.

Channel-specific secrets (signing keys, bot tokens, webhook URLs) are stored per channel; rotate them in the channel config, not in the dialog flow.

Authentication for the web channel uses a JWT or OAuth token issued by the identity provider; configure allowed origins (CORS) explicitly rather than wildcard.

Role-based access: the digital assistant administrator role manages channels and publishing; the developer role edits skills but cannot promote to production.

Deployment path: develop in a draft, test with the skill tester, publish a version, attach channels, then promote across environments by exporting and importing the assistant package.

Secrets and connection credentials live in the identity domain or a vault, not in exported packages; verify credentials are re-entered after import.

Enable channel logging and conversation transcripts for audit; transcripts contain user utterances, so apply data-retention limits consistent with privacy policy.

Health checks: monitor the channel's webhook endpoint and the backend REST services separately; a failing backend surfaces as repeated error-handler transitions in the flow.