API/ActivityInstance/GetOrCreate

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:

Parameter	Description
`ActivityNumber`	Required - ID label of an activity
`LearningPlanInstanceId`	Required - ID number of a learning plan instance; normally retrieved using the /API/ActivityInstance/GetOrCreate API.
`TaskGroupId`	Optional - ID number of a task group
`TaskGroupTitle`	Optional - 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 Displayed	Cause of Error Message	How 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 both	The parameter string contained values for both the TaskGroupID and TaskGroupTitle parameter	Resubmit the API Call and include either the TaskGroupID or TaskGroupTitle parameter
TaskGroupId or TaskGroupTitle is required	The parameter string contained no values for either the TaskGroupID and TaskGroupTitle parameter	Resubmit 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 ID	Open 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 TaskGroupTitle	The Learning Plan Instance provided contains multiple Task Groups with the same Task Group Title	Open 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 provided	Resubmit 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 provided	Resubmit 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 LearningBuilder	Resubmit 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 String	Update 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 Number	Remove 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.

LearningBuilder Documentation

API/ActivityInstance/GetOrCreate

Overview

Error Messages

Notes

Requirements

Related articles

Related pages