Author: Chris Cappetta
Introduction
Building a truly connected business doesn't just mean connecting systems together. It also means connecting people with the systems and processes.
A "message action" is the most common sort of integration call from Boomi Flow to another system, via Boomi Integration. Phrased differently - it is the most common method to connect a "human-layer" Boomi user interface with a "technology-layer" Boomi system integration.
This article, Flow package, and Integration process library asset provides a working example of this message action feature.
Assets and quick-setup instructions
Flow import token:
r3q8qk6sgnjQh27Yk/8/PAF4xHa+zSudWZlGfn2MuyO2jq22Vvq+RuADzCC3BCg/
More infoBasic runtime Process Library Sample:
Get the Processes Now!
Quick setup instructions:
(1) Import the Flow package to your Flow tenant, and import the process library sample to your Integration tenant.
(2) In Boomi Integration, you'll need to create a Flow Service component, because those components can not currently be shared in the process library.
(Tip: right-click > Open image in new tab to see any images full size)
(3) To most easily use the Flow package provided above, I recommend using the external name 'fssmessage' for your Flow service. If you use something else, for example if you're adding this action to an existing Flow service, you can modify that portion of the URL path when updating the service of the Flow you imported.
(4) In the Message Actions tab, Add Message Action. For the Name field use "MessageActionSample" and for the Process field select the Integration process named "Message Action Sample" (which is the process you imported from the Integration process library):
(5) The basic runtime Shared Web Server should have Basic auth and Intermediate API. The shared web server URL needs to be accessible to the cloud, so one of the public runtime clouds is often easiest. Deploy the Integration process and your newly created Flow Service component to your own basic runtime.
Tip - A lot of folks miss that the Flow Service component needs to be deployed. If you get an error like "No such path..." while installing the service on the next step, your culprit may be an un-deployed Flow Service component.
(6) In Boomi Flow - navigate to Services. Find and hit the Edit pencil on the "Basic runtime Message Service."
- Populate the appropriate basic runtime Shared Web Server base URL ahead of /fs/fssmessage (replacing https://connect.boomi.com if your basic runtime shared web server has a different base URL).
- Populate your username and token from the "User Management" tab of your basic runtime Shared Web Server.
- Finally, hit Update Service.
This should connect the imported Flow to your deployed copy of the Integration process. You should then be able to run your copy of the Flow to test the message action feature!
Deep dive into how the design works
The Integration Process
The Flow Service start step operation of the Integration process allows you to define whether the process supports a Message Action, a File Resource, or a Data Action. In the start step operation you are able to define a Request and a Response profile. These will always be JSON profiles, and the root of the profile will always be an Object. If data only needs to be moved in one direction (e.g. if you don't need input data to get the desired response from Integration) the un-necessary profile selection can be left empty.
The Integration profile entries will align with input and output bindings on the Flow message action, which are associated with Flow values by configuring the Message map element on a Flow canvas.
Entries in the request and response JSON profiles can be Simple, Object, or Array(Repeating). Array(Absolute) profile entries are not supported through this connector.
Simple profile entries can be Character, Number, Boolean, or Date/Time. Flow expects any Date/Time data in its request and response profiles to be a format of yyyy-MM-dd'T'HH:mm:ss.SSS'Z' .
Simple profile entries will not create a type in Flow upon installing or updating the service. Simple profile entries will show in the message action configuration itself. Many folks get confused looking for a type after installing a service with simple profile entries.
Conversely Object and Array(Repeating) profile entries nested within that "base level" root object of the JSON profile will automatically create a type in Flow when the service is installed or updated.
The screenshot below shows how the Flow message action bindings align with Integration JSON profile entries. The blue arrows are 'simple' JSON profile entries. Those align to Flow String, Number, Boolean and Date/Time values. Conversely the yellow arrows are Object and Array(Repeating) JSON profile entries. The yellow arrows are where the platform will (1) automatically generate a type when the Flow Service is installed and (2) align to Flow object and list values respectively.
(Reminder - to see full-size right click > open image in new tab)
You can use Character, Number, Date/Time, and Boolean entries within these "complex" array or object profile entries. The "entries" in an basic runtime profile array or object will align with the "properties" in the Flow type.
In theory you can nest layers of a profile indefinitely (e.g. to include list of data within each record of a returned list), but the Flow UI only supports the 'first level' types. Additional layers would need to be manipulated at the code level.
When configuring an object or array entry in the Integration profile, bear in mind that the Flow type names and message action binding names will be automatically sourced from the names you use in your Integration JSON profiles. The best practice is to give all "layers" of that object or array entry the same name, and to do so before installing the service in Flow for the first time. If you don’t use these naming practices, your types will still be created but will be generated within Flow with a name like MyProcessName REQUEST Object_1.
The correct configuration will appear as 2 layers for an object, 4 layers for an array; as can be seen in the image below.
If an Array(repeating) in a profile you've configured isn't working and only has three 'layers' instead of the four shown in these screenshots, it's likely that you have a simple entry within the Array(Repeating) portion of the profile. You would need to modify that auto-generated simple array entry to be an object.
The screenshot below shows an example of how the Integration object and array profile entires align to Flow types.
Concept deep dive:
Flow handles its types by name rather than by an underlying target-system-specific unique identifier. This enables powerful functionality around redirecting a service between multiple like-copies of a data source (e.g. when cloning the Flow into new tenants or projects, when setting up dev/prod systems of record, and even changing the integration behavior based on runtime rules during an in-flight workflow). The trade-off is that Flow generally considers any substantial changes to existing type and property names in a target system to be a new addition rather than an update of an existing type or property. From a best practice perspective this is why it is strongly preferable to define the type and property names accurately on the first service-installation, and to avoid modifying type and property names after initially installing a Flow Service. Adding new properties to a type as you continue to develop is perfectly fine. Removing properties also works without issue... the tips above are specifically oriented around changing existing type and property names midway through a development project.
If you must change an existing type or property name, the cleanest method is often to remove the offending property name, update the Flow Service, then re-add the new preferred name and update the service again. If this is not possible, any differences can be mitigated via the type API. The platform does typically handle switching the sort of data well (i.e. Character/Boolean/Number/DateTime), as long as the profile entry/type property name isn’t changed.
Logistics of the Integration Flow Service component
To connect a Flow with an basic runtime process, as is done in the quick setup steps of this document, your "Flow Service URL" is the path of the Flow Service component appended to the base URL of the basic runtime shared web server on which the Flow Service component is deployed.
The authentication should be Basic on that basic runtime Shared Web Server, and the Username/Token are the credentials inputted to the Flow service when installing or updating.
In the Message Actions tab of a Flow Service component, if you select Add Action you’ll be able to select from any processes that have a Flow Services Server start step. You are able to include many message actions on a single Flow Service component, as well as many data actions or file resources on the same component.
Note: If you later update the start step profiles of your Integration process, you’ll need to update the service in Flow after re-deploying your Integration process and service. If you modify portions of the Integration process, aside from the start step profiles, you should only need to re-deploy the basic runtime portion of the design... and you should not need to update the service on the Flow side. We have observed that it sometimes takes a minute or so for the changes to go into effect after the 'successful deployment' alert pops up in Integration.
Pro tip: Integration doesn’t support running a listener process in test mode from the building canvas (e.g. a process starting with the Web Service Listener or a Flow Service Listener). You can build your process with a "no data" start step for testing prior to initially connecting it with your Flow, but many folks are not aware that there is still a way to run a Flow-connected Integration process in test mode!
Once you’ve run the Flow once, and see the execution in Integration Process Reporting, you are able to click the execution timestamp and drill down to the Flow Service connector details in the execution record and run the document in test mode from an 'action' icon.
This little-known way to quickly test updates to your Integration process is far superior to the more-common approach of re-deploying everything, updating the service on the Flow side, and re-running as an end user. In addition to just seeing if the end result errors, this method allows you to see the one or many "Documents" going into each step in the process; which is extremely useful in troubleshooting.
The screenshot below shows the step source data on a map when running a Flow process in test mode using this method.
Adding the Message Action to a given Flow
The message action is invoked with a message map element in Flow. In the message element configuration you'll be prompted to select a service. If the Integration service you've installed isn't visible in this message element picklist, you might need to import the service to that Flow using the shared elements icon on the right-hand-column (shown below).
After selecting the service, you'll be presented a list of available message actions, that align to each of the message actions you've configured into the Flow Service component on the Integration side. If you don't see the message action, there may be some issue with your profile. I've seen the message action be hidden if the Integration request or response profiles are invalid for the Flow Services Server... e.g. if the entry within an array(repeating) entry is itself a singleton, instead of an object.
Once you've selected the action, if everything else is in order you'll be offered the opportunity to select, or create, the appropriate Flow values for inputs and outputs to the Integration call; and the connection is ready to go!
Summary
Message actions are a tremendously useful and versatile method to connect Flow with other systems via Integration. If you found this article and accelerator pack useful please hit the 'useful thumb' down below or leave a comment to let us know that you'd like to see more content like this (both of those options are only accessible if you're logged into Boomiverse)! Thanks for reading and have a great day.
Discover solutions to your business problems
This solution is part of the Boomi solutions catalog, providing templates and innovative ideas to build an app for any use case from purely simple to massively complex, all in record time.
> Discover more Boomi solutions
Next steps?
- Get started with your free Boomi trial today!
- Learn more about how Boomi can help accelerate your business outcomes
- Join us in the Boomiverse and collaborate with customers and Boomi experts, join on-demand training, and get real-time updates on all things Boomi
About the Author
Written by Chris Cappetta (chris.cappetta@boomi.com)
Chris is an architect on the Boomi Innovation & Solutions team, based in Fort Collins. He enjoys mountain biking, nachos, and pushing the state of the Boomi art. Click here for a list of his other articles.