Reference ID Configuration in ONEiO

Introduction

In ONEiO, messages arriving from various endpoints are matched to existing conversations or start new ones based on unique identifiers. The Reference ID Configuration feature allows you to specify where and how these identifiers (or "reference IDs") can be found in a message.

By associating each reference ID with a specific endpoint and entity type, ONEiO ensures that the right conversation is matched accurately every time.

If you need to configure Reference IDs in your integration, please send an e-mail to support@oneio.cloud.
 

Overview

1. What is a Reference ID configuration?
2. How it works
3. When would you need a Reference ID configuration?
4. Example Scenarios
5. Limitations
6. How to set up or change the Reference ID configuration
    

What is a Reference ID configuration?

A Reference ID Configuration specifies which message fields contain the unique IDs for a particular endpoint and entity type.

For example, if Endpoint A needs to match incoming messages from Endpoint B based on a certain field (e.g.,  ticket ID ,  field-foo , etc.), you can define in the configuration that any values found in that Endpoint A field refer to Endpoint B’s ID. 

How it works

1. Identify the Endpoint and the Entity Type: The configuration states which endpoint’s ID is being referenced and for which entity type (e.g.,  incident , ticket , case , etc.).
2. Match the Field: You specify which field in the incoming message contains the ID of the referenced endpoint.
3. Accurate Conversation Matching: During inbound message processing, ONEiO checks the specified field to see if it matches any existing conversation. If there is a match, the conversation is updated. If not, a new conversation is created.

When would you need a Reference ID configuration?

Multiple Unique Identifiers

You might have multiple fields in the inbound message that store different IDs for different systems (e.g.,  external_id_systemA  and  external_id_systemB ). Configuring all those fields as reference IDs ensures each system’s ID is recognized. 

Reducing Conflicts

Different endpoints sometimes share the same ID format (e.g., all using short numeric IDs). By specifying the exact endpoint and entity type, ONEiO avoids mixing up IDs across endpoints.

Complex Integrations

When multiple systems work together, you may need to store separate IDs in your messages for each of those systems. Reference ID Configuration lets you define more than one reference ID within a single message, enabling the use of more than one External ID / Correlation ID in one inbound message for the same or different systems.

Example Scenarios

Scenario 1: Tracking External Ticket IDs

Let’s say you integrate a service desk tool (System X) with your CRM (System Y). Whenever System X sends a message, the message includes a field like  customer_ticket_id . You want ONEiO to recognize that  customer_ticket_id belongs to a ticket in System Y. 

In the Reference ID Configuration of System X, you would define:

• Reference Endpoint: System Y
• Reference Entity Type: Ticket (or whatever entity name is used in System Y)
• Local Attribute Name (field name on System X):  customer_ticket_id 

That way, ONEiO knows this specific field should match (or create) the conversation relevant to System Y’s ticket. This setup works very similarly to the External ID Attribute in the endpoint configuration, but is more precise - the attribute configured will work exclusively between System X and System Y.

Scenario 2: Multiple Reference IDs for One Endpoint

In this scenario, let's say you want to exchange information between two entities from System X (e.g. Incident and Change Request) to the entity Ticket from System Y. A common example would be sending updates from System X Incident and Change Request to the same System Y ticket.

To allow this behaviour, all three entities should go to the same conversation. So, let's say that in our setup, we have the following scenario:

• On System Y, the field-foo  stores the Incident ID from System X
• On System Y, the  field-bar  stores the Change Request ID from System X
• On System X, both entities Incident and Change Request use the same field names, so in both entities, the  correlation_id  field contains the Ticket ID from System Y

With these requirements, the Reference ID configuration will be the following:

Limitations

Endpoints that use Reference IDs should not be synced across environments (e.g., from QA to Production). If an endpoint is synced, its Reference ID setup will be overwritten by the configuration from the source environment.

This will break the Reference ID functionality and may cause conversation matching to fail - disrupting the integration.

After configuring Reference IDs, make sure to manually update the endpoint configuration in each environment (Test, Production, etc.) to preserve the correct setup.

How to set up or change the Reference ID configuration

The Reference ID configuration is not accessible through the ONEiO user interface; any changes must be performed by the ONEiO support team. As an end user, you can request the setup and updates for Reference IDs, but you cannot modify them yourself.

Setting Up Reference IDs: Step-by-Step

1. Gather Your Requirements: Start by collecting the information ONEiO Support will need to configure your Reference IDs
   • Identify which fields in the messages sent to ONEiO hold the IDs.
   • Confirm the endpoint name and entity type for each ID.
   • Clarify if you need multiple reference IDs or just one.
2. Contact ONEiO Support: Once you’ve gathered your requirements:
   • Create a support request describing your Reference ID setup needs.
   • Provide the endpoint names, entity types, and the relevant fields/attributes that contains the IDs.
   • Explain the desired behavior — for example, how IDs should be used to match or link messages across endpoints.
3. ONEiO Support Implements the Configuration: The ONEiO Support team will
   • Review your request and update your environment.
   • Apply the appropriate Reference ID configuration based on the details you provided.
4. Test the Setup: Once the configuration is applied in QA:
   • Send a few test messages from your inbound systems.
   • Confirm that the conversation matching behaves as expected (i.e., updates existing conversations correctly or starts new ones if no match is found).
5. Go Live! 🚀
   • Ask the ONEiO Support team to promote the Reference ID setup to your Production Environment.
   • Once they confirm the setup is live, closely monitor your integration, checking if messages are being routed and matched as expected and watching for any unexpected behavior or mismatches.