ScoreExpress Docs

Appearance

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. In order 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 in order 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.

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

  1. 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.
  2. the second to provide the data from a selected eventDiscipline.

The specific details of 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, 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 code of the country 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"
      }
    ]
  }
]

Copyright © 2025 A Double