Custom Groovy Field Mapping is similar to Custom Java Field Mapping in that they both can handle more complex logics and allow multiple fields to participate at the same time. Custom Groovy Field Mapping is easier to use because the Groovy script is embedded in the customization description XML file, and therefore will not require a separate jar file. Groovy code can be defined either from the Gateway user interface or in the XML description file as shown below.
The syntax of Custom Groovy Field Mapping in the customization description XML file is also similar to Custom Java Field Mapping. The following is an example from Customization.xml in SampleCustomization project.
<GroovyFieldMappingTemplates>
<App1Name>Sample</App1Name>
<App2Name>P6</App2Name>
<GroovyFieldMappingTemplate>
<Description>Sample Groovy resource field mapping</Description>
<App1BusinessObjectName>Resource</App1BusinessObjectName>
<App2BusinessObjectName>Resource</App2BusinessObjectName>
<Name>SampleGroovyResourceFieldMap</Name>
<PDIBusinessObjectName>Resource</PDIBusinessObjectName>
<GroovyFieldMapping>
<Direction>GuestToPDI</Direction>
<SourceFields>EmployeeName,SampleDate</SourceFields>
<TargetFields>Name,PDISampleDate</TargetFields>
<RequireAllFields>true</RequireAllFields>
<Script>
<![CDATA[
Name = EmployeeName.toUpperCase();
if (containsField("EmployeeName")) {
{Name} = [EmployeeName].toUpperCase();
}
if (containsField("SampleDate")) {
def cal = new GregorianCalendar();
cal.setTime([SampleDate]);
cal.add(Calendar.DATE, -1);
cal.add(Calendar.HOUR, 2);
{PDISampleDate} = cal.getTime();
}
}
]]>
</Script>
</GroovyFieldMapping>
</GroovyFieldMappingTemplate>
</GroovyFieldMappingTemplates>
- At the top, declare the two applications involved in the integration.
- Declare what business object from each side is involved. In this example, it is Resource object for all 3 sides.
- Within one Groovy mapping (GroovyFieldMapping tag), specify the following tags:
- Direction: The direction of the mapping, it could be App1ToPDI, App2ToPDI, PDIToApp1 or PDIToApp2.
- SourceFields: Comma-separated field names from the source object.
- TargetFields: Comma-separated field names from the target object.
- Script: The script in Groovy code.
- RequireAllFields: When set to True, this mapping will be skipped unless all the source fields are present in the source object.
Within the Groovy script, use brackets to surround a source field, and curly brackets for a target field as in the following example:
{Name} = [EmployeeName].toUpperCase();
Where EmployeeName is a field from the source object, and Name is a field from the target object.
You can also use the containsField method to test whether a field exists in the source object. In the above example, the script uses containsField to test whether EmployeeName or SampleDate fields are there, before it executes the logic. This is important to know so as to avoid null pointer exceptions.
When the RequireAllFields tag is set to true, the script will only be called when all source fields are present in the source object; no possibility for null pointer exception there. But when the RequireAllFields tag is set to false, the script will be executed even when some source fields are not present in the source object. In the case when a source field is not present in the source object, for a primitive type field, such as integer, long, double types, the value will be set to default value 0; for a string type field, it will be set to default value ""; for a date type field, it will be set to null.
Limitations
For security reasons, the following limitations have been enforced on Groovy capability:
- Loops are not allowed.
- Closure is not allowed
- Class loading or reflection is not allowed
- New classes cannot be defined
- File system access is not allowed
- Network access is not allowed
- Classes under java.lang and java.util only can be accessed, but not any other packages
- Writing one or more expressions and calculating one or more target fields from one or more source fields is allowed