Three steps: platform configuration, the activity in the service flow, and prompt / output design.
- Configure the provider (an administrator). The Workflow runtime needs a watsonx.ai provider definition in its custom configuration (100Custom.xml through the custom XML secret of the CR) with the project id, the provider URL and an authentication alias that holds the IBM Cloud API key; with restricted egress the operator needs a NetworkPolicy allowing outbound 443 to the watsonx.ai endpoint:
<!-- 100Custom.xml (custom XML secret of the Workflow CR); the auth alias is a Liberty authData entry holding the API key -->
<properties>
<server merge="mergeChildren">
<generative-ai merge="mergeChildren">
<watsonx-provider merge="replace">
<project-id>0f2a...-your-watsonx-project</project-id>
<provider-url>https://us-south.ml.cloud.ibm.com</provider-url>
<auth-alias>watsonxAuth</auth-alias>
<connection-timeout>15</connection-timeout>
<read-timeout>45</read-timeout>
</watsonx-provider>
</generative-ai>
</server>
</properties>
# CR: shared_configuration.sc_egress_configuration.sc_restricted_internet_access: true -> add a NetworkPolicy for egress 443 to *.ml.cloud.ibm.com and iam.cloud.ibm.com
# BAW 25.0+: the provider can be watsonx.ai on Cloud Pak for Data (on-premises), deploy-on-demand or custom foundation models- Add the activity: in the service flow editor the generative AI tooling offers a task whose configuration is the model, the prompt (with variable substitution from tw.local), generation parameters (max tokens, temperature) and an output variable; it runs synchronously like an integration step, so give it an error boundary event (timeouts, quota).
- Design prompt and output: ask for JSON and validate it; keep personal data out of prompts where the model provider is outside your boundary; log the prompt id and the model for audits.
Prompt (generative AI task "Classify request"):
You are an assistant for a bank's service desk. Classify the customer request below into exactly one category
from [ADDRESS_CHANGE, CARD_LOST, COMPLAINT, OTHER] and give a one-sentence summary.
Answer with JSON only: {"category": "...", "summary": "...", "confidence": 0.0-1.0}
Request: <#= tw.local.request.text #>
Output variable: tw.local.aiText (String)
// script step after the task: parse defensively, fall back to a human decision
try {
var r = JSON.parse(tw.local.aiText.replace(/^[^{]*/, "").replace(/[^}]*$/, ""));
tw.local.category = ["ADDRESS_CHANGE","CARD_LOST","COMPLAINT","OTHER"].indexOf(r.category) >= 0 ? r.category : "OTHER";
tw.local.summary = String(r.summary || "").substring(0, 500);
tw.local.confidence = Number(r.confidence) || 0;
} catch (e) { tw.local.category = "OTHER"; tw.local.confidence = 0; }
tw.local.needsReview = tw.local.confidence < 0.8; // routes to a review task in the BPDOperational notes: model calls cost money and take seconds - do not put them in loops over lists without batching, cache results for identical inputs, and set the read timeout below the service flow's transaction timeout; the runtime stores the generated text in instance data like any variable (retention rules apply); and test prompts in the watsonx.ai Prompt Lab first, then copy them into the activity.
References