API - Data Sync

Introduction

The Data Sync API act as a synchronisation between your data source and our CMS. This is useful if you already have your data in a system and you are able to export it as data feeds.

Prerequisites

The data must be exposed in data feeds accessible on the web.
The feed must follow the structure defined in this documentation
The data must follow the formats and requisites described in this documentation

If you are unable to achieve all these requirements, we may be able to provide a service that will convert your existing data feeds to match the format we require. Contact us for more info.

Authentication

The CMS will add the authenticationToken parameter with a value that your implementation manager can provide. If you want to protect your data, your server will have to validate that token. This is optional.

Example: https://website.com/datafeed/tags.json?authenticationToken=410fcbaeb33448dda131158705ea8ccb

Data models

Model	Info

Model	Info
stage	A location where an activity takes place
location	A general location
activity	Can represent a show, a conference, an event Can optionally have one or more schedule items
scheduleItem	Is linked to an activity. It associates the activity to one or both of these: a stage a timeSlot
timeSlot	The date and time information of a scheduleItem
performer	Can represent a speaker, as guest, an artist Is usually used to identify multiple performers of a same event (schedule item)
tagCategory	You can create tag categories for activity, stage and scheduleItem
tag	A tag is linked to a tagCategory and you can assign a tag to one or more objects. Tags can be used to filter content in the app.
widgetCollection	A collection of widgets that can be linked to an object
widget	Widgets are used to add extra content to an object

Examples of how you can use the data model

Data feed

Data must be split into five different data feeds. They are all optional, you may use only the feeds that you need.

feed	Info

feed	Info
tags	Data for tagCategories and tags
stages	Data for all the stages
activities	Data for all the activities along with their optional scheduleItems and timeSlots
performers	Data for all the performers
locations	Data for all the locations

Data format

Feeds must be valid JSON. They need to be served by a secure web server (https) that is using a valid certificate. The web server must return an HTTP status of 200.

Each JSON feed must be an object with a required attribute that represents the feed objects like stages or activities, and an optional errors attribute that contains a list of any errors that occurred while preparing the data. The value for that attribute is a list of objects.

Example for activities:

{
    "activities": [
        {
            "id": "activity1",
            "name": "First Activity"
        },
        {
            "id": "activity2",
            "name": "Second Activity"
        }
    ],
    "errors": [
      "Server returned 404 error",
    ]
}

Data attributes

Tag Category

Attribute	Type	Required	Info

Attribute	Type	Info
id	string (256 characters max)	Must be unique across all tag categories IDs must maintain consistency (i.e. a given Tag Category must keep the same ID across each data sync). Not maintaining IDs between syncs can cause issues with pins on a map.
name	string or object for multi-language support	The name of the tag category Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
object_types	array of string	Defines the types of objects that can use that tag category. Choices are: `activity`, `schedule_item`, `performer` and `location` (use this one for stages). At least one type is required.
tags	array	A list of tag objects to create for this category

Tag

Attribute	Type	Required	Info

Attribute

Type

Required

Info

id

string (256 characters max)

Must be unique across all tags

IDs must maintain consistency (i.e. a given Tag must keep the same ID across each data sync). Not maintaining IDs between syncs can cause issues with pins on a map.

name

string
or
object for multi-language support

The name of the tag

Use a string if your content is in a single language or if you want to use the same value for all the languages

If you want to use different values for each language you can use an object. See Localization of text attributes for more info

Stage

Attribute	Type	Required	Info

Attribute	Type	Info
id	string (256 characters max)	Must be unique across all stages IDs must maintain consistency (i.e. a given Stage must keep the same ID across each data sync). Not maintaining IDs between syncs can cause issues with pins on a map.
name	string or object for multi-language support	The name of the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
subtitle	string or object for multi-language support	An optional subtitle for the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
description	text or object for multi-language support	An optional description for the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info Description supports basic HTML tags like `<p>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>` and `<li>`
address	string or object for multi-language support	An optional address for the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
coordinates	object	An optional Coordinates object
photo	object	An optional Photo object
order	integer	An optional order that is used to sort the stages in the app. A stage with `order` 1 will be listed before one with `order` 12. Stages without an `order` will be listed alphabetically after the ones that have a value for `order`
tags	array	A list of tag IDs use for this object

Location

Attribute	Type	Required	Info

Attribute	Type	Info
id	string (256 characters max)	Must be unique across all locations
name	string or object for multi-language support	The name of the location Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
subtitle	string or object for multi-language support	An optional subtitle for the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
description	text or object for multi-language support	An optional description for the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info Description supports basic HTML tags like `<p>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>` and `<li>`
address	string or object for multi-language support	An optional address for the stage Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
coordinates	object	An optional Coordinates object
photo	object	An optional Photo object
order	integer	An optional order that is used to sort the locations in the app. A location with `order` 1 will be listed before one with `order` 12. Locations without an `order` will be listed alphabetically after the ones that have a value for `order`
tags	array	A list of tag IDs use for this object
widget_collection	object	An optional Widget Collection object

Coordinates

Attribute	Type	Required	Info

Attribute	Type	Required	Info
latitude	string or number (20 characters max)	If one is provided, the other is required	Latitude coordinate of the stage
longitude	string or number (20 characters max)	If one is provided, the other is required	Longitude coordinate of the stage

Photo

Attribute	Type	Required	Info

Attribute

Type

Required

Info

url

string

Latitude coordinate of the stage

fingerprint

string (64 characters max)

highly recommended

A string that the CMS will use to quickly determine if the file has changed since the last sync. Can be a date, a timestamp, a hash… The fingerprint needs to change when the photo is updated.

Providing a fingerprint will greatly improve the speed of imports

Activity

Attribute	Type	Required	Info

Attribute	Type	Info
id	string (256 characters max)	Must be unique across all activities
name	string or object for multi-language support	The name of the activity Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
subtitle	string or object for multi-language support	An optional subtitle for the activity Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
description	text or object for multi-language support	An optional description for the activity Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info Description supports basic HTML tags like `<p>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>` and `<li>`
photo	object	An optional Photo object
order	integer	An optional order that is used to sort the activities in the app. An activity with `order` 1 will be listed before one with `order` 12. Activities without an `order` will be listed alphabetically after the ones that have a value for `order`
schedule_items	list	List of Schedule Items objects.
tags	array	A list of tag IDs use for this object
widget_collection	object	An optional Widget Collection object

Schedule Item

Attribute	Type	Required	Info

Attribute	Type	Info
id	string (256 characters max)	Must be unique across all schedule items
stage_id	string (256 characters max)	Must be the ID of a stage that is present and valid in the stages feed.
time_slot	object	An optional Time Slot object
performers	array	A list of Schedule Item Performer objects
tags	array	A list of tag IDs use for this object
widget_collection	object	An optional Widget Collection object

Schedule Item Performer

Attribute	Type	Required	Info

Attribute	Type	Required	Info
performer_id	string (256 characters max)		Must be the ID of a performer that is present and valid in the performers feed.
order	integer		An optional order that is used to sort the performers of the schedule item in the app. A performer with `order` 1 will be listed before one with `order` 12.

Time Slot

Attribute	Type	Required	Info

Attribute	Type	Info
start_date	string of an ISO-8601 date (YYYY-MM-DD)	The start date of the schedule item
start_time	string of an ISO-8601 time (hh:mm)	The start time of the schedule item Time zone is assumed to be local to your event. (Can be changed in the CMS by your implementation manager)
end_date	string of an ISO-8601 date (YYYY-MM-DD)	The end date of the schedule item. If omitted, the end date is assumed to be the same as the start date Must be the equal or after the `start_date`
end_time	string of an ISO-8601 time (hh:mm)	The end time of the schedule item Time zone is assumed to be local to your event. (Can be changed in the CMS by your implementation manager) The `start_time` is required if you provide an `end_time`

Performer

Attribute	Type	Required	Info

Attribute	Type	Info
id	string (256 characters max)	Must be unique across all performers
name	string or object for multi-language support	The name of the performer Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
subtitle	string or object for multi-language support	An optional subtitle for the performer Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info
description	text or object for multi-language support	An optional description for the performer Use a string if your content is in a single language or if you want to use the same value for all the languages If you want to use different values for each language you can use an object. See Localization of text attributes for more info Description supports basic HTML tags like `<p>`, `<strong>`, `<em>`, `<u>`, `<ol>`, `<ul>` and `<li>`
photo	object	An optional Photo object
order	integer	An optional order that is used to sort the performers in the app. A performer with `order` 1 will be listed before one with `order` 12. Performers without an `order` will be listed alphabetically after the ones that have a value for `order`
tags	array	A list of tag IDs use for this object
widget_collection	object	An optional Widget Collection object

Attribute	Type	Required	Info

Attribute	Type	Required	Info
widgets	array		A list of Widget objects

Attribute	Type	Required	Info

Attribute	Type	Required	Info
widget_type	string		Defines the type of widget. Available choices are `button`, `link_collection` and `title_subtitle`
widget	object		Each widget types have their own attributes, see Button Widget, Link Collection Widget and Title Subtitle Widget for more info

Attribute	Type	Required	Info

Attribute

Type

Required

Info

button_text

string
or
object for multi-language support

The text to display on the button

Use a string if your content is in a single language or if you want to use the same value for all the languages

If you want to use different values for each language you can use an object. See Localization of text attributes for more info

url

string
or
object for multi-language support

The URL to open when the user taps on the button. Can be a web link or an internal link. Ask your implementation manager for available internal links.

icon

string

An icon to display on the button. Ask your implementation manager for a list of available choices

Attribute	Type	Required	Info

Attribute	Type	Required	Info
links	array		A list of Link objects

Link

Attribute	Type	Required	Info

Attribute	Type	Info
url	string	The URL to open when the user taps on the button. Can be a web link or an internal link. Ask your implementation manager for available internal links
label	string	An optional label to display for this link. If not set, a default label will be set based on the URL you entered
icon	string	An optional icon to display for this link. Ask your implementation manager for a list of available choices. If not set, a default icon will be set based on the URL you entered.

Attribute	Type	Required	Info

Attribute

Type

Required

Info

title

string
or
object for multi-language support

You need to provide at least a title or a subtitle

The text to display as the title

Use a string if your content is in a single language or if you want to use the same value for all the languages

If you want to use different values for each language you can use an object. See Localization of text attributes for more info

subtitle

string
or
object for multi-language support

The text to display as the subtitle

Use a string if your content is in a single language or if you want to use the same value for all the languages

If you want to use different values for each language you can use an object. See Localization of text attributes for more info

Localization of text attributes

If you want to use different value for each language you can use an object like this:

{
  "eng": "An English name",
  "fre": "Un nom en français"
}

When using multi-language, the value for the main language is required. Values for other languages are optional and will fallback on the main language if they are not provided. The main language is defined in the CMS by the implementation manager.

Supported language codes

ISO 639-2 three letter codes (ex. eng, fre, ger)
ISO 639-1 two letter codes (ex. en, fr, de)

Examples

{
  "tags": [
    {
      "id": "music",
      "name": "Music Genre",
      "object_types": ["activity"],
      "tags": [
        {
          "id": "123",
          "name": {
            "eng": "Rock"
          }
        },
        {
          "id": "dance",
          "name": {
            "eng": "Dance"
          }
        }
      ]
    },
    {
      "id": "access",
      "name": "Access level",
      "object_types": ["schedule_item"],
      "tags": [
        {
          "id": "vip",
          "name": "VIP"
        }
      ]
    }
  ]
}

CMS

Configuration

An implementation manager will setup the CMS for you. They will need the URLs of your feed(s) and optionally the authentication token you want to use.

When the setup is complete, you will have access to the Data Sync section from the left menu where you will be able to test and sync your data.

Sync flow

Test run

During a test run, the CMS will load the data feed and validate the content. A report will display the list of objects that are valid along with any validation errors that needs to be fixed.

Nothing is imported during a test run, the CMS data is not changed in any way.

Photos are not validated during a test run.

Sync

During a sync, the data is first validated. If there are any validation errors, the sync is stopped and the data is not changed.

Once every object is validated, they are imported. The import of photo is run after the objects are imported. If there are any issues with the import of photos, the sync will still complete and you will have access to the list of errors.

The data is synchronized to match the feed:

An activity with ID “123” will completely replace the activity with ID “123” that was created during a previous sync
If an activity with ID “345” was previously imported and is no longer present in your data feed, it will be deleted from the CMS

Change log

Date	Author	Notes

Date	Author	Notes
2022-02-04	Yan Chouinard	Initial version
2022-02-22	Yan Chouinard	Added support for two letters language codes
2022-05-11	Yan Chouinard	Hide Performers until they are supported
2022-05-19	Yan Chouinard	Added Tags and Widgets
2022-08-24	Yan Chouinard	Added Locations
2022-10-06	Yan Chouinard	Update Tag’s object_types field
2023-05-10	Yan Chouinard	Added order for Activities and added more info for start_time and end_time
2023-06-12	Yan Chouinard	Added Performers and order on Location and Stage
2023-09-05	Mahmoud Ahmed	Added the `errors` attribute to the feed.

Introduction

Prerequisites

Authentication

Data models

Examples of how you can use the data model

Data feed

Data format

Data attributes

Tag Category

Tag

Stage

Location

Coordinates

Photo

Activity

Schedule Item

Schedule Item Performer

Time Slot

Performer

Widget Collection

Widget

Button Widget

Link Collection Widget

Link

Title Subtitle Widget

Localization of text attributes

Supported language codes

Examples

CMS

Configuration

Sync flow

Test run

Sync

Change log