Custom Data Sources

Introduction

IC Robotic makes it easy to integrate your data with our platform in order to write templates based on live data directly in our editor.

In order to do so, all you need is to implement two endpoints: One for searching your data subjects (Search Endpoint), and one for getting the actual data (Data Endpoint). For instance, if you were to write about soccer games, you would search for actual matches, and return a list of matches based on the search term. When an match in the results is selected you would retrieve the data for that specific game.

Currently, we only support authentication provided as queryparameters.

Once you've set up your endpoints, contact us to have your custom data source set up.

The Search Endpoint

This endpoint takes query, and returns a list of Content References, which must look like this:

[{
    "Id": "123102387", // String
    "ReferenceName": "Real Madrid 1 - 2 Barcelona", // Display name
    "ReferenceDescription": "Location: Santiago Bernabéu", // Optional description
    "Time": "2020-01-01T00:00:00" // Optional time
}]

The endpoint must return a JSON List/array of these, and must take a query parameter named query which is the search string, as well as an optional page and pagesize, for example like this:

https://mysoccerservice.com?query=Barcelona&page=1&pageSize=10

The Data Endpoint

Once we have found a subject to write about, we need to retrieve the data. This is done using the Data Endpoint, which takes an Id and returns a list of Variables, like so:

[
    { ..variable 1.. },
    { ..variable 2.. },
    ..etc.,
]

Variables are pretty straight forward; they have a Type, a Name, a Value, and an optional Description.

The data endpoint takes a queryparameter named id, which is the id returned from the search endpoint:

https://mysoccerservice.com?id=123102387

Metadata

It's possible to include some metadata, which will be passed on when generating content. To do so, include the metadata as follows:

{
    "Metadata": (insert any valid json object here),
    "Variables": [.. your variables..]
}

The metadata will then be included in the response of the generation endpoint, as a property named Metadata.

Variable Types

The platform supports variables of type Text, Number, Date, List and Bool.

Text

A text variable contains basic text.

{
    "Type": "Text",
    "Name": "Hometeamname",
    "Description": "Name of the home team",
    "Value": "Barcelona"
}

Number

Contains a number in the form of a decimal (any number you write will be treated as a decimal).

{
    "Type": "Number",
    "Name": "Hometeamgoals",
    "Description": "Amount of hometeam goals",
    "Value": 3
}

Date

A DateTime of the format yyyy-MM-ddTHH:mm:ss.

{
    "Type": "Date",
    "Name": "Matchdate",
    "Description": "Date of the match",
    "Value": "2020-01-01T18:00:00"
}

List

Contains a json-array of Text.

{
    "Type": "List",
    "Name": "Goalscorers",
    "Description": "Players who scored a goal",
    "Value": ["Lional Messi", "Ansu Fati", "Eden Hazard"]
}

Note that the templating language allows you to do operations on your data, so on lists you can do things such as count the number of items, format the items in a specific way, or do set-operations such as union or intersect, which means you often dont need to supply specific variables such as "amount of goalscorers" or "Goalscorer first names". These can be handled by the templating language.

Bool

Contains a boolean value (true/false).

{
    "Type": "Bool",
    "Name": "Hometeamwin",
    "Description": "Whether the hometeam won",
    "Value": false,
}

Variable Names

To organize your variables when using the editor, we will treat underscores (_) as groupings. This means that if you specify the name teams_hometeam_name, this will group all variables that start with teams, then all that start with hometeam, and finally the last part of the name will be treated as the name of the variable.

Note that internally all names of variables start with { and end with }, but you do not have to add that in your naming, as we will add it for you.

Supported characters beside underscores are letters, numbers, and dashes (-).