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:

rma_elements.png

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:
Attribute Description
[Control Attributes] See Control Attributes.

<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 operation—the 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.

Let’s 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.

Let’s 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.



Topic revision: 08 Feb 2019, DinosLambropoulos
 

This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback