Defining case keys (system vs. external)

Overview

A case key uniquely identifies each case instance across Maestro and external systems. Use a system key when Maestro is the system of record, or use an external (customer-defined) key to map an upstream CRM, ERP, or LOB identifier so the same real-world case is recognized across tools without maintaining a separate mapping table. This guide walks through both options and explains when to choose each.

Audience: Intermediate — Automation Developers, Business Architects

Prerequisites

• Access to Studio Web.
• A case project created in Studio Web (or the intention to create one).
• If using an external key: the upstream system identifier format (for example, CRM case number, policy number, or order ID from ERP).
• If supplying case data from an external system: a Data Fabric VDO or a configured connector in Integration Service.

Step 1: understanding the two key types

Before configuring, determine which key type fits your scenario.

Key Type	Description	Example	When to Use
System key	Auto-generated by Maestro on case creation. Uses a constant prefix you define plus an incrementing number.	HC-1234, CLM-00891	Maestro is the system of record. No upstream identifier exists, or you do not need to correlate with external tools.
External (customer-defined) key	You pass an upstream ID so the same real-world case is recognized across Maestro and other systems.	CRM case number, policy number, order ID from ERP	The case originates in another system (CRM, ERP, ticketing tool) and humans or integrations must correlate the case across tools.

Note:

Every case also receives an immutable, auto-generated caseID system field at creation. This internal correlation key ties the Case Entity [Coming Soon] , Case Documents, and Case Comments together regardless of which key type you configure.

Step 2: creating or opening a case project

Opening Studio Web

1. Navigate to Studio Web.
2. Select Case Management Project to create a new project, or open an existing one.

Naming the case type

1. Enter a Case Name (for example, HomeClaims, DisputeResolution).

Step 3: configuring a system key

Use a system key when Maestro generates the identifier automatically.

Selecting the system key option

1. In the case creation settings, locate the Case Key configuration.
2. Choose Constant Prefix Key.

Defining the prefix

1. Enter a short, meaningful prefix that identifies the case type (for example, HO for Home Claims, CLM for general claims).
2. Maestro appends an auto-incrementing number to produce keys such as HO-1234.

Saving the configuration

1. Confirm the prefix value.
2. Save the case settings. Every new case instance now receives a system-generated key with your prefix.

Step 4: configuring an external (customer-defined) key

Use an external key to align each Maestro case with an identifier from an upstream system such as a CRM, ERP, or ticketing platform.

Choosing the external key option

1. In the case creation settings, locate the Case Key configuration.
2. Select the External Key (customer-defined) option.

Mapping the external identifier to the case key

Supply the upstream ID through one of the supported trigger methods:

Trigger Method	How It Works
Data Fabric VDO trigger	Register the external source as a Virtual Data Object (VDO) in Data Fabric. Use the VDO as the case trigger. Map the external identifier field (for example, policyNumber or crmCaseId) to the case key. The trigger payload fields also become case fields available throughout all stages.
Wait for connector trigger	Configure a Wait for connector event as the case trigger. The API or connector payload is treated as the case entity [Coming Soon] . Map the external ID field from the payload to the case key. All payload fields are available across stages and tasks.

Verifying the mapping

1. Confirm that the external identifier field is mapped to the Case Key field.
2. Save the case settings.

Note:

• The external key allows humans and integrations to look up a Maestro case using the same ID they already use in the source system, eliminating the need for a separate mapping table.
• If the external key value is not provided during case creation, the case will not have a cross-system reference. Ensure the trigger payload always includes the upstream identifier.

Step 5: setting up the case trigger

The case trigger determines how a case instance is created and how data — including the case key — is populated.

Configuring the trigger

1. Open the Trigger configuration in the case plan designer.
2. Select one of the following:
   • Data Fabric Entity trigger — use a "Row created" event (or equivalent) for a native or VDO entity.
   • Wait for connector trigger — use a connector event from Integration Service (for example, an API call or a channel message).

Mapping trigger fields to case fields

1. Map incoming fields from the trigger payload to the case entity fields.
2. Confirm that the external identifier (if using an external key) is included in the mapping.

These mapped fields become case fields usable in conditions and tasks across all stages.

Step 6: publishing and verifying

Validating the case plan

1. Run the built-in validation in Studio Web to confirm stages, tasks, transitions, and the case key configuration are correct.

Publishing and deploying

1. Select Publish from Studio Web.
2. Deploy and activate the case plan in the target folder.

Creating a test case instance

1. Trigger a new case using the configured trigger method.
2. Open the Case App or Case Instance Management in Maestro.
3. Locate the new case instance and confirm the case key:
   • System key: Verify the key follows the prefix format (for example, HO-1234).
   • External key: Verify the key matches the upstream identifier passed in the trigger (for example, the CRM case number).

Expected outcome

After completing these steps:

• Each new case instance displays the configured key type in the Case App and Case Instance Management.
• System key cases show an auto-generated identifier with your constant prefix.
• External key cases display the upstream identifier passed from the CRM, ERP, or other source system, enabling cross-system correlation without a separate mapping table.
• All case fields from the trigger payload are available for use in stage rules and task inputs.

Use case example

Scenario: A property insurance company processes home claims that originate in their CRM (Salesforce).

• The CRM generates a claim ID such as SF-CLM-88421.
• The company wants Maestro cases to use the same ID so adjusters, agents, and integrations can reference a single identifier across both systems.

Configuration:

1. Register the Salesforce Claims object as a Data Fabric VDO.
2. Create a case trigger using the VDO's "Row created" event.
3. Select External Key and map the salesforceClaimId field to the case key.
4. After deployment, every new case created from a Salesforce claim record carries the original CRM ID (for example, SF-CLM-88421) as its Maestro case key.

Adjusters searching in Maestro or Salesforce use the same identifier, and downstream API integrations correlate records without maintaining a lookup table.

Troubleshooting

Issue	Resolution
External key is blank after case creation	Confirm the trigger payload includes the external identifier field and that the field is mapped to the case key in the trigger configuration.
Duplicate external keys across cases	Maestro does not enforce uniqueness on external keys by default. Implement uniqueness checks in the upstream system or add validation logic in the trigger.
Case key prefix does not appear	Verify the Constant Prefix Key option is selected and a prefix value is saved in the case settings.
Trigger fields are not available in stage conditions	Ensure the trigger payload fields are mapped correctly. Fields from the trigger become case fields only after mapping.

Limitations

• Case user roles and access support is not yet available.
• Native case-entity support in Data Fabric is not yet available.
• Maestro Case follows the same billing as Maestro. Work executed inside a case consumes the native consumables of each task type (AI agents, RPA workflows, API workflows, IS connectors).

Next steps

• Configure the case entity and trigger to supply business data across all stages.
• Model primary and secondary stages to define the lifecycle of your case.
• Add tasks to stages to assign work to humans, AI agents, RPA workflows, and connectors.
• Define stage rules to control entry, complete, exit, and re-entry behavior.
• Configure SLAs and escalations to enforce time-based expectations at the case and stage level.