Skip to main content

Routes — Automation

The Automation tab of a route carries its triggers — the settings that determine when the route runs by itself. Without a trigger, the route runs only when someone starts it by hand on Execution.

Which trigger is suited to what is described under Triggering.

Permissions​

The tab belongs to the route and therefore follows the Routes permission:

Level on RoutesWhat you can do on the tab
Nonethe Routes menu item is missing, and with it this tab
Read onlyview all triggers and all their fields; the fields are grayed out
Fulladd, change and delete triggers

The Automation permission belongs to a different screen, however similar the two words sound. It allows pausing and resuming a route's automation during operation — that happens on Execution.

In the example: A. Vogt has Full on Routes and sets up the triggers. M. Brandt has Read only — Brandt sees the same triggers, all fields read only.

The Automation tab with the trigger list on the left and the selected weekly trigger on the right.

Layout​

The tab consists of two areas side by side.

AreaContent
Trigger (left)the list of all triggers of this route, per row the type and a summary of the setting — e.g. Scheduled with Daily 02:00. A warning sign next to the name shows a finding on this trigger, tooltip This trigger has validation issues. Above it the Add trigger button.
Detail (right)all fields of the trigger selected in the list, and in the header Delete trigger.

If the route has no trigger yet, the right side shows No triggers yet with the hint "Add your first trigger — it determines when the route runs automatically."

A route can carry several triggers. "Artikel Cambira Austria" has two: the daily run at 2:00 AM and the weekly full run on Sunday at 3:00 AM.

Delete trigger asks first: "The trigger '…' will be deleted. This action cannot be undone." You confirm with Delete.

Adding a trigger​

Add trigger opens Choose trigger type. The choices are:

TypeDescription in the dialogWhen offered
ScheduledStarts the route on a fixed schedule.always
EventReacts when a record is created or changed.only for direction Export or Internal

Select creates the trigger and opens it on the right.

Two further types come about in a different way. Dispatch input is created automatically as soon as a dispatch route has this route as a target (below). Manual is the state without a trigger: a route that is meant to run only by hand has an empty list.

If the route carries a Dispatch input, Add trigger is missing: the dispatch input remains its only trigger.

Scheduled​

Mode​

A switch with two positions, Simple and Advanced. Simple leads to the guided form, Advanced to the cron expression. Everything the guided form can set can also be written as an expression; the expression goes further. In both modes the next runs appear below the schedule.

Simple mode​

FieldMeaningAppears for
FrequencyEvery N minutes, Every N hours, Daily, Weekly, Monthlyalways
Intervalthe N — how many minutes or hours lie between two runsEvery N minutes, Every N hours
WeekdaysMo to Su, at least oneWeekly
Day of month1 to 31 or Last dayMonthly
Timehour and minute, format HH:mmDaily, Weekly, Monthly

The interval is a choice from fixed values:

FrequencyIntervals offered
Every N minutes1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30
Every N hours1, 2, 3, 4, 6, 8, 12

For Day of month 29, 30 or 31, the hint "Months without this day are skipped — choose 'Last day' for the end of the month." appears. The run is therefore dropped entirely in such a month instead of moving to the next possible day.

Advanced mode​

A Cron expression field, example 0 6 * * *. An unreadable expression turns the field red, and so does an empty field.

An expression beyond the guided form — e.g. several times a day — is also allowed. The field is then headed by: "Expression is too complex for simple mode — switching back to simple mode resets the expression." The switch does reset it and says so briefly: "Advanced expression discarded — cannot be represented in simple mode".

Next runs​

Between the schedule and the Run type, both modes show the next points in time at which this trigger becomes due. They show whether the schedule hits what was intended — especially with a cron expression.

The times are server time, regardless of the time zone of your workstation.

Instead of the list, the following can appear there:

MessageMeaning
Expression invalidthe cron expression is unreadable
Preview currently unavailablecalculating the preview failed; the setting itself is unaffected

Run type​

What a run of this trigger takes along. Which run types are offered is decided by the route's data origin — chosen when creating the route:

Data originRun types offered
DatasetFull, Incremental
QueueDrain queue
Dispatch inputnone — a route supplied this way has no run type

A newly created scheduled trigger is set to Incremental where this type exists, otherwise to the only one offered.

In the example: "Artikel Cambira Austria" reads a dataset and runs Incremental daily and Full on Sundays. The dispatch route "Statusmeldungen Kessler" reads a queue and runs every 10 minutes with Drain queue.

If a REST connection pages by Page number or Offset and its Detect changes is not set to Source returns a change token, Incremental needs a sort. Without one, the check reports "Connection is not set up to read in sorted order" at the run type. It is fixed on the connection, under Batch fetch.

If the run type is Full and the frequency Every N minutes, the hint appears: "A full run transfers all data every time. At such short intervals that is usually unnecessary — 'Incremental' transfers only changes." The setting remains permitted nonetheless.

Items per cycle​

Only for the run type Drain queue. The upper limit of how many messages a run processes before it ends; the next run continues. Empty means unlimited. If a fetch returns several messages, each counts on its own; whatever is left in the list once the limit is reached stays unacknowledged and comes again in the next run.

Cleanup​

A checkbox Report records no longer delivered. It appears only if both apply:

  • the run type of this trigger is Full, and
  • on the Behavior tab, Delete behavior has the strategy Deactivate in the target system.

If it is switched on, Xchange reports to the target system after the run every record that the route transferred earlier and that this run no longer delivered — because it dropped out of the data filter or was deleted in the source. What happens to it there is set by the route's delete behavior.

In the example: on the Sunday full run of "Artikel Cambira Austria" the cleanup is switched on; on the daily incremental run the checkbox is missing entirely.

Xchange holds a cleanup that would report an unusually large number of records and waits for a decision; that is described on Execution.

Event​

An event trigger reacts to a record having been created or changed in SAP Business One. It exists only on routes with direction Export or Internal — where the route reads from SAP Business One.

The event trigger of "Artikel Webshop": Trigger set to Same as fetch endpoint, Trigger on Created and Changed, below it the hint about the route's data filter.

Trigger​

A switch Trigger with three positions. It decides what is listened to — and with it also which fields appear below it at all:

PositionMeaningFits when …
Same as fetch endpointlistens to the same object the route reads from, and takes over the route's data filterthe route is meant to pass on exactly the records that changed — "Artikel Webshop" listens to items this way
Other objectlistens to a different object than that of the source datathe change shows on a different object than the one the route reads — e.g. on the stock level of an item
Custom procedurelistens to an object of your choice; instead of field conditions, a database procedure of your own decides what counts as a triggerfield conditions cannot express what counts — e.g. only the change of one particular field

Same as fetch endpoint requires that the route's fetch endpoint points to an object that raises events. If it does not, the error "The route's fetch endpoint raises no SAP event. Choose another object for the trigger, or fetch from an endpoint that does." appears directly below the switch. As long as it is there, activation is blocked.

The fields below it per position:

FieldSame as fetch endpointOther objectCustom procedure
Trigger onyesyesyes
Object—yesyes
Fetch-key field—yes, see belowyes, see below
Field conditions—yes—
Procedure name——yes

Field conditions therefore exist exclusively for Other object. For Same as fetch endpoint the route's data filter applies instead; the hint there says so: "The trigger uses the route's data filter. Change it on the 'Source data' tab."

In the example: "Artikel Webshop" is set to Same as fetch endpoint with Created and Changed, without an object of its own and without conditions. Because the route carries no data filter either, the trigger sees every change to an item, around 140 a day.

Conversely, for Other object: only the field conditions decide; the data filter of the source data stays out of play for this trigger. If the route carries a data filter, the hint below the switch says so: "The source data filter does not apply to this trigger. Only the conditions below decide. Add any restriction that is also meant to apply to the event there." Without a data filter the hint is missing.

Custom procedure chooses the object and Trigger on just as Other object does. Only the field conditions are replaced by the Procedure name.

Trigger on​

Two switches, Created and Changed, individually or both. At least one must be on.

Object​

The SAP Business One object whose changes are listened to — e.g. Items. Only for Other object and Custom procedure.

Fetch-key field​

The field of the selected object from which the key of the record to be fetched comes. It appears only if the object listened to is a different one than that of the source data — if the trigger listens to the same object the route reads, the key is already known.

Example: the route reads items but listens to stock levels. This field then says which field of the stock level carries the item number.

Procedure name​

Only for Custom procedure: the name of a stored procedure in the database, at most 200 characters. If there is none with this name, "No stored procedure with this name was found" appears below it.

Generate template opens a window with a skeleton to copy, on the Skeleton tab. If the object keeps a change history in SAP Business One, the Field change tab is added — a skeleton that additionally evaluates the changed fields.

Field conditions​

Only for Other object. The conditions a changed record must meet for the trigger to fire.

They are arranged in groups:

ElementMeaning
How the groups are combinedAND or OR — applies once to all groups together, the same for every transition
Group 1, Group 2, …per group its own Combine, again AND or OR, for the conditions within this group
Add conditiona row in this group
Add group / Remove groupone group more or fewer

The field conditions hold up to 6 groups with up to 5 conditions each. When a limit is reached, adding stops there, and the editor names the limit, e.g. At most 5 conditions per group.

Each condition is a row of Field, Operator and Value.

Operators
Comparisonequals, does not equal, is greater than, is greater than or equal to, is less than, is less than or equal to
Setsis one of, is none of
Textcontains, does not contain, starts with, does not start with
Presenceis empty, is not empty

Which operators a row offers depends on the selected field — a date field offers different ones than a text field. The split by field type is the same as in the data filter, see Routes — Source data. For is empty and is not empty the Value column disappears. The value list of is one of and is none of holds up to 20 values.

Until an object is selected, the field selection says Select an object. Fields that only the fetch delivers carry the marker Only evaluable on fetch — they belong in the data filter of the source data.

Without conditions it reads No conditions yet.; the trigger then fires on every change to the object. Remove condition and Remove group ask first; a condition without a field and without a value disappears without asking.

A route that triggers itself​

An internal route can trigger itself. If its event listens with Created to the object its primary step creates, every new record triggers the route again. The route reports this as a warning, e.g. "Route creates 'DeliveryNotes' itself and can trigger itself again — narrow the event with a condition the created records do not meet".

The warning stays even with field conditions, because whether the created records miss them cannot be checked in advance. A step that only updates does not raise it.

Dispatch input​

Xchange creates this trigger — it appears in the list as soon as a dispatch route has this route as the target of one of its rules. Here it is protected from deletion, and it remains the route's only trigger.

The detail shows one of three states:

StateDisplay
Assigned"Fed by dispatch route '…'" and the link Open dispatch route
Unassigned, with possible sendersthe hint that there is no assignment yet, and below it the list Dispatch routes on the same connection to choose from
Unassigned, without possible sendersthe same hint and the link Create dispatch route

In the second and third states, the route is not yet fully set up: a route with data origin Dispatch input only gets something to do once a dispatch route supplies it.

In the example: "Abholung Kessler" is supplied by the dispatch route "Statusmeldungen Kessler" — its first rule passes every message with status = picked there.

Which rule passes which message where is shown on the Dispatch tab of the dispatch route.

What else applies​

  • A change here takes effect only after activation. It sits in the draft and takes effect in operation only with the activated configuration snapshot — see Validate and activate.
  • Whether the route runs is decided by Execution. A paused route stays put, even when its schedule becomes due. Pausing and resuming happens on Execution.
  • What is transferred is set by the data filter on the Source data tab. The run type only says how much of it comes along each time.
  • The run type Drain queue tolerates only one trigger. A route that reads from a queue has exactly one.

See also​