XML Engine

The XML Engine is an interface method through which workflows outside the SmartOffice application can obtain or update data stored in SmartOffice, with no need to manually sign in. Via a Proxy that is attached to SmartIntegrator, well-formed XML-requests containing relevant data are sent or received.

Examples of XmlEngine functionality:
  • Each night, your application synchronizes the data in SmartOffice with the data in another system.
  • From another application, you search/insert/update/delete records in your SmartOffice database.
  • On another website, you retrieve and display records (e.g., calendar entries, tasks, contacts, policies, accounts) that are stored in your SmartOffice database.

Using the API

If you are not going to be creating a button or adapter, you will have to become familiar with SmartOffice’s Test Bed OR create your own UI which will function in the same manner. In the least technical explanation, this API’s purpose is to allow any of SmartOffice’s users the ability to retrieve and insert data using XML requests. This section assumes the user has a general understanding of XML syntax.

You must also implement debug logging in your application to log the XML requests and responses sent and received via the API. This information aids Ebix in analyzing any issues that may arise.

Operations

Seven different operations can be used in the request XML: INSERT, UPDATE, DELETE, GET, SYNC, SEARCH and METHOD.

Data elements are the children of operation elements. Operations can be the manipulation of an object or a method call. Object manipulation operations call SmartOffice data beans internally.

The METHOD operation exposes methods from SmartOffice’s internal business functions.

Client applications can use the METHOD operation to perform predefined business rules.

Object elements under operation elements will be performed with the specified operation.

A single operation may have multiple data objects.

*When testing your Requests using SmartIntegrator the “<header></header>” tags and the user login information is not required because that information is entered at the top of the UI.
  • InsertOperation- creates new objects with sub-objects, returns the Object ID on the new records.
  • UpdateOperation- overwrites values on existing objects, requires the Object ID of the record to be updated.
  • DeleteOperation- removes records from the database and cascade deletes child objects, requires the Object ID of the record to be removed.
  • GetOperation- returns requested values for an object based on Object ID.
  • SearchOperation- returns requested values for multiple objects based upon a search criteria.
  • MethodOperation- triggers special functionality in SmartOffice. Each method has its own input and output parameters.
  • SyncOperation- synchronizes values for multiple records based upon processing workflow defined in the XML request.
Request XML
<request version='1.0'>
  <header>
    <office/>
    <user/>
    <password/>
  </header>
  <insert>
    <Contact>
      <LastName>Ackerman</LastName>
      <FirstName>Joseph</FirstName>
      <MiddleName>M</MiddleName>
      <Title>Dr</Title>
      <TaxID>559658750</TaxID>
      <Person>
        <Dob>1950-02-27</Dob>
        <Gender>1</Gender>
        <Occupation>Medical</Occupation>
        <JobTitle>Chief Of Staff</JobTitle>
        <Marital>1</Marital>
        <Salary>150000</Salary>
      </Person>
      <PreferredPhone>
        <AreaCode>626</AreaCode>
        <Number>5853505</Number>
      </PreferredPhone>
    </Contact>
  </insert>
</request>

Response XML
<response version="1.0">
  <header>
    <sessionClosed/>
  </header>
  <insert>
    <Contact _status="inserted" _type="obj" id="Contact.1.31">
      <PreferredPhone _status="inserted" _type="obj" id="Phone.1.16"/>
    </Contact>
  </insert>
  <_status>OK</_status>
</response>

Referring Objects/Properties

SmartIntegrator provides an option to refer objects/properties in the same request. In the request, use the refid attribute to assign a reference ID to an object. Then refer to the object elsewhere in the request using the @ symbol followed by the reference ID (e.g., @ReferenceID). To refer to a property of an object, use @ReferenceID.PropertyName.

Using @ReferenceID without the property name retrieves the object ID.

Example:
<request version='1.0'>
  <header>
    <office/>
    <user/>
    <password/>
  </header>
  <insert>
    <Contact refid="john">
      <LastName>Doe</LastName>
      <FirstName>John</FirstName>
      <Title>Dr</Title>
      <TaxID>559658750</TaxID>
      <Person>
        <Dob>1950-02-27</Dob>
      </Person>
    </Contact>
    <SmartPad>
      <Keywords type="ref">@john.TaxID</Keywords>
      <Note>How are you?</Note>
      <ContactID type="ref">@john</ContactID>
    </SmartPad>
  </insert>
 </request>

Response XML
<response version="1.0">
  <header>
    <sessionClosed/>
  </header>
  <insert>
    <Contact id="Contact.1.33" _type="obj" refid="john" _status="inserted"/>
    <SmartPad id="SmartPad.1.36" _type="obj" _status="inserted"/>
  </insert>
  <_status>OK</_status>
  <_systime>2015-06-03T17:15:11</_systime>
  <!-- Cost 65 mill seconds. -->
</response>

SampleSmartIntegratorPostHTML

Storing Contact Identifiers in SmartOffice

You can create your own unique identifiers (or "keys") for SmartOffice contacts and store them in the SmartOffice database. You can then send search requests containing these keys to XMLEngine to retrieve the corresponding SmartOffice contact object IDs. SmartOffice has a ContactExtLink object for storing these keys.

The following example shows how to store a unique ID for an existing SmartOffice contact using the InsertOperation. Note the following:
  • You should populate the ExtLinkSource property with the name of your company or application.
  • The ExtLinkContactId property is where you put the unique key itself.
  • The CreatedById refers to the SmartOffice user who is creating the ID. This property does not affect the request but is still required.
Request XML
<request version='1.0'>
    <header>
        <office>myoffice</office>
        <user>jdoe</user>
        <password>password</password>
    </header>
    <insert>
        <ContactExtLink>
            <ContactId>Contact.1.310</ContactId>
            <ExtLinkSource>MyService</ExtLinkSource>
            <ExtLinkContactId>1Os3Ki3Dt7</ExtLinkContactId>
            <CreatedById>User.1.1</CreatedById>
        </ContactExtLink>
    </insert>
</request>

Response XML
<response version="1.0">
    <header>
        <sessionClosed /> 
    </header>
    <insert>
        <ContactExtLink id="ContactExtLink.1.1" _type="obj" _status="inserted" /> 
    </insert>
    <_status>OK</_status> 
    <_systime>2016-11-07T19:50:30</_systime> 
    <!-- Cost 65 mill seconds. --> 
</response>

Once you have associated your key with a SmartOffice contact record, you can send that key as part of a SearchOperation request to retrieve the corresponding SmartOffice contact’s object ID.

The following example uses the key created above to retrieve the contact’s SmartOffice object ID. Note that the expression containing the ExtLinkContactId property is commented out. This is because that property is not currently searchable and will return an error. Your application will need to parse the response for the record with the matching key.

Request XML
<request version='1.0'>
    <header>
        <office>myoffice</office>
        <user>jdoe</user>
        <password>password</password>
    </header>
    <search>
        <object>
            <ContactExtLink>
                <ContactId/>
            </ContactExtLink>
        </object>                      
        <condition>
            <expr prop='ExtLinkSource' op='eq'>
                <v>MyService</v>
            </expr>
            <!-- <expr prop='ExtLinkContactId' op='eq'>
                     <v>1Os3Ki3Dt7</v>
                 </expr> -->
        </condition>
    </search>
</request>

Response XML
<response version="1.0">
    <header>
        <sessionClosed/>
    </header>
    <search total="1" searchid="" pagesize="2000" more="false" page="">
        <ContactExtLink id="ContactExtLink.1.1" _type="obj">
            <ContactId>Contact.1.310</ContactId>
        </ContactExtLink>
    </search>
    <_status>OK</_status>
    <_systime>2016-11-07T19:54:47</_systime>
    <!--Cost 28 mill seconds.-->
</response>

Impersonation Mode

SmartOffice allows you to create a single set of user credentials on the server that, through Impersonation Mode, can be used to work on behalf of every other user in the system. This is extremely powerful access and should only be used to connect a system you are sure you can trust to SmartOffice.

To use Impersonation Mode you first have to create the credentials as a special User Account. This can only be done from the "system" Office. Click on the Integration User Setup item in the Setup side menu.

You can then click on the Add button and save a new Integration User with a User Name and a Password of your choosing. Again, for a production system these credentials need to be kept very secure. These credentials allow more access to data than the User Account that created them.

SmartIntegrator requests that use these credentials can retrieve "system" Office data like any "system" Office user. For example, you can use these credentials to retrieve the complete listing of Office Names and User Names on the system:
<request version='1.0'>
    <header>
        <office>systemQA4</office>
        <user>EbixCentral</user>
        <password>abc123</password>
    </header>
    <search>
        <object>
            <Office>
                <OfficeName/>
                <Users>
                    <User>
                      <UserName/>
                    </User>
                </Users>
            </Office>
        </object>
    </search>
</request>


<?xml version="1.0" encoding="UTF-8"?>
<response version="1.0">
    <header>
        <sessionClosed/>
    </header>
    <search total="552" searchid="" pagesize="2000" more="false" page="">
        <Office id="Office.1" _type="obj">
            <OfficeName>SYSTEMQA4</OfficeName>
            <Users _type="objs">
                <User id="User.1.1" _type="obj">
                    <UserName>ALLUSERS</UserName>
                </User>
                <User id="User.1.2" _type="obj">
                    <UserName>admin</UserName>
                </User>
                <User id="User.1.76" _type="obj">
                    <UserName>EbixCentral</UserName>
                </User>
            </Users>
        </Office>
        <Office id="Office.3" _type="obj">
            <OfficeName>KAPIL1QA4</OfficeName>
            <Users _type="objs">
                <User id="User.3.1" _type="obj">
                    <UserName>ALLUSERS</UserName>
                </User>
                <User id="User.3.2" _type="obj">
                    <UserName>admin</UserName>
                </User>
            </Users>
        </Office>
...
        <Office id="Office.1001523728" _type="obj">
            <OfficeName>filiqa4</OfficeName>
            <Users _type="objs">
                <User id="User.1001523728.1" _type="obj">
                    <UserName>ALLUSERS</UserName>
                </User>
                <User id="User.1001523728.2" _type="obj">
                    <UserName>franklin</UserName>
                </User>
            </Users>
        </Office>
...
        </search>
    <_status>OK</_status>
    <!--Cost 2434 mill seconds.-->
    <!--Warning!!! Missing parameter 'AppName' in connection URL.-->
</response>

Now that we know all the Office Names and User Names, we can start impersonating those users through SmartIntegrator to work on their behalf. In the operation object add an "office" parameter populated with the Office Name you want to work in and a "user" parameter populated with the User Name you want to work on behalf of.
<request version='1.0'>
    <header>
        <office>systemQA4</office>
        <user>EbixCentral</user>
        <password>abc123</password>
    </header>
    <search office="filiqa4" user="franklin">
        <object>
            <Contact>
                <LastName/>
                <FirstName/>
            </Contact>
        </object>
        <condition>
            <expr prop='LastName' op='starts'>
                <v>A</v>
            </expr>
        </condition>
    </search>
</request>

<?xml version="1.0" encoding="UTF-8"?>
<response version="1.0">
    <header>
        <sessionClosed/>
    </header>
    <search total="8" searchid="" office="filiqa4" pagesize="2000" more="false" page="" user="franklin">
        <Contact id="Contact.1001523728.15" _type="obj">
            <LastName>Ackerman1</LastName>
            <FirstName>Joeshep1</FirstName>
        </Contact>
        <Contact id="Contact.1001523728.16" _type="obj">
            <LastName>Anderson</LastName>
            <FirstName>Philip</FirstName>
        </Contact>
        <Contact id="Contact.1001523728.18" _type="obj">
            <LastName>Ackerman</LastName>
            <FirstName>Joeseph</FirstName>
        </Contact>
        <Contact id="Contact.1001523728.20" _type="obj">
            <LastName>ARAUJO</LastName>
            <FirstName>WILLIAM</FirstName>
        </Contact>
        <Contact id="Contact.1001523728.23" _type="obj">
            <LastName>Ackerman</LastName>
            <FirstName>Joseph</FirstName>
        </Contact>
        <Contact id="Contact.1001523729.12" _type="obj">
            <LastName>Ackerman</LastName>
            <FirstName>Joeshep</FirstName>
        </Contact>
        <Contact id="Contact.1001523729.14" _type="obj">
            <LastName>Anderson</LastName>
            <FirstName>Phil</FirstName>
        </Contact>
        <Contact id="Contact.1001523729.15" _type="obj">
            <LastName>Ackerman</LastName>
            <FirstName>Joiye</FirstName>
        </Contact>
    </search>
    <_status>OK</_status>
    <!--Cost 2289 mill seconds.-->
    <!--Warning!!! Missing parameter 'AppName' in connection URL.-->
</response>

FAQ's

What is the URL of SmartIntegrator XmlEngine on my server?

It is always the base SmartOffice URL with /xmlengine at the end. So, if you sign in to SmartOffice and see the URL https://mysmartoffice4.ez-data.com/index.htm?trustedWindow=1 then the SmartIntegrator REST Service URL is https://mysmartoffice4.ez-data.com/xmlengine.

Do you have a WSDL?

The xmlengine servlet is a REST Service where everything is posted as XML and there is no WSDL. A REST Service provides more flexibility in the features and accessibility to a large data model like ours as opposed to a SOAP Web Service that would have a WSDL. We have chosen to sacrifice interoperability for flexibility.


-- Main.dustin - 24 Oct 2012

<request version='1.0'> <header><office/><user/><password/> </header> <insert><Contact refid="john"><LastName>Doe</LastName><FirstName>John</FirstName><Title>Dr</Title><TaxID>559658750</TaxID><Person><Dob>1950-02-27</Dob></Person></Contact><SmartPad><Keywords type="ref">@john.TaxID</Keywords><Note>How are you?</Note><ContactID type="ref">@john</ContactID></SmartPad> </insert> </request>
Topic revision: 11 Nov 2016, 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