API - Schedule import

Introduction

There are two approaches to provision data into gomanager (Greencopper's content management system):

1. Manually entering data into gomanager
2. Requesting data to be imported into gomanager from an external server (your server)

This document deals with the second approach: importing data into gomanager. The schedule import API detailed in the document is used for transferring data from your server to gomanager. Once imported, data can be made available on mobile apps and web schedule embeds (web widget embedded in the event website). As soon as gomanager gets connected to your server over the schedule import API, the user of gomanager will be able to request an import of all the data hosted on your server. Each import wipes out previously imported data contained in gomanager and replaces it by the newly imported data. The user of gomanager can also configure automatic imports (weekly or daily).

This document is the reference specification for the schedule import API. Objects are represented in XML format and transferred over HTTP or HTTPS. You have access to a test tool in gomanager that will help you validate that your implementation is compliant with this specification.

If any question related to this document, please contact your assigned project manager or the support team for emergencies outside business hours. Contact details available in the Support section of gomanager.

Table of contents

Steps to get data imported into gomanager

Follow the steps below to import and publish data on your mobile apps and website schedule embed:

1. Add/update your event data in your event database (your server)
2. Login to gomanager then go to the Import page (left menu) and then click on the Import button
3. Gomanager will connect to your server with the authentication token. A request to transfer the data through our API will be made.
4. Your server should responds with the data over the API with the authentication token
5. Once the transfer is done, you can validate the imported data
6. In gomanager you click on the Publish button to publish the newly imported data 
7. Gomanager pushes the newly imported data to mobile apps and/or web schedule embeds

The architecture diagram below shows the process of importing and publishing an event data set.

Importing and testing with gomanager

Gomanager offers you a test tool and the possibility to import data. This is available from the Import section of the left menu (see below).

Testing

A test tool is available in gomanager to test your implementation. This tool invokes each API method on your server and check for syntax errors. If an error is found, the tool explains the error type and location in the XML document. The tool also check consistency of identifiers used in your object representations. The tool does not try to fetch photos and will therefore don't warn if photos are unavailable.

The tool never imports data into the project. The state of your project data is not affected by a test. 

Importing

Once you have successfully tested and validated that gomanager can access your server data over the API, you can request gomanager to retrieve the dataset and import it into the project. Unlike the test tool, the import process affects the project data. Previously imported data is wiped out and replaced by the newly imported data. 

If you have provisioned manually data in gomanager, this data will not be wiped out while importing a new dataset. Only previously imported data is wiped out.

Data manually entered into gomanager should not be linked to imported data as updating imported object many lead to data inconsistency issues. Manually entered data and imported data can live together in the same project but they should be kept separated and not linked together.

Encoding

XML documents must be UTF-8 encoded. Each XML document should specify the UTF-8 encoding with a specific header as show below:

<?xml version="1.0" encoding="UTF-8"?>

XML documents must be well-formatted and strictly follow to the W3C rules. You can check the validity of XML documents exposed by your server with the W3C validator available here: http://validator.w3.org

Finally, all texts should be contained in CDATA sections.

Security

All interactions over the API require the use of an authentication key. This key is only shared between you and Greencopper. This authentication key is specified as a part of request/response parameter named “authenticationToken“. Interactions that do not bear the authentication token will fail.

Content can be transferred over plain text HTTP or over HTTPS.

Interface objects

Object types

Six types of objects are manipulated over the API:

Object schema

The following diagram shows the object schema:

Associations between objects are shown in the picture below.

Associations between objects and tags are shown in the pictures below.

Tags declared for a type of object can not be linked to other types of objects. An Event Tag can not be used to tag a Venue. 

Objects are characterized by multiple attributes.

Object identifiers 

The object identifier is a common attribute for all object types (Venues, Events, Artists, Shows, Performances, and Tags):

• id: Unique identifier of the object. This identifier is used by other objects for reference purpose. 
  Presence of this attribute is Mandatory. 
  The object identifier is represented by a character string of maximum length 256 characters. The identifier shall be unique for a given object type. 
   

Localization of text attributes

Text attributes that can be localized (which means available in several languages) are referred to as Localized texts.  The structure of localized texts is shown below:

• <textName>: the name of the attribute for which the assigned value is to be localized, e.g. “title”, “subtitle”, “link1”, etc…
  • value: value of the text in a given language. There must be a value element for every supported language (even in the case of identical values across all languages). 
    • lang: Attribute indicating the language according to the ISO 639-2  standard. String of 3 lowercase characters.
      
      

...
<title>
	<value lang="eng"><![CDATA[On Tour]]></value>
	<value lang="fre"><![CDATA[En tournée]]></value>
</title>
...

Schedulable attributes 

All objects except Tags share these attributes:

• sortOrder: explicit sorting order, as a positive integer. By default, objects have an implicit order (alphabetical for Events, Venues and Artists, start date and time for Shows and Performances). This can be modified with sortOrder. Sort order is ascending: lower values precede higher values. 

• generic[1|2|3|4|5|6]: localized texts that can be used for project-specific purposes. These attributes should not be set unless their use has been specifically defined for the project.

Schedulable common attributes

The following attributes are common to object type Events, Artists and Venues:

Venue-specific attributes

Venues have the following additional attributes:

Artist-specific attributes

Artists have the following additional attributes:

Event-specific attributes

Events have the following additional attributes:

Show-specific attributes

Shows have the following additional attributes:

Performance-specific attributes

Performances have the following additional attributes:

Tag-specific attributes

Tags have the following additional attributes:

XML formatting

All objects are serialized in XML format:

• Each object is a XML element named after the object’s type (e.g. a Venue is a <venue> XML element).
• Each attribute of an object is represented by a XML element as a child of the object’s XML element (e.g. a Venue title is a <title> XML element, child of the <venue> element).

Note: All strings must be set inside a CDATA section to avoid encoding issues.

For instance, an Artist object is represented in the following form:

<artist>
    <id>4</id>
    <title>
        <value lang="eng"><![CDATA[MGMT]]></value>
        <value lang="fre"><![CDATA[MGMT]]></value>
    </title>
    <description>
        <value lang="eng"><![CDATA[MGMT (officially pronounced em-gee-em-tee[1], but colloquially pronounced 'Management') is …]]></value>
        <value lang="fre"><![CDATA[MGMT (prononcé [ɛmdʒiɛmti]1), précédemment connu sous le nom de The Management, est …]]></value>
    </description>
    <photo updateDate="2010-12-31 23:59" credit="Wikipedia"><![CDATA[http://upload.wikimedia.org/wikipedia/commons/d/de/MGMT_Burlington_2005-09-12.jpg]]></photo>
    <link1>
        <value lang="eng"><![CDATA[http://www.whoismgmt.com/en/home]]></value>
        <value lang="fre"><![CDATA[http://www.whoismgmt.com/fr/home]]></value>
    </link1>
</artist>

Interface methods

Gomanager requests data over 4 interface methods. Each method of the interface is called via the HTTP GET method. Your server must return the results in UTF-8 encoded XML format.

List of methods

Below is the list of supported interface methods. 

Note: extension .ext can be replaced by any specific extension (.php, .asp, .xml, etc.) or it can also be omitted, e.g. /shows

Method parameters

Gomanager always provides the authentication token when invoking methods over the interface, e.g. http://www.festival.com/api/method.ext?authenticationToken=xxx

• authenticationToken: The use of the authentication token ensures that only authorized requests will be served. Your server must verify the validity of the authentication token for each request. 

Error codes

If one of the methods is not required (no “Artists” or no “Events”), your server will return a 404 header. 

Otherwise, methods could return one of theses supported error codes:

• 800: Incorrect parameter(s). One or more parameters of the method are invalid or missing.

• 801: Authentication key is invalid.

• 802: Service unavailable.

Example of an error response:

<error>
    <code>800</code>
    <description><![CDATA[Bad arguments]]></description>
	<detail><![CDATA[The argument ‘authenticationToken’ was not found in the request. Please check the request.]]></detail>
</error> 

Artist method

This method provides a list of all Artists with their associated Artist Tags.

• The XML root element is artists.
• Each Artist Tag is represented by a "tag" XML element. Important: all Artist Tags must be declared before the Artists in the document. 
• Each Artist is represented by a artist XML element.
• Each Artist can refer to a subset of the declared Artist Tags.
  

Example: 

<?xml version="1.0" encoding="UTF-8"?>
<artists>
    <tag>
        <id>tag_1</id>
        <title>
            <value lang="eng"><![CDATA[On Tour]]></value>
            <value lang="fre"><![CDATA[En tournée]]></value>
        </title>
        <color>#00ff00</color>
    </tag>
    <tag>
    	<!-- Another tag -->
    </tag>
    <!-- ... -->
    <artist>
        <id>4</id>
        <title>
            <value lang="eng"><![CDATA[MGMT]]></value>
            <value lang="fre"><![CDATA[MGMT]]></value>
        </title>
        <description>
            <value lang="eng"><![CDATA[MGMT (officially pronounced em-gee-em-tee[1], but colloquially pronounced 'Management') is an…]]></value>
        </description>
        <photo updateDate="2010-12-31 23:59" credit="Wikipedia"><![CDATA[http://upload.wikimedia.org/wikipedia/commons/d/de/MGMT_Burlington_2005-09-12.jpg]]></photo>
        <link1>
            <value lang="eng"><![CDATA[http://www.whoismgmt.com]]></value>
            <value lang="fre"><![CDATA[http://www.whoismgmt.com]]></value>
        </link1>
        <link2>
            <value lang="eng"><![CDATA[http://www.myspace.com/mgmt]]></value>
            <value lang="fre"><![CDATA[http://www.myspace.com/mgmt]]></value>
        </link2>
        <style>
            <value lang="eng"><![CDATA[Electro, pop]]></value>
            <value lang="fre"><![CDATA[Électro, pop]]></value>
        </style>
        <tags>
            <tagId>tag_1</tagId><!-- Reference a tag declared above artists --> 
    		<!-- Other tags references -->
        </tags>
    </artist>
    <artist>
        <!-- Another artist -->
    </artist>
    <!-- ... -->
</artists>

Events method

This method provides a list of all Events with their associated Event Tags.

• The XML root element is events.
• Each Event Tag is represented by a "tag" XML element. Important: all the Event Tags must be declared before the Events in the document. 
• Each Event is represented by a "artist" XML element.
• Each Event can reference a subset of the declared tags.
  

Example:

<?xml version="1.0" encoding="UTF-8"?>
<events>
      <!-- Example with events without tags, just list of events -->
	<event>
		<id>101</id>
		<title>
			<value lang="eng"><![CDATA[U2 - Special night]]></value>
			<value lang="fre"><![CDATA[Soirée spéciale U2]]></value>
		</title>
		<subtitle>
			<value lang="eng"><![CDATA[Wonderful night]]></value>
			<value lang="fre"><![CDATA[Soirée exceptionnelle]]></value>
		</subtitle>
		<sortOrder>2</sortOrder>	
	</event>
	<event>
    		<id>102</id>
    		<title>
    			<value lang="eng"><![CDATA[Electric night]]></value>
    			<value lang="fre"><![CDATA[Nuit électrique]]></value>
    		</title>
    		<sortOrder>1</sortOrder>
      </event>
    	<!-- ... -->
</events>

Shows method

This method provides a list of all Shows with their associated Tags and Performances.

• The XML root element is shows.
• Each Show Tag is represented by a "tag" XML element. Important: all the Show Tags must be declared before the Shows in the document. 
• Each Show is represented by a "show" XML element.
• Each Show can reference a subset of the declared tags.

The recommended usage is to link the Show directly to the artist or event id.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<shows>
    <tag>
        <id>free</id>
        <title>
            <value lang="eng"><![CDATA[Free]]></value>
            <value lang="fre"><![CDATA[Gratuit]]></value>
        </title>
    </tag>
    <tag>
        <id>paid</id>
        <title>
            <value lang="eng"><![CDATA[Paid]]></value>
            <value lang="fre"><![CDATA[Payant]]></value>
        </title>
    </tag>
	<show>
        <id>10</id>
		<artistId>7</artistId>
        <dateStart>2010-07-03</dateStart>
        <timeStart>19:00</timeStart>
        <dateEnd>2010-07-04</dateEnd>
        <timeEnd>03:45</timeEnd>
        <venueId>1234</venueId>
        <tags>
            <tagId>free</tagId>
        </tags>
	</show>
   
	<show>
        <id>11</id>
		<artistId>4</artistId>
        <dateStart>2010-08-03</dateStart>
        <timeStart>19:00</timeStart>
        <dateEnd>2010-08-03</dateEnd>
        <timeEnd>21:00</timeEnd>
        <price>
            <value lang="eng"><![CDATA[Start at $35]]></value>
            <value lang="fre"><![CDATA[A partir de 35 €]]></value>
        </price>
        <linkTicket>
            <value lang="eng"><![CDATA[http://bit.ly/Fu87e]]></value>
            <value lang="fre"><![CDATA[http://bit.ly/Fu87d]]></value>
        </linkTicket>
        <venueId>1234</venueId>
        <tags>
            <tagId>paid</tagId>
        </tags>

    </show>
</shows>

Alternatively, Each “show" XML element can have a "performance" XML element as a child of the "performances" XML element of the Show. Ask guidance from us if you are willing to use this alternative method so your project can be configured accordingly.

Example with performances :

<?xml version="1.0" encoding="UTF-8"?>
<shows>
    <tag>
        <id>free</id>
        <title>
            <value lang="eng"><![CDATA[Free]]></value>
            <value lang="fre"><![CDATA[Gratuit]]></value>
        </title>
    </tag>
    <tag>
        <id>paid</id>
        <title>
            <value lang="eng"><![CDATA[Paid]]></value>
            <value lang="fre"><![CDATA[Payant]]></value>
        </title>
    </tag>
    <show>
        <id>10</id>
        <dateStart>2010-07-03</dateStart>
        <timeStart>19:00</timeStart>
        <dateEnd>2010-07-04</dateEnd>
        <timeEnd>03:45</timeEnd>
        <eventId>101</eventId>
        <venueId>1234</venueId>
        <tags>
            <tagId>free</tagId>
        </tags>
        <performances>
        	<performance>
                	<id>20</id>
                	<artistId>2</artistId>
                	<dateStart>2010-07-03</dateStart>
        	    	<timeStart>19:00</timeStart>
            </performance>
        	<performance>
                	<id>21</id>
                	<artistId>3</artistId>
                	<dateStart>2010-07-03</dateStart>
        	    	<timeStart>22:30</timeStart>
            </performance>
        </performances>
   
	</show>

</shows>

Venues method

This method provides a list of all Venues with their associated Venue Tags.

• The XML root element is venues.
• Each Venue Tag is represented by a "tag" XML element. Important: all the venue tags must be declared before the venues in the document. 
• Each Venue is represented by a "venue" XML element.
• Each Venue can reference a subset of the declared tags.
  

Example: 

<?xml version="1.0" encoding="UTF-8"?>
<venues>
    <tag>
        <id>tag_1</id>
        <title>
            <value lang="eng"><![CDATA[District]]></value>
            <value lang="fre"><![CDATA[Quartier]]></value>
        </title>
        <color>#ff0000</color>
    </tag>
    <tag>
    	<!-- Another tag... -->
    </tag>
    <!-- ... -->
    <venue>
        <id>1234</id>
        <title>
            <value lang="eng"><![CDATA[Manhattan]]></value>
            <value lang="fre"><![CDATA[Manhattan]]></value>
        </title>
        <subtitle>
            <value lang="eng"><![CDATA[Manhattan, NYC]]></value>
            <value lang="fre"><![CDATA[Manhattan, ville de New York]]></value>
        </subtitle>
        <description>
            <value lang="eng"><![CDATA[Manhattan is one of the boroughs of New York City. Located primarily on Manhattan Island ...]]></value>
            <value lang="fre"><![CDATA[Manhattan est l'une des cinq circonscriptions (borough) de la ville de New York...]]></value>
        </description>
        <photo updateDate="2010-05-09 11:22" credit="Wikipedia">
            <![CDATA[http://upload.wikimedia.org/wikipedia/commons/8/80/NYC_wideangle_south_from_Top_of_the_Rock.jpg]]></photo>
        <link1>
            <value lang="eng"><![CDATA[http://www.manhattan.com]]></value>
            <value lang="fre"><![CDATA[http://www.manhattan.com/fr]]></value>
        </link1>
        <gpsLatitude>3.23456789</gpsLatitude>
        <gpsLongitude>-46.23456789</gpsLongitude>
        <sortOrder>78</sortOrder>
        <tags>
            <tagId>tag_1</tagId> <!-- Reference a tag declared above venues --> 
			<tagId>gc-venuetag-stage</tagId> <!-- Reference a generic tag (with icon) --> 
    		<!-- Other tags references -->
        </tags>
    </venue>
    <venue>
        <!-- Another venue -->
    </venue>
    <!-- ... -->
</venues>

Triggering automatic import and publication

Gomanager supports the possibility to trigger an automatic import of your data and, if no error detected, a publication of imported data on your web schedule embed and/or mobile apps. Unlike the manual two-step process of importing then publishing data, the programmatic triggering combines import and publication. If the import process is successful and new data was detected then the imported data is automatically published to mobile apps and/or web schedule embed.

Web service URL and parameters

For this purpose, your system can request an automatic import/publication by invoking a web service over HTTPS. The end service URL is shown below:

https://api1.greencopper.com/goevent/schedule/import-publish/<tag>/<token>/ 

URL parameters:

• <tag>: The project tag of your project. It is assigned by Greencopper and communicated to you.
• <token>: The authentication token.  This value is assigned by Greencopper and communicated to you. This is used to ensure that Greencopper's server only processes legitimate traffic. 

POST request

The POST request requires the following parameters:

• username:  The username used for  logging into your gomanager account.
• password: The password used for  logging into your gomanager account.

POST response

Greencopper's server responds to each POST request with a corresponding POST response. Two types of responses are supported:

• message: indicates that the request was processed correctly.
• error: indicates that the related action could not be completed and an error code provides some information for troubleshooting purpose.

Regardless of response type, the XML structure of a response is as follows:

• root name: message or error
  • code: a numerical code indicating success or an error.
  • description: a short description (text, could include HTML tags).
  • detail: a long description (text, could include HTML tags). This field might be empty.

Response codes

The table below lists response codes supported over the web service:

Response examples

The XML response below is an example of a response indicating a successful action outcome:

The XML response below is an example of a response indicating an erroneous outcome:

Change log 

• March 16, 2017: adding a section on triggering and importing
• January 14, 2017: major refactoring of the document to make content flow better. 
• August 7,  2020: added livestreamUrl attribute to shows

The release of gomanager version 6.0 in March 2014 introduced significant changes to the schedule import API. If you implemented our API before March 2014, you should consider the following aspects to update your solution:

1. Objects named Participants are renamed Artists

2. Objects named Plays and Cast are respectively renamed Shows and Performances

3. An object Show must be associated to an object Event or an object Artist (but not both). 
   If a Show is associated to an Event, it can have multiple Performances. 
   If a Show is associated to an Artist, no Performance are allowed.

4. The attribute date start of an object Performance is no more mandatory.

5. Objects Artists, Events, Venues and Shows can be associated to newly introduced objects Tags. 
   Each object can have several tags, and it will be able to filter them down on mobile and web. 
   Tags have an id, a title and a color. 
   Each Tag can be associated to a single kind of object (Artist, Event, Venue, Show).

6. Objects Artists and Events can have a Discoverable attribute. 
   If set to true, they will be display in the Discover screen on mobile apps.

7. Series objects don't exist anymore. 
   Attributes special and type are no more available.