Skip to content
English
  • There are no suggestions because the search field is empty.

What is Reference Workflow Maintenance in SmartTMS?

Reference Workflow Maintenance is a page in the SmartTMS Admin Portal (under AFS Clients) used to control which references a user must enter when booking a shipment. Traditionally, required references were based on fixed system settings. Reference Workflows add flexibility — required fields can now depend on values entered for other fields, or on choices the user makes during booking.

In the system, a workflow is stored in the REFERENCE_WORKFLOW_CONFIG table, with a related child table holding its fields. A client starts using Reference Workflow logic for booking as soon as they have one active workflow.

Key facts about workflows:

  • Only active workflows are used during booking. Inactive workflows can still be edited.
  • Workflows can have a filter that limits when they apply.
  • The default workflow is the active workflow with no filter.
  • A client cannot have two active workflows with the same filter, or two active default workflows.

How do I add a Reference Workflow?

  1. In the SmartTMS Admin Portal, go to AFS Clients → Reference Workflow Maintenance.

      

  2. If no workflows exist yet, click + Add Workflow to create the first one. This becomes the default workflow (no filter, applies whenever active) and starts with no fields.

      

  3. Use EDIT, COPY, or the Activation Status toggle to manage a workflow:
    • COPY creates a secondary workflow — useful as a backup or for a filtered/specific use case.
    • Secondary workflows can be deleted if inactive; at least one workflow must always remain in the system (deactivate it instead of deleting it if it's not needed).


        
  4. Select a workflow to see its fields listed in the grid below it.
  5. Once all required fields are set up, toggle Activation Status on to make the workflow live. From that point, the client uses this workflow's logic to collect references during booking.

How do Reference Workflow filters work?

A filter is a key/value pair tied to a specific System Setting Key (for example, CLIENT_TIME_ZONE or SMART_RATERS). Click EDIT on a workflow to update its name or filter.

 

During booking, SmartTMS resolves which workflow to use as follows:

  1. The UI requests the active Reference Workflow for the current user and account.
  2. The backend pulls all active workflows for the client.
  3. Any active default workflow automatically applies (only one is allowed at a time).
  4. A filtered workflow applies when the SETTING_KEY value for the current user/account matches the filter's configured value. The system checks user level first, then account level, then system level.
  5. Precedence: a matching filtered workflow wins over the default. If two filtered workflows match at once (not recommended), the oldest active one is used.

  

Most clients only need a single active default workflow and don't need filters.

How do I add fields to a workflow?

Fields fall into two categories:

  • Reference to Collect – a standard reference field, which can be required or optional, and can depend on other fields.
  • Decision Field – not saved to the system; it's a question shown to the user whose answer determines which other references are required.

To add a field, click ADD on the row after which the new field should appear — the field is inserted right there. Use the Up/Down arrows to reorder fields afterward if needed. Fields are presented to users in the same order they appear in the grid.

  

Input types

  • Text – single-line text entry
  • Text Area – multi-line text entry
  • Dropdown List – a predefined set of selectable values

Field settings

  • Reference Type – what the collected value maps to. Can be set to "Decision Only (no reference type)", meaning the value is never saved — it only drives which other fields appear.
  • Label – defaults to the reference type name for standard fields; for decision-only fields, write a label describing the question being asked.
  • Required – whether the field must be filled in during booking.
  • Allowed Values – the option list for a Dropdown field.
  • Depends On – up to two dependency fields, each with a required value. The dependency is shown first; if its entered/selected value matches what's configured here, this field then appears. If both dependencies are set, both must match.

Advanced options

Click Show advanced options in the Add/Edit Field dialog to access:

  • Value Filter – a regular expression the entered value must match to be valid.
  • Format Hint – text shown to the user describing the expected format.
  • Notes – internal-only; not shown during booking. Commonly used to record the Jira ticket that prompted the field's creation.
Building a Value Filter without writing regex by hand

A guided helper is available so you don't need to write raw regex:

  1. Choose a data type: Digits Only, Letters Only, Alpha-Numeric, or Any.
  2. Choose a length constraint: Fixed Length, Min Length, Max Length, or Range.
  3. If you need something the guided options can't produce, choose FREEFORM to enter a custom regular expression — a test box is provided to validate it before saving.