Create a course

This endpoint allows creating a course in the business catalog, together with all its trainings.

POST /api/v2/businesses/{businessId}/courses

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",
  "expiresAfter": "string",
  "requirementIds": [
    "string"
  ],
  "unlockCatalogLocationIds": [
    "string"
  ],
  "trainings": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "day": 0,
      "order": 0,
      "duration": "string",
      "needsTrainer": false,
      "needsValidation": false,
      "coverCatalogLocationId": "string"
    }
  ]
}
Details

  • id: external identifier of the course. If it is not provided when creating the course, Orquest generates one automatically. When updating a course, it is ignored and the identifier in the URL is kept.

  • name*: name of the course. Maximum 50 characters.

  • description: description of the course. Maximum 500 characters.

  • abbreviation*: abbreviation of the course. Maximum 3 characters.

  • color*: color used to represent the course, in hexadecimal format (for example, #4338CA).

  • expiresAfter: validity period of the course approval, in ISO-8601 format (for example, P1Y for one year or P6M for six months). If it is not provided, the approval does not expire.

  • requirementIds: list of external identifiers of the courses that the employee must have passed and in force before the result of this course can be recorded.

  • unlockCatalogLocationIds: list of external identifiers of the tasks from the task catalog that the course enables once passed.

  • trainings: list of trainings that make up the course. For each training, the following information is included:

    • id: external identifier of the training. It must be unique within the course. If it is not provided, Orquest generates one automatically.

    • name*: name of the training.

    • description: description of the training.

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

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

    • duration*: duration of the training, in ISO-8601 format (for example, PT2H for two hours or PT90M for ninety minutes). It cannot exceed one day.

    • needsTrainer: indicates whether the training requires a trainer. Defaults to false.

    • needsValidation: indicates whether the training is assessed. If true, the result of the training is passed or failed; if false, only attendance is recorded. Defaults to false.

    • coverCatalogLocationId: external identifier of the catalog task that the employee covers while attending the training.

Request example

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

POST /api/v2/businesses/BUSINESSID/courses
{
    "id": "CRS-CAJ",
    "name": "Cash register",
    "abbreviation": "CAJ",
    "color": "#F7C2E5",
    "description": "Payment methods, POS operation and cash count",
    "expiresAfter": "P1Y",
    "requirementIds": [
        "CRS-VAC"
    ],
    "unlockCatalogLocationIds": [
        "000001"
    ],
    "trainings": [
        {
            "id": "TRN-CAJ-NOR",
            "name": "Cash register rules and payment methods",
            "day": 1,
            "order": 1,
            "duration": "PT1H",
            "needsTrainer": false,
            "needsValidation": false
        },
        {
            "id": "TRN-CAJ-TPV",
            "name": "POS operation",
            "day": 1,
            "order": 2,
            "duration": "PT3H",
            "needsTrainer": true,
            "needsValidation": false,
            "coverCatalogLocationId": "000001"
        },
        {
            "id": "TRN-CAJ-ARQ",
            "name": "Cash count and reconciliation",
            "day": 2,
            "order": 1,
            "duration": "PT1H",
            "needsTrainer": true,
            "needsValidation": true
        }
    ]
}

If the request is correct, the response will be a 201 Created with the information of the created course.

Considerations

The request is atomic: the course and all its trainings are created together or nothing is created.

All the identifiers in the request are external identifiers and must exist in the business for the request to be valid.

If the id of the course or of any of its trainings 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 course with a random external identifier 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 requirementIds does not exist in the business.

Catalog location not found: <locationId>

One of the tasks in unlockCatalogLocationIds or in coverCatalogLocationId does not exist in the business catalog.

400 Bad Request

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 3 characters

The abbreviation field exceeds 3 characters.

For input string: <color> under radix 16

The color field is not a valid hexadecimal color.

training name is required

A training has no name.

training day is required / training day must be greater than 0

A training has no day or its value is lower than 1.

training order is required

A training has no order.

training duration is required / Duration cannot be longer than 1 day

A training has no duration or its duration exceeds one day.

Duplicated training outerId in course trainings

Several trainings have the same id within the course.

409 Conflict

The request conflicts with data already stored

A course with the given id already exists in the business.

Useful links

What is a course?

What is a task?