User Guide : Designing and Executing Processes : Process Steps and Associated Components : Aggregator Step
 
Share this page                  
Aggregator Step
The Aggregator step allows you to choose an Aggregator instance to add to a process. The Aggregator component assembles a data object from individual message object. It is done by passing a message object containing a part to the PutMessage action. The Aggregator component must know when all the parts have been provided to produce the complete data object. The input message contains information that indicates the Aggregator on how to become part of a complex object. A typical application for an Aggregator component includes assembling complex documents from discrete parts.
Aggregator Step Properties
After adding an /download/attachments/25952258/Aggregator_Step.png?version=1&modificationDate=1491993572009&api=v2 Aggregator step from the Toolbox Palette to the canvas, you can double-click the step on the canvas and specify the following step properties in the Properties tab displayed at the bottom.
Setting
Description
Name
Unique name for the step.
Description
Description of the step (optional).
Enabled
Select this option to enable the step for execution. If it is not enabled, then the step on the canvas is greyed-out.
This option is useful when troubleshooting a process, especially when there are numerous steps in the process.
Error Handling
Select any of the following:
Abort Process - All the steps after the current step are skipped or the entire process is aborted (depending on how you have set the error logging options) if this step aborts due to an error.
Ignore Error - The remaining steps in the current process are executed even if this step aborts due to an error. This is selected by default.
Select Aggregator
Select an aggregator instance. These instances are displayed when you add an aggregator message component in the Configuration tab. For more information, see Adding Message Components in Configuring Processes.
Action
Select the action for the aggregator instance.
Parameters
Parameters for the selected action. Specify the values for the parameters.
Properties
Properties for the selected action. Specify the values for the properties.
Note:  The Actions, Parameters, and Properties are specific to the component type. For information about this, based on the component instance selected in the Select Aggregator drop-down list, see the component type in Aggregator Step Components.
Aggregator Step Components
EDI X12 Functional Group Aggregator
File Transfer Aggregator
JDBC WebRowSet Aggregator
HL7 Message Fragment Aggregator
HL7 Message Aggregator
EDI X12 Functional Group Aggregator
EDI X12 Functional Group Aggregator assembles pieces of an EDI (X12) file based on its Functional Group Header/Trailer (GS/GE).
EDI X12 Functional Group Aggregator Properties
You can specify the following properties when you create an instance of this aggregator component in the Configuration tab > Message Components section.
Property Name
Description
BuilderFile
Location and file name, where the aggregator component assembles the pieces of the EDI file.
Supported Actions
 
Action
Description
Connect
Opens a persistent connection to the component source.
Disconnect
Break the connection with the component source.
PutMessage
Sends the data contained in a DJMessage object to the database. The maximum size limit for DJMessage is 512 MB.
Supported Action Parameters
 
Action
Parameter
Description
PutMessage
Message
Message string
Supported Action Properties
There are no supported action properties.
File Transfer Aggregator
File Transfer Aggregator reassembles a file that was split into message objects by the File Transfer Iterator. The aggregator uses information stored in the properties of the message objects to reassemble the file. Therefore, you must set the deserialize option to True to read information from the header file.
File Transfer Aggregator Properties
You can specify the following properties when you create an instance of this aggregator component in the Configuration tab > Message Components section.
Property Name
Description
BuilderDirectory
Name of the directory that the aggregator must use as a temporary directory when processing message objects.
NotifyDirectory
Location where the aggregator generates notification files.
Typically, the instance properties are set in a process that splits the file using the File Transfer Iterator. After an iterator step is used to execute a GetMessage action using the File Transfer Iterator, a Script step is used to set the properties on the message returned by the iterator step.
The aggregator can write any notification information to a file such as the status of the file that was reassembled. This file is generated if the NotifyDirectory option is set.
Note:  The BuilderDirectory and NotifyDirectory options do not support Internet addresses. The property values must be local directories or directories that can be accessed from the local computer.
The following expressions demonstrate how to set the message properties in the Script step:
Dim msg as DJMessage
Set msg = FindMessage( "Iterator_1_Output" )
msg.Properties( "DJFT TargetMode" ) = "Append"
msg.Properties( "DJFT TargeExpirationType" ) = "Hours"
msg.Properties( "DJFT TargetExpiration" ) = 2
Where,
TargetMode: Indicates whether to replace or append to the target. Allowable values are Replace and Append.
TargeExpirationType: The type of the target expiration value. Allowable values Years, Months, Days, Hours, Minutes, Seconds.
TargetExpiration: The time period for the transfer. The time expires when the current time equals the start transfer time plus the target expiration value.
Supported Actions
 
Action
Description
Connect
Opens a persistent connection to the component source.
Disconnect
Break the connection with the component source.
PutMessage
Sends the data contained in a DJMessage Object to the aggregator. The maximum size limit for DJMessage is 512 MB.
Supported Action Parameters
 
Action
Parameter
Parameter Description
Connect
-
-
Disconnect
-
-
PutMessage
Message
When the PutMessage action is called for an aggregator, the aggregator uses the body and/or properties of the Message parameter to add to the final output file that it is creating.
Supported Action Properties
There are no supported action properties.
Supported DJFT Properties and Parameters
The following properties must be set manually, if the previous process step does not generate it before calling the component.
Property
Description
SourceName
The name of the source file.
TranferUnitType
Indicates how to divide the source file into pieces. Allowable values are Bytes and Records.
TransferUnitCount
The number of bytes of number or records to include in each piece.
RecordLength
The number of characters to include in a record.
SourceRecordSeparator
The record separator to use when splitting the source. Default None.
SourceEncoding
The character set of the source data. The default is ENC_OEM (0).
TargetHostSystem
The name of the target host system.
TargetName
The name of the target file.
TargetExpiration
The time period for the transfer. The time expires when the current time equals the start transfer time plus the target expiration value.
TargetExpirationType
The type of the target expiration value. Allowable values Years, Months, Days, Hours, Minutes, Seconds.
TargetMode
Indicates whether to replace or append to the target. Allowable values are Replace and Append.
TargetRecordSeparator
The record separator to use when assembling the target. If not set, the SourceRecordSeparator value is used.
TargetEncoding
The character set of the target data. If not set, the SourceEncoding value is used.
The following are the parameters.
Parameter
Description
TransferId
Uniquely identifies each transfer. It is a hash of the source name, target host, target name and transfer start time.
PieceNumber
Indicates the sequential order of the piece.
PieceSize
Indicates the size of the message body in bytes.
Priority
The priority of the piece. Default 0. The last message has a priority of 1.
TotalPieceCount
The total number of pieces.
StartTime
The date/time the transfer started.
Supported Charactersets for encoding
The following are the values for supported character sets:
ENC_UTF16= -4
ENC_UTF8= -3
ENC_UCS2= -2
ENC_ERROR= -1
ENC_OEM= 0
ENC_ISO8859_1= 1// 8859-1
ENC_CP1252= 2// Microsoft 1252
ENC_ISO8859_2= 3
ENC_ISO8859_3= 4
ENC_ISO8859_4= 5
ENC_ISO8859_5= 6
ENC_ISO8859_6= 7
ENC_ISO8859_7= 8
ENC_ISO8859_8= 9
ENC_ISO8859_9= 10
ENC_CP1250= 11
ENC_CP1251= 12
ENC_CP1253= 13
ENC_CP1254= 14
ENC_CP1255= 15
ENC_CP1256= 16
ENC_CP1257= 17
ENC_CP1258= 18
ENC_SHIFTJIS= 19// Japanese Shift-JIS
ENC_WSHIFTJIS = 20 //Windows Shift-JIS (932)
ENC_GB2312 = 21 // Windows Extended GB (936)
ENC_KSC5601= 22// Win Unified Hangul (949)
ENC_BIG5= 23// Windows Big5 (950)
ENC_CP037= 24// EBCDIC USA/Canada
ENC_CP500= 25// EBCDIC International
ENC_CP875= 26// EBCDIC Greek
ENC_CP1026= 27 // EBCDIC Latin5 Turkish
ENC_CP437= 28// DOS Latin US
ENC_CP737= 29// DOS Greek
ENC_CP775= 30 // DOS Baltic Rim
ENC_CP850= 31 // DOS Latin 1
ENC_CP852= 32 // DOS Latin 2
ENC_CP855= 33 // DOS Cyrillic
ENC_CP857= 34 // DOS Turkish
ENC_CP860= 35 // DOS Portugese
ENC_CP861= 36 // DOS Icelandic
ENC_CP862= 37 // DOS Hebrew
ENC_CP863= 38 // DOS CanadaF
ENC_CP864= 39 // DOS Arabic
ENC_CP865= 40 // DOS Nordic
ENC_CP866= 41// DOS Cyrillic Russian
ENC_CP869= 42 // DOS Greek 2
ENC_CP874= 43 // DOS Thai
ENC_CP273= 44// EBCDIC Germany
ENC_CP277 = 45 // EBCDIC Norway and Denmark
ENC_CP278 = 46 // EBCDIC Sweden and Finland
ENC_CP280= 47// EBCDIC Italy
ENC_CP284= 48// EBCDIC Spain
ENC_CP285= 49// EBCDIC UK
ENC_CP297= 50// EBCDIC France
JDBC WebRowSet Aggregator
JDBC WebRowSet Aggregator connects to a specified database, issues insert, update, and delete statements (based on the WebRowSet data), and iteratively writes the WebRowSet XML data to the database. The write XML formats are described by WebRowSet XML schema at https://docs.oracle.com/javase/7/docs/api/javax/sql/rowset/WebRowSet.html. Insert, update, and delete statements have their own schema format (available at this link). The component only accepts the format described by XML schema.
To use this aggregator, you must have the following skill set:
Database administration
WebRowSet implementation
Java Database Connectivity (JDBC) knowledge
To connect to a database using JDBC WebRowSet Aggregator, you must provide information about the required type 4 JDBC drivers, database connection values, and the location of the batch response log file. In addition, the relevant type 4 JDBC-compliant driver JAR files must be available on the computer where the process runs that uses this aggregator. For example, to use IBM DB2, you must have db2cc.jar on your computer.
This aggregator supports the following databases (type 4 driver only):
Oracle
IBM DB2
PSQL
Microsoft SQL Server
JDBC WebRowSet Aggregator performs the following actions based on the processes that you define:
Reads the connection information, loads the drivers, and connects to the target database using the host URL, user ID, and password
Begins a transaction or batch update process
Parses the batch request and performs an insert/update/delete on the database. This action is performed for every transaction in the batch.
Writes the transaction status to the batch response log file
Ends the transaction or batch update process
Disconnects from the target database
Tip:  To submit SELECT statements to a database, use JDBC WebRowSet Iterator.
JDBC WebRowSet Aggregator Properties
You can specify the following properties when you create an instance of this aggregator component in the Configuration tab > Message Components section.
Property
Description
Log File Location
Log file location where the transaction status for the entire session is written.
Driver
JDBC driver to load.
For example, com.domain.jdbc.v2.Driver
Host URL
URL connection to the data base.
For example, jdbc:domain://myuser/demodata
User ID
User name for the database session.
Note:  Provide the user name and password for the database session only if it is configured for your database.
Password
Password for the database session.
Note:  Provide the user name and password for the database session only if it is configured for your database.
Jar Location
Location of the folder that contains the JAR files that are required to load the JDBC driver. JDBC WebRowSet Aggregator loads the drivers based on this location.
Note:  You cannot append multiple paths to the value. All the driver JAR files must be located in the same folder.
For example, for PSQL, you must load the pvjdbc2.jar and pvjdbc2x.jar files.
Caution!  Always use the latest .jar files for a particular database version.
Global Transaction
Select this option to set the aggregator instance as global.
Supported Actions
 
Action
Description
PutMessage
Sends the WebRowSet XML data contained in a DJMessage Object to the database. The maximum size limit for DJMessage is 512 MB.
During a database session, the WebRowSet XML is sent to the specified database that is associated with the step. The WebRowSet XML document contains the following:
The primary key
The data to insert, update, or delete in the specified table in the WebRowSet
The SQL SELECT statement to specify the table
GetMessage
Returns the log contents of the previously executed PutMessage action. This is optional.
Connect
Opens a persistent connection to the database
Disconnect
Closes an existing database connection and performs cleanup actions.
Tip:  Call Connect and Disconnect explicitly in your process flow.
BeginTransaction
Starts an implicit transaction for the session that can be committed or rolled back. You must specify the session to associate with the BeginTransaction action.
CommitTransaction
Commits any SQL statements that have been sent for insert/update/delete operations made on the database using the WebRowSet XML data.
RollBackTransaction
Rolls back any SQL statements that have been sent to the database using the WebRowSet XML format. You must specify the session to associate with the RollBackTransaction action.
Supported Action Parameters
 
Action
Parameter
Parameter Description
PutMessage
Message
Name of the message to put.
GetMessage
Message
Name of the message to get.
Connect
-
-
Disconnect
-
-
BeginTransaction
-
-
CommitTransaction
-
-
RollBackTransaction
-
-
Supported Action Properties
 
Action
Property
Property Description
PutMessage
Ignore Update Errors
Indicates whether the batch update operations must be stopped on the occurrence of the first error. The options are:
True - Batch update operations continue regardless of the SQL errors that may occur during the current batch request.
False - Batch update operations stop at the occurrence of the first error during the batch request. The default value is False.
Note:  This option applies only to the errors or SQL exceptions that occur while running JDBC statements.
GetMessage
 
-
Connect
-
-
Disconnect
-
-
BeginTransaction
-
-
CommitTransaction
-
-
RollBackTransaction
-
-
Handling Null and Empty Tags in WebRowSet XML
If your WebRowSet XML file contains null values, you must modify it to include them as one of the following:
<columnValue><null/><columnValue>
<columnValue xsi:nil='true'><columnValue>
If you have specified xsi:nil=true and have included a column value, then xsi:nil takes preference and a null value is inserted.
String Data Type
If your WebRowSet XML data contains an empty string (specified as either <columnValue></columnValue> or <columnValue><emptyString/></columnValue>), then an empty string is inserted in the database for Character, VARCHAR, and CLOB data types.
Numeric, Date, Timestamp, Time, Boolean, Bit Data Types
If your WebRowSet XML data contains the following, then a value of null is inserted for that column.
<columnValue></columnValue>
<columnValue><emptyString/>
</columnValue>
Errors
The following table lists the various error conditions that are specific to JDBC WebRowSet Aggregator.
Code
Name
Description
Reason
8
ERR_WRITERR
Error during the execution of the SQL statements
ERR_WRITERR is returned when Ignore Update Errors= false and an exception (StopOnErrorException) occurred when running the SQL statements.
This error code denotes the error that occurred during the execution of the SQL statements constructed out of a WebRowSet batch request.
This error code is also returned when there is an exception at the time of writing the batch response log to the log file.
The methods returning this error code are GetMessage, Connect, Disconnect, and PutMessage.
99
COMPLETED_WITH_ERROR
Error when a batch request failed
COMPLETED_WITH_ERROR is returned when Ignore Update Errors="true" and an exception occurred when running a SQL statement.
This error indicates that the particular batch request has failed.
The PutMessage method returns this error code.
27
ERR_CLOSERR
Error when disconnecting from the database
ERR_CLOSERR is returned when an exception is encountered at the time of disconnecting from the given database.
The Disconnect method returns this error code.
19
ERR_OPENERR
Error when connecting to the database
ERR_OPENERR is returned when an exception is encountered while connecting to the target database.
The Connect method returns this error.
98
ERR_TRANSACT
Error during transaction sequence
ERR_TRANSACT is returned when an exception occurs while the beginTransaction, CommitTransaction, or RollbackTransaction methods are run by JDBC WebRowSet Aggregator component.
34
ERR_INVALID
Error while parsing the WebRowSet XML document
ERR_INVALID is returned when an exception occurs while parsing of the WebRowSet XML document.
Possible causes:
Invalid XML element
Invalid formats.
Examples:
Specify a date value in a format other than yyyy-mm-dd.
Enter an alphanumeric value for an integer value.
Use this error code to either commit or rollback that particular transaction depending on your requirements.
The PutMessage method returns this error code.
The batch response log file contains all the records leading up to (but not including) the record that returned ERR_INVALID.
96
ERR_PK_UNDEFINED
Error when a primary key is not defined in the WebRowSet XML document
ERR_PK_UNDEFINED is returned when there are no primary keys defined in the WebRowSet XML request.
The PrimaryKeyNotDefinedException is thrown in this case.
The PutMessage method returns this error code.
44
ERR_NOTSUP
Error when the WebRowSet XML request contains unsupported data types
ERR_NOTSUP is returned when the WebRowSet XML request contains unsupported data types like binary data.
The UnSupportedDataTypeException is thrown in this case.
JDBC WebRowSet Aggregator checks the column type present in the metadata section to confirm if the data type is binary.
The PutMessage method returns this error code.
Batch Response Logging
JDBC WebRowSet Aggregator provides a batch-logging feature.
If the PrimaryKeyNotDefinedException and UnsupportedDataTypeException occur before updating the database, then JDBC WebRowSet Aggregator does not log the transaction status for the batch request.
If no exceptions occur while updating the database, then the component writes the transaction status to the log file. The log file records the entire session regardless of whether you perform a commit or rollback on a transaction or batch.
If you want the log file contents created at runtime for every batch request, call the GetMessage action. The GetMessage action returns the log file contents of the previously executed PutMessage method.
Unsupported Data Types
The following table lists the data types that JDBC WebRowSet Aggregator does not support.
Database
Data Type
Oracle
Long Raw (Binary)
Raw (Binary)
MLSLabel
Blob (Binary)
BFile
URowId
URIType
DB2
BLOB (Binary)
SQLServer
Binary
Image (Binary)
VarBinary
PSQL
Binary
LongVarBinary