Download Groovy Integration

Overview

When dealing with complex file uploads, you can use a Groovy class or code snippets. Groovy runs within the JVM and is controlled by the DIH framework, so it can access the same classes, objects, and environmental components as DIH. This allows you to manipulate the file upload data while it is being uploaded, reducing the need for temporary or staging areas.

There is no parameter for Groovy. It should be coded in any of the following:

Executable Code Block with Groovy

The coded Groovy applies to all uploads for any task that uses the Executable.

To add a Groovy to an Executable, select com.ria.converter.api.executor.file.FileUploadWorkEntryExecutor in the Executable Class field and add the Groovy code to the first Code Block.

If a task linked to an executable contains Groovy code in the Data Block, the Groovy code in the Code Block will not be executed.

Task Data Block with Groovy

The coded Groovy applies only to the task where it is coded.

The coded Groovy is specified with the following parameters:

  • parameterName = value[;] The parameterName must be one of the supported Parameters. The value for the parameter can be specified over multiple lines, but the parameter name must start in the first column. A ; at the end of the line is optional. A parameter specified in a Data Block overrides any value for the same parameter in the Parameters definition.
  • groovy = … groovy code … There is no parameter for Groovy but a Groovy class or snippet. For more information, see Download Groovy methods.

Download Groovy class

Refer to the Upload Groovy class for information on coding a Groovy class. This information is generic and applies to downloads as well.

Download Groovy imports

Refer to the Upload Groovy imports for information on coding a Groovy class. This information is generic and applies to downloads as well.

Some DIH classes are commonly required by a download Groovy class. In addition to the default imports, the following are included in the DIH package, so they do not have to be imported.

  • com.ria.converter.api.runtime.TaskWorkExecutorParameters
  • com.ria.converter.api.runtime.ThreadLogger
  • com.ria.core.util.Utils
  • java.text.SimpleDateFormat
  • com.ria.converter.domain.maintenance.source.model.SourceColumn

Download Groovy methods

For file download, the following optional methods can be implemented or coded.

chooseMultiFileId

The def chooseMultiFileId(Map columnValues) method is used for multi-file downloads, where the {} placeholder is specified in the filePath parameter. It returns a file ID to be injected into the filePath in place of the {} placeholder.

For example:

def state = columnValues.get('STATE')
if (state == 'MD' || state == 'NJ') return 'east'
if (state == 'IL' || state == 'MI' || state == 'OH') return 'midwest'
if (state == 'AK' || state == 'LA') return 'south'
if (state == 'CA' || state == 'SD') return 'west'
return 'dunno'

startDownload

The startDownload initiates the file to download.

def startDownload(String fileId, TaskWorkExecutorParameters parameters, File file){
    //Add logic here
}

In a multi-file download, fileId identifies the file and can be used to perform file-specific processing.

The TaskWorkExecutorParameters include all run parameters, such as filePath, csvDelimiter, and any custom parameters.

The following are the main methods of the TaskWorkExecutorParameters object:

  • String getRequiredStringParameterValue(String parameterId)
  • String getOptionalStringParameterValue(String parameterId, String defaultValue)
  • String getNullableStringParameterValue(String parameterId)
  • Integer getIntegerParameterValue(String parameterId, Integer defaultValue)
  • Boolean getBooleanParameterValue(String parameterId)
  • Boolean getBooleanParameterValue(String parameterId, Boolean defaultValue)
  • Boolean hasParameterValue(String parameterId)

The File is for reference only. The method will open or create the file as needed.

For example, to log a message at the start of a download, use:

{% code overflow=“wrap” %}

def startDownload(ThreadLogger.logInfo('Starting download for job %s to output file %s',parameters.getJobName(), file.getAbsolutePath())){
    //Add logic here
}

{% endcode %}

buildHeader

If the buildHeader method is present and the createHeader parameter is set to true, the buildHeader method will be called at the beginning of the run to generate a header string for writing to the output file. This provides a programmatic alternative to the header parameter.

def buildHeader(String fileId, Map recordColumns, Map sourceColumns){
    //Add logic here
}

The recordColumns includes the list of columns to be downloaded and the definition of each column in its associated SourceColumn object.

The sourceColumns contains the complete list of columns, including those that were not selected for download. The sourceColumns has the following get methods to retrieve details about a column:

Method Description
String getColumnName() Returns a string with the column name.
int getColumnSeq() Returns an integer with the column’s ordinal sequence in the table or query.
boolean isPrimaryKey() Returns a boolean to determine if the column is a primary key.
int getColumnType() Returns an integer that specifies the type of column. For example, it returns a 1 for a character, 2 for numeric, etc. For the complete list of types, see Class java.sql.Types.
int getColumnSize() Returns the column size in bytes that is mainly relevant for character columns.
Integer getPrecision()

Returns the size of the integer part of a number. For example, precision is 15 in AMOUNT(15,2).

Returns null for non-numeric columns.
Integer getScale()

Returns the size of the decimal part of a number. For example, scale is 2 in AMOUNT(15,2).

Returns null for non-numeric columns.

To get more details about any of the columns in either recordColumns or sourceColumns, retrieve the sourceColumn object for the column and then use the above methods to get the info. For example:

def amountCol = recordColumns.get('AMOUNT')
def amountIntSize = amountCol.getPrecision()

The column definition can be used to determine things like field length for a fixed format record. You can also use \n to return multiple lines for a multi-line header.

buildXmlRoot

The buildXmlRoot method is called at the beginning of the run to generate the XML root element for writing to the output file. This provides a programmatic alternative to the xmlRoot parameter.

def buildXmlRoot(String fileId, Map recordColumns, Map sourceColumns){
    //Add logic here
}

For recordColumns and sourceColumns, see buildHeader.

This method must return a properly formed XML element. The closing element for the end of the download is automatically derived from this. For example, return '<xmlrootFromGroovy>'.

buildRecord

The buildRecord method creates the record for the output file.

def buildRecord(String fileId, Map columnValues){
    //Add logic here
}

The columnValues contains all the columns and their values as selected and formatted from the source. You can also retrieve the value for a column using the get method. For example:

String custNo = columnValues.get('CUSTOMER_NUMBER')
String effDt = String.valueOf(columnValues.get('EFFDT'))

This method returns a string that has the record to write to the file. For example,

return custNo+','+effDt

buildTrailer

The buildTrailer method creates a trailer record to write to the output file.

def buildTrailer(String fileId, Map columnValues){
    //Add logic here
}

The columnValues contains all the columns and their values as selected by the trailer parameter’s SQL query. If no trailer parameter is specified, the columnValues will be empty. You can also retrieve the value for a column using the get method. For example:

String totalAmount = String.valueOf(columnValues.get('TOT_AMOUNT'))
return 'Total amount = '+totalAmount

endDownload

The endDownload marks the end of the download and finalizes the file.

def endDownload(String fileId, TaskWorkExecutorParameters parameters, File file){
    //Add logic here
}