# Route shape ## Introduction The `route` shape is used when a process flow needs to split into multiple paths, based on a given set of conditions. Conditions are defined based on any fields found in the schema associated with your source data, so the scope for using routes is huge. To define multiple routes for your process flow, you must: 1. Add a `route` shape. 2. Configure the `route` shape to add required routes and conditions. 3. Build the flow for each configured route by adding [shapes](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes) in the usual way. {% hint style="info" %} A single incoming payload for [any process flow shape](https://open.gitbook.com/~site/site_dIV1g/~/revisions/9dTvdvRJIRVZQXuBMMnJ/process-flows/building-process-flows/process-flow-shapes) should not exceed 500MB. We recommend processing multiple, smaller payloads rather than one single payload (1000 x 0.5MB payloads are more efficient than 1 x 500MB payload!). For payloads up to 500MB, consider adding a[ flow control shape](https://open.gitbook.com/~site/site_dIV1g/~/revisions/9dTvdvRJIRVZQXuBMMnJ/process-flows/building-process-flows/process-flow-shapes/standard-shapes/flow-control-shape) to batch data into multiple, smaller payloads. Payloads exceeding 500MB should be batched at source. {% endhint %} ## Need to know * By default, multiple routes are processed in parallel when a process flow runs - one does not wait for another to complete before starting. * If a route shape is added without route conditions, incoming data flows down ALL defined routes. * There is no limit on the number of routes that can be added for a `route` shape. ## Accessing route shape settings When you add a `route` shape to a process flow, the shape is added to your canvas with two placeholder route stems - for example:
To configure these routes (and add more if needed) click the 'cog' icon associated with this shape to access [route settings](#configuring-route-data-for-a-new-route-shape). ## Configuring route data for a new route shape {% stepper %} {% step %} **Add source integration details** Optionally, select a `source integration` and `endpoint` to determine where the incoming payload for the route shape is coming from - for example:
{% hint style="info" %} If you leave these fields blank, the route shape will receive whatever data is passed from the previous step in the flow. {% endhint %} {% endstep %} {% step %} **Choose a routing method** Select a `routing method` to determine what should happen if a payload record matches conditions defined for more than one route:
These options are summarised below: | Option | Summary | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Follow all matching routes | If a record matches defined conditions for multiple routes, send it for onward processing down all matched routes. | | Follow first matching route only | If a record matches defined conditions for multiple routes, send it for onward processing down the first matched route, but no more. |
Example To help understand how these options are used, consider an example where two routes are defined: * Route 1 is to send all orders where the `product_type` ordered is `shoes` to Warehouse 1 * Route 2 is to keep all orders where the `product_type` ordered is `boots` to Warehouse 2 But what should happen with an order that includes **both** shoes and boots? * If we choose to **follow all matching routes**, then this order will flow down both routes - ending up in the payload for Warehouse 1 and Warehouse 2. * If we choose to **follow first matching route only**, this order will only flow down route 1 - ending up in the payload for Warehouse 1.
{% endstep %} {% step %} **Set date format** If any of your routes are filtering by date, you can select a `date format` here:
By default, dates are expected in the form `Y-m-d H:i:s` . If yours are different, select the format from this list (a wide range of standard date formats is available). {% endstep %} {% step %} **Set payload format (optional)** Use the `payload format` selector to set the expected format for incoming payloads:
Available formats are: `Auto` (the `route` shape determines the format received), `JSON`, `XML`, `Plain`. {% endstep %} {% step %} **Edit the first route** Click the 'edit' icon associated with the first route:
Then enter your required name for this route - it's a good idea to ensure this indicates the route's purpose. For example:
{% endstep %} {% step %} **Set the filter operator for this route** If you intend to define multiple rules/filters for this route, select the required operator from the `filter logic` dropdown field:
* Select `AND` so all defined filters must apply for a match * Select `OR` so any one of the defined filters will result in a match {% hint style="info" %} If you only need to define one filter, just leave the default setting in place (it has no effect). {% endhint %} {% endstep %} {% step %} **Configure rules (filters) for this route** Then click the `add new filter` button:
Filter settings are displayed:
From here, you can select a `field` (from the `data schema` associated with the `source endpoint` selected in step 1) - for example:
Alternatively, you can toggle the manual input option to ON and add syntax for [dynamic variables](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables):
{% hint style="info" %} The manual data path field supports [metadata variables](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables/metadata-variables). {% endhint %} Now, use the remaining `operator`, `type` and `value` options to define the required filter. {% hint style="info" %} Presentation of the `value` field is dependent upon your selected `type`. When defining a `value`, you can include [payload](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables/payload-variables), [flow](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables/flow-variables), and [metadata](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/dynamic-variables/metadata-variables) variables. {% endhint %} {% hint style="info" %} When a string filter `type` is selected, you have the option to select the `regex` operator and then define a regex value. This provides greater flexibility if you can't achieve the desired results using standard operators. `preg_match` is used for pattern matching. {% endhint %} The following data types are available when defining filters:
Variable typeVariable is defined and passed as...
StringA string value.
NumberA numeric value.
Specific dateA selected date - choose the required date/time from a date picker.
Dynamic dateA +/- number of seconds, minutes, hours, days, months, years to be matched relative to the current date.
BooleanA true/false value.
Use the `keep matching?` toggle option to choose how matched records should be treated:
Here: * If the `keep matching?` option is toggled `off`, matched records are removed from the payload before it moves on down the flow for further processing. * If the `keep matching?` option is toggled `on`, matched records remain in the onward payload, and all non-matching records will be removed. {% endstep %} {% step %} **Confirm rule settings** Click the `save` button (at the bottom of the panel) to confirm these settings. The new rule is added for your first route - for example:
{% endstep %} {% step %} **Confirm route settings** Repeat steps 7 and 8 to add any additional rules for this route. When you've added all required rules, click the `save`/`update` button at the bottom of the panel. {% endstep %} {% step %} **Configure the second route** Repeat steps 5 to 9 to configure the second route. {% endstep %} {% step %} **Add more routes (optional)** Add any additional routes required using the `add route` button. Each time you add a new route, the canvas updates with an additional route stem from your route shape. {% endstep %} {% endstepper %} ## What next? Having defined all required routes and associated conditions, the `route` shape on the canvas will have the corresponding number of route stems, ready for you to add shapes. For example: