Quick Start - My First Workflow

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.

• Go to your project's 'Connectors' page
• Ensure the project engine is stopped
• Search for the FTP utility connector
• Select it from the list
• Select 'Install' (on the right-hand side)

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'.

• Go to the 'Project Settings' page
• Scroll to the bottom
• Add a new connector with the blue '+' button on the right-hand side

With a successful test connection to the FTP site, it's time to build your first workflow.

• Go to the 'Project Assets' page
• Select the '+' symbol at the top right
• Choose 'Add Workflow' to launch the new workflow wizard
  • This wizard is about defining your workflow's 'trigger' (aka its starting point/initial data source). In this case, the trigger will connect to the FTP site and retrieve the XML file
• Give the workflow a meaningful name and description
• Under 'Creation Method', choose 'Create a New Workflow' from the dropdown

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.

• If the project engine (top-right corner) isn't running, start it
• If it's already running, restart it after adding a new workflow

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:

• Go to the Saltbox connectors page and install the HubSpot connector
• Go to project settings and create a connection configuration to your HubSpot system
  • N.B connection configurations can have different settings depending on the complexity of authorization on the system's API
  • For HubSpot, you need the API URL, which is https://api.hubapi.com
• Create a private app in HubSpot at Settings > Integration > Private Apps
• Configure the scope of the desired access to HubSpot
• Retrieve the client token and client key to enter the connection configuration in Saltbox

Once you've created the connection configuration in Saltbox, go to the workflow designer.

• Click on the workflow link from the 'Project Assets' page to open the workflow designer
• Expand the HubSpot connector on the left by clicking on it
• Find the 'Create a Company V3' action
• Click and hold it until a black box forms around it
• Drag this action onto your workflow to the first blue '+' icon inside the main branch

.

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.

• Click the "name" field in the target
• Drag and drop a field from your source onto it
  • Remember to click and hold on the source until the black box forms around it.

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.)

• Save your map
• Return to the workflow designer
• Rerun your workflow

You should receive the success message.

Next, check HubSpot to ensure your company has integrated. 

Next