SYNC Operation
The SYNC operation of
XmlEngine allows you to create, update or delete objects in SmartOffice based on a defined record-matching algorithm (RMA).
When sending a SYNC request, you specify the data you want to sync (using the <objects> element) and the conditions by which SmartOffice should determine whether a match already exists in the database (using the <rma> element>. You also define what SmartOffice should do under various record-matching scenarios (e.g., match found, match not found, etc.).
Elements
<rma> Element
This element defines the record-matching algorithm you want SmartOffice to use in determining whether a matching object exists in the database. The <rma> element contains several child elements that you use to define the RMA. The following illustration shows the structure of the <rma> element and its child elements:
The <rma> element has two attributes:
Attribute |
Description |
object |
(Required) The SmartOffice object type that the RMA applies to (e.g., Contact). |
start |
(Required) The starting phase of the RMA. The value is the ID of the phase (see the next section). |
[Control Attributes] |
See Control Attributes. |
<phase> Element
The <rma> element must contain one or more phases, each defined using a <phase> element. Phases break the RMA into discrete sections containing their own queries and logic steps. The available attributes are:
Attribute |
Description |
id |
(Required) The phase identifier. This is a numerical value that is used to reference the phase in other portions of the RMA. |
[Control Attributes] |
See Control Attributes. |
<query> Element
The <phase> element must contain one or more <query> elements. A query defines the conditions (using the <condition> element) that will be applied when searching for a match as well as the actions that will occur when the conditions are met or not met. The available attributes are:
<logic_step> Element
Within a <query> element, a logic step can be used to narrow down the results of a query. For example, if a query condition results in multiple matches (i.e., an ambiguity), a logic step can apply additional conditions on those results (using the <condition> element) to arrive at a match. The available attributes are:
Attribute |
Description |
id |
(Required) The logic step identifier. This is a numerical value that is used to reference the logic step in other portions of the RMA. |
[Control Attributes] |
See Control Attributes. |
<condition> Element
Under each <query> and <logic_step> element, add one more conditions. For information about the syntax for defining conditions, see
SearchOperation.
<return> Element
When creating an RMA, you can add control attributes that instruct
XmlEngine to return a list of records that match the RMA. The <return> element is where you define the properties that you want returned.
<objects> Element
This element defines the input of your SYNC operationthe data you want to sync to the
SmartOffice database. One or more objects can be defined here.
Control Attributes
Control attributes allow you to define the actions that will occur when the conditions in your RMA are applied to the
SmartOffice database.
For example, the control attribute
match=update tells
XmlEngine that, if a condition is applied and a match is found, update the record in
SmartOffice with the data specified in the <objects> element.
Note: Control attributes can be used with the <rma>, <phase>, <query> and/or <logic_step> elements. Attributes specified for child elements override attributes specified in parent elements. Ebix recommends that you use control attributes only with the <query> and <logic_step> elements until you become more familiar with how the SYNC operation works.
Control Attribute |
Description |
match |
Defines what happens when a single match is found. |
ambiguity |
Defines what happens when more than one match is found. |
no-match |
Defines what happens when no match is found. |
insufficient-data |
Defines what happens when the input defined in the <objects> element does not contain the properties required by the RMA. |
The available attribute values are:
Attribute Value |
Description |
ignore |
Ignore processing/do nothing. |
insert |
Insert the objects defined in the <objects> element into the SmartOffice database as new records. |
update |
Update the matching record(s) in the SmartOffice database with the data specified in the <objects> element. |
delete |
Delete the matching record(s) in the SmartOffice database. |
return |
Return all matching objects with the properties defined in the <return> element. |
exit |
Exit from the current step. |
[phase ID] or [step ID] |
Run the specified phase/step. |
Example
Request XML:
<request version="1.0">
<header>
<office>myoffice</office>
<user>jdoe</user>
<password>password</password>
</header>
<sync>
<rma object="Contact" start="phase1">
<phase id="phase1">
<query no-match="phase2" match="update" ambiguity="step1">
<condition>
<expr prop="LastName" op="eq">
<v type="ref">Contact.LastName</v>
</expr>
</condition>
<condition>
<expr prop="TaxID" op="eq">
<v type="ref">Contact.TaxID</v>
</expr>
</condition>
</query>
<logic_step id="step1" no-match="phase2" match="update" ambiguity="return">
<condition>
<expr prop="FirstName" op="eq">
<v type="ref">Contact.FirstName</v>
</expr>
</condition>
</logic_step>
</phase>
<phase id="phase2">
<query no-match="insert" match="update" ambiguity="return">
<condition>
<expr prop="TaxID" op="eq">
<v type="ref">Contact.TaxID</v>
</expr>
</condition>
</query>
</phase>
<return>
<Contact>
<LastName/>
<FirstName/>
</Contact>
</return>
</rma>
<objects>
<Contact>
<LastName>Ackerman</LastName>
<FirstName>Joseph</FirstName>
<TaxID>111111111</TaxID>
<WebAddresses>
<WebAddress>
<WebAddressType>1</WebAddressType>
<Address>jackerman@domain.com</Address>
</WebAddress>
</WebAddresses>
</Contact>
</objects>
</sync>
</request>
In this example, the record-matching algorithm defined in the <rma> element contains two phases. The first phase contains a query defining two conditions for a match (last name and tax ID) and a logic step defining an additional condition (first name) if the query returns an ambiguous result.
Lets look at the query first:
<query no-match="phase2" match="update" ambiguity="step1">
<condition>
<expr prop="LastName" op="eq">
<v type="ref">Contact.LastName</v>
</expr>
</condition>
<condition>
<expr prop="TaxID" op="eq">
<v type="ref">Contact.TaxID</v>
</expr>
</condition>
</query>
The attributes of the <query> element specify what will happen when the conditions are applied. If there is no match, phase 2 of the RMA will begin. If there is a single match, the contact will be updated with the data specified in the <objects> element. If there is ambiguity (i.e., more than one match), the RMA will go to logic step 1 to further narrow down the matches.
Lets look at that logic step:
<logic_step id="step1" no-match="phase2" match="update" ambiguity="return">
<condition>
<expr prop="FirstName" op="eq">
<v type="ref">Contact.FirstName</v>
</expr>
</condition>
</logic_step>
The logic step refines the query by taking the query results and applying an additional condition (in this case, checking for a match on the first name). If no match is found, phase 2 of the RMA will begin. If a match is found, the contact will be updated with the data specified in the <objects> element. If there is still ambiguity even after matching on the first name, the request will just return a list of the matching records .
In the second phase of the RMA, the query contains only one condition, a match on the tax ID:
<query no-match="insert" match="update" ambiguity="return">
<condition>
<expr prop="TaxID" op="eq">
<v type="ref">Contact.TaxID</v>
</expr>
</condition>
</query>
Again, the attributes of the <query> element specify what will happen after the conditions are applied. If there is no match, the contact data specified in the <objects> element will be inserted into the database as a new contact. If there is a single match, the contact will be updated with the data specified in the <objects> element. If there is ambiguity (i.e., more than one match), the request will return a list of the matching records and do nothing else.
The <return> element defines what data
XmlEngine will return about each object when instructed to return data. In our example, when the XML specifies that results should be returned,
XmlEngine will return the last name and first name of all contacts that were a match.
<return>
<Contact>
<LastName/>
<FirstName/>
</Contact>
</return>
Finally, the <objects> element in our example contains the input data for the sync operation. Here, we define the object type (<Contact>) and the properties of the object that we want to process using the RMA.
<objects>
<Contact>
<LastName>Ackerman</LastName>
<FirstName>Joseph</FirstName>
<TaxID>111111111</TaxID>
<WebAddresses>
<WebAddress>
<WebAddressType>1</WebAddressType>
<Address>jackerman@domain.com</Address>
</WebAddress>
</WebAddresses>
</Contact>
</objects>
For more on data synchronization, see the
TwoWayContactSycnronization White Paper.