Jobs API

Introduction

The Jobs API covers several sub-APIs, including:

Getting access to the API

The Jobs API is enabled globally by default, and can be disabled with the JOBS_API config option set to false.

It is fully accessible to all the clients which have the jobs/all permission enabled.

The API endpoints rely on the base endpoint of each client. In this documentation, we will designate the base endpoint by <base-endpoint>. To get the base endpoint of a client:

  • Go to the Access > API Consumers > Clients page.
  • Click on the (i) icon of a client.
  • The endpoint is indicated next to the Base endpoint label.

The API endpoints also rely on the type of job. In this documentation, we will designate type of job by <type>. The type is given for each API in the documentation below.

Common features

Creating a job

Use the POST method on <base-endpoint>/jobs/<type> with the following JSON props:

Param Description
replay Optional boolean. Set to true to (re)start the job as soon as possible.
repeat Required string: now, on, everyMinute, hourlyAt, dailyAt, weeklyOn, monthlyOn, yearlyOn. Its value has an impact on the following params.
date ISO 8601 date
time String: now or time with the HH:MM format.
minute Int between 0 and 59.
week_day Int between 1 and 7.
month_day Int between 1 and 31.
month Int between 1 and 12.

When repeat has the value:

  • now: the date, time, minute, week_day, month_day, month are ignored.
  • on: the date param must be defined.
  • everyMinute: the date, time, minute, week_day, month_day, month are ignored.
  • hourlyAt: the minute param must be defined.
  • dailyAt: the time param must be defined.
  • weeklyOn: the time and week_day params must be defined.
  • monthlyOn: the time and month_day params must be defined.
  • yearlyOn: the time, month_day and month params must be defined.

Updating a job

Use the PUT method on <base-endpoint>/jobs/<type>/<job-id> with the same above content.

Getting the jobs

Use the GET method on <base-endpoint>/jobs/<type> with the following params:

Param Description
store Optional. The slug of a store.
service Optional. The slug of a store.

Getting a job

Use the GET method on <base-endpoint>/jobs/<type>/<job-id>.

Deleting the jobs

Use the DELETE method on <base-endpoint>/jobs/<type>.

Deleting a job

Use the DELETE method on <base-endpoint>/jobs/<type>/<job-id>.

Getting the job logs

Use the GET method on <base-endpoint>/jobs/<type>/<job-id>/logs.

Statements Validation API

The <type> for this API is validation. Creating and updating jobs accept the following specific params:

Param Description
clear Required boolean. Set to true in order to delete invalid statements.
store Optional slug of a store. When omitted, a job is created for each available store.

Statements Pseudonymization API

The <type> for this API is pseudo. Creating and updating jobs accept the following specific params:

Param Description
until Required string: now, date, 1_hour, 1_day, 1_week, 1_month, 1_year.
until_date ISO 8601 date. Must be defined when until has the value date.
store Optional slug of a store. When omitted, a job is created for each available store.

Data Pulling API

The <type> for this API is pull. Creating and updating jobs accept the following specific params:

Param Description
service Required string: all, statements, activities, activity-profiles, agents, agent-profiles, states
until Required string: now, date, 1_hour, 1_day, 1_week, 1_month, 1_year.
until_date ISO 8601 date. Must be defined when until has the value date.
connection Required. Internal ID of a connection.
validate_statements Boolean. Check the xAPI pipeline options.
check_conflicts Boolean. Check the xAPI pipeline options.
void_statements Boolean. Check the xAPI pipeline options.
update_activities Boolean. Check the xAPI pipeline options.
update_agents Boolean. Check the xAPI pipeline options.
update_vocab Boolean. Check the xAPI pipeline options.
update_activity_ids Boolean. Check the xAPI pipeline options.
update_agent_ids Boolean. Check the xAPI pipeline options.
authority_name String. name of the authority. Check the xAPI pipeline options.
authority_homepage URL. homePage of the authority. Check the xAPI pipeline options.
store Required slug of a store.

Data Pushing API

The <type> for this API is push. Creating and updating jobs accept the following specific params:

Param Description
service Required string: all, statements, activities, activity-profiles, agents, agent-profiles, states
until Required string: now, date, 1_hour, 1_day, 1_week, 1_month, 1_year.
until_date ISO 8601 date. Must be defined when until has the value date.
connection Required. Internal ID of a connection.
raw Boolean. When set to true, export only the statements raw definition.
sync_updates Boolean. When set to true, use the updated timestamp (not the stored timestamp) to synchronize data.
pseudonymize_statements Boolean. Check the xAPI pipeline options.
store Required slug of a store.

Data Clearing API

The <type> for this API is clearing. Creating and updating jobs accept the following specific params:

Param Description
service Required string: all, statements, activities, agents, activity-profiles, agent-profiles, states.
until Required string: now, date, 1_hour, 1_day, 1_week, 1_month, 1_year.
until_date ISO 8601 date. Must be defined when until has the value date.
store Optional slug of a store. When omitted, a job is created for each available store.

Agent Deletion API

The <type> for this API is agent-deletion. Creating and updating jobs accept the following specific params:

Param Description
agent Required. JSON encoded xAPI agent.
person Required boolean. When set to true, all the agents of this person are deleted.
store Optional slug of a store. When omitted, a job is created for each available store.

Data Seeding API

The <type> for this API is seeding. Creating and updating jobs accept the following specific params:

Param Description
config Optional string. Name of the config file to be used.
store Required slug of a store.

Conformance Testing API

The <type> for this API is testsuite. Creating and updating jobs accept the following specific params:

Param Description
section Optional string. The xAPI section to be checked.
store Required slug of a store.
client Required slug of a client.

Logs Deletion API

The <type> for this API is logs-deletion. Creating and updating jobs accept the following specific params:

Param Description
max_level Required int: 0 (debug), 1 (info), 2 (notice), 3 (warning), 4 (error), 5 (critical), 6 (alert), 7 (emergency). Logs up to this level are deleted.
until Required string: now, date, 1_hour, 1_day, 1_week, 1_month, 1_year.
until_date ISO 8601 date. Must be defined when until has the value date.
store Optional slug of a store.

Stores Deletion API

The <type> for this API is stores-deletion. Creating and updating jobs accept the following specific params:

Param Description
store_id The internal ID of a store.

CMI5 tokens Deletion API

The <type> for this API is cmi5-tokens-deletion. Creating and updating jobs accept the following specific params:

Param Description
until Required string: now, 1_hour, 1_day, 1_week.
store Optional slug of a store.