Listener Configuration

1. Overview

Setting up a Listener Configuration is a required step when doing a real-time data sync. You will configure your Event Stream Source with your data sync information. You can review an example Listener Config setup here.

2. Setting up the Listener Config

1. Navigate to the Listener Config table in Cinchy (Image 1).

Image 1: Listener Config table

1. In a new row, add in your listener config configuration data. Review section 3 for more information.

2. Ensure that it is set to Enabled in order for your real-time data sync to run successfully.

3. Listener Configs Table Columns

To subscribe to an event stream, make sure you have a Cinchy Listener running connected to the Cinchy instance you are on. You will need to create a record in the Listener Configs table and Enable it to subscribe to events.

The example values in this section follow the use case outlined here.

Refer to the table below for information about the columns in the Listener Config.

Column	Description	Example
Name	The name of your Listener Config	New Hire Sync
Event Connector Type	Select from the drop-down list which event stream you are listening in on.	Cinchy CDC
Topic	This column expects a JSON value with certain specific information. Please review the **Topic Column** table below for details.	{ "tableGuid": "3daba5da-5e07-4d35-8d7c-d451a2c9068e", "fields": [ { "column": "Name" }, { "column": "Title" } ], }
Connection Attributes	This field will change depending on your stream source. For this example, we are using the attribute expected for the Cinchy Event Broker/CDC stream source.	{}
Status	This sets where your config is Enabled or Disabled. Make sure you set the value to Disabled when creating the config for the first time. This will give you a chance to correctly configure the listener before it is picked up by the service. After configuring the listener correctly you should flip the value to Enabled.	Disabled
Data Sync Config	The name of the Data Sync Config you created in the Connections UI or via XML.	New Hires
Subscription Expires On	This field is a timestamp that is populated by some Event Listeners (eg. Salesforce) service when it has successfully subscribed to a topic.
Auto Offset Reset	In the case where the listener is started and either there is no last message ID, or when the last message ID is invalid (due to it being deleted or it's just a new listener), it will use this column as a fallback to determine where to start reading events from. Earliest will start reading from the beginning on the queue (when the CDC was enabled on the table). This might be a suggested configuration if your use case is recoverable or re-runnable and if you need to reprocess all events to ensure accuracy. Latest will fetch the last value after whatever was last processed This is the typical configuration. None will not read start reading any events.	Latest

2.1 JSON Topic Column

For the topic JSON, you need to provide the following:

Parameter
Table GUID	The GUID of the table whose notifications you wish to consume. You can find this in the Design Table screen for Cinchy v5.5+, and in the Tables table otherwise.
Column(s)	The names of the columns you wish to include. Note: If you will be using the runQuery=true parameter in your data sync, you only need to include the Cinchy Id in the topic JSON.
BatchSize	The desired result batch size. This will default to 1 if not passed in. The maximum batch size is 1000; using a number higher than that will result in a Bad Request response.
Filter	Optional. When CDC is enabled, you can set a filter on columns where you are capturing changes in order to receive specific data.

2.2 Topic JSON Example

{
    "tableGuid": "3daba5da-5e07-4d35-8d7c-d451a2c9068e",
    "fields": [
        {
            "column": "Name"
        },
        {
            "column": "Title"
        }
    ],
}

Appendix A - Additional Attributes

messageKeyExpression

Each of your Event Listener message keys a message key. By default, this key is dictated by the Cinchy ID of the record being changed.

When the worker processes your Event Listener messages, it does so in batches, and for efficiency and to guarantee order, messages that contain the same key will not be processed in the same batch.

The messageKeyExpression property allows you to change the default message key to something else.

Possible Use Case

• Ensuring records with the same message key can be updated with the proper ordering to reflect an accurate collaboration log history.

Example Syntax

In the below example, we want the message key to be based on the [Employee Id] and [Name] column of the table that CDC is enabled on.

{ "messageKeyExpression": "CONCAT(New.[Employee Id], '-', New.[Name])", … }