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 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: |
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. |
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 |
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: |
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