Creates a new Learning Plan Instance, or returns an existing one matching the specified criteria.

Commonly used to start a new application for a Practitioner.

Overview

Accepts as input a Learning Plan identifier and a Member Role identifier.

If a matching Learning Plan Instance exists, it is returned.

If there is no matching Learning Plan Instance, and the specified Member is eligible to start a new instance of the Learning Plan, a new instance is created and returned. This Learning Plan Instance is functionally equivalent to an end user clicking the “Begin” button to start a new application.

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_LEARNING_PLAN_INSTANCE permission.

Request

GET /API/LearningPlanInstance/GetOrCreate
?LearningPlanId=<int>
&LearningPlanTitle=<string>
&UniqueID=<string>
&RoleName=<string>

Querystring Parameter	Description

Querystring Parameter

Description

LearningPlanId
or
LearningPlanTitle

Required: Identifier for the LearningPlanDefinition to match

You must provide one of these values, but not both.

UniqueID

Required: The Unique Identifier of the Member Role that owns (or will own) the desired Learning Plan Instance.

This can be obtained using the /OData/Members API.

RoleName

The title of the relevant Role. Used to disambiguate the UniqueID when it is shared by multiple MemberRole records for the same Member.

Response

If successful:

{ 
  "success": true, 
  "LearningPlanInstanceId": {LPI ID}
}

If unsuccessful:

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

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.

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.