First published on 07/21/2023/10:00 pm
The Saltbox Platform is a flexible, sophisticated, easy-to-use integration platform as a service (iPaaS) solution.
However, we recommend creating a basic workflow to learn design basics before launching the Space Shuttle.
Most modern systems use application programming interfaces (APIs) to facilitate data exchange. Before APIs, most integrations were file-based, including .CSV files, fixed-width files, and XML or JSON data contained in files and exchanged between PCs/servers via file transfer protocol (FTP).
We suggest starting your first workflow by creating a file on an FTP site and retrieving the data with a Saltbox workflow. An XML file stored on an FTP site is an ideal first retrieval.
Start by installing the FTP utility connector in Saltbox.
The FTP connector will indicate a successful installation.
You'll also upgrade and manage connector versions here. (New connector releases are made when new functionality is added. Please refer to 'Release Notes'.)
Once the connector is installed, create a connection to a specific FTP site with a 'Connection Configuration'.
With a successful test connection to the FTP site, it's time to build your first workflow.
The connector being used for the trigger is the FTP connector. The connection configuration is the name of the connection configuration you created a few moments ago, and the data type is FTPGetFileMessageSource. (This gets the file contents, whereas GetFileMetaDataSource retrieves metadata about the file, such as the name, size, and date created, if you wish to use this to retrieve the contents later in the workflow.)
In the 'Format Settings' window, you'll tell Saltbox which data format is coming in from the file; in this case, 'XML (Saltbox Core Connector)'.
Next, define the file location and use filename filters to filter out particular file names. Wildcards (*) are accepted here.
For this example, we created the file inside a training directory and called it 'Customer.xml'.
Therefore, the file or folder path is /Training/customer.xml in the workflow wizard.
Save the workflow with the blue 'Save' button.
Go back to the project assets page.
Next, open the workflow by clicking on its name.
As you can see below, the workflow has no actions, so it won't do anything other than retrieve the file data. However, it's good practice to run the workflow and ensure the trigger returns data.
Run the workflow with the run icon on the top right of the page.
If everything was configured correctly, you'll receive a message that the workflow was successful. (If the workflow wasn't successful, please go to the error-handling page).
Click the 'View Details' link to go to the 'Message Trace' screen. This is frequently used to debug workflows that fail during development.
On the message trace screen, a green bar at the top indicates the workflow's success. If you click the green bar, you'll get more details and a link to the messge.xml.
This shows you the data returned from the workflow trigger (i.e., your file in the format the data came in as, whether that's CSV, JSON, etc.), as always converted to XML.
The workflow uses the data in XML format until the point of sending it to the target system, where it's converted. This conversion is usually done automatically by the Saltbox connector (i.e., if you're using the HubSpot connector to create a company in HubSpot, the Saltbox connector knows HubSpot requires the JSON format and automatically converts the XML to JSON).
It's good practice to save the data returned by the trigger to the workflow files at this stage—not because we want to save the data itself, but because we want to use the format/structure of the data to transform the data to the structure of other systems.
Use the save button on the top right of the screen to save the XML as a file in the 'Samples' directory.
Now, you have data flowing into Saltbox from your file via your workflow trigger. You can now configure the workflow to send the data to an intended target system. In this instance, we'll use HubSpot (You can sign up for a 14-day trial to do this.)
Steps:
Once you've created the connection configuration in Saltbox, go to the workflow designer.
.
Once released, the action will show in pink because it isn't fully configured. To complete the configuration, click the pen icon on the 'edit' action.
To change the action's description (at the top right of the screen), you must apply a map. (Maps transform data from one structure to another in Saltbox.)
To apply a map, select the name of the connection configuration you created earlier.
Now, the action should show in white and have an additional icon with one arrow pointing left and one pointing right. This is the map icon.
Save the workflow before you enter the map.
Once the workflow is saved, click the map icon to go to the 'Visual Data Mapper' screen (VDM).
Here, you'll map your source field structure to the target structure. If you're using a connector, the target structure will be defaulted. The source structure is the data structure you got back from the trigger.
On the source window, select the option to update the source and choose your sample file. (Alternatively, you can rerun your workflow. It will fail, but the action now has the data source being sent to it and will automatically update)
Now, map your source fields from your file to the fields in HubSpot. Tip: Start with one and ensure it works before gradually increasing the complexity of the field mappings.
Once successfully mapped, an arrow/line will form from the source to the target to visually demonstrate the mapping.
This is a direct mapping, but you can use things like functions, lookups, and Javascript calculations for more advanced mappings. (Documentation is available in other subjects.)
You should receive the success message.
Next, check HubSpot to ensure your company has integrated.
|
Last modified: 03/25/2025/12:45 pm |