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:

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.
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 https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/2319253584.
Unique Id	See section on https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/2319253584.
Token	See section on https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/2319253584.
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 Role, Learning 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 Role, Learning 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