workshops-catalog.md

Workshop catalog

A single training portal can hosted one or more workshops. The REST API endpoints for the workshops catalog provide a means to list the available workshops and get information about them.

Listing available workshops

The URL sub path for accessing the list of available workshop environments is /workshops/catalog/environments/. When making the request, you must supply the access token in the HTTP Authorization header with type set as Bearer:

curl -v -H "Authorization: Bearer <access-token>" \
<training-portal-url>/workshops/catalog/environments/

The JSON response is of the form:

{
  "portal": {
    "name": "learningcenter-tutorials",
    "uid": "9b82a7b1-97db-4333-962c-97be6b5d7ee0",
    "generation": 451,
    "url": "<training_portal_url>",
    "sessions": {
      "maximum": 10,
      "registered": 0,
      "anonymous": 0,
      "allocated": 0
    }
  },
  "environments": [
    {
      "name": "learningcenter-tutorials-w01",
      "state": "RUNNING",
      "workshop": {
        "name": "lab-et-self-guided-tour",
        "id": "15e5f1a569496f335049bb00c370ee20",
        "title": "Workshop Building Tutorial",
        "description": "A guided tour of how to build a workshop for your team's learning center.",
        "vendor": "",
        "authors": [],
        "difficulty": "",
        "duration": "",
        "tags": [],
        "logo": "",
        "url": "<workshop_repository_url>"
      },
      "duration": 1800,
      "capacity": 10,
      "reserved": 0,
      "allocated": 0,
      "available": 0
    }
  ]
}

For each workshop listed under environments, where a field listed under workshop has the same name as it appears in the Workshop custom resource, it has the same meaning. The id field is an additional field which can uniquely identify a workshop based on the name of the workshop image, the Git repository for the workshop, or the website hosting the workshop instructions. The value of the id field does not rely on the name of the Workshop resource and must be the same if the same workshop details are used but the name of the Workshop resource is different.

The duration field provides the time in seconds after which the workshop environment expires. The value is null if there is no expiration time for the workshop.

The capacity field is the maximum number of workshop sessions that you can create for the workshop.

The reserved field indicates how many instances of the workshop are reserved as hot spares. These are used to service requests for a workshop session. If no reserved instances are available and capacity has not been reached, a new workshop session is created on demand.

The allocated field indicates how many workshop sessions are active and currently allocated to a user.

The available field indicates how many workshop sessions are available for immediate allocation. This is never more than the number of reserved instances.

Under portal.sessions, the allocated field indicates the total number of allocated sessions across all workshops hosted by the portal.

Where maximum, registered, and anonymous are nonzero, they are the limit on the number of workshops run.

• The maximum is the total number of workshop sessions that can be run by the portal across all workshops. If allocated for the whole portal has reached maximum, no more workshop sessions are created.

• The value of registered when nonzero indicates a cap on the number of workshop sessions a single registered portal user can have running at the one time.

• The value of anonymous when nonzero indicates a cap on the number of workshop sessions an anonymous user can have running at the one time. Anonymous users are users created as a result of the REST API being used or if anonymous access is enabled when the user accesses the portal through the web interface.

By default, only workshop environments currently marked with a state of RUNNING are returned, that is, those workshop environments which are taking new workshop session requests. If you also want to see the workshop environments which are currently in the process of being shut down, you must provide the state query string parameter to the REST API call and indicate which states workshop environments to return for.

curl -v -H "Authorization: Bearer <access-token>" \
https://lab-markdown-sample-ui.test/workshops/catalog/environments/?state=RUNNING&state=STOPPING

You can include the state query string parameter more than once to see workshop environments in both RUNNING and STOPPING states.

If anonymous access to the list of workshop environments is enabled and you are not authenticated when using the REST API endpoint, only workshop environments in a running state are returned.