Creates and adds a new Activity Instance to a Learning Plan Instance, or returns an existing Activity Instance.

Commonly used to report attendance or work history to a Practitioner’s application.

To bulk load Activity Instance data, see API/WorkflowImportQueue/CreateBatch

Overview

Accepts as input an Activity Number, a Learning Plan Instance Id, and a Task Group identifier.

If a matching Activity Instance exists, it is returned. Otherwise, a new one is automatically created.

When a new one is created, it is functionally equivalent to an end user clicking the “Add Activity” button on a Learning Plan Task Group.

If more than matching Activity Instance records are found, or if the new instance cannot be created, an error is returned.

Calling the API

This is not a REST-style API, it is a GET request that has potential side effects.

Authentication

Requires an API Key with the GET_OR_CREATE_ACTIVITY_INSTANCE permission.

Request

GET /API/ActivityInstance/GetOrCreate
?ActivityNumber=<string>
&LearningPlanInstanceId=<int>
&TaskGroupId=<int>
&TaskGroupTitle=<string>

Querystring Parameter	Description

Querystring Parameter	Description
`ActivityNumber`	Required: Identifier for the `ActivityDefinition` to add
`LearningPlanInstanceId`	Required: Identifier for the `LearningPlanInstance` to add it to. (Can be retrieved using API/LearningPlanInstance/GetOrCreate ).
`TaskGroupId` or `TaskGroupTitle`	Required: Identifier for the Task Group to add to You must provide one of these values, but not both.

Response

If successful:

{
  "success": true,
  "ActivityInstanceId": {int},
  "WorkflowInstanceId": {int}
}

If unsuccessful:

{
  "success": false,
  "errors": [array of strings]
}

Error Messages

Error Message	Cause / How to resolve
ActivityNumber is required.	Provide a value for `ActivityNumber` in the querystring
Only one of TaskGroupId or TaskGroupTitle should be specified, not both	Only one of these values should be provided, not both.
TaskGroupId or TaskGroupTitle is required	Either `TaskGroupID` or `TaskGroupTitle` must be provided
There was more than one Task Group on LearningPlanInstance #{x} with the ID# {y}	The Learning Plan Instance provided contains multiple Task Groups with the same Task Group ID. Open a support ticket; this should not happen under normal usage.
There was more than one Task Group on LearningPlanInstance #{x} with title {y}	The Learning Plan Instance provided contains multiple Task Groups with the same Task Group Title. Pass `TaskGroupId` instead.
There was no Task Group #{x} found on LearningPlanInstance #{y}	The Learning Plan Instance does not contain a Task Group with the specified details.
There was no Task Group named {x} found on LearningPlanInstance #{y}	The Learning Plan Instance does not contain a Task Group with the specified details. Check your spelling, or use `TaskGroupId` instead.
Learning Plan Instance ID #{x} not found.	The Learning Plan Instance ID is invalid.
Activity {x} not found.	The Activity Number does not match any published activities in LearningBuilder.
Activity {x} cannot be added to the Task Group {y}	The specified Activity Number cannot be added to the specified Task Group due to its configuration.
There are multiple <ActivityNumber> activities in Task Group <TaskGroupTitle>	The Learning Plan Instance contains more than one incomplete Activity matching the Activity Number. This API does not support retrieving Activity Instance data in this scenario.

LearningBuilder Documentation

API/ActivityInstance/GetOrCreate