file attacher

File Attacher

Version: 17.07

Supported Since: 17.01

What is a File Attacher?

UltraESB-X message has four main parts. They are payload, headers, properties and attachments. Attachments can be used to carry any additional information with the message. Note that attachment is set to the message and not to the message context. Therefore once the life cycle of the message ends, attachments' life cycle also ends. Basically when a message is sent out using an Egress Connector or when the flow ends with one of Flow End elements (see Successful Flow End and Exceptional Flow End), the message’s life cycle ends and same is applied to the attachments of the message. Attachment does not get automatically sent out when the message is sent out through an Egress Connector. It has to be manually processed to send it out either through a Custom Processing element which sets the payload by processing attachments or through an Egress Connector that supports sending out attachments.

A File Attacher is a processing element which can be used to attach a file from the local file system to the message. The given file by will be first wrapped using FileFormat which is an implementation of XMessageFormat, when setting it an attachment.

In order to use this processing element, you must first select the Attachment Processor dependency from the processor list when you are creating an empty Ultra project. If you have already created a project, you can add this dependency via Component Registry. From Tools menu, select Ultra Studio → Component Registry and from the Processors list, select the Attachment Processor dependency.

Alternatively, you can add the following dependency to the maven pom.xml manually.

<dependency>
    <groupId>org.adroitlogic.x.processors</groupId>
    <artifactId>x-processor-attachment</artifactId>
    <version>17.07</version>
</dependency>
file attacher outports

Out Ports

Next

The message will be sent to this outport if the file attachment is successful

On Exception

The message will be sent to this outport if the processing element failed in attaching file

Parameters

File Path*

Basic

File Path represents the path of the file to be attached in the local file system. File Path can be either absolute or relative.

Following place holders can also be used when giving the file path. Relevant values for the place holders will be extracted from the message context.

  • @{variable.<variable_name>} - to get value from a variable

  • @{message.id} - to get the message id

Few examples are as follows.

  • /tmp/attachment-@{message.id}.csv - preparing path appending message id

  • /tmp/attachment_@{variable.my_var}.csv - preparing path appending value of variable my_var

  • /tmp/@{variable.my_var}/attachment-@{message.id}.csv - preparing path appending value of variable my_var and message id

  • /tmp/csv_attachment.csv - simply a string path without the use of any place holder

Further following place holder can be used to get the current timestamp.

  • @{current.timestamp} - this will use the default timestamp pattern yyMMddHHmmssZ

  • @{current.timestamp.<timestamp_pattern>} - this will use the given timestamp pattern. Note that timestamp pattern given here should be a pattern compatible with SimpleDateFormat.

Content Type

Basic

This is an optional parameter which represents the content type of the file.

Use File Name as Attachment Name

Basic

Boolean parameter to set whether to use the file name as the attachment name or whether to give a different attachment name using the optional Attachment Name parameter.

Default value of this parameter is true. Therefore by default file name will be used as the name for the attachment.

Attachment Name

Basic

Attachment Name parameter can be used optionally to give a name to the attachment. Note that to use this value as the name for the attachment "Use File Name as Attachment Name" boolean parameter should be set to false.

Attachment Name given to the attachment should be used when it is accessed later.

For an example if this attachment needs to be accessed in a Custom Processing Element, Attachment Name parameter value must be used as the method argument key when calling XMessage API method getAttachment(String key).

@Processor(displayName = "AttachmentAggregator", type = ProcessorType.CUSTOM)
public class AttachmentAggregator extends AbstractSequencedProcessingElement {

    @Override
    protected ExecutionResult sequencedProcess(XMessageContext xMessageContext) {
        XAttachment attachment = xMessageContext.getMessage().getAttachment("file.csv").get();

        // relevant processing code

        return ExecutionResult.SUCCESS;
    }
}

Attachment Name is case sensitive (like all Java Variables). Therefore Attachment Name "my_attachment" will not be considered same to the Attachment Name "My_Attachment".

Attachment name must be unique to the flow. If same attachment name is used in more than one File Attacher elements or in a Payload Attacher element, there is a possible risk of one attachment being replaced by another attachment.

Following place holders can also be used when giving the attachment name. Values for the place holders will be extracted from the message context.

  • @{variable.<variable_name>} - to get value from a variable

  • @{message.id} - to get the message id

Few examples are as follows.

  • attachment-@{message.id} - appending message id

  • attachment_@{variable.my_var} - appending value of variable my_var

  • attachment_@{variable.my_var}_@{message.id} - appending value of variable my_var and message id

  • csv_attachment - simply a string value without the use of any place holder

Further following place holder can be used to get the current timestamp.

  • @{current.timestamp} - this will use the default timestamp pattern yyMMddHHmmssZ

  • @{current.timestamp.<timestamp_pattern>} - this will use the given timestamp pattern. Note that timestamp pattern given here should be a pattern compatible with SimpleDateFormat.

Sample Use Case

In the following use case we have a flow which starts with a NIO HTTP Ingress Connector and ends with NIO HTTP Egress Connector. In the middle we have used a File Attacher to attach a csv file. Then we have used a Custom Processing Element which will aggregate the content of the attached csv file and prepare the payload to be sent out through NIO HTTP Egress Connector. Complete flow for the use case is shown below.

file attacher flow

Configuration for the File Attacher processing element is as follows.