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 Demographic Synchronization via CSV.

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.

Method Name	Field	Description
GetDemographicData	Version	Constant that determines what version of the specification should be applied. Must be “7.8.0”
	TimeStamp	See section on Secure Tokens.
	UniqueId	See section on Secure Tokens.
	Token	See section on Secure Tokens.

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 Workflow Attributes page for a list of support data types.

Field	Description
Success	A response code indicating success or failure. 0 = Success 1 = Bad Token 2 = Unique Identifier Not Found
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) NOTE: If source system has Province data in a common state field, if it is more than 2 characters and send in the Province field instead.
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.