Nil Values / Nillable
The XML Schema specification allows for an element to be valid without content if the nillable="true" attribute has been defined for that specific element in the schema. In the instance XML document, you can then indicate that the value of an element is nil by adding the xsi:nil="true" attribute to it. This section describes how MapForce handles nil elements in source and target components.
'xsi:nil' versus 'nillable'
The xsi:nil="true" attribute is defined in the XML instance document.
The xsi:nil="true" attribute indicates that, although the element exists, it has no content. Note that the xsi:nil="true" attribute applies to element values, and not to attribute values. An element with xsi:nil="true" may still have other attributes, even if it does not have content.
The xsi:nil attribute is not displayed explicitly in the MapForce graphical mapping, because it is handled automatically in most cases. Specifically, a "nilled" node (one that has the xsi:nil="true" attribute) exists, but its content does not exist.
Nillable elements as mapping source
MapForce checks the xsi:nil attribute automatically, whenever a mapping reads data from nilled XML or XBRL elements. If the value of xsi:nil is true, the content will be treated as non-existent.
When you create a target-driven connection from a nillable source element to a nillable target element with simple content (a single value with optional attributes, but without child elements), where xsi:nil is set on a source element, MapForce adds the xsi:nil attribute to the target element (for example, <OrderID xsi:nil="true"/>).
When you create a Copy-All connection from a nillable source element to a nillable target element, where xsi:nil is set on a source element, MapForce adds the xsi:nil attribute to the target element (for example, <OrderID xsi:nil="true"/>).
To check explicitly whether a source element has the xsi:nil attribute set to true, use the is-xsi-nil function. It returns true for nilled elements and false for other nodes.
To substitute a nilled (non-existing) source element value with something specific, use the substitute-missing function.
•Connecting the exists function to a nilled source element returns true, since the element node actually exists, even if it has no content.
•Using functions that expect simple values (such as multiply and concat) on elements where xsi:nil has been set does not yield a result, as no element content is present and no value can be extracted. These functions behave as if the source node did not exist.
Nillable elements as mapping target
When you create a target-driven connection from a nillable source element to a nillable target element with simple content (a single value with optional additional attributes, but without child elements), where xsi:nil is set on a source element, MapForce inserts the xsi:nil attribute into the target element (for example, <OrderID xsi:nil="true"/>). If the xsi:nil="true" attribute has not been set in the XML source element, then the element content is mapped to the target element in the usual fashion.
When mapping to a nillable target element with complex type (with child elements), the xsi:nil attribute will not be written automatically, because MapForce cannot know at the time of writing the element's attributes if any child elements will follow. For such cases, define a Copy-All connection to copy the xsi:nil attribute from the source element.
When mapping an empty sequence to a target element, the element will not be created at all, independent of its nillable designation.
To force the creation of an empty target element with xsi:nil set to true, connect the set-xsi-nil function directly to the target element. This works for target elements with simple and complex types.
If the node has simple type, use the substitute-missing-with-xsi-nil function to insert xsi:nil in the target if no value from your mapping source is available. This can happen if the source node does not exist at all, or if a calculation (for example, multiply) involved a nilled source node and therefore yielded no result.
Functions which generate xsi:nil cannot be passed through functions or components which only operate on values (such as the if-else function).
Mapping NULL database fields to xsi:nil
If you map a NULL database field to an nillable element of an XML schema, MapForce generates only those target elements which actually contain database data. Elements of NULL database fields are not created in the target component. Connecting the exists node function to such a source element results in false for the NULL fields.
To force the creation of all elements in the target component, use the substitute-missing-with-xsi-nil function from the node functions of the core library.
The screenshot above illustrates how the substitute-missing-with-xsi-nil function is used to create target elements for all database fields:
•All missing/NULL database fields contain <OrderID xsi:nil="true"/> in the target element.
•Existing data from database fields is mapped directly to the target element e.g. <OrderID>1</OrderID>.
To see the NULL fields of a database component, click the Database Query button and run a query on the database table(s). Null fields are shown as [NULL] in the Results window.
Mapping xsi:nil to NULL database fields
If you map a nilled XML element to a database column, MapForce writes a NULL value to the database. You can also use the set-null function if you want to set a database field to NULL unconditionally.