Skip to main content

REST API (Cinchy Event Triggered)

Overview​

Data changes in Cinchy (CDC) can be used to trigger a data sync from a REST API data source to a specified target. The attributes of the CDC Event are available to use as parameters within the REST API Data Source Definition to narrow the scope of the request. For example, a lookup.

\

Info tab​

You can find the parameters in the Info tab below (Image 1).

Values​

ParameterDescriptionExample
TitleMandatory. Input a name for your data syncREST API (CDC) to Cinchy
DescriptionOptional. Add in a description for your sync. There is a 500 character limit in thie field.
VariablesOptional. Review our documentation on Variables here for more information about this field.
PermissionsData syncs are role based access systems where you can give specific groups read, write, execute, and/or all of the above with admin access. Inputting at least an Admin Group is mandatory.

Source tab​

Mandatory and optional parameters for the Source tab are outlined below (Image 2).

\The following column parameters can be found in the Listener Config table:

ParameterDescriptionExample
NameMandatory. Provide a name for your listener config.REST API (CDC) real-time sync
Event Connector TypeMandatory. Select your Connector type from the drop-down menu.REST API (CDC)
TopicMandatory. This field is expecting a JSON formatted value specific to the connector type you are configuring.See the Topic tab.
Connection AttributesMandatory. This field is expecting a JSON formatted value specific to the connector type you are configuring.See the Connection Attributes tab.
StatusMandatory. Set to "Enabled" to activate the listener. Leave on "Disabled" until you are ready to start syncing.Enabled/Disabled
Running StatusRead-only. Shows the current state of the listener as Starting, Running, or Failed. This is automatically managed by the system. For more information, see the Listener status section.Running
ActiveManaged by User/System. Indicates whether the listener is set to retry after failure ("Yes") or has stopped attempting to sync and requires user intervention ("No").Yes/No
Data Sync ConfigMandatory. This drop-down will list all the data syncs on your platform. Select the one that you want to use for your real-time sync.CDC Data Sync
Subscription Expires OnSalesforce Stream Sources only. This field is a timestamp that's auto populated when it has successfully subscribed to a topic.
MessageAuto-populated. This field reports errors that occur during the sync.
Auto Offset ResetEarliest, Latest, None. Determines where to start reading events if there is no last message ID or if it's invalid. Can be adjusted post-configuration. Learn moreEarliest ,Latest, None

Example use case​

An organization wants to use the Dun & Bradstreet API for enriching company information, such as the number of employees or their addresses. When a company record is added or modified in a table called Companies inside of Cinchy, a D&B API should be triggered with the Company Name (a mandatory field on the Companies table) passed in as a parameter, and the Company record should be enriched with the company information from the API response.

Define the connection​

The following sections in the Source configuration of the Connections experience can reference attributes of the CDC Event as parameters:

  • Auth Request -> Body
  • Auth Request -> Request Headers -> Header -> Header Value
  • Auth Request -> Endpoint URL
  • Body
  • Request Headers -> Header -> Header Value
  • API Endpoint URL

Parameters use the column name or alias as defined in the CDC Event's Listener Config prefixed with an @. For example, @CompanyName would be the parameter name for the following Cinchy CDC listener Topic configuration.

{
  "tableGuid": "420c1851-31ed-4ada-a71b-31659bca6f92",
  "fields": [
    {
      "column": "Cinchy Id",
      "alias": "CinchyId"
    },
    {
      "column": "Company Name",
      "alias": "CompanyName"
    }
  ]
}
warning

Parameter names are case sensitive when used in the Connection configuration. Parameter matching is performed using literal string replacements. Names shouldn't contain spaces (spaces are automatically removed), and should have differing prefixes.

The following set of parameters will be available on every event even if they're not present in the Listener Config table:

  • @Version
  • @DraftVersion
  • @CinchyRecordType
  • @ApprovalState
  • @ModifiedBy
  • @Modified
  • @Deleted

Listener config​

To configure a REST API (Cinchy Event Triggered) connection, a listener must be configured. If configuring using the Listener Config table, you would select the Event Connector Type of Cinchy CDC.

Otherwise, you can set up your listener configuration for your data sync through the Connections UI, keeping the following constraints in mind:

  • Column names in the listener config shouldn't contain spaces. If they do, they will be automatically removed. For example, a column named **Company Name **will become the replacement parameter @CompanyName.
  • The replacement parameter names are case sensitive.
  • Column names in the listener config shouldn't be prefixes of other column names. For example, if you have a column called Name, you shouldn't have another called Name2 as the value of @Name2 may end up being replaced by the value of @Namesuffixed with a 2.

Example Listener Configuration​

{
  "tableGuid": "420c1851-31ed-4ada-a71b-31659bca6f92",
  "fields": [
    {
      "column": "Cinchy Id",
      "alias": "CinchyId"
    },
    {
      "column": "Company Name",
      "alias": "CompanyName"
    }
  ]
}