Calem Integration 4: Subscribing to Data Changes via REST API

Data change events and subscription are available in Calem Enterprise R2019b. Administrators can register 3^rd-party applications as listeners in Calem. These listeners are notified when records are changed in Calem.

Step 0. What is a Data Change Event

A data change event is a user action to update data including creation, editing, and deletion.

Data change subscription and Calem REST API enable customers to build two-way integration with Calem. This blog discusses the steps to set up event listeners in Calem.

Step 1. Data Change Event Setup

A data change event can be created for Calem to generate data change stream for a table.

• Menu path: Admin module | Open | Data Change Event
• Table name defines the table that the data change events should be generated.
• Track Attributes: use this flag to track changes of category attributes
• Track Selected: use this flag to track changes of selected base and custom fields defined in the "Field" tab.
• Optionally track edit, create and delete events.
• The Sync checkbox will send data change events as part of the data change transaction.
  • This option is useful if you are building a real-time integration and want the user changes to fail if another application reject the changes.
  • Otherwise, the data change events are placed in a queue and will be sent to other applications later as a cron job.

 Step 2. Event Listeners

Event listeners are 3rd-party REST web services.

• Menu path: Admin module | Open | Data Change Listeners
• Client Id and Secret are used in the invocation of the REST web service that listens to Calem data change events.
• Client URL is the web service address.
• See Calem Enterprise API Guide for more information about authentication and JSON data encoding in building web service listeners.

• Listeners are then assigned to subscribe to events.

Step 3. Event Queue

Once events and listeners are configured the notification process is executed periodically to send events to listeners.

• Menu path: Admin module | Open | Event Queue
• Events are generated and stored in Event Queue.
• The events will be picked off and queued in Event Notification Queue for notification to listeners.
  • Status "New": events are created.
  • Status "Processed": events are queued in notification queue.
  • Use Event Notification Queue to view the notification status.
• Event Queue can be browsed and searched by list search row

Step 4. Event Notification Queue

Event Notification Queue shows the status of event notification.

• Menu path: Admin module | Open | Event Notification
• Event notification statuses are recorded in this list for one to review what events are notified or there are errors in the notification.
  • Status "New": queued for notification
  • Status "Processed": notification successful
  • Status: "Failed": unable to notify a listener - see "Comment" field for error messages.

 Step 5. Integration Monitors

Integration monitors can be configured to receive email notifications when errors happen in outbound event notification.

• Menu path: Org module | ACL Profiles | Monitor User
• "Integration Monitor" role may be defined for users to receive error notifications.
  • "Site" field may be populated to receive notification for a site.
  • Set "Site" field to empty to receive notification from all sites.

Additional resources

• Calem Integration Part II: REST API
  
• Calem Enterprise REST API Guide (customer account required)
• User Guide and Admin Guide (customer account required)
• Calem Enterprise Training Site
  
• Calem Enterprise Blogs
  
• Calem Enterprise demo