Widget wizards are the series of panels with various content and input fields that will guide end users in setting up your Widget. You have control over the content on each panel as well as the sequence of panels.
You can customize the look-and-feel of the Widget to seamlessly embed within a hosting application.
In this article:
Important Concepts
Be sure to fully understand the relationship between Processes, Extensions, and Widgets described in the Getting Started with Widgets section.
The Widget wizard configuration resides within a Process component. This ensures the various Connection field, Process Property, and Map Extension references in the wizard are in sync with those configured in the Process.
This also means the Widget is tied to a single Process, not multiple Processes. If your integration scenario requires multiple Processes, you should adopt a parent/child Process design. The Widget would then be configured in the parent Process only.
The input fields available to the Widget configuration come from the Extensions defined in the Widget's underlying Process only. Again, if your integration scenario includes child Processes, you will need to define the Extensions for all the appropriate parent and child Process' Connection fields, Process Properties, Maps, etc. in the parent Process. Any Extensions defined in the individual child Processes will effectively be ignored by the Widget configuration. Note: You can and in most cases will have Extensions defined (even the same Extensions) in the child Processes for use during testing.
You will typically only need to create one Widget wizard for a given Process. However, it is possible to create multiple Widgets on top of the same Process. An example of when you might want to do this is if you wanted to offer multiple versions/tiers/price points of your Widget, maybe a "lite" version with minimum configuration options and reduced functionality and a "premium" version with more options and broader functionality.
Another important thing you will configure in the Widget wizard is whether the Widget's Atom will be deployed locally or to the Cloud. This depends on the specific applications connected in your integration. If your integration connects to on-premise applications, the Widget must be deployed locally; if all the applications are web-based, it could be deployed to the Cloud.
Make the wizard steps as simple as possible for your end users. Minimize the number of panels and input fields and provide help text and descriptions to guide users and reduce support calls.
Creating Widgets
To create a new Widget wizard:
- Open an existing Process.
- Click Widgets above the canvas.
- Click the Add icon. The Widget will automatically generate the standard panels as well as panels for the Connection and Process Property Extensions you defined in the Process.
- Configure the various properties, panels, and fields as desired.
- When finished, click OK and save the Process.
Then to view and test the Widget, you will need to deploy the Process and then assign the Widget to a Widget Manager.
See Modifying Widget Wizard Content below for more information.
Editing Widgets
To edit an existing Widget, within the Process click Widgets, select the Widget and click the Edit icon above the list. Make your changes and when finished, click OK and save the Process.
Remember for the changes to be available to end users, you need to deploy the Process and update the Widget assignment for the Widget Manager with the new deployment version.
Deleting Widgets
To delete an existing Widget, within the Process click Widgets, select the Widget and then click the Delete icon above the list.
 | Important
You should never delete a Widget than has been installed by end users. Although deleting the Widget wizard will not affect end users by deleting or removing their installed Widget instances, you will not be able to update their instances going forward. |
Modifying Widget Wizard Content
When the Widget is first generated, for convenience a number of panels and fields are automatically generated based on the Process' Extensions. By default a panel is created for each Connection with Extensions, for each Map Extension, a single panel for the Process Extensions, and a single panel for Scheduling. From there you can modify, rearrange, add, and remove panels and fields as desired, with a few exceptions noted below.
To rename the Widget, edit the "Title" under Widget Properties to the right, and click Apply Changes
Note: Any changes you make to the Widget are not saved until you save the Process. Simply clicking OK does not save your work.
Working with Panels
To modify a panel's properties or content, select the panel from the list on the left. To rename a panel, edit the "Label" under Panel Properties to the right, and click Apply Changes. You can modify the panel's content in the middle section. See Working with Fields for more information.
To add a new panel, click the Add icon next to Widget Panels.
To remove a panel, select the panel and then click the Delete icon next to Widget Panels.
To change the sequence of the panels, select one and use the Move Up/Move Down buttons.
Widgets do not currently support conditional panel sequencing.
Predefined Panels
There are several auto-generated and required panels that you must include in your Widget.
Introduction
The first panel in your Widget should be an introductory one that describes what your Widget does and any other pertinent information.
License
This panel should contain or link to your license agreement and/or terms and conditions.
Scheduling
This panel allows end users to configure a schedule for their integration to run automatically.
Installation
This panel must always be the last panel in your Widget. It contains a single special "installer" field with several important options:
| Field |
Description |
| Installation Type |
This indicates whether the Widget will be deployed locally or to the AtomSphere Cloud. Which value to choose depends on the applications in your integration: if your integration connects to on-premise applications, the Widget must be deployed locally; if all the applications are web-based, you could choose to deploy it to the Cloud.
If "In the Cloud", you can choose to which Cloud to deploy. The majority of Cloud-based Widgets will use the Boomi AtomSphere Cloud. Partners who have provisioned their own private Clouds will see their Cloud in the list. |
| Install |
If Installation Type is "Local", choose whether the Atom is installed as an NT Service (default) or in Desktop Mode only. Desktop Mode is really only required for integrating with client-only applications such as QuickBooks and Peachtree. |
The Installation Type can be modified after creation. For Cloud-based integrations, you may find it easier have the Widget deployed locally during development and testing for debugging purposes. Once it is stable, switch the Installation Type to "In the Cloud" and redeploy.
Working with Fields
To modify the content and fields for a given panel, select that panel in the list along the left side. The current content is displayed in the middle section under "Widget Panel Fields". To configure a particular field, select the field to display its properties to the right. Make any changes as desired and click Apply Changes.
To add a new field, click the Add icon next to Widget Panel Fields, and choose a field type. See Widget Panel Field Types below for more information.
To remove a field, select the field and then click the Delete icon next to Widget Panel Fields.
To move a field up or down in the panel, select the field and use the Move Up/Move Down buttons.
Widgets do not currently support the ability to conditionally show/hide fields based on the values of other fields.
Widget Panel Field Types
You can add a number of different types of content to Widget panels.
| Types |
Description |
| Text |
Adds a text area. You can use basic HTML markup to perform simple formatting. For advanced formatting, see Widget Manager Styling.
Supported tags: <b>, <i>, <strong>, <em>, <p>, <br>, <a>, <image>, <ol>, <ul>, <li> |
| Image |
Adds an image. To reference an image, you must enter a URL location. These means the image must be hosted and publicly available. You cannot upload images to AtomSphere. |
| Separator |
Adds a horizontal rule to help divide sections. No additional configuration. |
| Field |
Opens a dialog to choose a Property Field or Special Field to add. Property Fields include Connection and Process Property Extensions. |
| Map |
Adds a Map configuration section. See Map Fields for more information. |
| Cross Reference |
Adds a Cross Reference configuration section. See Cross Reference Fields for more information. |
| Schedules |
Adds a Schedule configuration section. You should only have one Schedule field for a given Widget. Add the Schedule field to its own panel. |
Property Fields
The Property Field chooser dialog displays a list of the Connection and Process Property Extensions defined for the Process. The icon next to each property indicates whether or not the property has been added to a panel yet. Simply click the field name to add it to the current panel. (Note: to cancel out of the chooser dialog, click Close icon in the upper right corner.)
Once added to the panel, select the field to display its properties below. Make any changes as desired and click Apply Changes.
| Property |
Description |
| Type |
- String - Regular text field. Value entered is passed as-is to Process at runtime.
- Number - Text field that only allows numeric characters. Value entered is passed as-is to Process at runtime.
- Boolean - Check box. Value passed to Process at runtime will either be "true" or "false".
- Date - Date picker. Value passed to Process at runtime will be in the format: "yyyy-MM-dd'T'HH:mm:ss'Z'".
- Password - Text field with obfuscated values. Note the value is not actually encrypted and will passed to the Process as plain text. Important: Password-type fields for Connector extensions ARE encrypted.
|
| Required |
If checked, the end user must enter/choose a value for this field. Not applicable for Boolean types. |
| Label |
Label the end user will see for this field. |
| Help Text |
Help text to display when end user focuses on this field. |
| Default Value |
Default value that will be entered in the field during initial Widget setup. |
| Allowed Values |
Use the Add/Edit/Delete icons to modify the list of allowed values. If at least one item is entered, the field will be rendered as a dropdown list to the end user. For each item, specify a user-friendly label and the actual value that will be passed to the Process at runtime. Not applicable for Boolean and Password types. |
Note: the Type and Required properties for Connection Extensions are defined by the Connector and are often not editable.
Connection and Process Property Extensions defined after the Widget has been created are not automatically added. You will need to modify the Widget and add the new fields manually.
Map Fields
Map fields represent a customization of a specific Data Map Extension defined in the Process. Map fields allow the end user to customize a mapping between two objects as defined in the Data Map and Object Definition Extensions. Depending on the application Connector used in the map, the wizard will dynamically browse the end user's specific application instance to retrieve their custom fields that can then be configured in the mapping.
Upon initial Widget creation, a panel for each Data Map Extension will be created for you automatically. If you define new Data Map Extensions later, you will need to create a panel and add the Map field manually. Add each Map field to its own panel.
Once added to the panel, select the field to display its properties below. Make any changes as desired and click Apply Changes.
| Property |
Description |
| Label |
Emphasized text at the top of the mapping panel. |
| Description |
Longer text description. |
| Source |
Column header above source object's fields. |
| Destination |
Column header above destination object's fields. |
Cross Reference Fields
Cross Reference fields represent a customization of a specific Cross Reference Table Extension defined in the Process. Multiple Cross Reference fields may be added to a single wizard panel. They are rendered as collapsible sections to minimize UI real estate.
Once added to the panel, select the field to display its properties below. Make any changes as desired and click Apply Changes.
| Property |
Description |
| Label |
Name of Cross Reference to be disabled in the section header. |
| Description |
Longer text description to be disabled within section. |
Special Fields
QuickBooks Company File Detector
The field simplifies configuration for QuickBooks desktop integrations by automatically connecting to the user's desktop to interrogate their QuickBooks application and retrieve the full path to the company file. This requires a) the user run the Widget wizard from the PC/server where the QuickBooks client is installed, and b) the desired QuickBooks company is currently open and the Administrator user is logged in under Single User Mode.
This field is only available if your Process contains a QuickBooks Connection and the "Company File Path" property is extended.
See also:
This page
Other pages
Account
