Skip to main content

Routes — Source data

On the Source data tab you determine where a route takes its records from, which of them it looks at in the first place and what a single record looks like. What happens to this data afterwards is set on the Mapping tab; what happens to a record that no longer applies in the source, on the Behavior tab.

Which sections the tab shows depends on the data origin of the route and on its type. Each route shows a part of them. The overview is under Layout.

In the example: "Artikel Cambira Austria" fetches the items from its own SAP Business One company and transfers them to CAMBIRA_AT. Its data origin is Dataset, so it shows most of the sections of this tab. For the two sections that only a route from a queue has, "Bestellungen Webshop" comes in as well.

Permissions​

Permission on RoutesWhat you can do
Read onlyview all sections and their values, read the data preview, look at reference data
Fullin addition, change all fields, create and remove conditions, change filter fields and additional data, reload records

With Read only the buttons disappear; the entries stay. Load from source, Add additional data, Add condition, Add field, Add link and Fetch additional data are hidden; the fields themselves are still there and readable. One exception is Reference data — the dialog opens read-only as well.

What a permission is and who grants it is described under Permissions.

Layout​

The tab is split into two columns, and you can move the dividing line between them:

  • on the left the settings, from the source to the additional data,
  • on the right the Data preview.

The right column can be hidden entirely with the Data preview button. The left one contains up to eight sections, depending on the route:

SectionAppears for data originFurther condition
Data sourceDataset, Queue—
AcknowledgmentQueue—
Data filterDataset—
Change filterDataset—
Field structureDataset, Queueonly on transferring routes, and only if the connection supplies a field structure
Reference dataall threeonly on transferring routes
Record identificationall threeonly on transferring routes
Additional dataall threeonly on transferring routes

A dispatch route shows none of the sections from Field structure on, and no data preview. Next to the Data source heading it has the Reference data button instead; the Data preview button is missing. Its counterpart is the Dispatch tab.

You choose the data origin when you create the route; after that it appears on the General tab as display only — see Routes. What the three values mean is explained in Routes.

The Source data tab, with the settings on the left and the preview of a record on the right.

Data source​

This is where Xchange picks up the records.

FieldMeaning
Fetch endpointWhat the route reads. For SAP Business One the name of the object (Items), for a REST connection the path (orders/pending). Required.
Single-fetch endpointOnly for type Processing: how a single record is read again when only its key is available. The placeholder in curly braces is replaced by the key: Items('{{ItemCode}}').
Fetch returnsOnly for Queue: whether a fetch brings one message or several messages in a list. With several messages, each list entry is processed and acknowledged on its own; where the list is located is set by the connection in Records. A new route is set to several messages. If the test message contains a list, the editor suggests this value. For SAP Business One the field is missing — there every fetch brings one message.
Message IDOnly for Queue: the field by which Xchange recognizes a message — when acknowledging and when the same message is delivered a second time. If it is missing, every delivery counts as a new message. Required with several messages.

The Single-fetch endpoint is sometimes filled by Xchange itself. Where the connection brings a field structure that addresses a single record by rule, Xchange sets the field on saving and shows it as immutable — it then follows the Fetch endpoint. If the field structure changes later, Validate marks the field with Invalid value, and the checklist names the expected value; Reset to derived value next to the field takes it over. If the connection only brings a template for the single fetch, Xchange fills an empty field with it, and you can change it. In all other cases you enter it.

It becomes required only through the trigger. An event from SAP Business One reports only the key of an object; a route with such a trigger must therefore be able to read the record again and requires the field. A route that goes through an entire dataset gets every record delivered in full; for it the field is optional. Which trigger produces which case is described under Triggering.

If the connection's field structure describes no reading endpoint, the fields are followed by "The field structure describes no reading endpoint. You can still enter the fetch endpoint by hand." The suggestion list of the Fetch endpoint then stays empty.

On a dispatch route, the Reference data button sits next to the heading; such a route has no section of that name. The button opens the dialog in which you insert a record.

In the example: "Artikel Cambira Austria" reads Items and enters Items('{{ItemCode}}') as the single fetch. "Bestellungen Webshop" reads orders/pending and recognizes a message by message_id.

Acknowledgment​

Only a route whose data origin is Queue has this section. It tells the partner system that a message has arrived — otherwise it would be picked up again on the next run.

The Acknowledgment section with the acknowledgment endpoint and one row reporting back the message ID.

FieldMeaning
Acknowledgment endpointWhere the confirmation goes, e.g. orders/confirm. May contain a placeholder that Xchange replaces with the Message ID: orders/{{message_id}}/confirm. The button with the key inserts it; it appears as soon as a Message ID is entered. Required with several messages.
Target field / Source tableWhat is in the confirmation. Per row, one field of the acknowledgment and the value that goes into it. The button at the left edge of Source toggles as in the mapping row: Path reads the value from the message and keeps its type — a number goes out as a number. Constant writes a fixed text, e.g. success — if it stays empty, the field goes out with empty text.

Add row creates a row, Remove row at the end of the row takes it out. The table holds up to 10 rows; after that the editor reports At most 10 rows. Without rows it reads No acknowledgment fields. — the acknowledgment then goes out empty, to the endpoint alone.

A faulty row turns red only once you have edited it; the messages list it from the start.

The acknowledgment is sent as soon as Xchange has committed the message — before the transfer. Whatever goes wrong afterwards, no later run fetches it from the queue again. What happens in this case is described under Execution.

In the example: "Bestellungen Webshop" acknowledges at orders/confirm and reports back the message_id as a Path in one row.

Data filter​

The data filter narrows down which records concern the route at all. Below the heading it says for full and incremental runs: it applies to every run. A full run reads the entire dataset within the filter.

Without a condition it reads No condition — all records included.

Groups, rows and how they are combined​

The data filter has two levels.

  • A group carries the condition rows. Above it is Combine with the values AND and OR — it applies to the rows within this group.
  • From the second group on, How the groups are combined also appears, likewise AND or OR. Add group creates another one.

The data filter holds 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 6 groups.

A condition row has the columns Field, Operator and Value.

The Type column appears only when needed. It is there only where the field structure leaves the data type of a field open — then you choose it yourself, because it alone decides which operators are offered. Where the type is known, the column is missing.

In the example: "Artikel Cambira Austria" has one group with two rows and the combination OR: ItemsGroupCode equals 100, ItemsGroupCode equals 101 — the item groups Armaturen and Ersatzteile. That is 1,186 of the 2,418 items in the master data.

A data filter with one group of two condition rows combined with OR.

Fields from linked objects​

The field list of a row is divided into Own fields and Linked. Under Linked are branches with the fields of other objects, and they get there in three ways:

BranchWhere it comes fromSelectable itself
Sub-list of the record, e.g. the lines of a documentfrom the field structure, without any action on your partonly its fields
Detected link, labeled Object (via field)from the field structure: a field of the record refers to another objectyes
Custom link, labeled with the target objectby you, via Add linkyes

If you select a branch itself instead of one of its fields, the condition reads: there is a linked record. For a sub-list this choice does not exist, because every document has lines.

Add link sits at the foot of the field selection when the route reads from SAP Business One. The dialog asks for:

Field of the linkMeaning
Fromthe object from which the link starts
Target objectthe object that is added
Field / Field in target objectthe two fields that must be equal — between them is the fixed equals

In the field selection, a custom link shows the two fields next to the target object, e.g. ItemCode = U_ItemCode, and the pencil icon Change link. It opens the same dialog with the saved values. Only custom links can be changed; detected ones are given by the field structure.

A block is created where a link can hit several records. It carries a heading of its own, and that heading says what it checks: without conditions it reads is present — then it is enough that there is any linked record at all. As soon as a condition is in it, it reads at least one: at least one linked record must satisfy all conditions of the block. Remove block takes it out together with its conditions.

The operators​

Which operators a row of the data filter offers follows from the data type of the selected field. The data filter knows fourteen — each individual field type gets a part of them. The change filter knows no operators — it is a list of fields, see Change filter.

OperatorTextNumberDateSelection listBoolean
equals✓✓✓✓✓
does not equal✓✓✓✓✓
is empty✓✓✓✓✓
is not empty✓✓✓✓✓
is one of✓✓✓
is none of✓✓✓
contains✓
does not contain✓
starts with✓
does not start with✓
is greater than✓✓
is greater than or equal to✓✓
is less than✓✓
is less than or equal to✓✓

Read the table like this: Text offers ten operators, Number ten, Date eight, Selection list six, Boolean four.

In addition:

  • greater and less exist only on Number and Date, a partial-text search only on Text, a choice from several values on Text, Number and Selection list.
  • For is empty and is not empty there is no value. The Value column stays empty for them.
  • The value list of is one of and is none of holds up to 20 values.
  • A date field offers Today in the Value next to the calendar — tooltip Compare against the current date. The condition then compares with the date of each run instead of with a fixed date. Today is available with equals, does not equal and the four greater and less operators; an entered date replaces it. The change filter and additional data do not know Today.

If a path points to a set of values instead of a single one, the list changes completely. In the data filter, only is empty and is not empty then remain.

If the type of a field is unknown, the row offers the full list of its filter. That is the same case in which the Type column appears.

The way from the empty route to the finished filter is described under Narrow down with a data filter.

Count matches​

Count matches runs the filter against the source as a trial and gives the number of records it hits. This is pure reading: the target system stays untouched.

In two cases a message appears instead of the number: No fetch endpoint configured, as long as the fetch endpoint is missing, and a message naming the condition that cannot be evaluated.

Change filter​

The change filter decides what an incremental run takes along. Below the heading it says for incremental runs: a full run ignores it.

It is built more simply than the data filter: a single list with up to 5 fields, exclusively fields of the route itself. Links to other objects and blocks are reserved for the data filter.

The change filter is a list of fields. Above the list it says "A record counts as changed when any of these fields holds a later or higher value than at the last run." — there is no operator, no value and no AND/OR toggle. Each field is compared with the position the previous incremental run left behind: the largest value of this field it read. Each field keeps its own position, and a record comes along as soon as one of them lies above its position.

The field picker offers only date and number fields — a change timestamp or a sequential number — plus fields whose type Xchange does not know. A sequential number such as DocEntry detects only newly created records: a change to an existing one leaves it unchanged. Detecting changes needs a date field such as UpdateDate.

A field that is neither a date nor a number — e.g. from an import — is reported by the check at the Field cell with "The change filter allows only date or number fields". This blocks activation.

If a field is empty in the reference data, the check warns at its Field cell: ""Field" is empty in the reference data — such records are found only through another field". A record without a value in this field never lies above the position; it comes along only if a second field matches it.

When you create it, Xchange makes a suggestion. If it knows the date fields of the source, it adds one row per date field. You can keep the suggestion, shorten it or replace it.

Some fetch endpoints filter by themselves. If Detect changes on the connection is set to Source returns a change token, the endpoint itself returns only what has changed since the last run. Then Add field is missing, and in its place is "The fetch endpoint returns only the changes since the last run. A change filter is not required here." — an existing filter, however, remains fully editable.

Whether a REST connection is fit for incremental runs is checked not by this section but by the Run type on the Automation tab; what the connection needs for it is described under Connections — Batch fetch.

In the example: "Artikel Cambira Austria" keeps the prefill — the fields UpdateDate and CreateDate. The nightly run thereby takes along, of the 1,186 items, the changed and the newly created ones.

The way there is described under Transfer only what changed, how to handle the very first run under Limit the first run.

Field structure​

The Field structure is what Xchange knows about the structure of a record: which fields exist and which data type each has. It comes from the connection and describes only the structure.

It is the basis for the suggestion lists of this tab and of the mapping.

The section appears only where the connection supplies a field structure. Without it, the suggestion lists are empty, and you enter the fetch endpoint, fields and paths by hand. Whether and in which format a connection supplies its field structure is described under Connections.

The section shows a single line naming the state:

DisplayMeaning
"Fetching field structure …"The fetch is running.
"Last fetched: …" / "As of …."When the field structure was last read.
"Enter the fetch endpoint above."Without a Fetch endpoint there is nothing to fetch.
"The field structure is currently unavailable. Try again later."The connection was temporarily unreachable.
"The field structure could not be read. Check the field structure source on the connection."The connection supplies a field structure that Xchange cannot read.

Reference data​

Reference data is a real record from the source that you work on. Unlike the field structure, it contains values.

It is needed so that the mapping can be built on something verifiable, so that the data preview shows real values and so that the additional data can be run at all.

There are two ways to get it:

WayWhen
Load from sourceXchange fetches the record from the source itself — by its key or, when a display field is set, optionally by its value. Appears only once a single fetch is possible.
Insert manuallyYou paste it as JSON. The way for everything that Xchange cannot read again by itself. When you apply it, the dialog checks whether the text is valid JSON.

If Load from source fails, the message names the cause:

MessageWhen
"Record with this key was not found."The source does not know the key you entered.
"Record with this display value was not found."No record carries the display value you entered.
"Several records have this display value. Please enter the key."The display value is not unique.
"The source does not support searching by display value. Please enter the key."The source cannot search by the display field.
"Your user lacks permission to read in the source."The search by display value fails on the read permission.
"Your user lacks permission for this object in SAP Business One (HTTP 403)."SAP Business One denies your user the object.
"The source system is currently unreachable. Please retry later."The source system does not respond.
"The source system rejected the sign-in. Reload the page and sign in again. If the error persists, check the Service Layer's OIDC trust configuration."The Service Layer rejects your sign-in.
"The source system rejected the request. Check the key you entered and the route's single-fetch endpoint."The source rejects the single fetch as faulty.
"The source system rejected the connection's credentials. Check the connection's credentials."The connection's credentials are not accepted.
"The single-fetch endpoint is not configured. Please set it on the Source data tab."The Single-fetch endpoint is empty.
"The reference data changed since it was loaded. Reload the page and try again."Someone has replaced the reference data elsewhere in the meantime.
"Record could not be loaded."Any other cause.

Field structure and reference data together make up the Data preview.

Record identification​

Record identification states how Xchange recognizes a record and how you recognize it. It has two fields.

Key field​

The Key field is the field by which a record is recognized. It distinguishes a second transfer of the same record from a new one. It is required on every transferring route — even on one that receives its data exclusively by delivery.

Who sets it depends on the connection:

  • If the connection addresses a single record by rule, Xchange takes the key together with the Single-fetch endpoint from the Fetch endpoint and shows it as immutable, e.g. ItemCode. If the field structure names no key for the endpoint, it is followed by "No key found in field structure."; if the route knows no field structure at all, it reads "Pick the key fields from the pasted reference data, or enter a JSONPath."
  • Otherwise you choose it yourself via the field selection or enter a path, e.g. DocEntry.

The field always shows the stored key. If it is empty or does not match the single fetch's placeholders, Validate reports an error and the route cannot be activated. If a key shown as immutable no longer matches the field structure, Validate marks the field with Invalid value, and the checklist names the expected key. Reset to derived value next to the field then takes the key from the fetch endpoint.

Where the key in the target system comes from is a different question and is decided on the Mapping tab; see Routes — Mapping.

In the example: "Artikel Cambira Austria" has ItemCode as its key. Because ARM-4711 has the same name in both companies, the match at the target is unambiguous.

Display field​

The Display field is the value by which you recognize the record — for a document from SAP Business One, the document number you know from the document rather than the internal key. History and Clarification show it beside the key, and the quick search finds a record by it as well.

It is for display and for searching. In Transfer individually and Load from source you can name a record by its display value, provided the source has a fetch endpoint. How Xchange recognizes a record remains the key field; changing the display field changes nothing about that.

  • For documents from SAP Business One it is prefilled with the document number. You can override it; Reset to derived value restores the document number.
  • Otherwise it is empty, and you pick the field from the field structure, e.g. orderNumber.
  • It is never required. If it stays empty, History and Clarification show the key alone.

Validate reports a display field that is not a valid field path (Not a valid field path), and one the field structure does not know ("Display field" does not exist in the field structure).

Additional data​

Sometimes the source record lacks something. An item carries its master data, its prices are elsewhere; an order carries a customer number, the address for it is in the customer master data. Additional data are queries that load such details before the mapping runs.

The additional data of a route, with the query list on the left and its settings on the right.

On the left is the list of queries, on the right the settings of the selected one. Without a query it reads No additional data yet. Add additional data creates one, Delete removes it after confirmation. A warning sign next to the name shows a finding on this query, tooltip This additional data has validation issues.

If the stored settings of a query cannot be read, the form shows empty fields, and above them it says: The stored settings of this additional data cannot be read. Empty fields are shown; the stored settings are kept until you change something here.

In the example: "Lieferaufträge Kessler" has two queries; "Kunde" is selected.

The settings of a query​

The fields build on each other — some appear only once an earlier decision has been made. The form shows them in three groups.

What is read:

FieldMeaningAppears
NameThe name of the query in the list. Without a name it is called after its position, e.g. Additional Data 2 — that is also how the messages name it.always
Query targetWhich SAP company is read from: This company or the company of the connection.only if the route connects two SAP companies; never on an internal route
LevelMain record or Rows of a list — see below.always
Row listThe list whose rows are queried, e.g. OriginalPayload.DocumentLines[*].level Rows of a list
Object in the Main object blockWhat is read, e.g. Items or BusinessPartners.always
Sub-object in the Main object blockA list within the main object, e.g. ItemPrices. Optional.if there are sub-lists
Object in the Related object blockA second object read together with the main object, e.g. ItemGroups for Items. Optional. The main object itself is not offered.always
Sub-object in the Related object blockA list within the related object. Optional.if the related object has sub-lists
ConditionsWhich records the query reads — see Conditions of a query.as soon as a main object is selected

Links:

FieldMeaningAppears
Link to rowWhich record belongs to a row: Field of the row = Field of the main object. You pick the Field of the row from the fields of the row, nested ones included; fields inside a list are not offered. The field of the main object need not be a key field — any field SAP Business One can search by, a user-defined one included. It must, however, identify each record uniquely: if a value matches several records, the fetch fails. Rows whose Field of the row is empty get no additional data.level Rows of a list
Link to main recordWhich records belong to the main record: Field of the main record = Field of the main object, e.g. CardCode = CardCode. You pick the Field of the main record from the fields of the main record, nested ones included; fields inside a list are not offered. Optional; once either field is set, the other is required. Unlike on the row level, a value may match several records. If the Field of the main record is empty in the record, the query reads nothing.level Main record
Link to object in the Main object blockHow the sub-list hangs off the main object: Field of the main object = Field of the sub-object.as soon as a sub-object is selected
Link to main objectWhich record of the related object belongs to the main object: Field of the main object = Field of the related object, e.g. ItemsGroupCode = Number.as soon as a related object is selected
Link to object in the Related object blockHow the sub-list hangs off the related object: Field of the related object = Field of the sub-object.as soon as a sub-object is selected there

Result:

FieldMeaningAppears
FieldsWhich fields are taken over. Required: the mapping offers exactly these fields, and the Column name of a value list is chosen among them.as soon as a main object is selected
Result typeObject list — whole records — or Value list — only one column.level Main record
Column nameWhich column fills the value list.result type Value list
Row limitUpper limit of the rows read, at most 1000. The field may stay empty if a link to the main record or a condition narrows the query; if it then reads more than 1000 rows, the fetch fails.level Main record

The Level determines how often the query runs. Main record runs it once per record — suitable when you are looking for something about the record as a whole. Rows of a list runs it per row — suitable when each line of a document needs its own additional detail. The level also determines which fields appear afterwards at all: Result type, Column name and Row limit exist only on the main record. The first link in the Main object block stands in the same place on both levels and is called Link to row or Link to main record, depending on the level. If the main object's key field appears under the same name in the row or directly in the main record, the form proposes both fields. If you change the level, both fields stay; if the left one no longer fits the new level, it is marked red. If the new level has a field of the same name, the left field stays unmarked but now means that field — check it after every change of level.

Every link is a row with two fields that must be equal. Both fields are required as soon as the row appears — only the Link to main record may stay entirely empty. They must be of the same kind — a text field does not match a number field — and a field for long text is suitable for neither side. Messages name block and row before the field, e.g. Additional data 2 · Related object · Link to main object: "Field of the related object" is missing. If the two fields do not match, both turn red and the message names the whole row: Additional data 2 · Related object: "Link to main object" links fields that cannot be compared. Change either field and the row counts as open again until the next check.

The three links to a sub-object or related object may have several rows. That covers both Link to object rows and the Link to main object. A record then belongs only if every row applies. So the sub-list ContactEmployees of BusinessPartners reads only the default contact person when a second row ContactPerson = Name stands below CardCode = CardCode — with the first row alone you get every contact person of the customer. The Link button with the plus sign below the last row adds an empty row, the X at the end of a row removes it; a row with fields only after a confirmation. The last row always stays. Every row follows the same rules as above, and every message stands at its row. If the same pair of fields appears twice, a warning points it out. The Link to row and the Link to main record keep a single row.

When you select a related object, the form proposes the link. If exactly one field of one object refers to the other in SAP Business One, that link fills the row. Otherwise the form enters the related object's key as Field of the related object and the field of the same name as Field of the main object — a leading U_ and upper or lower case do not count. If there is no such field, or more than one, that half stays empty. Every proposal can be overwritten.

A change takes along what hung off the changed object. If you select a different related object or clear the field, its link, its sub-object and the fields and conditions that concerned it are removed. The same holds for a changed sub-object. If you change the main object, the related object stays; only the Field of the main object of its link is proposed again.

Conditions of a query​

A condition has Field, Operator and Value. Without a condition it reads No condition — all records are retrieved.

The value can be a fixed entry or a reference into the source record. In the second case you enter a path, e.g. OriginalPayload.ItemCode — so each run gets the value of the record it is currently working on.

The operators of an additional-data condition are a separate, smaller set than those of the data filter: equals, does not equal, is greater than, is greater than or equal to, is less than, is less than or equal to, starts with, ends with, contains, is empty, is not empty. ends with exists only here.

The field list fills from the source: if it reads Enter the fetch endpoint. or Load a message., the basis for it is still missing.

Xchange checks a placeholder in the Condition value while you are still editing and marks the field red if it points nowhere: "'Condition value' does not exist in the field structure". If it points to a list or an object, the field reports "'Condition value' points to a list or an object instead of a single value" — a condition always compares with a single value.

Running​

The queries are run via Fetch additional data in the data preview. The button appears only once reference data is loaded and at least one query exists; without reference data it reads No reference data loaded yet. Once everything is loaded, Additional data fetched appears. If you change a query afterwards, Outdated — fetch again appears.

If a query cannot be run, Additional data incomplete appears with "1 query could not be run:" or "… queries could not be run:", and below it, per query, one of these reasons:

ReasonWhat is missing or does not fit
"Select a main object"No Object is selected in the Main object block.
"Select at least one field (main object or sub-object)"Fields is empty.
"Add a condition on the main object"The query needs a link or condition that narrows the main object.
"A field in the condition has no known data type — validate the draft and activate it again"The data type of a condition field is unknown.
"A row of the condition is invalid — validate the draft and activate it again"A condition row is incomplete or contradictory.
"The main object's field in the link has no known data type — validate the draft and activate it again"The data type of the link field is unknown.
"A placeholder cannot be resolved against the source record — check the placeholder and the source data"A path in the Condition value finds nothing in the reference data.
"The field from the link leads to no single value — choose the link's field again"The field of the row or of the main record is a list or an object.
"A comparison value does not match its field's data type and was not sent — check the condition and the source data"The value from the reference data does not fit the condition's field.
"No row of the row list carries the row's field from "Link to row" — check the field name against the data preview"The Field of the row occurs in no row.
"The main object's field from the link does not exist on the selected object — check the field name"The main object has no such link field.
"A field in the condition does not exist in the main object — check the field name"The main object has no such condition field.
"The main object's field from the link is a list or an object, not a single value — choose a different field"The link field in the main object is not a single value.
"A field in the condition is a list or an object, not a single value — choose a different field"The condition field is not a single value.
"A value from "Link to row" matches several records — choose a main-object field that identifies each record uniquely"On the row level a value matches several records.
"The query returns too many records — narrow its condition"The query reads more than 1000 rows.

Data preview​

The right column shows what the route really works with. If the connection supplies a field structure, you switch between two views with Display:

DisplayWhat you see
Reference datathe loaded record with real values, including fetched additional data
Field structurethe structure alone

Without a field structure, Display is missing and the column shows the reference data.

If there is nothing yet, it reads Insert reference data to fill the data preview. If only the field structure is loaded, Field structure loaded — insert reference data to see actual values. points out the difference.

The column can be shown and hidden with the Data preview button. It sits next to the Data source heading; if the route has no data source of its own, next to Reference data. On a dispatch route there is neither the column nor the button. The column's heading with Fetch additional data stays in place while you scroll.

See also​