Process Synchronization Service

Process synchronization is the means by which progress in a credentialing process is shared with a member management system. This process allows the member management system to capture specific credentialing milestones, such as completing an application, acceptance or rejection of an application. Process data includes the parameters of the process (e.g., start and end dates, reporting start and end dates) as well as progress information (e.g., number of units achieved, submitted or not submitted).

If the external system will be using process data (e.g., date credential achieved, exam date, current CE units) the preferred approach is for the member management system to retrieve current data from LearningBuilder™ when it is needed. This can be accomplished both as an ad hoc request and as a scheduled process.

Process Synchronization Implementation

Implementing requires the following two components:

  1. The member management system generates a token and calls the LearningBuilder™ SOAP web service once for each member’s role in the system to be synchronized. Generally, a member will have only one role/credential but if there is more than one, each role/credential will be requested separately.

  2. The LearningBuilder™ SOAP service validates the token and returns results.

Data flow

 The Figure below shows process data requested by the external system and returned by LearningBuilder™.

Technical Specifications

The member management system will submit a GetRoleData transaction via XML using SOAP 1.1.

The transaction will be submitted to the following URL:

https://[YourSite].LearningBuilder™.com/services/ProcessSynchronization.svc

Below is an example of the request. The Schema for the SOAP/1.1 envelope is found here: http://schemas.xmlsoap.org/soap/envelope/.

 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">  <soapenv:Header/>  <soapenv:Body>   <tem:GetRoleData>    <tem:Version>7.8.0</tem:Version>    <tem:TimeStamp>1196367600</tem:TimeStamp>    <tem:Role>Practitioner</tem:Role>    <tem:UniqueId>3</tem:UniqueId>    <tem:RequestDepth>Activity</tem:RequestDepth>    <tem:RequestType>Summary</tem:RequestType>    <tem:Token>token</tem:Token>   </tem:GetRoleData>  </soapenv:Body> </soapenv:Envelope>

The following table describes each field in the Get Role Data XML call.

Field

Description

Version

Constant that determines what version of the specification should be applied. Must be 7.8.0

Timestamp

See section on Secure Tokens.

Unique Id

See section on Secure Tokens.

Token

See section on Secure Tokens.

Role

Text. Must be a string with a valid role that corresponds to the member’s record in LearningBuilder™. This is often ‘Practitioner’, but varies by client. It can be the name of a credential if members can have multiple credentials.

Request Depth

Text. Request depth determines how much of the individual’s process information to return. The options can include the following: 
Role (default)—Only Member Role information is returned. 
LearningPlan—Member Role and process information is returned 
TaskGroup—Member Role, process and task group information is returned
Activity—All data related to the process for the role is returned
To optimize performance, make a request at the depth that returns the fewest unnecessary fields.

Request Type

This field determines which system view to use for the data extract. The options are Summary and Detail. The specific fields returned for Member RoleLearning Plan Instance, and Activity Instance are configured within Summary and Detail Entity Views. For performance reasons, include only necessary fields in requests. (Optional; defaults to Summary if blank or invalid)


The member management SOAP web service validates the token and returns the GetRoleDataResponse. Below is an example of the response.

Note that the elements in the XML example below were manually ordered for readability.  LearningBuilder™ will likely generate them in alphabetical order.  However, the hierarchy will be maintained.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">  <s:Body>   <GetRoleDataResponse xmlns="http://tempuri.org/">    <GetRoleDataResult xmlns:a="http://schemas.datacontract.org" xmlns:i="http://www.w3.org/2001/XMLSchema-instance ">     <a:Success>0</a:Success>     <a:Profile>      <a:Title>Title</a:Title>      <a:FirstName>First Name</a:FirstName>      <a:MiddleName>Middle Name</a:MiddleName>      <a:LastName>Last Name</a:LastName>      <a:Suffix>Suffix</a:Suffix>      <a:AlternateName>Alternate Name</a:AlternateName>      <a:PrimaryEmail>Email@email.com</a:PrimaryEmail>      <a:RecordStatus>Active</a:RecordStatus>     </a:Profile>     <a:RoleInstances>       <a:RoleInstance>        <a:Role>Practitioner</a:Role>        <a:Label>Label 1</a:Label>        <a:Status>Member-Active</a:Status>        <a:UniqueIdentifier>3</a:UniqueIdentifier>        <a:BeginDate>01/01/2012</a:BeginDate>        <a:EndDate>01/01/2012</a:EndDate>        <a:[ExtrinsicField1]></a:[ExtrinsicField1]>   . . . More Extrinsic Role fields per client specifications        <a:Workflow>         <a:CurrentStep>1 </a:CurrentStep>         <a:CurrentStepTitle>Current Step Title </a:CurrentStepTitle>         <a:Status>Completed Successfully</a:Status>        </a:Workflow>        <a:LearningPlansForRoleInstance>         <a:LearningPlanForRoleInstance>          <a:LearningPlanType>Maintenance</a:LearningPlanType>          <a:LearningPlanName>Learning Plan Name</a:LearningPlanName>          <a:CycleStartDate>01/01/2012</a:CycleStartDate>          <a:CycleEndDate>12/31/2012</a:CycleEndDate>          <a:ReportingStartDate>01/01/2012</a:ReportingStartDate>          <a:ReportingEndDate>12/31/2012</a:ReportingEndDate>          <a:MinimumUnits>100</a:MinimumUnits>          <a:RequestedUnits>1</a:RequestedUnits>          <a:GrantedUnits>1</a:GrantedUnits>          <a:[ExtrinsicField1]></a:[ExtrinsicField1]>    . . . More Extrinsic Role fields per client specifications          <a:TaskGroupsForLearningPlan>            <a:TaskGroupForLearningPlan>              <a:TaskGroupName>Task Group Name</a:TaskGroupName>              <a:Complete>False</a:Complete>              <a:Required>True</a:Required>                           <a:GrantedUnits>1</a:GrantedUnits>              <a:RequestedUnits>1</a:RequestedUnits>              <a:RequiredUnits>1</a:RequiredUnits>              <a:ActivitiesForTaskGroup>                <a:ActivityForTaskGroup>                  <a:ActivityTitle></a:ActivityTitle>                  <a:GrantedUnits>1</a:GrantedUnits>                  <a:RequestedUnits>1</a:RequestedUnits>                  <a:Workflow>                   <a:CurrentStep>1</a:CurrentStep>                  <a:CurrentStepTitle>Current Step Title</a:CurrentStepTitle>                   <a:Status>Completed Successfully</a:Status>                  </a:Workflow>                </a:ActivityForTaskGroup>                <a:ActivityForTaskGroup> . . . . . . . More Activity Instances                </a:ActivityForTaskGroup              </a:ActivitiesForTaskGroup>            </a:TaskGroupForLearningPlan>            <TaskGroupForLearningPlan> . . . . . . . More Task Group Instances            </a:TaskGroupForLearningPlan>          </a:TaskGroupsForLearningPlan>          <a:Workflow> <a:CurrentStep>1</a:CurrentStep>           <a:CurrentStepTitle>Current Step Title </a:CurrentStepTitle>           <a:Status>Completed Successfully</a:Status>          </a:Workflow>         </a:LearningPlanForRoleInstance>         <a:LearningPlanForRoleInstance> . . . . . . . More Learning Plan Role Instances         </a:LearningPlanForRoleInstance>        </a:LearningPlansForRoleInstance>       </a:RoleInstance>       <a:RoleInstance> . . . . . More Role Instances       </a:RoleInstance>     </a:RoleInstances>    </GetRoleDataResult>   </GetRoleDataResponse>  </s:Body> </s:Envelope>

The following table describes each field in the Get Role Data Result XML. Optional fields vary by client configuration based on the fields selected for each entity (Member RoleLearning Plan Instance, and Activity Instance ).

Field/Node

Max Size

Description 

Success 

2

A response code indicating success or failure. 
0 = Success 
1 = Bad Token -- see troubleshooting notes below.
2 = Unique Identifier Not Found 
3 = Role not Found 

Profile

 

Always provided if Success > 1. 

Title 

100

Title of Person.

First Name 

50

First Name of Person.

Middle Name 

50

Middle Name of Person.

Last Name 

50

Last Name of Person.

Suffix 

50

Suffix of Person.

Alternate Name 

200

Alternate Name used on formal certificates.

Primary Email 

100

Email address used for communicating with user.

Record Status 

50

Active—The member is considered to be participating in the system fully 
Inactive—The member is not considered to be participating in the system. 
Password Reset—The member has requested a new password 
New—The member has created an account but has not completed the registration process. 

Role Instances

 

Always provided if Success is > 2. May be zero, one or many occurrences. One per Member Role Instance of the Role requested.  The actual list of fields returned in this node is configured in the Role Grant XML View within LearningBuilder™.  The fields listed below are all optional. 

Role 

50

Same as Role in input (Optional). 

Label 

50

Name of Role Instance.  Generally used where there are multiple instances to differentiate them.

Is Granted 

5

True or False (Optional). 

Status 

50

List is specific per client. For Practitioner, this is often ‘Applicant,’ ‘Member-Active,’ or ’Member Lapsed.’ For non-Practitioner roles, there is often no status and therefore this may be blank (Optional). 

Unique Identifier 

200

The Unique Identifier for the role.  This may not be the same as the Unique Id in the request if the member has more than one Unique Id and the Unique Id in the request corresponded to a different role.

Begin Date 

10

Begin date of the role. Definition may vary by role and client. Examples include certification date, application date (Optional). 

End Date 

10

End date of the role. Definition may vary by role and client. Examples include certification expiration dates (Optional). 

[Extrinsic Fields] 

Varies 

Client specific fields for the role; always optional. Field names are defined by the client when adding Extrinsic Fields to the Member Role - Grant  or Member Role - Edit Workflow (Optional). 

Workflow

 

One per entity instance (Role and Learning Plan). 

Current Step 

 10

The execute order of the current step of the workflow for this entity instance. This a sequential number based on the workflow configuration. (integer) 

Current Step Title 

 200

The Title of the current step of the workflow for this entity instance.

Status 

 

The status of the workflow. Options include: 
Completed Successfully—The workflow has completed all review steps successfully. 
Completed Unsuccessfully—The workflow has completed all steps but in an unsuccessful capacity. 
Owner Complete—The workflow is in a state in which the owner has progressed past their last step.  Further progress required the participation of other roles (e.g., the application is being reviewed) 
Incomplete—The workflow is in progress and the owner has additional steps they must perform (e.g., the application has not been submitted). 

Learning Plan(s) For Role Instance

 

Provided if Depth is ‘LearningPlan’, 'TaskGroup' or ‘Activity.’ May be zero, one or many occurrences per role instance. One per Learning Plan. The actual list of fields returned in this node is configured in the Learning Plan XML View within LearningBuilder™.  The fields listed below are all optional. 

Learning Plan Type 

50 

‘Application,’ ‘Maintenance,’ or ‘Appellate’ (always provided).  

Learning Plan Name 

250

Optional. 

Cycle Start Date 

10

The start of the cycle for which activities can be taken (optional). 

Cycle End Date 

10 

The end of the cycle for which activities can be taken (optional). 

Reporting Start Date 

10

The start of the period for which activities can be reported as taken. This is often the same as the Cycle Start Date (Optional). 

Reporting End Date 

10 

The end of the period for which activities can be reported as taken. This is often after the Cycle End Date to allow activities taken during the end of the cycle to be reported (Optional). 

Minimum Units 

10

The minimum number of units for a learning plan to be accepted (optional). 

Requested Units 

10 

The number of units added by the member. These units may or may not have been verified (optional). 

Granted Units 

10

The number of units added by the member that have been verified (optional). 

[Extrinsic Fields] 

Varies

Client specific fields for the role; always optional. Field names are defined by the client when adding Extrinsic Fields to the Complete Learning Plan Workflow (optional). 

Workflow 

 

Same as Workflow above. 

TaskGroup(s) For Learning Plan

 

Provided if Depth is 'TaskGroup' or ‘Activity.’ May be one or many occurrences per learning plan instance. One per Task Group.

Task Group Name

250

The name of the task group 

Required Units

10

Minimum units required for the task group to be complete.

Requested Units

10 

The number of units added to this task group. These units may or may not have been verified. 

Granted Units

10

The number of units added to this task group that have been verified. 

Complete

5

False if any practitioner requirements for the task group have not yet been completed. True otherwise, including if there are no requirements for the task group.

Required

5

True if task group has any required activities, minimum tasks or minimum units.

Activity(s) for Task Group

 

Provided if Depth is ‘Activity.’ May be zero, one or many occurrences per task group instance. One per Activity Instance.  The actual list of fields returned in this node is configured in the Activity Completion XML View within LearningBuilder™.  The fields listed below are all optional. 

Activity Title

250

Title of the activity (optional)

Workflow

 

Same as Workflow above.

Troubleshooting

If you get the success code of 1, Bad token, try the following:

  • Check the IncomingTokenSecretKey

  • Confirm the Timestamp is the correct format

  • Confirm the Timestamp is within the TokenTimeout period (usually 300 seconds)

  • Confirm that your server and the LearningBuilder server are both correctly synchronized to GTM.

  • Confirm the Token was generated using SHA-256

  • Confirm that the TokenSecretKey App Config setting is properly configured