Skip to main content

Events

Updated

Events

Events represent scheduled training events in the system.

Search

The following example fetches the first page of events starting on or after 1st May 2023 at 00:00 UTC, sorted by code and start time (ascending):

query EventsOnDate {
  events(
    filters:[
       {field: timeZonedStart, operation: ge, value: "2023-05-01T00:00:00Z"}
    ]
    orderBy: [
      {field: code, direction: asc}
      {field: timeZonedStart, direction: asc}
    ]
  ) {
    edges{
      node{
        id
        code
        title
        learningMode
        start
        end
      }
    }
  }
}

For the full range of available filters see the EventField API Reference.

Create

The following example creates a new LMS event for the specified course templates, location, tax type, start and end times:

mutation CreateEventFromTemplate {
  event{
    createLMS(input:{
      courseTemplateId:"Q291cnNlVGVtcGxhdGU6MTE="
      eventType: public
      timeZonedLmsStart: "2023-01-05T09:00:00-05:00"
      timeZonedLmsEnd: "2023-01-05T18:00:00-05:00"
      timeZoneName: "America/New_York"
      locationId: "TG9jYXRpb246NzY="
      taxTypeId:"VGF4VHlwZTox"
    }) {
      event{
        id
        lifecycleState
        timeZonedStart
        timeZonedEnd
      }
      errors{
        label
        message
        value
      }
    }
  }
}

The response shows the new event's lifecycleState is draft:

{
  "data": {
    "event": {
      "createLMS": {
        "event": {
          "id": "Q291cnNlOjE=",
          "lifecycleState": "draft",
          "timeZonedStart": "2023-01-05T14:00:00Z",
          "timeZonedEnd": "2023-01-05T23:00:00Z"
        },
        "errors": []
      }
    }
  }
}

You can also set a default price and Custom Field values as part of the same creation call, rather than in follow-up mutations. defaultPrice selects which of the course template's price levels becomes the event's default, by Financial Unit and Price Level:

mutation CreateEventWithDefaults {
  event{
    createLMS(input:{
      courseTemplateId:"Q291cnNlVGVtcGxhdGU6MTE="
      eventType: public
      timeZonedLmsStart: "2023-01-05T09:00:00-05:00"
      timeZonedLmsEnd: "2023-01-05T18:00:00-05:00"
      timeZoneName: "America/New_York"
      locationId: "TG9jYXRpb246NzY="
      taxTypeId:"VGF4VHlwZTox"
      defaultPrice: {financialUnitId: "GBP", priceLevelId: "UHJpY2VMZXZlbDox"}
      customFieldValues: [{definitionKey: "Q3VzdG9tRmllbGREZWZpbml0aW9uOjE1Nw==", value: "Thursday"}]
    }) {
      event{ id }
      errors{ label message value }
    }
  }
}

Duplicate

An existing Event can be duplicated to a new start date with the duplicate mutation:

mutation DuplicateEvent {
  event{
    duplicate(
      eventId: "Q291cnNlOjE="
      input: {
        newStartDate: "2023-06-01T09:00:00"
        timeZoneName: "America/New_York"
      }
    ) {
      event{ id timeZonedStart }
      errors{ label message value }
    }
  }
}

Update

For the full range of available update parameters see the EventUpdateInput API Reference.

Publish

To publish an Event, update its lifecycleState field:

mutation PublishEvent {
  event{
    update(
      eventId: "Q291cnNlOjE="
      input:{
        lifecycleState: published
      }
    ) {
      event{
        id
        lifecycleState
      }
      errors{
        label
        message
        value
      }
    }
  }
}

Cancel

Similarly, to cancel an event update it to cancelled:

mutation CancelEvent{
  event{
    update(
      eventId: "Q291cnNlOjE="
      input:{
        lifecycleState: cancelled
      }
    ) {
      event{
        id
        lifecycleState
      }
      errors{
        label
        message
        value
      }
    }
  }
}

Cancelling an Event also cancels its Sessions, so they do not need to be cancelled individually.

Sessions

Sessions belonging to an Event can be deleted in bulk with the session.delete mutation. Sessions with assigned learners (or non-existent session IDs) will return an error:

mutation DeleteSessions {
  session{
    delete(input: {sessionIds: ["U2Vzc2lvbjox", "U2Vzc2lvbjoy"]}) {
      errors{ label message value }
    }
  }
}

Learners

Registration

Learners can be added to a published event by associating them with a Contact in your TMS: 

 mutation AddLearner {
  event{
    registerContacts(
      eventId:"Q291cnNlOjE="
      input:{
        contacts:[
          "UGVyc29uOjM1",
          "UGVyc29uOjM="
        ]
      }
    ) {
      event{
        id
        learners(orderBy:[{field: id, direction: desc}]){
          edges{
            node{
              id
              contact{
                id
                personalName{
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

The response from the above example will show the most recent learners (ordered by descending ID) and their requested details:

{
  "data": {
    "event": {
      "registerContacts": {
        "event": {
          "id": "Q291cnNlOjE=",
          "learners": {
            "edges": [
              {
                "node": {
                  "id": "bGVhcm5lcjoy",
                  "contact": {
                    "id": "UGVyc29uOjM=",
                    "personalName": {
                      "name": "Jane Smith"
                    }
                  }
                }
              },
              {
                "node": {
                  "id": "bGVhcm5lcjox",
                  "contact": {
                    "id": "UGVyc29uOjM1",
                    "personalName": {
                      "name": "Mary Green"
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

The event.registerContacts mutation also accepts pricing and administrative options in the same call:

  • priceLevelId applies a Price Level to the Learner so registrations show the level's pricing rather than "Custom". It requires financialUnitId (a Currency or Token Type ID), and if amount is not provided it is set to the level's price.
  • orderDate sets the Order date on the Registration, useful when importing historical data. The order date can also be changed later through the registration.update mutation.
  • communicationsContactId nominates a Contact to receive all communications relating to these registrations.
  • expiresAt sets when LMS access for the Learner expires, and brandId overrides the brand on the new registration.
mutation AddLearnerWithOptions {
  event{
    registerContacts(
      eventId:"Q291cnNlOjE="
      input:{
        contacts:["UGVyc29uOjM1"]
        financialUnitId: "GBP"
        priceLevelId: "UHJpY2VMZXZlbDox"
        orderDate: "2023-04-01T09:00:00Z"
        communicationsContactId: "UGVyc29uOjM="
      }
    ) {
      event{ id }
      errors{ label message value }
    }
  }
}

For the full range of named learner registration options (including price specifications) see the EventRegisterContacts API Reference.

Progress

Learner progress on an Event is handled by our LMS API

Events can be set up to automatically mark a Learner as "passed" on completion of all relevant content. Moreover, automatic achievement awarding can be configured. For more information, see our Support Documentation

You can manually record completion of an Event with the following:

mutation RecordCompletion {
  learner{
    recordResult(
      learnerId: "bGVhcm5lcjoy"
      hasPassed: true
    ) {
      learner{
        id
        hasPassed
      }
      errors{
        label
        message
        value
      }
    }
  }
}

You can also optionally override any achievements you wish to award or prevent:

mutation OverrideAchievements {
  learner{
    recordResultWithAchievements(
      input:{
        learnerId: "bGVhcm5lcjoy"
        hasPassed: true
        manualAchievements:[
          {
            achievementTypeId: "QWNoaWV2ZW1lbnRUeXBlOjE="
            achieved: true
          }
        ]
      }
    ) {
      learner{
        id
        hasPassed
      }
      errors{
        label
        message
        value
      }
    }
  }
}

Related articles