Synchronizing Constituent Data

Upload Constituent Record Changes to Luminate Online

For a two-way synchronization, the next step is to use the Create, Update and Delete operations to upload changes from the external database since the last synchronization to Luminate Online, for example: 


<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <ns3:Session xmlns:ns3="urn:soap.convio.com" soapenv:mustUnderstand="0">
         <ns3:SessionId>c55d8f07700b4aa8401e2b9c4d4262efa6da30d8:JSESSIONID=abcKuVJBroiHpeNByWZ3r:10000100:2008-12-01T18:13:46.019Z</ns3:SessionId>
      </ns3:Session>
   </soapenv:Header>
   <soapenv:Body>
      <ns3:Create xmlns:ns3="urn:soap.convio.com">
         <ns3:PartitionId>123</ns3:PartitionId>
         <ns3:Record xmlns:ns1="urn:object.soap.convio.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:Constituent">
            <ns1:ConsName>
               <ns1:FirstName>Albus</ns1:FirstName>
               <ns1:LastName>Dumbledore</ns1:LastName>
            </ns1:ConsName>
            <ns1:UserName>albus</ns1:UserName>
            <ns1:PrimaryEmail>albus@hogwarts.edu</ns1:PrimaryEmail>
            <ns1:HomeAddress>
               <ns1:Street1/>
               <ns1:City>Hogsmeade</ns1:City>
               <ns1:State>CA</ns1:State>
               <ns1:Zip>94702</ns1:Zip>
               <ns1:Country>USA</ns1:Country>
            </ns1:HomeAddress>
         </ns3:Record>
      </ns3:Create>
   </soapenv:Body>
</soapenv:Envelope>

Each request can include up to 50 constituent records. Luminate Online responds with a Result element for each record:


<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <CreateResponse xmlns="urn:soap.convio.com" xmlns:ens="urn:object.soap.convio.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Result>
            <ResultCode>OK</ResultCode>
            <Message>New user added.</Message>
            <Record xsi:type="ens:Constituent">
               <ens:ConsId>1001482</ens:ConsId>
               <ens:PrimaryEmail>albus@hogwarts.edu</ens:PrimaryEmail>
            </Record>
         </Result>
      </CreateResponse>
   </soap:Body>
</soap:Envelope>

The result of Create operation includes the constituent ID (ConsId), the unique primary key that Luminate Online has assigned to each newly created constituent. The result of the Update and Delete operations includes the ConsId of the existing record that the system matched to the request, if any.

The middleware should check the ResultCode for each record and take appropriate action if an error or collision has occurred.

The requests and responses for the Update and Delete operations have the same structure.

Download Constituent Record Changes from Luminate Online

The next step in the conversation is to download new, updated and deleted constituent records from Luminate Online: 


<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <ns3:Session xmlns:ns3="urn:soap.convio.com" soapenv:mustUnderstand="0">
         <ns3:SessionId>3868cf8ebb49e046a024e18ad8420ea931fe8b64:JSESSIONID=abc_g9cmWx9L0_dZyWZ3r:10000101:2008-12-01T18:13:47.722Z</ns3:SessionId>
      </ns3:Session>
   </soapenv:Header>
   <soapenv:Body>
      <ns3:GetIncrementalInserts xmlns:ns3="urn:soap.convio.com">
         <ns3:PartitionId>123</ns3:PartitionId>
         <ns3:RecordType>Constituent</ns3:RecordType>
         <ns3:Page>1</ns3:Page>
         <ns3:PageSize>3</ns3:PageSize>
         <ns3:Field>ConsId</ns3:Field>
         <ns3:Field>ConsName</ns3:Field>
         <ns3:Field>UserName</ns3:Field>
         <ns3:Field>PrimaryEmail</ns3:Field>
         <ns3:Field>HomeAddress</ns3:Field>
      </ns3:GetIncrementalInserts>
   </soapenv:Body>
</soapenv:Envelope>

Luminate Online Web Services will respond to this request with a set of constituents updated during the synchronization window by agents other than the caller (it may be another admin or the constituent herself):


<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <GetIncrementalInsertsResponse xmlns="urn:soap.convio.com" xmlns:ens="urn:object.soap.convio.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Record xsi:type="ens:Constituent">
            <ens:ConsId>1001483</ens:ConsId>
            <ens:ConsName>
               <ens:FirstName>Harry</ens:FirstName>
               <ens:LastName>Potter</ens:LastName>
            </ens:ConsName>
            <ens:UserName>potter</ens:UserName>
            <ens:PrimaryEmail>potter@leakycauldron.com</ens:PrimaryEmail>
            <ens:HomeAddress>
               <ens:Street1>4 Privet Drive</ens:Street1>
               <ens:City>Little Whinging</ens:City>
               <ens:State>CA</ens:State>
               <ens:Zip>94705</ens:Zip>
               <ens:Country>USA</ens:Country>
            </ens:HomeAddress>
         </Record>
      </GetIncrementalInsertsResponse>
   </soap:Body>
</soap:Envelope>

Note that the system limits each request to a maximum of 200 records. To download larger record sets, the client must make multiple requests, incrementing the Page parameter each time. The basic logic that a client must implement to download a full set of records is as follows:

  1. Make an initial request to GetIncrementalInserts, GetIncrementalUpdates or GetIncrementalDeletes. Specify Page 1 and a PageSize of up to 200.
  2. Process the records in the response, counting them as you go.
  3. If the number of records in the response equals the requested PageSize, then make another request, this time specifying Page = 2 and always using the same PageSize.
  4. Continue until the number of records in the response is less than the PageSize. Note that the record count in a response may be zero if the size of the record set is an even multiple of the requested PageSize.
Note: All three methods, GetIncrementalInserts, GetIncrementalUpdates, and GetIncrementalDeletes must be called in order to retrieve all of the Luminate Online records that may have changed during the synchronization window.

GetIncrementalUpdates returns the list of previously-synchronized records that have been updated on the Luminate Online system during the synchronization window that were created before the start of the synchronization window. Records created after the start of the synchronization window and later modified would be downloaded as new, using GetIncrementalInserts, rather than as updated from the standpoint of the client. This method returns only updates to constituent records that have been assigned a key on the external system. This method retroactively includes any previously updated records if their key was assigned during the current sync window. Processing for this method on the middleware should handle the possibility of collisions.

GetIncrementalInserts returns the list of records added to the Luminate Online Web Services partition during the synchronization window. Processing of this response should add or merge these records into the external database according to your policy on detecting and handling duplicates. Also, it is good practice for each record added to update the MemberId field of the record in the Luminate Online database with the unique primary key value assigned to that record by the external database system, for example: 


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:soap.convio.com">
  <soapenv:Header> <urn:Session><urn:SessionId>3868cf8ebb49e046a024e18ad8420ea931fe8b64:JSESSIONID=abc_g9cmWx9L0_dZyWZ3r:10000101:2008-12-01T18:13:47.722Z</urn:SessionId></urn:Session>
  </soapenv:Header>
  <soapenv:Body>
    <urn:Update>
    <urn:PartitionId>123</urn:PartitionId>
      <urn:Record xsi:type="ns3:Constituent"
        xmlns:ns3="urn:object.soap.convio.com"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ns3:ConsId>1001123</ns3:ConsId>
        <ns3:MemberId>98675</ns3:MemberId>
      </urn:Record>
      <urn:Record xsi:type="ns3:Constituent"
        xmlns:ns3="urn:object.soap.convio.com"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ns3:ConsId>1001124</ns3:ConsId>
        <ns3:MemberId>98676</ns3:MemberId>
      </urn:Record>
      <urn:Record xsi:type="ns3:Constituent"
        xmlns:ns3="urn:object.soap.convio.com"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ns3:ConsId>1001125</ns3:ConsId>
        <ns3:MemberId>98678</ns3:MemberId>
      </urn:Record>
    </urn:Update>
  </soapenv:Body>
</soapenv:Envelope>

This will make it easier to maintain synchronization between Luminate Online and the external database in subsequent syncs.

Note: If Luminate Online duplicate record detection is enabled, new constituent registrations may not be immediately visible through GetIncrementalInserts. Instead, the system first queues them for duplicate record checking. An automatic batch processes this queue periodically, inserting unique records, merging duplicates with existing constituent records, and flagging questionable duplicates to be checked manually by an administrator. Only after a record has been processed and either inserted as a new record or merged with an existing record will the data appear in a GetIncrementalInserts or GetIncrementalUpdates response.

GetIncrementalDeletes returns the list of records removed from the Luminate Online Web Services partition during the synchronization window.

Note: If a record was both added to and deleted from the Luminate Online partition during the synchronization window, only the deletion event, and not the insertion event, will be returned.

Synchronizing Summary Transaction History

The Luminate Online constituent record includes two sets of fields that summarize the constituent's online and offline transaction history. The values of these fields are commonly used for personalizing fundraising appeals and other content.

The first set of fields summarizes transactions that the constituent has made through all Luminate Online modules, including Donations, TeamRaiser, E-Commerce, etc. These fields are maintained exclusively by Luminate Online and are read-only. They can be downloaded as part of the synchronization process using the GetIncrementalInserts and GetIncrementalUpdates operations. They should not ever be uploaded as part of a Create or Update operation.

The WSDL defines two types of child elements for the online summary transaction history:

  1. TransactionSummary contains a brief record of a single transaction. The constituent record includes this summary for the first, largest and last transactions made by the constituent. Each transaction summary includes:
    1. Amount
    2. Campaign
    3. Date
    4. Donation type
    5. Payment method
    6. Tender type
  2. AnnualTransactionSummary contains two fields: the total amount and the number of transactions made in a particular year. The constituent record includes an annual summary for the current and previous years.

Luminate Online automatically updates the online transaction summary fields as appropriate when the constituent performs a transaction. The system updates the last modified date on the constituent record when it updates any of these fields, so the record will be included in the GetIncrementalUpdates operation.

Synchronizing Offline Transaction Summary history

The second set of fields summarizes the constituent's transaction history based on an external source, such as an offline donor database. These fields are updatable manually through the administrator interface or automatically via web services. They can be downloaded as part of the synchronization process using the GetIncrementalInserts and GetIncrementalUpdates operations. They can also be uploaded as part of a Create or Update operation.

The constituent record has five pairs of fields for external transaction history, each of which has a corresponding field in the WSDL:

  1. First gift date and amount
  2. Last gift date and amount
  3. Largest gift date and amount
  4. Year-to-date amount and count
  5. Lifetime amount and count

Note that maintenance of these fields is entirely up to the client or middleware. The field values can reflect online as well as offline activity, or follow any other sets rules defined by the client.

Querying for Additional Information

The synchronization logic implemented by the middleware may require additional information that is not provided by the upload or download responses. Luminate Online Web Services also provides a Query operation for this purpose.

A Query request must contain a QueryString in the general form: 

select Field1 [, Field2, Field3, ...] from RecordType [where
Criteria]

RecordType is the name of a top-level element in the Luminate Online WSDL that extends the Record base type, such as Constituent or Donation. The field list must be a subset of element names of fields that the WSDL defines for that type. To specify fields that are sub-fields of an embedded complex type, use dot notation, e.g. ConsName.FirstName or HomeAddress.City.

The query Criteria supports basic Boolean comparison expressions. See Luminate Online Query Language for reference to the grammar.

A typical query request looks like this: 


<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <ns3:Session xmlns:ns3="urn:soap.convio.com" soapenv:mustUnderstand="0">
        <ns3:SessionId>e96ce3db61a80642510225a783540f6dcb6e702d:JSESSIONID=abcMZ5dmWgZeidZtyWZ3r:10000100:2008-12-01T18:13:45.691Z</ns3:SessionId>
      </ns3:Session>
   </soapenv:Header>
   <soapenv:Body>
      <ns3:Query xmlns:ns3="urn:soap.convio.com">
         <ns3:QueryString>select ConsId from Constituent where ConsId = 1001482</ns3:QueryString>
         <ns3:Page>1</ns3:Page>
         <ns3:PageSize>3</ns3:PageSize>
      </ns3:Query>
   </soapenv:Body>
</soapenv:Envelope>

The structure of the response is identical to that of the GetIncrementalInserts, GetIncrementalUpdates, and GetIncrementalDeletes operations:


<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <QueryResponse xmlns="urn:soap.convio.com" xmlns:ens="urn:object.soap.convio.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Record xsi:type="ens:Constituent">
            <ens:ConsId>1001482</ens:ConsId>
         </Record>
      </QueryResponse>
   </soap:Body>
</soap:Envelope>
Parent topic: Data Synchronization

Leave a Comment

Nickname
Comment
Enter this word:
Change