Data analytics integration reference architecture

Integrating your Data Analytics system with S-360

You are the owner/maintainer of a data analytics system (named DatX in the following lines) and you want to integrate it with the S-360 instance having the following institution code: myvenue.

We expect this integration to provide the following features:

1. Synchronisation of contact data from S-360 to DatX

→ if a contact is created/updated in S-360, we want the modification to be pushed to DatX. In S-360 a contact represents either a person or a company.

2. Synchronisation of order data from S-360 to DatX

→ if an order is finalized (closed or abandonned) in S-360, we want the content of the order to be pushed to DatX. In S-360 an order represents a transaction between a contact and the institution. This transaction can be a sale, a refund, an option, a reservation...

3. Synchronisation of access control checks data from S-360 to DatX

→ If a ticket is checked at the gate of a venue, the information about that check is transmitted to DatX.

The following document indicates how to activate the integration between DatX and S-360, using S-360 standard mechanisms for all of the three streams described above.

Non-functional aspects

Data are synced every 15 minutes.

Pre-requisites

URLs

DatX provides 3 urls to which data will be POSTed from S-360.

• Contact synchronization URL. Example: http://datx.com/s360/contacts/myvenue
• Orders synchronization URL. Example: http://datx.com/s360/orders/myvenue
• Access control checks synchronization URL. Example: http://datx.com/s360/ticketchecks/myvenue

Take note that, in the examples above, DatX provides a different URL for each of the data streams (contacts, orders, access control checks). The URL also includes mention of the institution code (myvenue) of the S-360 instance. That design easly allows to integrate DatX with other S-360 instances using different institution codes.

All those URL must accept an array of JSON objects. If the payload is accepted, the URL must answer by a 200. If it is not accepted, it must answer with a different code. In that case, the same payload will be retried at the next call.

Authentication mechanism

DatX must provide the authentication mechanism for the URLs defined above.

S-360 supports the following authentication mechanisms when pushing data to remove systems:

• No authentication,
• Basic authentication,
• API Key

Contacts stream

The contact stream is put in place using S-360 contact webhook mechanism.

Please follow that link to discover the structure of the contact payload and explore the options of that mechanism: Contact webhook

New contacts will be pushed every 15 minutes, with a maximum of 500 contacts at every execution and a maximum of 50 contacts per payload.

Orders stream

The order stream is put in place using S-360 order webhook mechanism.

Please follow that link to discover the structure of the orders payload and explore the options of that mechanism: Order webhook

Finalized orders will be pushed every 15 minutes, with a maximum of 500 contacts at every execution and a maximum of 50 orders per payload.

Access control checks stream

The order stream is put in place using S-360 data export webhook mechanism.

The structure of the payload is the following:

[{
    "ticket_check_id":10228845124401,
    "movement_id":10228844462196,
    "ticket_id":10228844446468,
    "barcode":"072212349924430836880155",
    "access_time":"2023-02-09 18:25:10",
    "check_flow":"IN",
    "result":"OK",
    "failure_reason":"NO_FAIL"},

    {"ticket_check_id":10228845124402,
    "movement_id":10228844462195,
    "ticket_id":10228844446467,
    "barcode":"321488720810990025100150",
    "access_time":"2023-02-09 18:25:02",
    "check_flow":"IN",
    "result":"FAIL",
    "failure_reason":"NO_MORE_ENTRY_ALLOWED_TODAY"}]

The movement_id field allows to link those access with the movement data exported through the orders webhook.

The access control checks will be exported every 15 minutes, with a maximum of 2000 checks at each execution and a maximul of 50 checks per payload.

First time synchronization

Once the data flow is set up and tested, please determine, in accordance with the operators of myvenue the depth of past data to be retrieved: the date of the oldest dara to be retrieved.

Example: 01/01/2019

Which means that contacts updated before that date, orders created before that date and ticket checks having occurred before that date will not be pushed to DatX

S-360 team will do the appropriate set-up to synchronize those data.

Other technical approaches

Other technical approaches which necessitates developments or services on S-360's side are explored in that document. Possible architecture for data analytics systems integrations