Embedding Widgets

To provide end users with a seamless integration experience, you will embed the Widget Manager directly within a hosting web application. This allows users to seamlessly setup and manage their integrations directly within your application without having to link to another web site, re-authenticate, etc. The hosting application is responsible for identifying the Widget Manager "tenant" and enforcing user access restrictions to the Widget Manager interface if desired.

As of the June 8, 2011 release, the API-based approach to embed Widgets described in this article replaces the previous URL-generation approach described here. Please use this approach for all new Widgets. You should update your application's embedding code for existing Widgets as soon as is convenient.

In this article:

Important Concepts

Embedding a Widget Manager within a web application is a minimally invasive, UI-level integration. The complete Widget Manager user interface is served from the AtomSphere platform so the embedding application simply needs to make a few API calls to the AtomSphere platform to retrieve a customer-specific Widget URL and then render that URL within an <iframe> on the page. There are no proprietary AtomSphere components or libraries that must be installed on the embedding application's servers.

The work flow for the embedding application is as follows:

1. Obtain the Partner User ID from the current page's session or context to identify the current tenant or user.
2. Make an AtomSphere API call to retrieve any existing Widget instances for the given Partner User ID.
3. If no instances currently exist, make a second AtomSphere API call to generate a URL and optionally specify Process Extension overrides. Otherwise go to the next step.
4. Populate the <iframe> tag with the URL returned from the API call, along with the Account Name and Email Address.

The AtomSphere API supports both SOAP and RESTish web services styles. Examples below use the SOAP API.

Prerequisites

• The AtomSphere API must be enabled for the AtomSphere account in which you are developing the Widget.
• Have or create an AtomSphere User that has the AtomSphere API permission.

Steps to Embed a Widget Manager

Step 1 - Obtain the Partner User ID

The Partner User ID is a unique value that is used to identify the end customer's specific Widget Manager instance. For most integration scenarios, this value will be that of the end user's instance or tenant of the embedding application (e.g. Account Number, Tenant ID, Organization ID, etc.), not the actual end user itself. The specific value to use and logic to obtain this value will vary for each embedding application.

See Understanding Widget User Management for more information about Partner User IDs.

Step 2 - Query for Widget Instances

The purpose of this step is to query if a Widget instance already exists to determine if you need to make a second call to retrieve a new Widget instance URL. If no instances currently exist, you will proceed to Step 3. Otherwise, you will take the URL returned and proceed to Step 4.

See Understanding Widget Manager Overrides below for more information.

Notes:

• If your Widget Manager has multiple Widgets assigned, you can optionally include a Widget ID to the getWidgetList request to query for an instance of a specific Widget.
• The Widget Install Mode setting for your Widget Manager will also dictate how many instances can be installed. See Widget Managers for more information.

Use the getWidgetList API to return a list of Widget instances for the given Widget Manager and Partner User ID. This will return the Widget Manager URL and zero or more Widget instances.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.platform.boomi.com/">
   <soapenv:Header>
   ...
   </soapenv:Header>
   <soapenv:Body>
      <api:getWidgetList>
         <api:managerId>WIDGET MANAGER ID</api:managerId>
         <api:partnerUserId>PARTNER USER ID</api:partnerUserId>
         <!--Optional:-->
         <api:widgetId>WIDGET ID</api:widgetId>
      </api:getWidgetList>
   </soapenv:Body>
</soapenv:Envelope>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:getWidgetListResponse xmlns:ns2="http://api.platform.boomi.com/">
         <ns2:result url="WIDGET MANAGER URL">
            <ns2:widget instanceId="WIDGET INSTANCE 1 ID" id="WIDGET ID"/>
            <ns2:widget instanceId="WIDGET INSTANCE 2 ID" id="WIDGET ID"/>
         </ns2:result>
      </ns2:getWidgetListResponse>
   </S:Body>
</S:Envelope>

Step 3 - Generate Override URL for New Instances (Optional)

The purpose of this step is to generate a URL for new instances that contains Widget Manager Override values for the Widget's Process Extensions values and brings the end user directly into the install wizard. This step only needs to be performed if you want to perform a new Widget installation with Widget Manager Overrides.

See Understanding Widget Manager Overrides below for more information).

During initial development you can use the getWidgetExtensionsTemplate API to retrieve the set of Process Extensions defined for the Widget. You will use this API in an ad hoc fashion while developing your embedding code to obtain the specific Connection IDs, Connection field names, and Process Property names to reference in the generateWidgetUrl request. Be careful to ensure the actual values you are providing are valid and expected for your underlying integration Process. Note that you will not use this call in your actual embedding work flow that is executed every time the Widget Manager is rendered.

Use the generateWidgetUrl API to provide a set of extension override values to be used in a new Widget instance. This will return the Widget Manager URL with overrides.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.platform.boomi.com/">
   <soapenv:Header>
   ...
   </soapenv:Header>
   <soapenv:Body>
      <api:generateWidgetUrl>
         <api:managerId>WIDGET MANAGER ID</api:managerId>
         <api:partnerUserId>PARTNER USER ID</api:partnerUserId>
         <api:widgetId>WIDGET ID</api:widgetId>
         <api:widgetExtensions>
            <!-- Optional -->
            <api:connections>
               <!-- One or more connections -->
               <api:connection id="CONNECTION COMPONENT ID">
                  <!-- One or more fields -->
                  <api:field id="CONNECTION FIELD ID" value="SOME VALUE"/>
               </api:connection>
            </api:connections>
            <!-- Optional -->
            <api:properties>
               <!-- One or more properties -->
               <api:property name="PROCESS PROPERTY NAME" value="SOME VALUE"/>
            </api:properties>
         </api:widgetExtensions>
      </api:generateWidgetUrl>
   </soapenv:Body>
</soapenv:Envelope>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:generateWidgetUrlResponse xmlns:ns2="http://api.platform.boomi.com/">
         <ns2:result>WIDGET MANAGER URL</ns2:result>
      </ns2:generateWidgetUrlResponse>
   </S:Body>
</S:Envelope>

Step 4 - Populate <iframe> Tag

The last step is to populate an <iframe> tag with the Widget URL obtained in the previous steps.

<html>
    <body style="margin: 0px;">
        <iframe src="<WIDGET MANAGER URL>?accountName=<ACCOUNT NAME>&emailAddress=<EMAIL ADDRESS>" style="border: 0px solid #ffffff" width="100%" height="100%" />
    </body>
</html>

Understanding Widget Manager Overrides

If desired, the embedding application can provide dynamic installation values to override any of the Process Extensions defined within the Widget. These override values are only applicable when installing new Widget instances and do not affect the Process Extension values for existing Widget instances.

The Widget Manager Overrides will override default values specified by the Widget developer as part of the Widget wizard configuration, however the end user may subsequently modify them if the fields are exposed in the Widget wizard.

There are several situations when you may want the embedding application to provide Process Extension values at install-time:

• Environment-specific Connection or Property values - For example, if you want to control the web services endpoint to which the integration connects based on whether the Widget Manager is embedded within a "test" or "production" environment of the embedding application, you could override the Connection endpoint with the "test" or "production" URL, respectively.
• Common and/or private Connection credentials - For example, if your integration scenario includes sending customers' data to the same FTP or web service endpoint with the same credentials that you do not want to share with end customers, you could predefine those Connection values in the embedding application and pass them into the Widget installation automatically. Note: You need to use the Widget Manager Overrides instead of configuring the common values in the underlying Process component to properly encrypt the password fields for the resulting Widget instance AtomSphere Accounts.
• Proprietary input screens - For example, if you want the embedding application to capture certain Connection or Property values outside of the Widget wizard interface, you can obtain those values and pass them into the Widget installation automatically.

If there are Process Extensions you need to set per Widget instance but you do not want to expose them to the end user (perhaps they contain sensitive information or are simply unnecessary or technical in nature), you can omit those Fields from the Widget wizard panels and then use Widget Manager Overrides to set their values.

Widget Styling

When embedding a Widget, you will probably want the Widget Manager interface to complement your hosting application to provide the appearance of a unified solution. Widget Manager Styling allows you to use the flexibility of CSS to customize the look-and-feel of the Widget Manager to match the styles used within the embedding application.

Tips for Multiple Widget Solutions

For partners wishing to offer multiple, mutually exclusive integration solutions to end customers, it is recommended to deliver each solution in a separate Widget Manager (with a single Widget assigned). Then you will employ logic in the hosting application to determine which Widget Manager to render based on user input and/or proprietary tenant permissions/licensing you have put in place.

Security and User Access

The end user does not need to login or re-authenticate to access the embedded Widget Manager. It is assumed the user is already successfully logged into the embedding application.

The Widget Manager does not provide varying levels of user-based permissions. This means if a user has access to the Widget Manager, that user can perform any of the functions available in the Widget Manager interface including view activity, changing configuration, and creating and deleting Widget instances. It is the responsibility of the hosting application to restrict access to the page where the Widget Manager is embedded as necessary. For example, you may wish to only grant access to the integration configuration to "administrator" or "power" users.

See also:

• Widget Managers
• Understanding Widget User Management