Export integrations

This document describes the structure for our generic export integration mechanisms for sales, register close statements, product edit events, newsletter signups and future exportable entities.

The data types that can currently be exported are:

  • Sales
  • Register Close Statements
  • Products Edit Events
  • Newsletter Signups

All exports happen through the same internal mechanism, namely the Export Queues.

Export Queues Overview

For each event that can be exported, the Ka-ching system can be configured to place the event entity in any number of queues. For instance, for each sale, the system can be configured to place the sale in two different export queues.

The export happens in three steps:

  1. Trigger
  2. Transformation
  3. Delivery

Trigger

Each queue can be configured to trigger an export to an external system in different ways:

  • Real time
  • By cron job

If the queue is configured to trigger real time, then an export will be started for each entity in the queue. If the cron job trigger is used, then the export will be performed in batches either daily or hourly based on the trigger configuration.

Transformation

When an export is performed, the data in the queue is first passed through a transformation step. Here you can configure an optional transformation of the exported data. Note that the expression forms in this step do have some limitations, so it should be considered to export the full data as it is and transform it at the receiving system.

Delivery

When the data is transformed it is passed to the delivery step. Here a configuration can specify to deliver to a web hook (an https endpoint), send an email, push to an FTP server and more.

Success / failure

When items in the queue are processed, they will end up in either a failure log or a success log. In case of failures, an error message from the delivery will be included, in order to make debugging integrations easier.

Trigger Types

Real time

The real time trigger takes a single element from the queue each time an element is added to the queue. The logical implication is that this trigger type will likely have a larger performance impact on the receiving end - since a request is made for each and every element.

Cron

This trigger can be configured to run once per hour or once per day and thus aggregates all the elements in the queue and process them in one go.

Built-in transforms

Identity

No transform is applied, and the JSON model will be our internal model as described in the Models documentation.

Mustache / handlebars

Mustache is a generic template language that can be used to output all sorts of data, like for instance JSON or HTML. Here is a link to the official Mustache template documentation https://mustache.github.io. The handlebars export is similar to mustache, but is a bit more flexible. The documentation can be found here: http://handlebarsjs.com.

CSV

The CSV export is quite elaborate and can be configured to provide a huge variety of content. Line items can be aggregated together and grouped by things like VAT. Payment transactions can be grouped together by type and currency.

Simple JSON

The Simple JSON transform lets you describe a simple, flat JSON output structure.

Built-in delivery methods

Email

Configure this in order to send the transformed data as an attachment to a number of email recipients.

Web hook

The web hook integration is a simple and easy way for you to obtain real time updates of sales from the Ka-ching system without the need to build your own integration framework. Each sale can be transformed or left as is and be POST’ed to a URL. This would most likely require some kind of credentials or token to be added as part of the URL or set as an auth header when the POST is performed.

Exportable Content

Sales

You can configure an export integration that will receive all sales from an entire account in the Ka-ching system. The Sales entity is described in details in the Models document and includes information about the line items in the sale, the payment transactions used to pay for the sale, the applied discounts and taxes, information about the source of the sale and the time of the sale.

Register Close Statements

You can configure an export integration that will receive all register close statements from an entire account in the Ka-ching system. The Register close statements entity is described in details in the Models document and includes information about aggregated totals for sales, returns and grouped by product group. It also contains information about the reconciliations of payment types and information about the source of the register close statement and the time of the register close event.

Product Edit Events

You can configure the system to perform an export of product details every time they change in the system. This is useful for the situation where you use the Ka-ching system as the primary source for products and wish other systems to reflect any changes made to the products. Product creation, product changes and product deletion events are exported.

Newsletter Signup Events

One of the Ka-ching SecondScreen modules allow customers to sign up to newsletters. This information can be sent to systems like Mailchimp using an export-configuration transforming the newsletter signup-event to the format required to sign up in Mailchimp.