The XML Engineis 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 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 NoteXmlEngine: You can send requests directly to XML Engine to access data in your own SmartOffice database. However, to access the databases of SmartOffice customers outside of your organization, you must send your requests through the SmartXchange proxy, which involves enclosing your XML Engine requests in special tags. For more information, see functionality: SmartXchange.
Examples of XML Engine use cases:
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. 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.
Important: The XML Engine URL is for sending requests for data stored in your own SmartOffice database. To send requests for data stored in the databases of SmartOffice customers outside of your organization, use the appropriate SmartXchange proxy URL instead. For more information, see SmartXchange.
The URL for sending requests directly to XML Engine on a particular server is the base SmartOffice URL with /xmlengine appended at the end.
For example, if you sign in to SmartOffice and see the URL https://mysmartoffice4.ez-data.com/index.htm?trustedWindow=1 then the SmartIntegrator XML Engine REST Service URL is https://mysmartoffice4.ez-data.com/xmlengine.
To complete the URL, you must also append the AppName provided to you by Ebix as a query string parameter. Example: https://mysmartoffice4.ez-data.com/xmlengine?AppName=YourAppName
In addition, when posting requests directly to XML Engine, you must pass the registration key provided to you by Ebix in the HTTP headers of your request. Use the regKey parameter for this purpose. One way to do this is to add the regKey attribute to the META tags. Example:
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" regKey="r5f6a412091c879cadfx0d15959b948bb5326c7efc8cef94">
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 SmartOffices 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.
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>
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>
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:
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 contacts object ID.
The following example uses the key created above to retrieve the contacts 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>
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>
What is the URL of SmartIntegrator XML Engine on my server?
It is 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 XML Engine REST Service URL is https://mysmartoffice4.ez-data.com/xmlengine.
Note that you must also append the AppName? provided to you by Ebix as a URL parameter. Example: https://mysmartoffice4.ez-data.com/xmlengine?AppName=YourAppName
In addition, when posting requests to XML Engine, you must pass the registration key provided to you by Ebix in the HTTP headers of your request. Use the regKey parameter for this purpose.
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.
SmartOffice Development Kit | |||||||
SmartIntegrator | Overview | FAQ | |||||
Adapters | When to Use | Creating Adapters | Menu Links | Testing | |||
XML Engine | Using the API | Object Referral | FAQ | ||||
Operations | INSERT | UPDATE | DELETE | GET | SYNC | SEARCH | METHOD |
SmartXchange | Proxy Users | Request/Response | |||||
Single Sign-On | SAML SSO | Code Requirements | Outbound | Inbound | Deep-Links | ||
Vendor Partnership | Architecture | Licensing | Security | Support | Certification | FAQ | |
Tools | TestBed | Data Dictionary | Column IDs | ||||
-- 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>