Appmiral Timetable Importer v3

Now with support for tags and multiple languages.

Introduction

The Appmiral Timetable Importer allows you to import timetable information from other systems into Appmiral and keep them in sync. This importer expects 2 URLs: one for stages and one for artists and their performances. These URLs can be static .json files hosted online or public API endpoints.

Every 15 minutes, the importer will perform a request to both URLs and sync the contents to the Appmiral database as Artists, Stages and Performances. This means that when the timetable is changed, it takes a maximum of 15 minutes before those changes are reflected in the Appmiral CMS and the app.

Differences from v2

The Appmiral Timetable Importer v3 is very similar to v2 but adds support for tags and multiple languages. The import format is now JSON only, XML is no longer supported!

Tags is a new field on both Artist and Stage that allows you to link specific tags to specific artists and stages. This is an array of tag slugs which will then be created in the Appmiral database and linked to the artist or stage. Tags can be further customized in the Appmiral CMS by giving it a nice display name, a color and whether or not it should be visible in the app.
To support multiple languages, some fields are now translatable. For those fields it is now possible to add different content for each language configured in the Appmiral CMS. See below for a more detailed explanation on how translatable fields work.

Translatable Fields

Fields that are translatable are always of type string or can optionally be an object containing a string for each language.

If a translatable field contains a string, it will set that value for the default language only.
If a translatable field contains an object, it will set each value for the specified languages. In this case the default language should always be present! The key is the short locale of the language!

In the below example, the field name is translatable but is identical in all languages. In that case it is possible to have the name field be a string.

{
  "name": "Main Stage"
}

In the next example, the field name is translatable but different in English and Dutch. If English is the default language, then "en" should always be included.

{
  "name": {
    "en": "Main Stage",
    "nl": "Hoofdpodium"
  }
}

Currently, Appmiral supports the following languages and locales: English (en), Arabic (ar), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), Galician (gl), German (de), Greenlandic (kl), Hebrew (he), Italian (it), Norwegian (nb), Polish (pl), Romanian (ro), Spanish (es) & Swedish (sv).

Note: To know which language(s) are configured for your application, please see the Appmiral CMS or reach out to us.

Stages

Stage Model

Field	Required	Type	Description
id	Yes	string	The ID of the stage. Has to be unique for each stage.
name	Yes	string / object	The name of the stage. Translatable.
priority	No	integer	The priority of the stage. This determines the position of the stage on various screens in the app. Default is 100.
description	No	string / object	The description for the stage. Can contain HTML. Translatable.
image	No	string / object	A URL to an image of the stage. Must be JPG or PNG. Should be at least 1500x1500. Stages should preferably be centered on the image. Translatable.
color	No	string	The color representing the stage. This color will be used on various screens in the app where the stage is mentioned. In HEX format including the #. e.g. "#FF0000".
tags	No	array of strings	A list of tags to link to the stage. Tags are slugs which should be lowercase and can contain a-z, 0-9 and -

Stage JSON Example

The example below contains a stage without translated fields and a stage with translated fields:

{
  "stages": [
    {
      "id": "1",
      "name": "Main Stage",
      "priority": 1,
      "color": "#FF0000"
    },
    {
      "id": "dance_hall",
      "name": {
        "en": "Dance Hall",
        "nl": "Danshal"
      },
      "priority": 2,
      "color": "#00FF00",
      "tags": [
        "genre-techno",
        "genre-hardstyle"
      ]
    }
  ]
}

Artists

Artist Model

Field	Required	Type	Description
id	Yes	string	The ID of the artist. It has to be unique for each artist and can never be changed. (Max. 500 characters)
name	Yes	string / object	The name of the artist. Translatable.
performances	No	array of Performance objects	A list of all performances of the artist.
priority	No	integer	The priority of the artist. This determines the position of the artist on various screens in the app. Default is 100.
description	No	string / object	The description for the artist. Can contain HTML. Translatable.
image	No	string / object	A URL to an image of the artist. Must be JPG or PNG. Should be at least 1500x1500. Artist should preferably be centered on the image. Translatable.
tags	No	array of strings	A list of tags to link to the artist. Tags are slugs which should be lowercase and can contain a-z, 0-9 and -
website	No	string / object	A URL to the website of the artist. Translatable.
facebook	No	string	A URL to the Facebook page of the artist.
twitter	No	string	A URL to the Twitter page of the artist.
linkedin	No	string	A URL to the LinkedIn page of the artist.
instagram	No	string	A URL to the Instagram profile of the artist.
tiktok	No	string	A URL to the TikTok profile of the artist.
youtube	No	string	A URL to the Youtube channel of the artist.
vimeo	No	string	A URL to the Vimeo channel of the artist.
spotify	No	string	A URL to the Spotify page of the artist or the artist's Spotify URI. Can be found by going to the artist in Spotify, choose Share and select "Copy Artist Link" or "Copy Spotify URI".
deezer	No	string	A URL to the Deezer page of the artist.
applemusic	No	string	A URL to the Apple Music page of the artist.
soundcloud	No	string	A URL to the Soundcloud page of the artist.

Note: if an artist image gets changed, make sure to adjust the URL as well. If the URL remains the same, the image will not be adjusted in the next import.

Performance Model

Field	Required	Type	Description
id	Yes	string	The ID of the performance. Has to be unique for each performance.
name	No	string / object	The name of the performance. This is optional and only necessary if the performance name is different from the artist name. Translatable.
description	No	string / object	Optional description on performance level. Translatable.
start_time	No	string	The start time of the performance. Date format has to be YYYY-MM-DD HH:mm:ssZ. Must be before or equal to end_time.
end_time	No	string	The end time of the performance. Date format has to be YYYY-MM-DD HH:mm:ssZ. Must be after or equal to start_time.
stage_id	No	string	The ID of the stage this performance takes place on.
priority	No	integer	The priority of the performance. This determines the position of the performance on various screens in the app. Default is 100.
hide_times	No	bool	Whether or not the time should still be hidden.

Tip: If the day of a performance is already known but the exact time is still unknown, use the same start_time and end_time on the day of the performance.
The application will show the day of the performance but no time.

Artists JSON Example

The example below contains an artist without translated fields and an artist with translated fields:

{
  "artists": [
    {
      "id": "1",
      "name": "Rihanna",
      "performances": [
        {
          "id": "1",
          "stage_id": "dance_hall",
          "start_time": "2019-08-24 21:00:00+02:00",
          "end_time": "2019-08-24 23:00:00+02:00"
          "description":"",
          "priority": 5,
          "hide_times": false
        }
      ],
      "priority": 1,
      "description": "<p>Robyn Rihanna Fenty (born 20 February 1988) is a Barbadian-born singer, songwriter, actress, and businesswoman. Born in Saint Michael, Barbados and raised in Bridgetown, during 2003, she recorded demo tapes under the direction of record producer Evan Rogers and signed a recording contract with Def Jam Recordings after auditioning for its then-president, hip hop producer and rapper Jay-Z. In 2005, Rihanna rose to fame with the release of her debut studio album Music of the Sun and its follow-up A Girl like Me (2006), which charted on the top 10 of the US Billboard 200 and respectively produced the successful singles \"Pon de Replay\", \"SOS\" and \"Unfaithful\". She assumed creative control for her third studio album Good Girl Gone Bad (2007) and adopted a public image as a sex symbol, while reinventing her music. Its lead single \"Umbrella\" became an international breakthrough in her career, as she won her first Grammy Award at the 50th Annual Grammy Awards in 2008.</p>",
      "image": "https://media.muzooka.com/images/4995441/landscape/16x9/medium1.jpg",
      "tags": [
        {
          "slug": "country-usa",
          "name": "USA"
        }
        {
          "slug": "genre-rnd",
          "name": "RNB"
        }
      ],
      "website": "http://rihannanow.com",
      "facebook": "https://www.facebook.com/rihanna",
      "twitter": "https://twitter.com/rihanna",
      "linkedin": null,
      "instagram": "https://www.instagram.com/badgalriri",
      "tiktok": "https://www.tiktok.com/@rihanna",
      "youtube": "https://www.youtube.com/channel/UCcgqSM4YEo5vVQpqwN-MaNw",
      "vimeo": null,
      "spotify": "spotify:artist:5pKCCKE2ajJHZ9KAiaK11H",
      "deezer": "https://www.deezer.com/en/artist/564",
      "applemusic": "https://music.apple.com/us/artist/rihanna/63346553",
      "soundcloud": "https://soundcloud.com/rihanna"
    },
    {
      "id": "taylor-swift",
      "name": {
        "en": "Taylor Swift",
        "nl": "Taylor Swift",
      },
      "performances": [
        {
          "id": "2",
          "stage_id": "1",
          "start_time": "2019-08-23 20:00:00+02:00",
          "end_time": "2019-08-23 22:10:00+02:00",
          "priority": 1,
          "hide_times": false
        },
        {
          "id": "3",
          "name": {
            "en": "Taylor Swift Exclusive Livestream",
            "nl": "Taylor Swift Exclusieve Live Stream"
          },
          "stage_id": null,
          "start_time": "2019-08-25 00:00:00+02:00",
          "end_time": "2019-08-25 00:00:00+02:00",
          "priority": 2,
          "hide_times": true
        }
      ],
      "priority": 2,
      "description": {
        "en": "Taylor Alison Swift (born December 13, 1989) is an American singer-songwriter. One of the world's leading contemporary recording artists, she is known for narrative songs about her personal life, which have received widespread media coverage. Born and raised in Pennsylvania, Swift moved to Nashville, Tennessee at the age of 14 to pursue a career in country music. She signed with the label Big Machine Records and became the youngest artist ever signed by the Sony/ATV Music publishing house. Her 2006 self-titled debut album peaked at number five on the Billboard 200 and spent the most weeks on the chart in the 2000s.",
        "nl": "Taylor Alison Swift (geboren op 13 december, 1989) is een Amerikaanse singer-songwriter, muzikante en actrice. Ze werd internationaal bekend met de single "Love Story" (2008), en scoorde daarna nog hits als "You Belong with Me" (2009), "I Knew You Were Trouble" (2012), "Shake It Off" (2014), "Blank Space" (2014) "Blank Space" (2014) en "Lover" (2020). Swift begon haar carrière in de countrymuziek, maar begon op haar vierde album Red (2012) te experimenteren met haar muziekstijl. Haar daaropvolgende albums zijn dan ook te plaatsen in de popmuziek. Op folklore en evermore (beide uit 2020) zijn ook invloeden van indiemuziek te horen."
      },
      "image": {
        "en": "https://media.muzooka.com/images/434181/landscape/16x9/medium1.jpg",
        "nl": "https://www.rollingstone.com/wp-content/uploads/2019/12/TaylorSwiftTimIngham.jpg?resize=1800,1200&w=1200"
      },
      "tags": [
        "country-usa",
        "genre-pop",
        "genre-indie"
      ],
      "website": {
        "en": "https://www.taylorswift.com/en",
        "nl": "https://www.taylorswift.com/nl"
      },
      "facebook": "https://www.facebook.com/TaylorSwift",
      "twitter": "https://twitter.com/taylorswift13",
      "linkedin": null,
      "instagram": "https://www.instagram.com/taylorswift",
      "tiktok": "https://www.tiktok.com/@taylorswift.14",
      "youtube": "https://www.youtube.com/user/taylorswift",
      "vimeo": null,
      "spotify": "https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02",
      "deezer": "https://www.deezer.com/us/artist/12246",
      "applemusic": "https://music.apple.com/us/artist/taylor-swift/159260351",
      "soundcloud": "https://soundcloud.com/taylorswiftofficial"
    }
  ]
}