Update a course

This endpoint allows updating the full definition of a course in the catalog, including its list of trainings.

PUT /api/v2/businesses/{businessId}/courses/{courseId}

The courseId is the external identifier of the course to be updated.

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:

PUT /api/v2/businesses/BUSINESSID/courses/CRS-CAJ
{
    "name": "Cash register",
    "description": "Payment methods, POS operation, cash count and refunds",
    "abbreviation": "CAJ",
    "color": "#F7C2E5",
    "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": "PT4H",
            "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 200 OK with the resulting course, with the same structure returned by Get course information.

Considerations

The request replaces the whole definition of the course: fields that are not sent are left empty or with their default value. The id in the body is ignored and the course keeps the identifier given in the URL.

Trainings are identified by their id:

  • Trainings with an existing id are updated.

  • New trainings, or trainings without id, are created.

  • Existing trainings that are not included in the request are removed from the course.

Course versioning

Some changes modify the structure of the course: adding or removing trainings, changing the day or order of any of them, or changing the tasks in unlockCatalogLocationIds.

If the course is already assigned to any employee and the change is structural, Orquest keeps the previous definition for the existing assignments and applies the new definition only to assignments created from that moment on. The course keeps its external identifier and the API always returns the current version.

Courses that have this course as a requirement and training paths that include it automatically switch to the updated current version.

A course cannot be a requirement of itself, either directly or indirectly through other courses.

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>

The courseId in the URL, or 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.

Requirement loop detected for course with id […​]

The given requirements create a loop, for example, because the course is a requirement of itself.

Useful links

What is a course?

What is a training path?