Cross-Reference Functions

xref:BulkPopulateDomainData

Syntax

xref:BulkPopulateDomainData(mapName, domainList, dataRowsPath, dataValuesPath, mode)

Description

The XREF bulk populate domain data function populates cross-reference data from XML. It sequences through the rows of data provided in the XML nodeset and uses the supplied domain list and data values path to access the values for each domain in each row. Each row of data is then inserted into the XREF framework for the specified map utilizing bulk insert to maximize performance. This function is expected to be used for processing large volumes of data. It provides an abstraction layer from the physical data persistence layer of the XREF framework. because inserts are done using bulk mode, duplicates are not looked for until the end of the insert sequence. If a duplicate is encountered, none of the rows of data will be inserted. When a domain contains multiple elements, each value for the domain must contain a compound value consisting of a value for each element in the domain separated by the concatenation string specified in the value map options. In this scenario, this function will unconcatenate the domain element values before inserting the data into the transformation framework.

Parameters

Parameter	Description
mapName	The name of a dynamic (cross reference) value map, as string.
domainList	A comma separated list of domain names identifying the order of the data values to be imported.
dataRowsPath	An XPath expression resulting in a series of XML nodes where each node represents one row of data.
dataValuesPath	An XPath expression (relative to each row of data) used to identify each node containing a data value within a row of data. The nodeset returned when this path is evaluated must contain the same number of nodes as there are domains in the specified domainList.
mode	Only `ADD` mode is supported.

Returns

Boolean indicating success or failure of the process.

xref:BulkPopulateElementData

Syntax

xref:BulkPopulateElementData(mapName, elementList, dataRowsPath, dataValuesPath, mode)

Description

The XREF bulk populate element data function populates cross-reference data from XML. It sequences through the rows of data provided in the XML nodeset and uses the supplied pairs of elements and XPath expressions to access the values for the elements in each row. Each row of data is then inserted into the XREF framework for the specified map utilizing bulk insert to maximize performance. This function is expected to be used for processing large volumes of data. It provides an abstraction layer from the physical data persistence layer of the XREF framework. because inserts are done using bulk mode, duplicates are not looked for until the end of the insert sequence. If a duplicate is encountered, none of the rows of data will be inserted.

Parameters

Parameter	Description
mapName	The name of a dynamic (cross reference) value map, as string.
elementList	A comma separated list of element names identifying the order of the data values to be imported.
dataRowsPath	An XPath expression resulting in a series of XML nodes where each node represents one row of data.
dataValuesPath	An XPath expression (relative to each row of data) used to identify each node containing a data value within a row of data. The nodeset returned when this path is evaluated must contain the same number of nodes as there are domains in the specified domainList.
mode	Only `ADD` mode is supported.

Returns

Boolean indicating success or failure of the process.

xref:populateXRefRow

Syntax

xref:populateXRefRow(mapName, referenceElementName, referenceValue, elementName, elementValue, mode)

Description

Use the populateXRefRow function to populate a cross-reference element with a value.

Parameters

Parameter	Description
mapName	The name of the cross-reference map, as string.
referenceElementName	The name of the reference element, as string.
referenceValue	The value corresponding to the reference element name, as string.
elementName	The name of the element to be populated, as string.
elementValue	The value with which to populate the element, as string.
mode	The mode in which the function populates the element. You can specify any of the following values: ADD, LINK, or UPDATE. The mode parameter values are case-sensitive and must be specified in the uppercase only.

Returns

This function returns the cross-reference value being populated as a string.

This table lists the results for the Xref:populateXRefRow function.

Mode	Reference Value	Value to Be Added	Result
ADD	Absent Present Present	Absent Absent Present	Success Exception Exception
LINK	Absent Present Present	Absent Absent Present	Exception Success Exception
UPDATE	Absent Present Present	Absent Absent Present	Exception Exception Success

Mode

Reference Value

Value to Be Added

Result

ADD

Absent

Present

Absent

Present

Success

Exception

LINK

Absent

Present

Absent

Present

Exception

Success

Exception

UPDATE

Absent

Present

Absent

Present

Exception

Success

Example

This table lists examples of the modes with their descriptions and exception reasons:

Mode	Description	Exception Reasons
ADD	Adds the reference value and the value. For example: xref:populateXRefRow("customers", "PS","PS101","Common","CM001","ADD") adds the reference value `PS101` in the `PS` element and the value `CM001` in the `Common` element of the `customers` cross-reference map.	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified elements are not found. The values provided are empty. The value being added is not unique across that element for that map. The element for that row already contains a value. The reference value exists.
LINK	Adds the cross-reference value corresponding to the existing reference value. For example: xref:populateXRefRow("customers", "Common","CM001","SBL","SB-101","LINK") adds the value `SB-101` in the `SBL` element of the `customers` cross-reference map and links it to the value `CM001` in the `Common` element.	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified elements are not found. The values provided are empty. The reference value is not found. The value being linked exists in that element for that map.
UPDATE	Updates the cross-reference value corresponding to an existing reference element-value pair. For example: xref:populateXRefRow("customers","PS", "PS100","PS","PS1001","UPDATE") updates the value `PS100` in the `PS` element of the `customers` cross-reference map to value `PS1001.`	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified elements are not found. The values provided are empty. The value being updated is not unique across that element for that map. Multiple values are found for the element being updated. The reference value is not found. The element for that row does not have a value.

Mode

Description

Exception Reasons

ADD

Adds the reference value and the value. For example:

xref:populateXRefRow("customers", 
"PS","PS101","Common","CM001","ADD")

adds the reference value PS101 in the PS element and the value CM001 in the Common element of the customers cross-reference map.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified elements are not found.
The values provided are empty.
The value being added is not unique across that element for that map.
The element for that row already contains a value.
The reference value exists.

LINK

Adds the cross-reference value corresponding to the existing reference value. For example:

xref:populateXRefRow("customers", 
"Common","CM001","SBL","SB-101","LINK")

adds the value SB-101 in the SBL element of the customers cross-reference map and links it to the value CM001 in the Common element.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified elements are not found.
The values provided are empty.
The reference value is not found.
The value being linked exists in that element for that map.

UPDATE

Updates the cross-reference value corresponding to an existing reference element-value pair. For example:

xref:populateXRefRow("customers","PS", 
"PS100","PS","PS1001","UPDATE")

updates the value PS100 in the PS element of the customers cross-reference map to value PS1001.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified elements are not found.
The values provided are empty.
The value being updated is not unique across that element for that map.
Multiple values are found for the element being updated.
The reference value is not found.
The element for that row does not have a value.

xref:populateXrefRowNVP

Syntax

xref:populateXRefRowNVP(mapName, referenceDomain, referenceNVP, targetDomain, targetNVP, mode)

Description

Use the xref:populateXrefRowNVP function to populate multiple elements in the cross-reference map with values.

Parameters

Parameter	Description
mapName	The name of the cross-reference map, as string.
referenceDomain	The name of the reference domain, as string.
rreferencesNVP	NVP list of reference elements and values, as string.
targetDomain	The name of the domain to be populated, as string.
targetNVP	NVP list of elements and values to be populated in the elements, as string.
mode	The mode in which the function populates the element. You can specify any of the following values: ADD, LINK, or UPDATE. The mode parameter values are case-sensitive and must be specified in the uppercase only.

Returns

This table lists the results for the populateXrefRowNVP function.

Mode	Reference Value	Value to Be Added	Result
ADD	Absent Present Present	Absent Absent Present	Success Exception Exception
LINK	Absent Present Present	Absent Absent Present	Exception Success Exception
UPDATE	Absent Present Present	Absent Absent Present	Exception Exception Success

Mode

Reference Value

Value to Be Added

Result

ADD

Absent

Present

Absent

Present

Success

Exception

LINK

Absent

Present

Absent

Present

Exception

Success

Exception

UPDATE

Absent

Present

Absent

Present

Exception

Success

Example

This table lists the modes with their descriptions and exception reasons:

Mode	Description	Exception Reasons
ADD	Adds the reference value and the value to be added. For example: xref:populateXRefRowNVP("Items","PeopleSoft", "<Setid>SHARE</Setid><ItemID>1005</ItemID>", "Common","<Common>” \| generate-guid() \| ”</Common>", "ADD") adds the reference values `SHARE/1005` in the `PeopleSoft` domain and the value `<guid1>` in the `Common` domain.	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified domains are not found. The specified elements are not found. The values provided are empty. The values being added are not unique across that domain for that map. The element for that row already contains a value. The reference value exists.
LINK	Adds the cross-reference value corresponding to the existing reference value. For example: xref:populateXRefRowNVP("Items","PeopleSoft", "<Setid>SHARE</Setid><ItemID>1005</ItemID>", "Retail","<Product>RP0005</Product>","LINK") adds value `RP005` to the `Retail` domain and links it to reference values `SHARE/1005` in the `PeopleSoft` domain.	Exceptions can occur due for following reasons: The specified cross-reference map is not found. The specified domains are not found. The specified elements are not found. The values provided are empty. The reference value is not found. The value being linked exists in that domain for that map.
UPDATE	Updates the cross-reference value corresponding to an existing reference element-value pair. For example: xref:populateXRefRowNVP("Items","PeopleSoft", "<Setid>SHARE</Setid><ItemID>1000</ItemID>", "PeopleSoft","<Setid>SHARE</Setid> <ItemID>10000</ItemID>","UPDATE") updates the value `1000` in the `ItemID` element of the `PeopleSoft` domain to value `10000.`	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified domains are not found. The specified elements are not found. The values provided are empty. The values being updated are not unique across that domain for that map. Multiple values are found for the domain being updated. The reference value is not found. The element for that row does not have a value.

Mode

Description

Exception Reasons

ADD

Adds the reference value and the value to be added. For example:

xref:populateXRefRowNVP("Items","PeopleSoft", 
"<Setid>SHARE</Setid><ItemID>1005</ItemID>", 
"Common","<Common>” | generate-guid() | ”</Common>", 
"ADD")

adds the reference values SHARE/1005 in the PeopleSoft domain and the value <guid1> in the Common domain.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified domains are not found.
The specified elements are not found.
The values provided are empty.
The values being added are not unique across that domain for that map.
The element for that row already contains a value.
The reference value exists.

LINK

Adds the cross-reference value corresponding to the existing reference value. For example:

xref:populateXRefRowNVP("Items","PeopleSoft", 
"<Setid>SHARE</Setid><ItemID>1005</ItemID>", 
"Retail","<Product>RP0005</Product>","LINK")

adds value RP005 to the Retail domain and links it to reference values SHARE/1005 in the PeopleSoft domain.

Exceptions can occur due for following reasons:

The specified cross-reference map is not found.
The specified domains are not found.
The specified elements are not found.
The values provided are empty.
The reference value is not found.
The value being linked exists in that domain for that map.

UPDATE

Updates the cross-reference value corresponding to an existing reference element-value pair. For example:

xref:populateXRefRowNVP("Items","PeopleSoft", 
"<Setid>SHARE</Setid><ItemID>1000</ItemID>", 
"PeopleSoft","<Setid>SHARE</Setid> 
<ItemID>10000</ItemID>","UPDATE")

updates the value 1000 in the ItemID element of the PeopleSoft domain to value 10000.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified domains are not found.
The specified elements are not found.
The values provided are empty.
The values being updated are not unique across that domain for that map.
Multiple values are found for the domain being updated.
The reference value is not found.
The element for that row does not have a value.

xref:markForDelete

Syntax

xref:markForDelete(mapName, elementName, elementValue)

Description

Use the xref:markForDelete function to delete a value in a cross-reference map when the element specified is the only element for a single domain. The value in the element is marked as deleted. If multiple domains reference the element or the domain the element is referenced by has multiple primary elements, use the xref:markForDeleteNVP function instead.

A cross-reference map row should have at least two mappings. Therefore, if you have only two mappings in a row and you mark one value for delete, then the value in another element is also deleted.

Any element value marked for delete is treated as if the value does not exist. Therefore, you can populate the same element with the xref:populateXRefRow function in ADD mode. However, if the element value is marked for delete as a reference, it cannot be used in the LINK mode of xref:populateXRefRow function.

Parameters

Parameter	Description
mapName	The cross-reference map name, as string.
elementName	The name of the element from which you want to delete a value, as string.
elementValue	The value to be deleted, as string.

Returns

This function returns true if deletion was successful; otherwise, it returns false.

An exception can occur for the following reasons:

The cross-reference map with the given name is not found.
The specified element name is not found.
The specified element name is not unique to a domain.
The specified value is empty.
The specified value is not found in the element.
Multiple values are found.

Example

The following code deletes the PS001 value in the PS element of the customers cross-reference map:

xref:markForDelete("customers","PS","PS001")

xref:markForDeleteNVP

Syntax

xref:markForDeleteNVP(mapName, referenceDomain, referenceNVP)

Description

Use the xref:markForDeleteNVP function to delete a set of values in a cross-reference map for a specified domain. The values in the elements are marked as deleted.

A cross-reference map row should have at least two mappings. Therefore, if you have only two mappings in a row and you mark one value for delete, then the value in the other domain is also deleted.

Any values marked for delete are treated as if they do not exist. Therefore, you can populate the same elements with the xref:populateXRefRowNVP function in ADD mode. However, if the element value is marked for delete as a reference, it cannot be used in the LINK mode of xref:populateXRefRowNVP function.

Parameters

Parameter	Description
mapName	The cross-reference map name, as string.
referenceDomain	The name of the reference domain, as string.
referenceNVP	NVP list of reference elements and values that you want to delete, as string.

Returns

This function returns true if deletion was successful; otherwise, it returns false.

An exception can occur for the following reasons:

The cross-reference map with the given name is not found.
The specified element name is not found.
All primary elements in this domain have not been specified.
The specified value is empty.
The specified value is not found in the element.
Multiple values are found.

Example

The following code deletes the specified values in the Setid and ItemID elements of the PeopleSoft domain from the Items cross-reference map:

xref:markForDeleteNVP ("Items","PeopleSoft","<Setid>SHARE</Setid><ItemID>1000</ItemID>")

xref:lookupXRef

Syntax

xref:lookupXRef (mapName, referenceElementName, xrefReferenceValue, elementName, needAnException)

Description

Use the lookupXRef function to look up a cross-reference element for a value that corresponds to a specific value in a reference element.

Parameters

Parameter	Description
mapName	The name of the cross-reference map, as string.
referenceElementName	The name of the reference element, as string.
referenceValue	The value corresponding to the reference element name, as string.
elementName	The name of the element to be looked up for the value, as string.
needAnException	Specify true or false. If the needAnException parameter is set to true, an exception occurs if the value being looked up in the map is not found. If the needAnException parameter is set to false, an empty value is returned if the value being looked up in the map is not found.

Returns

The value of the requested element.

An exception can occur for the following reasons:

The cross-reference map with the given name is not found.
The specified element names are not found.
The specified reference value is empty.
Multiple target values are found.

Example

The following code looks up the Common element of the customers cross-reference map for a value corresponding to the PS001 value in the PS element:

xref:lookupXRef("customers","PS","PS001","Common",true())

xref:lookupXRefNVP

Syntax

xref:lookupXRefNVP (mapName, referenceDomain, referenceNVP, targetDomain, needAnException)

Description

Use the lookupXRefNVP function to look up cross-reference values that correspond to a specified set of values in a reference domain. All primary elements in the reference domain must be included in the reference NVP list, but any qualifier elements are optional.

Parameters

Parameter	Description
mapName	The name of the cross-reference map, as string.
referenceDomain	The name of the reference domain, as string.
referenceNVP	NVP list of reference elements and values, as string.
targetDomain	The name of the domain to be looked up for the values, as string.
needAnException	Specify true or false. If the needAnException parameter is set to true, an exception occurs if the value being looked up in the map is not found. If the needAnException parameter is set to false, an empty value is returned if the value being looked up in the map is not found.

Returns

The return string includes values for all primary and qualifier elements in the target domain as an NVP list.

An exception can occur for the following reasons:

The cross-reference map with the given name is not found.
The specified domain names are not found.
The specified element names are not found.
The specified reference value is empty.
Multiple target values are found.

Example

The following code looks up the values of all elements in the Common domain of the Items cross-reference map that correspond to values SHARE/1000 in the PeopleSoft domain:

xref:lookupXRefNVP("Items","PeopleSoft","<Setid>SHARE</Setid><ItemID>1000</ItemID>","Common",true())