Create a training path

This endpoint allows creating a training path in the business catalog, grouping several courses and defining the schedule of all their trainings.

POST /api/v2/businesses/{businessId}/training-paths

Below is a detailed explanation of each of the fields that can make up the request body, with some being mandatory for the request to be successful.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "id": "string",
  "name": "string",
  "description": "string",
  "abbreviation": "string",
  "color": "string",
  "courseIds": [
    "string"
  ],
  "trainingsOrder": [
    {
      "trainingId": "string",
      "day": 0,
      "order": 0
    }
  ]
}
Details

  • id: external identifier of the training path. If it is not provided when creating the training path, Orquest generates one automatically.

  • name*: name of the training path. Maximum 50 characters.

  • description: description of the training path. Maximum 500 characters.

  • abbreviation*: abbreviation of the training path. Maximum 5 characters.

  • color*: color used to represent the training path, in hexadecimal format (for example, #1F7A5A).

  • courseIds*: list of external identifiers of the courses that make up the training path, in the order in which they must be taken. It must contain at least one course and cannot repeat courses.

  • trainingsOrder: schedule of all the trainings of the training path. If it is not provided, Orquest calculates it automatically. For each training, the following information is included:

    • trainingId*: external identifier of the training. It must belong to one of the courses of the training path.

    • day*: day of the training path on which the training takes place. It is a relative value starting at 1, the start day of the training path.

    • order*: order of the training within its day.

Request example

Once the analysis of the different fields has been done, an example of the request is shown:

POST /api/v2/businesses/BUSINESSID/training-paths
{
    "id": "TP-RES",
    "name": "Shift manager",
    "abbreviation": "RES",
    "color": "#C3AAFC",
    "description": "Full path: store, sales, cash register and closing",
    "courseIds": [
        "CRS-BTI",
        "CRS-VAC",
        "CRS-CAJ",
        "CRS-CIE"
    ]
}

If the request is correct, the response will be a 201 Created with the created training path.

Considerations

The trainingsOrder field defines on which day of the training path and in which order each training of its courses takes place. If provided, it must meet the following conditions:

  • It must include exactly all the trainings of all the courses of the training path, without repeating any.

  • It must respect the internal order of each course. Trainings from different courses can be interleaved.

If trainingsOrder is not provided, Orquest calculates the schedule automatically: courses are chained in the order of courseIds given in the request body and each one starts the day after the previous course.

All the identifiers in the request (courses and trainings) are external identifiers and must exist in the business.

If the id of the training path is not provided, Orquest generates an identifier automatically and returns it in the response.

The request is not idempotent: if it is repeated with the same id, it will return a conflict error; if it is repeated without id, a new training path will be created on each call.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

404 Not Found

Course not found: <courseId>

One of the courses in courseIds does not exist in the business.

Training not found in the training path courses: <training>

One of the trainings in trainingsOrder does not belong to the courses of the training path.

400 Bad Request

At least one course is required

The courseIds field was not provided or is empty.

One or more courses not found

The courseIds field contains repeated courses.

Name cannot be longer than 50 characters

The name field exceeds 50 characters.

Description cannot be longer than 500 characters

The description field exceeds 500 characters.

Abbreviation cannot be longer than 5 characters

The abbreviation field exceeds 5 characters.

-

The color field is not a valid hexadecimal color.

Training path order contains duplicate training ids

The trainingsOrder field contains repeated trainings.

Training path order must contain exactly all trainings from all courses, no more and no less

The trainingsOrder field does not include all the trainings of the courses of the training path, or it was sent empty.

Training path order does not respect the internal order of course

The schedule in trainingsOrder changes the order of the trainings of one of the courses.

409 Conflict

The request conflicts with data already stored

A training path with the given id already exists in the business.

Useful links

What is a training path?

What is a course?