Demographic Synchronization Service
The Demographic Synchronization process does not currently support the creation of Member Roles whose Grant Role Workflow uses the “Run Stored Procedure” Behavior. (LB-3146)
Demographic synchronization ensures that LearningBuilder™ incorporates the latest demographic data from an external member management system. Demographic synchronization is typically necessary in circumstances in which the member management system is the primary repository for demographic information, but that demographic information either informs or is affected by certification activities. Demographic synchronization is a one-directional process in which member management systems share current data with LearningBuilder™.
LearningBuilder™ is designed to refresh demographic data immediately upon sign-on. Our preferred approach is to call a web service that will return the needed data. However, if your system already has a web service, LearningBuilder™ can be extended to use an existing interface.
In some situations, there is a need to refresh data more often than the next time a user signs on. LearningBuilder™ also supports scheduling the bulk processing of a CSV file with demographic data. See https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/2319155280.
Demographic synchronization implementation via SOAP
Implementing requires only two components:
LearningBuilder™ to generate a token and call member management SOAP web service.
SOAP service to validate token and return results.
Data flow
Data flow for synchronizing LearningBuilder™ demographics with an external system.
Technical Specifications for SOAP
The member management web service should implement the following contract. Note that the order of parameters and the exact spelling/capitalization are significant to some web service frameworks. Consult your framework documentation for details.
LearningBuilder™ will submit a GetDemographicData transaction via XML using SOAP 1.1. 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:GetDemographicData>
<tem:Version>7.8.0</tem:Version>
<tem:TimeStamp>1196367600</tem:TimeStamp>
<tem:UniqueId>3</tem:UniqueId>
<tem:Token>token</tem:Token>
</tem:GetDemographicData>
</soapenv:Body>
</soapenv:Envelope>The member management SOAP web service should validate the token and then return the GetDemographicDataResponse. Below is an example of the response.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetDemographicDataResponse xmlns="http://tempuri.org/">
<GetDemographicDataResult 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:MemberName>Organization Name</a:MemberName>
<a:AlternateName>Alternate Name</a:AlternateName>
<a:WebSite>http://website.com</a:WebSite>
<a:Description>Description</a:Description>
<a:PrimaryEmail>Email@email.com</a:PrimaryEmail>
<a:Phones>
<a:Phone>
<a:PhoneType>Home</a:PhoneType>
<a:PhoneNumber>555-555-1212</a:PhoneNumber>
</a:Phone
</a:Phones>
<a:Addresses>
<a:Address>
<a:AddressType>Home</a:AddressType>
<a:AddressLine1>Address Line 1</a:AddressLine1>
<a:AddressLine2>Address Line 2</a:AddressLine2>
<a:AddressLine3>Address Line 3</a:AddressLine3>
<a:City>Address City</a:City>
<a:State>ST</a:State>
<a:MailCode>99999</a:MailCode>
<a:Country>USA</a:Country>
<a:Province>Province</a:Province>
</a:Address>
</a:Addresses>
</a:Profile>
<a:RoleInstances>
<a:RoleInstance>
<a:Role>Practitioner</a:Role>
<a:Label>Label</a:Label>
<a:IsGranted>True</a:IsGranted> <a:Status>Member-Active</a:Status>
<a:UniqueId>3</a:UniqueId>
<a:BeginDate>01/01/2012</a:BeginDate>
<a:EndDate>01/01/2012</a:EndDate>
<a:[CustomField1]></a:[CustomField1]>
. . . More Custom Role fields per client specifications
</a:RoleInstance>
<a:RoleInstance>
. . . Repeat for more roles
</a:RoleInstance>
</a:RoleInstances>
</GetDemographicDataResult>
</GetDemographicDataResponse>
</s:Envelope>The following table describes each field expected in the Get Demographic Data Result XML.
Optional fields are not required in the result XML and must be omitted if the member management system does not own the data (i.e. LearningBuilder™ will be responsible for maintaining the data).
The determination of which fields are maintained by which system varies by implementation.
Optional INTRINSIC fields that are blank in the XML will set the value to blank. EXTRINSIC fields that are blank in the XML will be ignored.
Any invalid values will be ignored and will not update the existing value. If the record is new, the default value will be used, if any.
Exception: there are no validation rules for Phone Numbers or Email addresses, and it is possible to input malformed data.
Any data that exceeds the maximum length specified below will be truncated.
In certain conditions, 'illegal / special' characters (such as "?/.\}{][,~!@#$%^&*()_+=-|\:'äÄü¼̠ϧ̉ȫōȫƼŁ) will cause system errors
All XML node names are case-sensitive.
Refer to the page for a list of support data types.
Field | Description |
Success | A response code indicating success or failure. |
Title | Title of Person (Optional, max of 100; ignored for Organizations) |
First Name | First Name of Person (Required for People, max of 50; ignored for Organizations) |
Middle Name | Middle Name of Person (Optional. max of 50; ignored for Organizations) |
Last Name | Last Name of Person (Required for People, max of 50; ignored for Organizations) |
Suffix | Suffix of Person (Optional, max of 50; ignored for Organizations) |
Member Name | Name of Organization (Required for Organizations; max of 101; ignored for People) |
Alternate Name | Alternate Name used on formal certificates (Optional, max of 200) |
Primary Email | Email address used for communicating with user (Optional, max of 100) |
Phones | Optional. They will be ignored if Phone Type and Phone Number are not both provided or if Phone Type is invalid. Only one phone per type will be stored or updated. |
Phone Type | Must be one of the following: Primary, Home, Work, Fax, Mobile or Other, if provided. |
Phone Number | Must include formatting. Ex: (800) 555-1212 or 800.555.1212 (max of 50) |
Addresses | Optional. Addresses will be ignored unless Address Type, Address Line 1, City and Country are provided and Address Type is valid. Only one address per type will be stored or updated. The entire address will be updated. Fields omitted from the XML will be set to blank. |
Address Type | Must be one of the following: ‘Home’, ‘Work’, ‘Home 2’, ‘Work 2’, ‘Primary’, or ‘Previous’, if provided. |
Address Line 1 | Required for each address. (max of 100) |
Address Line 2 | Optional (max of 100) |
Address Line 3 | Optional (max of 100) |
City | Required for each address. (max of 100) |
State | Optional, Must be 2 characters. (max of 2) |
Mail Code | Postal or Zip Code (Optional, max of 25) |
Country | Required for each address (max of 50) |
Province | Optional, Foreign Province (max of 100) Can also be used for "County" [New in Release 7.11] |
Role Instance | At least one is required. Multiple roles can be included. If there are no valid nodes, entire request will be ignored and not update member. |
Role | Must be a valid role that corresponds to the Member Type of this member. For people this is often ‘Practitioner’, but varies by client. For organizations, this is often 'Provider'. It could also be ‘Administrator’, ‘Reviewer’, ‘Auditor’ or other client specific roles. If role is invalid (i.e. unknown to LearningBuilder), entire node will be ignored. If Member Type of role does not match current member, entire request will be ignored. If this is a new member and there are multiple roles with different member types, entire request will be ignored. |
Label | Required if Role allows multiple instances and then used to find the correct instance of the role. If not provided and role allows multiple instances, entire node will be ignored. |
Is Granted | Optional. Must be True or False, True gives the member this role. False takes away the role. Defaults to True if not provided when adding a role. Invalid values will be ignored. |
Status | Optional. 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. If not provided when adding a role, it will default to the configured default status, if any. |
Unique Id | Must be same value as provided on input for primary role (i.e. Practitioner). Optional and often not provided for non-Practitioner roles. If a secondary role is provided its Unique Id duplicates one assigned to another person, the entire node will be ignored. (max of 200) |
Begin Date | Begin date of the role. Definition may vary by role and client. (Optional) [Prior to release 7.11, this was "Start Date"; "Start Date" is still supported for backward compatibility] |
End Date | End date of the role. Definition may vary by role and client. (Optional) |
[Custom Fields] | Client specific fields for the role; always optional. Field names will be client specific. |