Overview

This flow template begins by authenticating the session, sanitizing user-provided name data, and executing a multi-stage validation loop. The flow utilizes decision nodes to handle API response statuses and retry logic, ultimately parsing the Epic FHIR resource to extract a verified unique patient identifier for the AI Agent.

Pre-requisite

Webex AI Agent Studio
EPIC Prebuilt Integration

User

Flow Developer: Responsible for configuring, mapping variables, maintaining the flow logic, and publishing the flow.
End User (Patient): The individual providing patient data (e.g., Name, DOB, Phone).
AI Agent: The conversational interface that initiates the verification request and acts upon the validated output.
Epic EHR System: The backend source of truth for patient records.

Create flow

To begin building the flow from template, follow these steps:

Select or Create a Service: Navigate to the Services dashboard. You may either select an existing service from your list or create a new one to serve as the foundation for your flow.
Initiate Flow Creation: Once your service is selected, click the Create Flow.
Choose the Template: Within the "Create Flow" window, provide a friendly flow name (Note – the same flow name will have to be selected under AI Agent Studio Action to complete the configuration) and choose the template.
The AI Agent Start node configuration is shown in the next screen. You can observe the input received from the AI Agent and click Save.
Next, click on make live and publish the flow.
Go to AI Agent Studio, configure this flow under appropriate Ai Agent studio Action.

Flow Logic & Node Breakdown

Order	Node Type	Purpose	Outcome
1	AI Agent Event	This component receives a JSON payload from the AI Agent containing trigger information in the following format: `{ "patientLastname": "Lawson", "patientFirstname": "Dave", "patientDOB": "1921-01-01", "patientPhonenumber": "234-123-4567", "patientAddress": "123 Main St", "patientCity": "Madison", "patientState": "WI", "patientZipcode": "53703" }` To add a new input parameter to the flow, include the parameter in the JSON payload and click parse. The newly added parameter will then appear as a new variable in the output variables.	JSON input parameters from AI Agent
2	Epic Authenticate (OAuth)	This node is critical for establishing a secure, authorized session with the Epic EHR system before any patient data can be queried. • Method Name: Specifies the action to be executed, choose Authenticate. • AzureURL: Determines the target environment endpoint. Setting this to "Staging" ensures the flow connects to your staging or production environment. • SubscriptionKey: Maps the necessary API subscription key for your chosen environment, ensuring that the request is properly authorized by the API Management layer. • EpicTokenURL: Defines the specific endpoint used to exchange credentials for an access token. It utilizes the $(epicBaseURL) variable to allow for dynamic environment switching. The variable value can be configured in the flow settings under custom variables. • EpicClientId: Represents the unique identifier for your application, as registered in the Epic App. The variable value can be configured in the flow settings under custom variables.	Epic Patient Auth Token
3	Generate Array Evaluate	The node prepares name components for consistent formatting and processing. The function splits a given name string by spaces or hyphens into parts, capitalizes the first letter of each part, and converts the rest to lowercase, returning an array of these formatted name parts. Additionally, the code removes spaces or hyphens from a surname string by replacing them with an empty string.	Sanitized Name Array
4	Epic Patient Match	Queries `PatientMatch` endpoint using parameters.	Match Status/Patient ID
5	Evaluate	The script evaluates the `apiStatusCode` to determine the next action in a retry process: • When the status code is 200, it resets `retryCount` to zero and proceeds with "continue". • If the status code is 400, it resets `retryCount` to zero and triggers a "fail" response. • For any other status code, it increases `retryCount` by one if it is below `maxRetryCount` and signals "retry"; if the retry limit is reached, it signals "fail". • This mechanism governs whether to continue, fail immediately, or retry based on the API response and retry attempts. `apiStatusCode`, `retryCount` and `maxRetryCount` variable values can be updated in the flow settings under custom variables.	Boolean/Status Code
6	Data Parser	Transforms raw JSON response into usable variables.	Parsed Patient Object
7	Record Found?	Logic branch to check if a valid record exists.	Found/None
8	Evaluate	Extracts specific 'EPIC' identifier from the resource. The script performs the following steps: • It parses a JSON string stored in the variable patientDetails into a JavaScript object called patientData. • It accesses the identifier array located within the first entry of patientData at patientData.entry[0].resource.identifier. • It then iterates through each element in the identifiers array to find an object where the type.text property equals "EPIC". • Once found, it assigns the corresponding value of that identifier to the variable patientId and exits the loop.	Verified Patient ID

Variables & Data Mapping

Input JSON from AI Agent

{ “patientLastname": "Lawson", "patientFirstname": "Dave", "patientDOB": "1921-01-01", "patientPhonenumber": "234-123-4567", "patientAddress": "123 Main St", "patientCity": "Madison", "patientState": "WI", "patientZipcode": "53703" }

Output Variables sent to AI Agent

Configured in flow settings under flow settings: patientID, matchStatus, verificationTimestamp

{ "transactionID": "$(transid)", "flowname": "$(flowname)", "serviceName": "$(serviceName)", "statuscode": 1000, "patientId": "$(n17.patientFHIRId)", "patientFound": "$(patientFound)"}

Error Handling & Fallbacks

No Match Found: If the API returns a "None" status, the flow triggers a "Retry" prompt or requests secondary verification (e.g., last 4 digits of SSN).
API Timeout/Failure: Errors are logged in the Webex Connect console. The flow initiates a graceful fallback to a human agent if the retryCount exceeds maxRetryCount.
Invalid Credentials: Attempts are logged as security events; the administrator is notified, and the AI Agent informs the user that verification cannot be completed.

FAQs

Script Analysis & Logic

Question: What does the first Evaluate node script do?

Answer: This script ensures the patient's name is in a standardized format before being sent to the Epic API. It splits the input string into an array, capitalizes the first letter of each part, and removes special characters (spaces/hyphens) from the surname to ensure the API query is clean and compliant with Epic’s data requirements.

Question: How does the second Evaluate node handle API responses?

Answer: This node manages flow control based on HTTP status codes.
• 200 (Success): Resets the retryCount and proceeds to data parsing.
• 400 (Bad Request): Stops the flow immediately as the input is invalid.
• Other (e.g., 500, Timeout): Checks if the retryCount is less than the maxRetryCount. If so, it increments the count and triggers a "retry" loop; otherwise, it marks the flow as a "fail."

Question: What is the purpose of the final Evaluate node script?

Answer: This script parses the JSON response from the Epic EHR. It navigates the nested FHIR-based structure to find the specific identifier where the type.text is "EPIC." Once found, it extracts the value (the patient ID) and assigns it to the patientID variable for downstream use by the AI Agent.

General Implementation

Question: How do I handle multiple patients returned for one search?

Answer: You should add an additional "Evaluate" node after the Data Parser. If the entry array length is > 1, the AI Agent should be configured to ask the user for clarifying information (e.g., "I found two records, could you please confirm your date of birth?").

Question: Is the Epic Auth token cached?

Answer: Yes, the Epic Prebuilt node handles token caching automatically.