Functionally equivalent to clicking the “Begin” button on the Learning Plan List page to start a new Learning Plan.

Overview

/API/LearningPlanInstance/GetOrCreate can be used to locate an existing Incomplete LearningPlanInstance for a specific Practitioner.

If no existing record exists, but the specified Practitioner is eligible to start a new instance of the relevant LearningPlan, then the new instance is created and then returned.

Parameters

The following values should be specified in the querystring:

Parameter	Required?	Explanation

Parameter	Required?	Explanation
`LearningPlanId`	Required (unless LP title is specified¹)	The ID of the `LearningPlan` to locate or create.
`LearningPlanTitle`	Required (unless LP ID is specified¹)	The Title of the `LearningPlan` to locate or create.
`UniqueID`	Required	The `UniqueIdentifier` of the `MemberRole` that owns (or will own) the desired `LearningPlanInstance`. This can be obtained using the /OData/Members API.
`RoleName`	Optional	The title of the relevant `Role`. Used to disambiguate the `UniqueID` when it is shared by multiple `MemberRole` records for the same `Member`.

¹ You must provide either LearningPlanId or LearningPlanTitle, but not both.

For example:

/API/LearningPlanInstance/GetOrCreate?LearningPlanId=22&UniqueId=ABC123

Return value

If an error occurs, the return value is a JSON object like:

{ success = false, errors = string[] }

If a single pre-existing LearningPlanInstance was located, or a new one was successfully created, the return value is a JSON object like:

{ success = true, LearningPlanInstanceId = <LPI_primary_key> }

Business rules

Errors are thrown if:

The system cannot locate a single, Granted MemberRole record matching the specified UniqueID and RoleName (if provided);
Multiple Incomplete LearningPlanInstances exist that match the criteria;
No existing LPIs exist, and the LearningPlanId or LearningPlanTitle arguments do not uniquely identify a single LearningPlan to start;
No existing LPIs exist, and the specified MemberRole is not eligible to begin a new instance of the specified LearningPlan

If a single MemberRole is found, and it owns a single Incomplete LearningPlanInstance that matches the criteria, then the ID of that record is returned. In this case, there are no side effects to calling the API.

If no existing Incomplete LearningPlanInstances are found, and the specified MemberRole is eligible to start a new instance, then a new one is created and the ID of that record is returned. Subsequent calls to the API will return the same ID value (they will locate the now-existing record).

To be started via this API, the following conditions must be met:

Condition	Explanation

Condition

Explanation

The LearningPlan matching the criteria is included in the LearningPlanTypesToIncludeInPractitionersList App Config setting.

This setting controls which Learning Plans are accessible via the Practitioner interface, and therefore which Learning Plans are “startable” by the Practitoner.

The MemberRole is eligible to begin a new instance of the target LearningPlan

The MemberRole is either allowed to start the Learning Plan (due to the LP’s “Required Role” and “Required Role Status” settings),

-OR-

The Member does NOT already have the required Role, but they ARE allowed to start the Required Role’s Grant Role Workflow, and the default Role Status set by completing that Workflow satisfies the Learning Plan’s “Required Role Status” setting.

This is the same logic that controls whether or not the “Begin” button shows up on the Learning Plan List page.

It allows the LPI to be started if the owner has the necessary Role/Status, OR they are able to begin a Grant Role Workflow that would result in them having the necessary Role/Status.

Error messages

Message	Reason	How to resolve

Message	Reason	How to resolve
Member Role Unique Id <x> not found. Code `ERR-NO-ROWS`	No granted Member Roles were found that match the provided `UniqueId`.	Make sure you’re passing a valid `UniqueId`, and that the target Member Role is in a “granted” status.
Member Role Unique Id <x> not found. Code `ERR-TOO-MANY-ROWS`	More than 1 granted Member Roles were found that match the provided `UniqueId`.	Pass a `RoleName` parameter indicating which of the candidate records to use.
More than one {Glossary:LearningPlan} instance was found.	Multiple Learning Plan Instances in an Incomplete status were found that match the provided criteria.	Ensure that only one matching Learning Plan Instance is Incomplete.
More than 1 {Glossary:LearningPlan} named “{title}” was found.	No incomplete Learning Plan Instance exists, and the system found multiple Learning Plan Definitions that could be started.	Pass the `LearningPlanId` parameter to disambiguate the candidate Learning Plans.
No {Glossary:LearningPlans} ID#<n> found.	No incomplete Learning Plan Instance exists, and no Learning Plan Definition matching the criteria was found.	Make sure you’re passing a valid `LearningPlanId` and/or `LearningPlanTitle`.
No {Glossary:LearningPlans} titled ‘{title}’ found.