Federation Import API

The Federation Import API is designed to allow the import of event data from third party systems, such as federations, who have their own internal competition management. The primary goal is to transfer data from the third party system into ScoreExpress, however the option of returning data from ScoreExpress to the third party system is taken into account.

In the following topics, we will describe how the data transfer works, and how the third party system should be adapted to support the process. From here on the third party system will be called the source system.

General concept and workflow

Within ScoreExpress an event corresponds to the whole of competitions organized together, e.g. at one location in the same weekend. Within one event, multiple sections of competition can be created, mostly corresponding to different disciplines that are included in the event. Therefor we will call these sections event disciplines.

The transfer of data is initiated from within ScoreExpress (by the user) and consists of two major steps. The first step is to retrieve a list of events from the source system, such that the user can select the event which needs to be imported. To do so the source must implement a web service which returns a list of events in the correct format. The web service must also support a number of filter parameters to limit the list that is retrieved. From the list, the user will select from which event and event discipline data will be imported.

In the second step data from the event disciplines is collected with a second web service that the source system must provide. Again the service should return the requested data using the correct format, as specified in this document.

The data format includes many fields where the source system can add its own ID values for the corresponding data objects. Most of these fields are optional, however, they have crucial role in synchronizing data after the initial import. Therefor, it is strongly advised to include these external ID’s, as they are called.

General technical aspects

This API specification aims to provide a standardized way for ScoreExpress to retrieve information about competitions that are available in other information systems, e.g. a federation CMS.

To allow this information exchange, the source system needs to implement two web services:

The first is to provide a list of events (with includes event disciplines), such that the ScoreExpress user can pick the event to import information from.
the second to provide the data from a selected eventDiscipline.

The specific details for each of these services is described in the next sections. Below, we describe the general aspect about these web services.

Technical set up

The web services will expect the data in the response in JSON format. The description of the services in the next sections provides a JSON schema and examples of response data.

Configuration

The configuration of the web services is linked to the user profile in ScoreExpress (currently only editable by admin).

The configuration consists of following settings:

Full URL of both services
Authentication method and credentials

Authentication

ScoreExpress currently supports two authentication methods for the CMS web services:

Basic: based on the combination of a username and password.
Bearer token: based on a single token.

Should you be unable to provide access based on these options, contact us to discuss.

Event Information Web Service

The event information web service is used by ScoreExpress to retrieve a list of events from the source system. The list should contain the basic information that ScoreExpress needs to present the event as well as the event disciplines to the user, so they can pick their choice and id information, such that the chosen event can be retrieved in separate call.

The Remote Method

When ScoreExpress wants to retrieve a list of events, it will call the event list service as follows:

method: GET
url: <baseurl>/<method-path>

The base url and path need to be provided from the source system.

Optionally, filter parameters will be added to the url:

dateFrom: the earliest date to retrieve, format: YYYY-MM-DD. Selected events should have their first date at dateFrom or later.
dateTo: the latest date to retrieve, format: YYYY-MM-DD. Selected events should have their last day at dateTo or before.
title: filter for the title of the event, should be used together with wildcards, such that the provided string is included in the title of the selected events.

The Result JSON Schema

The event listing call should return an object of type eventListImport. This schema references the eventImport schema, which in turn references the eventDisciplineImport schema.

eventListImport schema

The result of the eventList call should be an array of eventImport objects.

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/eventListImport.schema.json",
  "title": "Event Import",
  "description": "default schema for importing events from third party systems, such as federations competition management",
  "type": "array",
  "items": {
    "$ref": "eventImport.schema.json"
  }
}

eventImport schema

For each event, the following fields are used:

id: ID of the event in the source system.
title: title of the event.
titleShort: Shorter version of the title, optional.
dateFrom: first date of the event, format YYYY-MM-DD
dateTo: last date of the event, format YYYY-MM-DD
venue: place or venue name for the event.
disciplines: array of eventDisciplineImport objects included in the event, see below for details.

Following fields can be provided with the import data, but should actually already be set automatically from the default values configured in the ScoreExpress user account:

copyright: copyright line to include in documents.
logo: base64 content of the logo file.
country: 3 character country code of the event (e.g. 'BEL'). List of country codes.
language: 2 character code of the language preference for the event, current options: 'en', 'nl', 'fr'.

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/eventImport.schema.json",
  "title": "Event Import",
  "description": "default schema for importing events from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "id": {
      "description": "ID of the event in the source system",
      "type": "string"
    },
    "title": {
      "description": "Title of the event",
      "type": "string"
    },
    "titleShort": {
      "description": "Shortened title of the event, optional",
      "type": "string"
    },
    "dateFrom": {
      "description": "first date of the event",
      "type": "string",
      "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
      "format": "date"
    },
    "dateTo": {
      "description": "last date of the event",
      "type": "string",
      "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
      "format": "date"
    },
    "venue": {
      "description": "name of the venue or city of the event",
      "type": "string"
    },
    "country": {
      "description": "IOC code of the country, optional, defaults to the organizer country",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "language": {
      "description": "two character code for the language, optional, defaults to organizer language",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "copyright": {
      "description": "event copyright line, optional, defaults to organizer copyright",
      "type": "string"
    },
    "logo": {
      "description": "base64 string with the logo image, svg, png or jpeg, optional",
      "type": "string"
    },
    "disciplines": {
      "description": "list of disciplines included in the event",
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "eventDisciplineImport.schema.json"
      }
    }
  },
  "required": [
    "id",
    "title",
    "dateFrom",
    "dateTo",
    "disciplines"
  ]
}

eventDisciplineImport schema

This object type contains the general information of the event discipline included in an event. Following fields apply:

id: id of the eventDiscipline in the source system.
title: title of the eventDiscipline.
titleShort: optional shorter version of the title.
code: code used to link the eventDiscipline the corresponding ScoreExpress discipline.
copyright: optional copyright line, defaults to value set on the event level.
logo: optional, base64 logo file contents.

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/eventDisciplineImport.schema.json",
  "title": "Event Discipline Import",
  "description": "default schema for importing event disciplines from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "id": {
      "description": "ID of the event discipline in the source system",
      "type": "string"
    },
    "title": {
      "description": "Title of the event discipline",
      "type": "string"
    },
    "titleShort": {
      "description": "Shortened title of the event, optional",
      "type": "string"
    },
    "code": {
      "description": "ScoreExpress code for the discipline",
      "type": "string"
    },
    "copyright": {
      "description": "event discipline copyright line, optional, defaults to event copyright",
      "type": "string"
    },
    "logo": {
      "description": "base64 string with the logo image, svg, png or jpeg",
      "type": "string"
    }
  },
  "required": [
    "id",
    "title",
    "code"
  ]
}

Example

json

[
  {
    "id": "123455767",
    "title": "National Championships Acrobatic & Rhythmic Gymnastics of Neverland",
    "titleShort": "NC Acrobatic & Rhythmic Gymnastics",
    "dateFrom": "2019-11-29",
    "dateTo": "2019-11-30",
    "venue": "Neverland Sports Centre",
    "country": "BEL",
    "language": "en",
    "copyright": "www.scoreexpress.be",
    "logo": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxzdmcgd2lkdGg9IjE0cHgiIGhlaWdodD0iMTRweCIgdmlld0JveD0iMCAwIDE0IDE0IiB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiPg0KICAgIDwhLS0gR2VuZXJhdG9yOiBTa2V0Y2ggNTIuNSAoNjc0NjkpIC0gaHR0cDovL3d3dy5ib2hlbWlhbmNvZGluZy5jb20vc2tldGNoIC0tPg0KICAgIDx0aXRsZT5hZGQtaWNvbjwvdGl0bGU+DQogICAgPGRlc2M+Q3JlYXRlZCB3aXRoIFNrZXRjaC48L2Rlc2M+DQogICAgPGcgaWQ9IlN5bWJvbHMiIHN0cm9rZT0ibm9uZSIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPg0KICAgICAgICA8cG9seWdvbiBpZD0iYWRkLWljb24iIGZpbGw9IiMwNTE5MzEiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDcuMDAwMDAwLCA3LjAwMDAwMCkgcm90YXRlKC0yMjUuMDAwMDAwKSB0cmFuc2xhdGUoLTcuMDAwMDAwLCAtNy4wMDAwMDApICIgcG9pbnRzPSIxIDEwLjQyNTEwMTIgNC40MjUxMDEyMSA3IDEgMy41NzQ4OTg3OSAzLjU3NDg5ODc5IDEgNyA0LjQyNTEwMTIxIDEwLjQyNTEwMTIgMSAxMyAzLjU3NDg5ODc5IDkuNTc0ODk4NzkgNyAxMyAxMC40MjUxMDEyIDEwLjQyNTEwMTIgMTMgNyA5LjU3NDg5ODc5IDMuNTc0ODk4NzkgMTMiPjwvcG9seWdvbj4NCiAgICA8L2c+DQo8L3N2Zz4=",
    "disciplines": [
      {
        "id": "36998456",
        "title": "National Championships Acrobatic Gymnastics of Neverland",
        "titleShort": "NC Acrobatic Gymnastics",
        "code": "gym-acro"
      },
      {
        "id": "36998457",
        "title": "National Championships Rhythmic Gymnastics of Neverland",
        "titleShort": "NC Rhythmic Gymnastics",
        "code": "gym-rg"
      }
    ]
  }
]

Event Discipline Participants Information

Once a user has picked a competition to import into ScoreExpress, a second callback will be used to retrieve the information for the competition.

The types of information included in the response depends on the information already available, but some types of information depend on other information being provided.

The Remote Method

When ScoreExpress wants to retrieve the information for a specific event discipline, the callback is executed as follows:

method: GET
url: <baseurl>/<method-path>/<event-discipline-id>

The Result JSON Schema

The JSON schema of the event data is derived from the csv format which is used for importing data. It is in a way a structured representation of the csv format.

The basic structure of the schema is an array of objects. Each object in the format represents a row in the csv file. Each object consists of a number of subobjects, where each subobject represents a group of related fields to be imported.

The subobjects included in the import data depend on which data you want to transfer, however, you need to take into account that some types depend on other types being present in the import data.

Below is a list of the subobjects that are included in the import data. For each object, it is clearly stated:

which fields can be included
which fields are mandatory and which are optional
which field(s) are used to uniquely identify the item to avoid creating duplicates.
Which other objects the group depends on
Which other objects depend on the object

This data structure is used to keep the management of relations between data items simple. Subobjects in the same item are automatically related. Eg. a member (person) is suposed to be a member of the club included on the same object.

This structure implies some data will be repeated throughout the import data, but it avoids the need of a convoluted system to manage object relations.

eventDisciplineDataImport

The general structure of the eventDisciplineDataImport schema is as follows:

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/eventDisciplineDataImport.schema.json",
  "title": "Event Discipline Data Import",
  "description": "default schema for importing all data related to an event discipline from third party systems, such as federations competition management",
  "type": "array",
  "items": {
    "description": "list of participants with related data",
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "club": {
          "$ref": "http://scoreexpress.io/schema/clubImport.schema.json"
        },
        "member": {
          "$ref": "http://scoreexpress.io/schema/memberImport.schema.json"
        },
        "group": {
          "$ref": "http://scoreexpress.io/schema/groupImport.schema.json"
        },
        "team": {
          "$ref": "http://scoreexpress.io/schema/teamImport.schema.json"
        },
        "category": {
          "$ref": "http://scoreexpress.io/schema/categoryImport.schema.json"
        },
        "participation": {
          "$ref": "http://scoreexpress.io/schema/participationImport.schema.json"
        },
        "teamParticipation": {
          "$ref": "http://scoreexpress.io/schema/participationImport.schema.json"
        },
        "session": {
          "$ref": "http://scoreexpress.io/schema/sessionImport.schema.json"
        },
        "order": {
          "$ref": "http://scoreexpress.io/schema/orderImport.schema.json"
        }
      }
    }
  }
}

club

The club section defines the basic information of the clubs.

Fields

name: name of the club.
externalId: id of the club in the source system,
country: 3 character IOC country code (of the club),
region: region code (of the club)

A list of country and region codes can be found here.

Unique identification

Clubs are identified by their name.

Dependencies

This item does not depend on any other items.

Other items that are related to the club:

member
all items dependent on member

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/clubImport.schema.json",
  "title": "Club Import",
  "description": "default schema for importing clubs from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "name": {
      "description": "name of the club of the judge",
      "type": "string"
    },
    "externalId": {
      "description": "id of the club in the source system, optional",
      "type": "string"
    },
    "country": {
      "description": "3 character IOC code of the country (of the club), optional",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "region": {
      "description": "region of the club in the country, list of region codes per country to be consulted, optional",
      "type": "string"
    }
  },
  "required": ["name"]
}

member

The member section defines the basic information of the club members. Club members are participants of the event, either as gymnasts, judges, coaches.

Fields

lastname: (sur)name of the member,
firstname: first name of the member,
gender: gender of the member ('male' or 'female'),
dob: date of birth,
externalId: id of the member in the source system,
judge: indicates which members can act as judge,
trainingCenter: the training center (in addition to the club)

Unique identification

Members are identified by their club, lastname and firstname.

Dependencies

For members to be imported, there needs to be:

a club,

The following sections depend on member:

group
team
participation
teamParticipation
order

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/memberImport.schema.json",
  "title": "Member Import",
  "description": "default schema for importing club members from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "lastname": {
      "description": "(sur)name of the judge",
      "type": "string"
    },
    "firstname": {
      "description": "first name of the judge",
      "type": "string"
    },
    "gender": {
      "description": "gender of the judge ('male' or 'female')",
      "type": "string",
      "pattern": "^male$|^female$"
    },
    "dob": {
      "description": "date of birth of the judge, optional",
      "type": "string",
      "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
      "format": "date"
    },
    "externalId": {
      "description": "ID of the person in the source system",
      "type": "string"
    },
    "judge": {
      "description": "indicates which members can act as judge, optional, default: false",
      "type": "boolean"
    },
    "trainingCenter": {
      "description": "the training center, optional",
      "type": "string"
    }
  },
  "required": ["lastname", "firstname", "gender"]
}

group

A group is a group of members that are performing their exercises together (as opposed to a team, where each member is performing individual exercises). The member is added to the group when this item is imported.

Fields

name: name of the group,
externalId: id of the group in the source system,

Unique identification

Groups are identified by their name and club

Dependencies

group depends on:

the club (to which the group belongs)
the member (that is part of the group)

There is no other section that strictly depends on group, but a group being added has following effects:

the category which goes with the group will be created as a group category
the participation that goes with the group will be created as a group participation rather than an individual participation.

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/groupImport.schema.json",
  "title": "Group Import",
  "description": "default schema for importing groups from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "name": {
      "description": "name of the group",
      "type": "string"
    },
    "externalId": {
      "description": "id of the group in the source system",
      "type": "string"
    }
  },
  "required": ["name"]
}

team

Teams are groups of members that are performing their exercises individually (as opposed to a group). The member is added to the team when this item is imported.

Fields

name: name of the team,
externalId: id of the team in the source system,

Dependencies

team depends on:

the club (to which the team belongs)
the member (that is part of the team)

team is required for a teamParticipation to be created.

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/teamImport.schema.json",
  "title": "Team Import",
  "description": "default schema for importing teams from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "name": {
      "description": "name of the team",
      "type": "string"
    },
    "externalId": {
      "description": "id of the team in the source system",
      "type": "string"
    }
  },
  "required": ["name"]
}

participation

The participation is the section which causes the member or group to be added to the competition as a participant.

Note that the section has no required fields. The section simply being present is enough.

Fields

bib: number of the participant,
reserve: true for reserve participants,
guest: true for guest participants,
subdivision: subdivision of the participation,
exercises: list of exercises that the participant selected to perform,
externalId: id of the participation in the source system,

Unique identification

Since this section has no required fields, the participant (either member or group) is identifying.

Dependencies

Adding a participation to a competition requires:

a category,
a member,

You need a participation to be able to add

a team participation.
an order entry.

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/participationImport.schema.json",
  "title": "Participation Import",
  "description": "default schema for importing participants from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "bib": {
      "description": "Number of the participant, optional",
      "type": "integer",
      "minimum": 1,
      "maximum": 9999
    },
    "reserve": {
      "description": "true for reserve participants, optional, default: false",
      "type": "boolean"
    },
    "guest": {
      "description": "true for guest participants, optional, default: false",
      "type": "boolean"
    },
    "subdivision": {
      "description": "subdivision of the participation, optional, default: 1",
      "type": "integer",
      "minimum": 1,
      "maximum": 99
    },
    "exercises": {
      "description": "exercises of the participation, optional",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "externalId": {
      "description": "ID of the participation in the source system, optional",
      "type": "string"
    }
  }
}

teamParticipation

On top of the individual or group participation, the corresponding team can be registered as a participant.

Fields

bib: number of the team participant,
reserve: true for reserve teams,
guest: true for guest teams,
externalId: id of the participation in the source system,

the team participation will have the same subdivision as the individual participation.

Dependencies

The team participation depends on:

the participation,
the team,

It does not have dependent items.

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/participationImport.schema.json",
  "title": "Participation Import",
  "description": "default schema for importing participants from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "bib": {
      "description": "Number of the participant, optional",
      "type": "integer",
      "minimum": 1,
      "maximum": 9999
    },
    "reserve": {
      "description": "true for reserve participants, optional, default: false",
      "type": "boolean"
    },
    "guest": {
      "description": "true for guest participants, optional, default: false",
      "type": "boolean"
    },
    "externalId": {
      "description": "ID of the participation in the source system, optional",
      "type": "string"
    }
  }
}

session

Adding this section will cause a session to be created.

Fields

name: name of the session,
date: date of the session,
externalId: id of the session in the source system,
competitionId: id of the competition in the source system that the session belongs to,

Unique identification

Sessions are identified by the combination of name and date.

Dependencies

Adding a session has no dependencies.

The order item depends on the session item.

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/sessionImport.schema.json",
  "title": "Session Import",
  "description": "default schema for importing sessions and starting order from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "name": {
      "description": "name of the session",
      "type": "number",
      "minimum": 1,
      "maximum": 9999
    },
    "date": {
      "description": "date of the session",
      "type": "string",
      "pattern": "\\d\\d\\d\\d-\\d\\d-\\d\\d",
      "format": "date"
    },
    "round": {
      "description": "round of the session, optional, default: 1",
      "type": "integer",
      "minimum": 1
    },
    "externalId": {
      "description": "ID of the session in the source system, optional",
      "type": "string"
    }
  },
  "required": ["name", "date"]
}

order

Fields

set: set of the participant/exercise,
rotation: rotation (block) of participant/exercise,
block_index: index of participant within the block,
exercise: label of the exercise. This field is only applicable for disciplines where the schedule is created per exercise.

Dependencies

the order depends on:

the session,
the participation,

No other items depend on the order.

Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://scoreexpress.io/schema/v1/orderImport.schema.json",
  "title": "Starting Order Import",
  "description": "default schema for importing starting orders from third party systems, such as federations competition management",
  "type": "object",
  "properties": {
    "set": {
      "description": "set of the participant/exercise, optional, default: 1",
      "type": "integer",
      "minimum": 1,
      "maximum": 99
    },
    "rotation": {
      "description": "rotation of participant/exercise, optional, default: 1",
      "type": "integer",
      "minimum": 1,
      "maximum": 99
    },
    "block_index": {
      "description": "index of the participant/exercise within the block, determines the order within the block",
      "type": "integer"
    },
    "exercise": {
      "description": "label of the exercise, only required for disciplines where the order is made per exercise",
      "type": "string"
    }
  },
  "required": ["block_index"]
}

Federation Import API ​

General concept and workflow ​

General technical aspects ​

Technical set up ​

Configuration ​

Authentication ​

Event Information Web Service ​

The Remote Method ​

The Result JSON Schema ​

eventListImport schema ​

eventImport schema ​

eventDisciplineImport schema ​

Example ​

Event Discipline Participants Information ​

The Remote Method ​

The Result JSON Schema ​

eventDisciplineDataImport ​

club ​

Fields ​

Unique identification ​

Dependencies ​

Schema ​

member ​

Fields ​

Unique identification ​

Dependencies ​

Schema ​

group ​

Fields ​

Unique identification ​

Dependencies ​

Schema ​

team ​

Fields ​

Dependencies ​

Schema ​

category ​

Fields ​

Unique identification ​

Dependencies ​

Schema ​

participation ​

Fields ​

Unique identification ​

Dependencies ​

Schema ​

teamParticipation ​

Fields ​

Dependencies ​

Schema ​

session ​

Fields ​

Unique identification ​

Dependencies ​

Schema ​

order ​

Fields ​

Dependencies ​

Schema ​

Federation Import API

General concept and workflow

General technical aspects

Technical set up

Configuration

Authentication

Event Information Web Service

The Remote Method

The Result JSON Schema

eventListImport schema

eventImport schema

eventDisciplineImport schema

Example

Event Discipline Participants Information

The Remote Method

The Result JSON Schema

eventDisciplineDataImport

club

Fields

Unique identification

Dependencies

Schema

member

Fields

Unique identification

Dependencies

Schema

group

Fields

Unique identification

Dependencies

Schema

team

Fields

Dependencies

Schema

category

Fields

Unique identification

Dependencies

Schema

participation

Fields

Unique identification

Dependencies

Schema

teamParticipation

Fields

Dependencies

Schema

session

Fields

Unique identification

Dependencies

Schema

order

Fields

Dependencies

Schema