Xref Utility Class Methods
This section describes the Xref class methods. The methods are discussed in alphabetical order.
BulkPopulateDomainData
Syntax
BulkPopulateDomainData (mapName, domainList, dataRows, 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 |
An array of domain names identifying the order of the data values to be imported. |
|
dataRows |
An array of XML nodes where each node in the array is 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.
Example
Local EOTF_CORE:Xref:Functions &xref = create EOTF_CORE:Xref:Functions(); Local string &mapName = "VendorIDs"; Local array of string &domainList = ...; Local array of XmlNode &dataRows = ...; Local string &dataValuesPath = "..."; Local string &mode = "ADD"; Local boolean &success = &xref.BulkPopulateDomainData(&mapName, &domainList, &dataRows, &dataValuesPath, &mode);
BulkPopulateElementData
Syntax
BulkPopulateElementData (mapName, elementList , dataRows, 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 |
An array of element names identifying the order of the data values to be imported. |
|
dataRows |
An array of XML nodes where each node in the array is 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 elements in the specified elementList. |
|
mode |
Only ADD mode is supported. |
Returns
Boolean indicating success or failure of the process.
Example
Local EOTF_CORE:Xref:Functions &xref = create EOTF_CORE:Xref:Functions(); Local string &mapName = "VendorIDs"; Local array of string &elementList = ...; Local array of XmlNode &dataRows = ...; Local string &dataValuesPath = "..."; Local string &mode = "ADD"; Local boolean &success = &xref.BulkPopulateElementData(&mapName, &elementList, &dataRows, &dataValuesPath, &mode);
ExtractData
Syntax
ExtractData (mapName, domainList, tempRecName, instance)
Description
You can use the XREF extract data function to generate and execute set-based SQL to extract cross-reference data into a specified table. Prior to data extraction, all data is removed from the temp table for the specified process instance. Element values are mapped to fields in the temp record using the order of the specified domain list followed by the element order specified in the value map definition. If no domains are specified, element values are mapped to fields in the temp record using only the element order specified in the value map definition. This function provides an abstraction layer from the physical data persistence layer of the XREF framework, and is expected to be used for processing large volumes of data.
The temp table has the following design constraints:
The first column will be PROCESS_INSTANCE.
The second column will be used for UniqueGUID (EOTF_COMMONELEMENT).
The remaining columns correspond to the elements in the specified domain(s).
Note: If the third column is named EOTF_IMPORT_FLG, it will be valued with N during the export.
The temp table column names do not have to match the element names in the map.
The temp table should be uniquely keyed by ProcessInstance, UniqueGUID.
There may be a performance benefit from having an index on the elements of each specified domain.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
The name of the dynamic cross reference map, as string. |
|
domainList |
The name of the value map domain(s) to extract data for. Provide null or an empty array in this parameter to extract data for all domains in the map. |
|
tempRecName |
The name of the temp table to extract data into, as string. |
|
instance |
The number to use when qualifying process instance, as integer. |
Returns
Boolean indicating success or failure of the process.
Example
Local EOTF_CORE:Xref:Functions &xref = create EOTF_CORE:Xref:Functions();
Local string &mapName = "VendorIDs";
Local array of string &domainList = CreateArray("PS");
Local string &tempRecName = Record.HR_VENDOR_TAO;
Local boolean &success =
&xref.ExtractData(&mapName, &domainList, &tempRecName, &instance);
LookupValue
Syntax
LookupValue (mapName, referenceElementName, referenceValue, elementName, needAnException)
Description
Locate the reference element value in a cross-reference value map, and return the equivalent value for the specified element name. This form of lookup is used to find a single reference element and return a single element value.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
referenceElementName |
Name of an element in the Xref in which to look for a value, as string. |
|
referenceValue |
Value of an element in the Xref to look for, as string. |
|
elementName |
Name of the element in the Xref for which to return equivalent values, as string. |
|
needAnException |
True to return error messages, false to return blank. |
Returns
An array of string containing the equivalent values of elementName in the Xref.
Example
This example will look up value &guid1 in the UniqueGUID element of the &TestName cross-reference map and return the equivalent value of element &EBS1:
Local string &returnValue = &xref.LookupValue(&TestName, &UniqueGUID, &guid1, &EBS1, True);
This example will look up a value that does not exist in element &EBS1 of the &TestName cross-reference map to verify that the default value (blank) is returned when the NeedAnException parameter is false:
&returnValue = &xref.LookupValue(&TestName, &EBS1, "NotFound", &UniqueGUID, False);
LookupValue1M
Syntax
LookupValue1M ( mapName, referenceElementName, referenceValue, elementName, needAnException)
Description
Locate the reference element value in a cross-reference value map, and return the equivalent values of the specified element name as a named value pair (NVP) list. This form of lookup is used to find a single reference element and return one to many equivalent values for the specified element.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
referenceElementName |
Name of an element in the Xref in which to look for a value, as string. |
|
referenceValue |
Value of an element in the Xref to look for, as string. |
|
elementName |
Name of the element in the Xref for which to return equivalent values, as string. |
|
needAnException |
True to return error messages, false to return blank. |
Returns
An array of string containing the equivalent values of elementName in the cross-reference.
Example
This example will look up value &guid1 in the UniqueGUID element of the &TestName cross-reference map and return the equivalent value of element &EBS1:
Local array of string &returnValue; &returnValue = &xref.LookupValue1M(&TestName, &UniqueGUID, &guid1, &EBS1, True);
This example will look up a value that does not exist in the UniqueGUID element of the &TestName cross-reference map to verify that no value is returned when the NeedAnException parameter is false:
&returnValue = &xref.LookupValue1M(&TestName, &UniqueGUID, "NotFound", &EBS1, False);
LookupValueNVP
Syntax
LookupValueNVP (mapName, referenceDomain, referenceNVP, targetDomain, needAnException)
Description
Locate the reference domain element values in a cross-reference map, and return the equivalent values of all elements in the specified domain as an NVP list. This form of lookup should be used when multiple elements exist in either the reference or return domain. All required elements in the reference domain must be included in the reference NVP list, but optional elements (qualifiers perhaps) do not have to be included. The return string will include values for all elements in the target domain as an NVP list regardless of whether they are required.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
referenceDomain |
Name of a domain in the XREF in which to look for a value, as string. |
|
referenceNVP |
Name value pairs of elements and values in the reference domain to look for, as an array of DataElement. |
|
targetDomain |
Name of the domain to return equivalent values for, as string. |
|
needAnException |
True to return error messages, false to return an NVP with the default values. |
Returns
An array of DataElement for name value pairs containing the equivalent values for the elements in the target domain, or the default values.
Example
This example will look up value &guid1 in the UniqueGUID domain of the &TestName cross-reference map and return the equivalent values for the &RTK domain:
Local array of EOTF_CORE:Common:DataElement &returnValue = &xref.LookupValueNVP(&TestName, &UniqueGUID, &UniqueGUIDrequestValues, &RTK, True);
MarkForDelete
Syntax
MarkForDelete (mapName, elementName, elementValue)
Description
Delete a value in a cross-reference map when the element specified is the only element for a single domain. If multiple domains reference the element, or the element is used in a domain containing multiple primary elements, the xref:markForDeleteNVP function should be used instead. The values in the elements are marked as deleted. If only two mappings are in a row and one of them is marked for deletion, then the value in the other domain will also be 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, using the element value marked for delete as a reference value in the LINK mode of the xref:populateXRefRow function would cause an error.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
elementName |
Name of the element in the Xref from which to delete a value, as string. |
|
elementValue |
Value of the element in the Xref to be deleted, as string. |
Returns
True if the delete succeeds.
Example
This example will delete the PS001 value in the PS element of the Customers cross-reference map:
&return=&xref.MarkForDelete("Customers", "PS", "PS001")
MarkForDeleteNVP
Syntax
MarkForDeleteNVP (mapName, referenceDomain, referenceNVP)
Description
Delete a set of values in a cross-reference map for a specified domain. The values in the elements are marked as deleted. If only two mappings are in a row and one of them is marked for deletion, then the value in the other domain will also be deleted. Any values marked for delete are treated as if they do not exist. Therefore, you can populate the same elements with xref:populateXRefRowNVP function in ADD mode. However, using the values marked for delete as a reference value in the LINK mode of the xref:populateXRefRowNVP function would cause an error.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
referenceDomain |
Name of a domain in the Xref from which to delete values, as string. |
|
referenceNVP |
Name value pairs of elements and values in the reference domain to be deleted, as an array of DataElement. |
Returns
True if the delete succeeds.
Example
This example deletes the specified values in the EBS domain from the Items cross-reference map:
Local array of EOTF_CORE:Common:DataElement &ebsNVP1 = CreateArrayRept(create EOTF_CORE:Common:DataElement(&EBS1), 1);
&ebsNVP1 [1].value = &value1;
Local boolean &return = &xref.MarkForDeleteNVP("Items", &EBS1, &ebsNVP1);
PopulateData
Syntax
PopulateData (mapName, domainName, tempRecName, recName, instance)
Description
You can use the XREF populate data function to generate and execute set-based SQL to populate cross-reference data from a specified source record (table or view). This function provides an abstraction layer from the physical data persistence layer of the XREF framework, and is expected to be used for processing large volumes of data.
The following steps are generated and executed in this function:
All data is removed from the temp table for the specified process instance.
Existing XREF data for the specified domain is extracted to the temp table with the import flag set to N.
Note: Element values are mapped to fields in the record based on map element order (not on name).
Distinct rows of stage data are inserted into the temp table if they do not already exist, with the update flag set to Y.
Note: Fields are mapped from temp to stage based on matching field names.
GUIDs are generated on the temp table where they are blank.
XREF data is inserted from the temp table where the import flag set to Y.
The stage data is updated with GUIDs from the temp table.
The temp table has the following design constraints:
The first column will be PROCESS_INSTANCE.
The second column will be used for UniqueGUID (EOTF_COMMONELEMENT).
The third column must be EOTF_IMPORT_FLG (for internal use by this function).
The remaining columns correspond to the elements in the specified domain.
The temp table column names do not have to match the element names in the maps.
The temp table column names must match the corresponding fields on the stage table.
The temp table should be keyed by ProcessInstance, UniqueGUID allowing for duplicates (blanks).
There may be a performance benefit from having an index on the elements of each specified domain.
Note: This function does not validate any of the data, therefore, users should be sure the data being populated does not violate any of the constraints defined in the value map definition. If the data rules are violated, future usability of the map may be impacted. This function is not responsible for protecting against the potential for truncation of existing data values caused by defining temp table fields shorter than the existing data values. If this occurs, no error will then be thrown, but existing values will not be matched properly to stage values, potentially resulting in unintended data redundancy.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
The name of a dynamic (cross reference) value map, as string. |
|
domainName |
The name of the value map domain to populate data for, as string. |
|
tempRecName |
The name of the temp table to extract existing XREF data to, as string. |
|
recName |
The name of the stage record to populate data from, as string. |
|
instance |
The number to use when qualifying process instance, as integer. |
Returns
Boolean indicating success or failure of the process.
Example
Local EOTF_CORE:Xref:Functions &xref = create EOTF_CORE:Xref:Functions(); Local string &mapName = "VendorIDs"; Local string &domainName = "PS"; Local string &tempRecName = Record.HR_VENDOR_TAO; Local string &recName = Record.HR_VENDOR_STG; Local boolean &success = &xref.PopulateData(&mapName, &domainName, &tempRecName, &recName, &instance);
PopulateValue
Syntax
PopulateValue (mapName, referenceElementName, referenceValue, elementName, elementValue, mode)
Description
Locate a reference element value in a cross-reference map and populate another element in the same data row with an equivalent value. This form of populate is used to find a single reference element and populate a single element value.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
referenceElementName |
Name of an element in the Xref in which to look for a value, as string. |
|
referenceValue |
Value of an element in the Xref to look for, as string. |
|
elementName |
Name of the element in the Xref in which to supply an equivalent value, as string. |
|
elementValue |
The equivalent value to be supplied to 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 uppercase only. |
Returns
The UniqueGUID value of the Xref row where the data was populated.
Example
This example will locate value &guid1 in the UniqueGUID element of the &TestName cross-reference map, and update the equivalent value of element EBS1 to &value1:
&value1 = &value1 | "0"; &returnValue = &xref.PopulateValue(&TestName, &UniqueGUID, &guid1, &EBS1, &value1, &UPDATE);
This example will add values &guid3 in the UniqueGUID element and &value3 in the EBS1 element to the &TestName cross-reference map data:
Local string &guid3 = UuidGen(); Local string &value3 = "00003"; &returnValue = &xref.PopulateValue(&TestName, &EBS1, &value3, &UniqueGUID, &guid3, &ADD);
This example will add value &value4 in the EBS1 element to the &TestName cross-reference map data, and let the code generate a random UniqueGUID:
Local string &value4 = "00004"; &returnValue = &xref.PopulateValue(&TestName, &EBS1, &value4, &UniqueGUID, "", &ADD);
PopulateValueNVP
Syntax
PopulateValueNVP (mapName, referenceDomain, DataElement referenceNVP, targetDomain, targetNVP, mode)
Description
Locate the reference domain element values in a cross-reference map, and populate another domain's elements in the same data row with an equivalent value. This form of populate should be used when multiple elements exist in either the reference or target domain. All required elements in the reference domain must be included in the reference NVP list, but optional elements such as qualifiers do not have to be included.
Parameters
|
Parameter |
Description |
|---|---|
|
mapName |
Name of a dynamic (cross-reference) value map definition, as string. |
|
referenceDomain |
Name of a domain in the Xref in which to look for a value, as string. |
|
referenceNVP |
Name value pairs of elements and values in the reference domain to look for, as an array of DataElement. |
|
targetDomain |
Name of the domain in which to populate equivalent values, as string. |
|
targetNVP |
Element names and their equivalent values (NVPs) to be populated in the Xref map, as an array of DataElement. |
|
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 uppercase only. |
Returns
The UniqueGUID value of the Xref row where the data was populated.
Example
This example will locate value &guid1 in the UniqueGUID element of the &TestName cross-reference map, and update the equivalent value of element EBS1 to &value1:
&value1 = &value1 | "0"; &ebsNVP1 [1].value = &value1; &returnValue = &xref.PopulateValueNVP(&TestName, &UniqueGUID, &guidNVP1, &EBS, &ebsNVP1, &UPDATE);
This example will add values &guid3 in the UniqueGUID element and &value3 in the EBS1 element to the &TestName cross-reference map data:
Local string &guid3 = UuidGen(); Local array of EOTF_CORE:Common:DataElement &guidNVP3 = CreateArrayRept(create EOTF_CORE:Common:DataElement(&UniqueGUID), 1); &guidNVP3 [1].value = &guid3; Local string &value3 = "00003"; Local array of EOTF_CORE:Common:DataElement &ebsNVP3 = CreateArrayRept(create EOTF_CORE:Common:DataElement(&EBS1), 1); &ebsNVP3 [1].value = &value3; &returnValue = &xref.PopulateValueNVP(&TestName, &EBS, &ebsNVP3, &UniqueGUID, &guidNVP3, &ADD);
This example will add value &value4 in the EBS1 element to the &TestName cross-reference map data, and let the code generate a random UniqueGUID:
Local array of EOTF_CORE:Common:DataElement &guidNVP4 = CreateArrayRept(create EOTF_CORE:Common:DataElement(&UniqueGUID), 1); Local string &value4 = "00004"; Local array of EOTF_CORE:Common:DataElement &ebsNVP4 = CreateArrayRept(create EOTF_CORE:Common:DataElement(&EBS1), 1); &ebsNVP4 [1].value = &value4; &returnValue = &xref.PopulateValueNVP(&TestName, &EBS, &ebsNVP4, &UniqueGUID, &guidNVP4, &ADD); &requestValues = CreateArrayRept(create EOTF_CORE:Common:DataElement(&EBS1), 1); &requestValues [1].value = &value4;