Designing a Flow

Version 24.1.8906

Designing a Flow

To access the CData Arc Flow designer, click the Flows tab, then either create a new workspace, or click the existing workspace card you want to work in.

A flow canvas appears. If you have pre-existing connectors, those connectors are shown on the canvas. From here, you can add and configure new connectors, connect and rearrange existing connectors, and configure existing connectors.

  • Left-click and hold on empty space in the canvas to drag the designer into position for a better view.
  • Use the zoom options in the lower-left of the canvas to reposition the connectors to suit your needs.

Note: You can also use a mouse to zoom if the mouse has a scroll wheel.

Creating Connectors

You have four ways to add a new connector to the flow:

  • Click the Add button in the top-right portion of the canvas.
  • Right-click on the canvas and choose Add Connector.
  • Click the plus sign that appears when you hover over the line connecting two existing connectors.
  • Hover over the input or output arrow of an existing connector, then click the plus sign that appears.

Based on the option you choose, you are presented with an add connector menu that lets you pick the connector to add. If you select one of the first two options above, Arc lacks context about what you’re setting up, so you’re presented with the dropdown that includes all connectors, as well as the sample flows included in all implementations. If you choose one of the latter two options, Arc presents just the connectors that are applicable for the context you are working in.

The following image shows the full modal. Each row includes the connector name and icon, and the connector category. Hover over a row to see the number of instances remaining with your current license. You can search by connector name, and filter the list by category.

Once you make your selection, the Add Connector modal appears. Here you can name the connector and select which action(s) it should perform. For descriptions of all the information presented in the modal, see Explaining the Add Connector Modal.

Depending on your connector choice, the options visible in the modal vary. For example, some connectors do not have any actions, some have multi-select checkboxes, some have single choice radio buttons, and some have single-select dropdowns. See Specifying Actions for more information. The modal also displays a preview of the connector as it will appear in the flow, and includes a link to the connector-specific documentation. The following image is the modal for an AS2 connector.

Tip: When you name the connector (in the Connector Id field), be sure to choose a name that clearly describes the operation the connector performs. See Connector Naming Conventions for some best practice recommendations.

Click Create Connector to create the connector and open its configuration tabs. See Configuring Connectors for more information.

Specifying Actions

When you create a connector, the Add Connector modal asks you to specify what action(s) you want to use for the connector.

Multi-action MFT connectors such as AS2 and AS4 support separate send and receive actions within one instance of the connector. Use the checkboxes to select one or both actions, as shown in the following image.

If you select both the send and receive actions in the modal, Arc creates two connector cards, one for each action. The card for the send action has a Go to Receive Action link, and the receive card has a Go to Send Action link. The following image shows an AS4 connector:

Note: For multi-action connectors, unselected actions do not display in the flow canvas but they are still functional. You can right-click a connector card and choose to show or hide an action, without having to re-create the connector.

Single action connectors such as the Database connectors support one action per instance (for example, Upsert, Select, or Lookup). Use the dropdown in the modal to choose your action.

Some connectors in the Transform category do not have selectable actions because they perform one task: translation. The Actions portion of the modal does not appear on these connectors.

Start Triggers and Flow End

Start Triggers appear before the first connector in a flow. They indicate what actions can initiate the flow.

Start triggers can have one or more states depending on which of the following configurations is being used by the connector:

  • Active receives: Appear when Receive Automation is enabled for the connector. The trigger displays Next scheduled receive, along with the datetime of the next receive.
  • Passive receives: Appear when the connector supports passive receiving. This means that external clients can send a file or a request to the connector at anytime. For example, the trigger for an AS2 connector displays When a file is received while the trigger for a Webhook displays When a request is received.
  • Enable Automation or Receive Manually: Enable Automation works when the user configures Receive Automation for a specific time interval. Receive Manually means you need to navigate to the connector Output and click the Receive button. This triggers the receive action once.

The Flow End displays on terminal connectors at the end of a flow, when Arc hands the message off to the underlying disk or where the message is consumed by the connector during its send action and no output is generated.

Connecting Connectors

To rearrange connectors in the designer, drag them to move around the canvas and rearrange them into your desired configuration.

To connect connectors, drag from the arrow in the Output section of the first connector to the arrow on the left side of the second connector, as shown in the following image:

This creates a logical relationship between the two connectors so that when the first connector generates a message or file, it is passed directly to the second connector for processing.

To connect a connector to a different connector, hover over the connection line and click and drag the handlebar at the end of the connection you want to change. Drop the connection onto the new connector. To disconnect a connector, click the handlebars next to the arrows at either end of the connection.

Configuring Connectors

To configure a connector, click the connector on the canvas to open the connector configuration wizard, as shown in the following image:

On the series of tabs that appear, you can configure and test all of the connector settings. When you finish making changes, select the gray x on the left side of the panel to close the connector configuration wizard and return that space to the canvas.

Additional Configuration Options

Right-clicking a connector in a flow brings up the following options:

  • Delete Connector deletes the connector.
  • Show Error Path displays the error path. Use it to specify the connector where files that throw an error should be routed.
  • Show Success Path displays the success path. Use it to specify the connector where files that are successfully sent should be routed.
  • Export Connector Settings exports connector settings from the current server as a zipped file (named ConnectorId.arcflow).
  • Copy Connector creates a copy of the configured connector with a new Connector Id.
  • Create API Settings creates a Flow API from the selected connector(s). See Flow API for more details.
  • Show Receive Action Only visible on connectors that allow multiple actions but the Receive action is currently hidden. Use it to show the receive action for the connector on the canvas.
  • Show Send Action Only visible on connectors that allow multiple actions but the Send action is currently hidden. Use it to show the send action for the connector on the canvas.

Explaining the Add Connector Modal

The following image of an AS2 Add Connector modal has been annotated to provide explain what each element in the preview is for. Each number corresponds to a description below.

  1. Use this arrow to connect the connector with the previous connector in the flow.

  2. The connector type. Hover over the icon to see a static description of its intended use.

  3. Hover over the information icon to see user-defined information about the connector and its role in the flow. The content displayed comes from the Connector Description field on the Settings tab.

  4. Click the ellipses to open the context menu. It includes actions such as Show Success Path, Show Error Path, Copy, Delete, and others.

  5. The user-defined name of the connector (from the Connector Id field).

  6. These five icons show transaction counts. The warning and pending icons are hidden if there are no transactions to display.
    • chain iconl Count of successful transactions.
    • chain iconl Count of unsent transactions.
    • chain iconl Count of transactions with warnings.
    • chain iconl Count of failed transactions.
    • chain iconl Count of pending transactions
  7. The status bar indicates the status of configured Service Level Agreements (SLAs). SLAs are configured on the connector Alerts tab. See SLAs for more information. The status bar has four states:
    • Starting: Displays a date and time in which the SLA will start.
    • In Progress: Displays when the SLA is in progress and is not at risk.
    • At Risk: Displays when the SLA is in progress and the configured deadline is approaching, but the configured volume has not been met.
    • Violated: Displays when the SLA deadline has passed and the expected volume was not met.
  8. The gray area in the connector provides key information. For example, an AS2 connector shows the specified action (send and/or receive) and the configured AS2 Id. A database connector shows the specified action (select, upsert, stored procedure, and so on) and the root table.

  9. Use the output arrow to connect the connector to the next one in the flow.

  10. The path to the connector where files that throw an error should be routed. Only visible if you right-click on the connector and choose Show Error Path.

  11. The path to the connector where successfully sent files should be routed. Only visible if you right-click on the connector and choose Show Success Path.

Best Practices

Most flows have a trigger connector at which data enters the flow and a terminal connector at which data exits the flow. For some cyclical flows, the entry and exit point might be the same connector.

For example, data might enter the flow at an AS2 connector when an external trading partner sends a business document over AS2. The data from this business document might need to be imported into a back-end system like a database. In this case, the AS2 connector is the trigger connector and the Database connector is the terminal connector for the flow.

When creating a new flow, it is often easiest to start with the trigger and terminal connectors. Then, “work inwards” by adding transform connectors to the flow that fill in the steps between the entry and exit point (for example, you might need to add connectors that transform an inbound AS2 payload into a database insert).

Interacting with the Local File System

CData recommends using the File connector when configuring a flow that interacts with the local file system. This is especially important for folders that are shared with external monitoring processes. Guidelines for file pickup and file drop-off are outlined below.

File Pickup

To monitor a directory for files to be processed in Arc, add a File connector as the trigger at the beginning of your flow. Uncheck the Send action in the Add Connector modal.

Then follow these steps to configure the connector:

  1. Open the Settings tab.

  2. Set the Path property to the directory that you want to monitor. You can use macros to dynamically resolve paths based on date and time; hover over the Path field for more information.

  3. Configure the File Mask property with the file pattern that you want to retrieve.

  4. To avoid reprocessing files that have already been picked up, configure one of these two options based on what works best for your flow:

    • In the Receive section, check the box for Delete files (after received). This option deletes files after they have been processed.
    • In the Caching section, check one or both caching options to maintain a file size and/or timestamp record of files that have been processed. The application skips cached files but does not delete them.
  5. Open the Automation tab.

  6. Receive automation should already be enabled. Set the desired polling interval for the directory.

File Drop-Off

To drop off processed files to the local file system, add a terminal File connector to the end of your flow.

Follow these steps to configure the connector:

  1. Open the Settings tab.

  2. Set the Path property to the directory where you want to drop off files. You can use macros to dynamically resolve paths based on date and time; hover over the Path field for more information.

  3. Open the Advanced tab.

  4. Use the Overwrite Option to specify how to handle files that already exist in the destination path.

Partner-Specific File Transfer Connectors

Connectors that send or receive files over the network (for example, AS2, AS4, FTP, SFTP, OFTP, and others) are bi-directional, but are configured for a single trading partner. In other words, a single AS2 connector could send and receive AS2 messages with Amazon, but it could not also send and receive files with Walmart.

Many MFT (Managed File Transfer) connectors require setting up a profile to exchange files. The Profiles Page contains a tab for configuring application-wide settings for each supported protocol. For example, the information configured in the AS2 profile is used in all AS2 connectors, and partner-specific AS2 connection details are configured in each AS2 connector.

Connector Naming Conventions

Connectors should always be given a descriptive name that communicates the role of the connector in the flow.

  • The name of an MFT connector (for example, AS2, AS4, FTP, SFTP, OFTP, and others) should indicate the remote party with whom files are exchanged, and the protocol over which the exchange occurs (for example: Walmart_Production_AS2).
  • The name of an EDI connector (such as X12 and EDIFACT) should indicate the name of the partner with whom the EDI document is exchanged, the direction of translation, and the format of the document (for example: Walmart_X12_Outbound).
  • The name of a Data Mapping connector (such as XML Map) should indicate the format/schemas that the connector is mapping from and mapping to (for example: Map_850_to_Orders).
  • The name of a Back-End Integration connector (for example, Database, MySQL, CData) should indicate the specific back-end system and the table in that back-end system if applicable (for example: PostgreSQL_Orders_table).

If you use the Connector Description field on a connector, you can hover your cursor over the information icon to see your description of that connector. If you do not see an information icon, the connector does not have any text in the field.

XML for Data Transformation

Arc uses XML as an intermediary format for data manipulation and transformation. Many connectors translate files of various formats into XML and vice versa (for example, the X12 connector, EDIFACT connector, CSV connector, and others). Additionally, Arc uses XML to model back-end system input and output (such as SELECTS and INSERTS into database-like systems).

Since most source and destination formats can be represented as XML, data transformation flows often have the following structure:

  • A connector that pulls or receives data in its original (source) format
  • A connector that converts this source format into XML (if it is not already XML)
  • An XML Map connector that transforms this source XML into a new structure representing the target (destination) format
  • A connector that converts this transformed XML into the destination format (if a non-XML format is required)
  • A connector that sends the finalized file to its intended destination

The XML Map Connector is the engine that performs the critical work in these data transformation flows. Becoming comfortable with data transformation is often a matter of familiarizing yourself with the XML Map connector’s visual designer.

Organize Flows into Workspaces

You can configure multiple separate flows on the same flow canvas without risk of cross-contamination, but dividing flows into different Workspaces can help reduce clutter and maintain organization.

Click the Flows tab to launch the workspaces grid. From here you can create new workspaces, import or export workspace configuration settings, and delete workspaces (except for the Default workspace). Only the connectors from the current workspace are displayed at any given time.

Connectors in different workspaces cannot be connected to each other, and the data and configuration files specific to these connectors are held in separate folder structures.