SmartIntegrator Adapters

An Adapter is a package that creates side-menu links or buttons in SmartOffice, which when clicked execute scripted events. The goal of an Adapter is to introduce functionality into SmartOffice that is not supported by default, especially when data from a page needs to be posted to an external website or application. Clicking an Adapter-created button or link sends the request to SmartIntegrator, which relies on the contents of the package to fulfill the request.

To create an Adapter, it is necessary to have an understanding of XHTML, XSLTs, and possibly JavaScript?. While anyone can create an Adapter package, it will require installation by the SmartOffice team who will install it into the SmartIntegrator. Adapter-created links are context-sensitive; availability and functionality in SmartOffice are defined during Adapter creation. Once the Adapter is installed, users that have access (see Licensing) to the button or link can click it to trigger the predefined script, which usually passes data from the SmartOffice page to the JavaScript? inside the Adapter package.

When to Use an Adapter

The following are scenarios in which you would want to develop an adapter:
  • Posting data outside of SmartOffice.
  • Writing a file locally and launching it through the MIME type.
Examples of SI Adapter functionality:
  • The SmartOffice User selects a Contact in SmartOffice and clicks a button, which exports the Contact data to a file they can save/open on their machine.
  • The SmartOffice User selects a Contact in SmartOffice and clicks a button, which uses the Contact data in a web service call to another web application.
  • The SmartOffice User clicks a side-menu item, which opens up a new window for another website.

Creating an Adapter

If you are developing your own button you will need to generate a ZIP file which contains all of the different aspects of the button (location, image, functionality, etc…).

The ZIP file should contain 3 files (application.xml, template.xml, and transform.xslt), each of which has their own format and purpose in regards to the button.

The image for the button has to be added to the SmartOffice server by someone at Ebix. They will place the image into the correct folder which contains all other SmartOffice images.

We will discuss in detail each of the individual files necessary to create a button in order for you to understand how each plays a part in creating your own button.

Application.xml

The values in this XML file define where/how the button you create will appear and how it will function.

You can define the description text, as well as the tooltip text.

You also define whether the license that makes the button appear is allowed for all users in a particular office, or is for the entire SmartOffice system.

If you are having the button open another window, you can define the window size, title bar options, and other web browser content.

Template.xml

This file defines exactly what data the button is going to access from the SmartOffice database.

This information is “context sensitive” which means the data elements you put in this file will depend on where this button will go within SmartOffice (i.e. Contact screen, policy screen, side menu, etc…).

Use the Data Dictionary documentation to determine how objects/data elements should be placed.

For example, if you wanted to create a Google search button based on Contact information, you would need the Contact object along with First Name and Last Name data elements in order to have the correct data to search upon.

The data provided in this file will be used to create a new XML file based on the template, and it will apply the data to the transform.xml file discussed next.

Transform.xslt

This file is where the functionality of the button will be executed using the data applied from the template.xml file.

This will require you to understand a little about XHTML, XSLT, and possibly some JavaScript?.

The functionality is limited to whatever you are able to accomplish from this file, so the more knowledgeable about web programming the better off you will be.

Depending on the complexity of the button, you will have multiple functions that you can modify based on the complexity of your requirements for the button. This is where more programming knowledge you possess will come in handy.

Note: When referencing form element attributes in Transform.xslt, use both the "id" attribute and the "name" attribute as a best practice to ensure compatibility with all web browsers.

Image file

Once your zip file is ready to upload with the 3 files listed above, you are ready to also add your image to the combination.

The SmartOffice UI will prompt you for the correct image you will wish to use for your button creation.

Side Menu Items

In the event you want your adapter to be immediately accessible from anywhere within the SmartOffice system, you can instead add a link to one of the side menu categories which will operate the same as a button.

Since this adapter is a LINK and not an actual BUTTON, you won’t be required to add an image for it.

Side menu adapters are typically used when there are no context specific data elements required (i.e. Contact, Policy, Investment information).

These items are primarily used for data elements related to the User, or to just a general navigation/redirect function.

While side menu items should only be used for generic or User specific functionality requirements, it is still possible for there to be context specific data required for a side menu item. In this event the button creator should account for users clicking on the side menu link when on the wrong object (i.e. Account information is required, but the user is in a Policy object). Appropriate error handling should be established for these occurrences.

Unit Testing

Unit testing is a crucial part of any new development/addition to an existing platform.

It is important for all adapters to be tested thoroughly by both the creator, as well as actual users to ensure the button is operating correctly.

If you are hosting your own SmartOffice system, and you have administrator acces, you have the luxury of logging in and uploading your button as often as needed. In this case, you are responsible for development and unit testing. Sign in to the System office, select Setup > SI Adapter from the side menu and export/install/reinstall buttons from there.

If you are not hosting your own SmartOffice system you will be required to work with someone at Ebix in development and unit testing. Ebix will typically try to help you make the changes in order to speed up the overall process. We are not able to provide administrator access to any of our development partners.


Topic attachments
I Attachment Action Size Date Who Comment
Sample_SI_Local_File_Button.zipzip Sample_SI_Local_File_Button.zip manage 2.0 K 14 Aug 2012 - 01:23 DavidEshelbrenner Sample SI Adapter Button for Local Application
Sample_SI_Web_Service_Button.zipzip Sample_SI_Web_Service_Button.zip manage 2.1 K 14 Aug 2012 - 01:23 DavidEshelbrenner Sample SI Adapter Button for Web Service
Topic revision: 01 Jun 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