Widgets must be enabled in your AtomSphere account. Contact your Boomi sales rep for more information.

Part 2 - Using Process Properties as "Preferences"

This article builds on the Widget built in Part 1 and shows you how to use Process Property Extensions as "preferences" to add sophistication and flexibility to your Widget.

But first, what's the use case for "preferences"?

Because Widgets are built on top of Processes, the base configuration and work flow is static. However there are often integration scenarios where there are two legitimate ways to do something, and it really depends on the end user's specific needs. To accommodate these scenarios, you can build both work flows into your Process and let the user choose which one they want during the Widget setup.

Here are some examples to get you thinking:

• Allow/disallow optional behavior, such as sending notifications or performing updates to existing records
• Execute/skip Process Calls to only integrate certain object types
• Provide customer-specific values such as default record types or GL accounts
• Enter a starting date from which to extract records

Prerequisites: Before creating Widgets, you should be familiar with general Process development, Process deployment, Process Properties, and Process Extensions.

1. Build conditional paths in the Process

Let's say we received feedback from some users who wanted the ability to export the raw XML data returned from Salesforce in addition to the CSV file. However, we think many users won't care or want the XML files. Both scenarios are valid so we decide to give each user the choice during Widget setup.

We can do this by using a Decision step in the Process that inspects a Process Property whose value will be set by the user in the Widget Wizard. The Process will now look something like this:

Branch to write out CSV file first, Decision to inspect property, Set Props to name XML file, write to same Disk connection

Let's take a closer look at the Decision step. Thinking ahead, we want to expose this option to the user as a check box to enable/disable writing the raw XML files to disk. The Decision step will then compare a Process Property ("PREF_EXPORT_XML") to a static value of "true" (check box values are either "true" or "false"). Note the Process Property name is completely arbitrary, but it's recommended you use a naming convention to help yourself. In this example, the property name is all caps with a prefix to make it easier to retype and self-describing, and to distinguish it from any other Process Properties that may be used in the Process.

2. Define the Extension

Now we need to define that Process Property as extensible so its value can be specified at deploy-time, i.e. by the end user. From the Process editor, click Extensions along the top and go to Process Properties. Enter the Process Property name and click Add. Be sure to type carefully, as this name must match the one configured in the Decision step exactly.

When finished, click OK and save the Process.

More on Process Extensions...

3. Add the new field to the Wizard

For the new Extension to be displayed to the end user, we need to add it to the Wizard. From the Process editor, click Widgets along the top, select your Widget, and click the Edit button above.

Let's add a new panel for our preferences. Click the Add button next to Widget Panels on the left and name it "Preferences". Now let's add some fields to the panel. Select the new "Preferences" panel, Click the Add button next to Widget Panel Fields, select Text type and enter a descriptive message. Add another field, but this time choose Field type. Under the "Properties" section, click the unused property "PREF_EXPORT_XML". Select the newly added field to configure its properties to the right. Let's change the Type to "Boolean" to render the field as a check box and enter a more user-friendly Label.

Your Wizard will now look something like this:

Click OK and save the Process.

More on Designing Widget Wizards...

4. Deploy and assign the new version

Go to the Deploy tab and deploy the most recent version of the Process. Then go to the Embed tab, select the Widget Manager, click the Edit button under Actions next to the assigned Widget to the right, select the most recent deployment version, and click OK.

5. Edit the Widget instance and run it

Open the Widget Manager in a browser (open your bookmark or regenerate the URL with the same Partner User ID) and refresh the page. If you already installed a Widget in Part 1, go to the My Integrations tab, select your Widget instance and click Edit, and note the new Preferences tab, otherwise click Create on the Setup New Integration tab and go through the wizard.

Run the integration with and without the preference enabled and note the results.

More on Widget End User Experience...

Next Steps

Once comfortable with the Widget basics, get as sophisticated as you need to, adding complexity to your underlying Processes, defining additional Process Properties and Extensions, incorporating Process Calls, and adding more content to the Wizard panels. Check out the Widget Design Tips for guidance.

As always, start simple and iterate! Good luck!