Skip to content

Keyed Rewrite Write Response

When a webservice creates or updates data, it typically replies with the fully populated record, but not always in the order it was sent. Keyed rewriting matches each element of the response back to its record by a value, not by position.

The XML Writer matches by key in the same way, with XPath in place of JPath and namespaces to declare.

If you send a list of customers, suppliers or products for insert, the reply may come back in a different order: reversed, grouped or sorted by the service. Sequential rewriting would then write each record's values onto the wrong record, without any error. Use keyed rewriting in that case.

IMan matches on a field marked as the key. It must uniquely identify a record among the siblings of its own transaction type, and each transaction type has exactly one.

The response must contain a value that can be matched back, or the rewrite does not happen. A unique incrementing value per record, or a customer, supplier or product id, will do.

Configuring the response

IMan parses the response using JPath. You configure it the way you configure a JSON Reader: an Initial Path, a Transaction Path per transaction and a Field Path per field.

The IMan dataset on the left, each record carrying a key value, beside a webservice response whose orders and line items come back in the reverse order — the connectors between them cross, because it is the key value and not the position that decides which record an element belongs to

Initial Path

The path to the first array, or repeating set of nodes, in the response.

Set it with Initial Return JPath on the writer's Field Mapping tab.

Transaction Path

The path to the array, or repeating set of nodes, holding this transaction's records. It is relative to the parent transaction's path, or to the Initial Path for the top-most transaction.

Set it with Transaction Type Return JPath, per transaction.

Unlike sequential rewriting, the order of the elements does not matter. IMan matches each one to its record by the key below.

Is Rewrite Key Field

Marks the field as the key used to match the response back to the IMan data.

The check box is in the field's own dialog, and appears only while the rewrite is set to Keyed Text Data. It is absent under Sequential or Binary, where there is nothing to key on.

A transaction with no key field is skipped, and so are its children

If a transaction type has no key field marked, IMan does not process it at all, whatever else is configured on it. Nor does it process any transaction beneath it.

IMan reports nothing. The rewrite writes nothing back for that branch. The walk starts at the top, so if the top-most transaction has no key field marked, the whole rewrite does nothing.

If a keyed rewrite appears to be ignored, check for an unmarked key field first.

A key in the response that matches no record fails the run

The opposite case does raise an error. Where the response carries a key value that no record in the dataset has, the transform stops with:

An error occurred whilst writing back values. Error - Cannot find
transaction in response data for [<key field> - <value>].

So a response containing more than was sent, or one whose key is read from the wrong path, is an error, not a partial rewrite. A sequential rewrite, by contrast, accepts a short response.

Response Field Path

The path to the property in the response holding this field's value, relative to the Transaction Path. Set it with Response JPath in each field's dialog.

IMan writes back only to fields with a populated Response JPath. Is Relative Response JPath decides whether IMan reads it from the Transaction Path or from the root.