Designing Architect Flows with Dynamic External Tagging for Real-Time Analytics Enrichment

How-To-Articles
1

Designing Architect Flows with Dynamic External Tagging for Real-Time Analytics Enrichment

What This Guide Covers

This guide details the implementation of External Tagging and Participant Data within Genesys Cloud Architect to enrich the conversation metadata in real-time. By the end of this masterclass, you will have a framework for injecting granular, business-specific data (e.g., Marketing Campaign IDs, Product SKU interest, Fraud Risk scores) into the interaction record, enabling advanced filtering in Performance Views and high-fidelity downstream reporting in third-party BI tools like PowerBI or Tableau.

Prerequisites, Roles & Licensing

Metadata enrichment requires standard Architect permissions but is most effective when paired with API-based retrieval.

  • Licensing: Genesys Cloud CX 1, 2, or 3.
  • Permissions:
    • Architect > Flow > View/Edit
    • Analytics > Conversation Detail > View (for validation)
  • OAuth Scopes: analytics, conversations.
  • Architect Actions: Set Participant Data, Set External Tag.

The Implementation Deep-Dive

1. External Tag vs. Participant Data: When to Use Which

Architects often confuse these two metadata containers.

  • External Tag: A single, searchable string (max 256 characters) that is indexed and visible in the Genesys Cloud Performance views without needing to expand the interaction details. It is perfect for a “Primary Key” or “Global ID” from an external system.
  • Participant Data (Attributes): A collection of Key-Value pairs stored on the interaction. These are not directly searchable in the UI “Performance” filters but are critical for data propagation and downstream API processing.

The Trap:
Using Participant Data for a field you need to filter on within the Genesys Cloud UI (e.g., “Was this a high-value customer?”). Since Participant Data isn’t indexed for standard Performance view filters, your supervisors will have to manually open every interaction to see the data.
The Solution: Map your most critical KPI to the External Tag. For example, if a caller selects “Refinance” in the IVR, set the External Tag to REFI_LOAN.

2. Implementing Dynamic Tagging in Architect

To set an External Tag, use the Set External Tag action. This action accepts a string expression.

Best Practice: Use a “Prefix-Suffix” pattern to make the tag more useful.

  • Expression: Append("MKTG_", Flow.CampaignID, "_", Task.LanguageCode)
  • Result: MKTG_FALL_SALE_EN-US

This allows for partial string matching and wildcard searches in the Analytics API.

3. Propagating Data Actions to Metadata

The most powerful use case is taking data returned from a CRM Data Action and “tagging” the interaction so the agent (and the reporter) knows exactly who the caller is before even answering.

Architect Implementation Pattern:

  1. Call Data Action: CRM Lookup.
  2. Success: Use Set Participant Data to store CRM_AccountID, Last_Purchase_Amount, and Account_Tier.
  3. Use Set External Tag to set the tag to Account_Tier (e.g., GOLD).

The Trap:
Setting Participant Data after a transfer to an external number or a different flow. Participant Data is attached to the current session. If you don’t set it before the “Transfer” action, you may lose the context of the IVR decisions.
The Solution: Always place your “Set Participant Data” blocks immediately after the decision point, never at the very end of the flow.

4. Downstream Analytics Enrichment

Once tagged, these interactions are now uniquely identifiable in the Analytics API. When you perform a POST /api/v2/analytics/conversations/details/query, you can filter by externalTag.

// Example Analytics Query Filtering by External Tag
{
 "interval": "2024-05-14T00:00:00.000Z/2024-05-15T00:00:00.000Z",
 "order": "desc",
 "orderBy": "conversationStart",
 "paging": {
  "pageSize": 25,
  "pageNumber": 1
 },
 "segmentFilters": [
  {
   "type": "and",
   "clauses": [
    {
     "type": "or",
     "predicates": [
      {
       "dimension": "externalTag",
       "value": "GOLD"
      }
     ]
    }
   ]
  }
 ]
}

Validation, Edge Cases & Troubleshooting

Edge Case 1: Tag Overwriting in Multi-Flow Environments

  • The failure condition: The External Tag set in the IVR flow disappears or changes after the call is transferred to an agent.
  • The root cause: The agent script or a subsequent “In-Queue” flow is also using the “Set External Tag” action, which overwrites the global string.
  • The solution: Use a Concatenation Strategy. Instead of overwriting, use Append(Conversation.ExternalTag, "|", "NEW_DATA"). This preserves the historical tagging path.

Edge Case 2: PII in Metadata

  • The failure condition: A compliance audit reveals Credit Card numbers or Social Security numbers in the External Tag field.
  • The root cause: A dynamic expression is pulling a raw CRM field into the tag without masking.
  • The solution: Implement a Safe-Tagging Wrapper. Create a reusable Architect task that strips non-numeric characters and truncates the string before setting the External Tag. Never tag an interaction with raw PII; use an “Interaction Token” or “External ID” instead.

Official References