Activities

Last updated: 11 Jul 2024

Integrate with PageUp's Learning Activities API to create and modify the activities your employees will complete.

Contents

  1. Before you begin
  2. Examples
  3. Validation responses

Before you begin

To begin using the Learning Activities API, there are a few things that you will need:

  1. The default activityType.id that will be assigned to activities you create
  2. The default owner.id that will be assigned to activities you create This information will be provided to you as part of a welcome email when you register for API credentials.

Examples

Please note, required fields activityType and owner, require id values that will be provided to you as part of a welcome email.

Creating an activity

The below is an example of how you can create a basic learning activity for your client. Fields that are required include: activityType, owner, accessLevel, title. Other fields provided in the example below are optional. For a full list of what fields are available, please refer to the API specifications below.

Request
PUT /v3/:clientId/learning/activities/externalId/:externalId
{
	"activityType": {
		"id": 1234
	},
	"owner": {
		"id": 1234
	},
	"accessLevel": "orgwide",
	"title": "Sample activity title",
	"description": "A sample description about the activity",
	"code": "EXT001",
	"content": {
		"type": "text",
		"text": "Content relating to the activity. Eg: Content from an online article."
	},
	"duration": {
		"duration": 10,
		"durationPeriod": "Minutes"
	},
	"costs": {
		"currency": {
			"code": "AUD"
		},
		"attendenceCost": 100.50
	}
}
Response
201 Created
{
    "id": 1234,
    "aggregateId": 3ac54c3f-903d-4403-8a1c-9ac81e9bd8db
    "url": "v3/456/learning/activities/externalId/ABCDE-01"
}

Updating an activity

Updating information against a learning activity can involve updating the existing values to new values, or you may wish to completely remove the existing value. Information on how to achieve both is outlined below. When updating information against an activity, you are only required to provide the fields you are updating, omitted fields indicate that their existing value will remain unchanged.

Changing values

Request
PUT /v3/:clientId/learning/activities/externalId/:externalId/
{
	"description": "An updated description for the sample activity.",
	"code": "CHG002"
}
Response
200 OK

Removing values

Request
PUT /v3/:clientId/learning/activities/externalId/:externalId/
{
	"code": null
}
Response
200 OK

Archiving an activity

If an existing learning activity is no longer required to be displayed within the organisation's learning library, the activity can be archived by sending through the below request for the nominated activity.

Archive one
Request
PUT /v3/:clientId/learning/activities/externalId/:externalId/
{
	"isArchived": true
}
Response
200 OK

The following fields are not required for activities, but can be useful to have.

Field Description
Code Only applicable if creating orgwide activities. Used in reporting and some bulk actions, a unique code helps identify this activity.
Description A short description makes it much easier for learners to find and understand the course they're signing up for.
Image Hero images make the library a more colourful and enjoyable experience to navigate.

Validation responses

When integrating with the Learning Activities API, you may receive a validation message in your response. Below is a non-exhaustive list of responses and what they mean.

Responses
Message Description
Cannot change access level from org-wide The activity you are attempting to edit currently has an access level of orgwide. Due to functionality differences between orgwide and public or private activities, we do not allow orgwide activities to have their accessLevel changed.
Cannot change access level to org-wide The activity you are attempting to edit currently has an access level of public or private. Due to functionality differences between public or private and orgwide, we do not allow public or private activities to have their accessLevel changed to orgwide.
Cannot change Aggregate ID for an existing activity The activity you are attempting to edit has an Aggregate ID that is different from the one you have provided. As the Aggregate ID is used to uniquely reference an activity, it cannot be changed once it has been set on creation.
Child activity would create a circular reference An activity or its child-activities you have specified reference themselves, creating a circular reference. Please remove or change the child activities specified as required.
If cost is supplied then currency code also needs to be supplied If you have specified activity costs (attendenceCost, cancellationCost, otherCost) then a currency code eg: AUD must also be supplied.
If currency code is supplied at least one cost also needs to be supplied If you have specified a currency.code value then you must supply a valid activity cost (attendenceCost, cancellationCost, otherCost)
Invalid access level for content type Only some accessLevel options can take advantage of certain content types. A private or public activity can only use a text or weblink based content type, whilst other content types (eg. scormcourse) are available to orgwide activities.
Field is invalid for access level The specified field cannot be used for the activities current accessLevel. Only some activity fields are available to be used for certain activity access levels. Eg. An orgwide activity has access to all fields, but public or private activities can only access limited fields.
Image does not exist The image key value specified in image.tempKey does not currently exist in temporary storage and therefore cannot be attached to an Activity. Validate that an image has recently been uploaded using the Image API and try again.