API/ActivityInstance/GetOrCreate

Owned by Seth Petry-Johnson
Last updated: Nov 14, 2024 by Edwing Arana
3 min read

Summary

Given an Activity Number and a Task Group identifier, returns information about the matching Activity Instance. If no Activity Instance is found, a new one is automatically created. The new record is functionally equivalent to an Activity Instance created by an end user via the "Add Activity" button on a Learning Plan Task Group.

If more than 1 matching Activity Instance record is found, or if a new instance cannot be created, an error is returned.

Overview

Given an Activity Number and a Task Group identifier, returns information about the matching Activity Instance. If no Activity Instance is found, a new one is automatically created. (This new record is functionally equivalent to the one created by an end user clicking the Add Activity button on the Task Group).

This is useful when you want to update an existing Activity Instance, if one exists, or create a new one. This API method avoids the need for you to check for existence and conditionally create a new record manually.
 
If more than matching Activity Instance records are found, or if the new instance cannot be created, an error is returned.

Request:
The following arguments are expected in the query string:

ParameterDescription
ActivityNumberRequired - ID label of an activity
LearningPlanInstanceId

Required - ID number of a learning plan instance; normally retrieved using the /API/ActivityInstance/GetOrCreate API.

TaskGroupIdOptional - ID number of a task group
TaskGroupTitleOptional - the name of a task group


You must provide EITHER the TaskGroupId or the TaskGroupTitle, but not both. This information can be obtained by a LearningBuilder admin or by using the administrative features.


Example:
/API/ActivityInstance/GetOrCreate?ActivityNumber=ACT0001&LearningPlanInstanceId=998&TaskGroupId=732

Response:
{"success":true,"ActivityInstanceId":14021,"WorkflowInstanceId":21979}
{"success":false,"errors":["error message goes here"]}

Error Messages

Error Message DisplayedCause of Error MessageHow to Resolve Error message
ActivityNumber is required.There was no Activity Number provided in the API call.Resubmit the API Call and include ' ActivityNumber=' in the parameter string
Only one of TaskGroupId or TaskGroupTitle should be specified, not bothThe parameter string contained values for both the TaskGroupID and TaskGroupTitle parameterResubmit the API Call and include either the TaskGroupID or TaskGroupTitle parameter
TaskGroupId or TaskGroupTitle is requiredThe parameter string contained no values for either the TaskGroupID and TaskGroupTitle parameterResubmit the API Call and include either the TaskGroupID or TaskGroupTitle parameter & value
There was more than one Task Group on LearningPlanInstance # <LearningPlanInstanceId> with the ID# <TaskGroupID>The Learning Plan Instance provided contains multiple Task Groups with the same Task Group IDOpen a Technical Support ticket to have the LearningBuilder Support team remove or update TaskGroupID conflicts.
There was more than one Task Group on LearningPlanInstance # <LearningPlanInstanceId>  with title TaskGroupTitleThe Learning Plan Instance provided contains multiple Task Groups with the same Task Group TitleOpen a Technical Support ticket to have the LearningBuilder Support team remove or update TaskGroupTitle conflicts.
There was no Task Group # <TaskGroupId> found on LearningPlanInstance # LearningPlanInstanceId>.The Learning Plan Instance Provided does not contain a Task Group with the Task Group ID providedResubmit the API Call with the Correct TaskGroupID or use the TaskGroupTitle parameter
There was no Task Group named  <TaskGroupTitle> found on LearningPlanInstance # <LearningPlanInstanceId>.The Learning Plan Instance Provided does not contain a Task Group with the Task Group Title providedResubmit the API Call with the Correct TaskGroupTitle or use the TaskGroupID parameter
Learning Plan Instance ID # <LearningPlanInstanceId>  not found.The Learning Plan Instance ID provided in the parameter string was not found in the LearningBuilder system.Resubmit the API Call with the correct Learning Plan Instance ID
Activity <ActivityNumber> not found.The Activity Number provided in the Parameter does not match any published activities in LearningBuilderResubmit the API Call with the correct Activity Number
Activity <ActivityNumber> cannot be added to the Task Group <TaskGroupTitle>The Activity number provided in the Parameter string can not be added to the Task Group specified in the Parameter StringUpdate the configuration of the Task Group specified to ensure the Activity requested in the Parameter string may be added or specify a specific Task Group)
There are multiple <ActivityNumber> activities in that Task Group <TaskGroupTitle>The Learning Plan Instance contains more the one open activity matching the imported Activity NumberRemove or complete open activities in the task group

Notes

  • Items encapsulated in <> in the error message will be replaced by the values presented in the Parameter String or returned by LearningBuilder through the system progressing through the API actions.


Requirements