The FileWriter component writes the received data from its input port to the specified output file. The received data can either be plain text or binary data.

File Writer is capable of handling:

  • Text files
    Text content from input message is written to the configured file in text format.
  • BinaryFiles
    Binary content from the input message is written to the configured file in binary format. 

Icon

File Writer uses core Java APIs to write the files.

Points to note

  • The component runs on the Peer Server and therefore the file paths and directories mentioned in the CPS should be valid on the machine where the Peer Server is running. If the component fails over to another peer, ensure that the machine on which the secondary Peer Server is running does have the same path available.
  • The received XML equivalent of the unstructured plain text needs to be transformed to its original format using the XML > Flat component.
  • FileWriter closes the file and moves it to the target directory on receiving a message having property COMPLETE whose value is set to true. This is useful even when you use Append if Exists output mode for the FileWriter component and you would like to close the file on the occurrence of this event.
  • The FileWriter component uses the JMS Header filename to get the file name from the input message.

Configuration and Testing

Interaction Configurations

Business logic configuration details are configured in the second panel, Interaction Configurations. Figure 1 illustrates the panel with Expert Properties view enabled.


Figure 1: Interaction Configurations.

Attributes

Is input Binary?

Specifies whether the input received on the input port is binary.

  • If enabled, it writes the data as bytes into the target file.
  • If disabled, it writes text to the specified target file in an unstructured fashion.
Icon

The Output message sent to the output port depends on the configuration provided here. When enabled, it hides the property Output Mode.

FileWriter Configuration

Click the FileWriter Configuration ellipses button to set these properties.


Figure 2: FileWriter configuration properties

Is Configured for Different Machine?

Specifies whether the Peer Server on which the component is to be launched and Fiorano Studio are running on the same machine or on different machines. This helps the component to determine the type of dialog to be shown while providing the paths of Source Directory, Working Directory, and Error Directory. When both the Peer Servers and the Fiorano Studio is running on the same machine, the paths to the above specified directories can be chosen from a file dialog with the directory structure of the current machine as shown in Figure 2. Otherwise, a text editor will be shown where the paths of Source/Working/Error directories need to be typed in as shown in Figure 3.

  • Enabled if the Peer Server on which the component is to be launched and the Fiorano Studio are running on different machines.
  • Disabled if the Peer Server and Fiorano Studio are on the same machine.

    In disabled state, paths of directories can be chosen from the file dialog. When the property is enabled, the paths of directories should be manually specified in the Text Editor as shown in Figure 2 and Figure 3.


    Figure 3: Choosing directory path using File Dialog


    Figure 4: Specifying directory path using Text Editor
Compute Paths relative to Directory

The path of the directory relative to which the paths of Target Directory, Working Directory, and Error Directory are computed. By default, this points to the FIORANO_HOME directory. If the paths specified for Target/Working/Error Directories are not absolute, their paths are calculated relative to the directory specified here.

Icon

If the path specified for Target Directory/Working Directory/Error Directory is absolute, the path specified for Compute Paths relative to Directory will not be used in the computation of the directory paths.

File name

The name of the file to which the input data has to be written is specified here. If the file with this name does not exist, a new file is created.

Icon
  • If the property "Use file details from message headers" is enabled, then this name would be used only if the FileName property is not present in the header of the incoming message.
  • When no file name is specified both in the CPS and the message header, FileWriter throws an exception.
Target Directory

The path of the directory where the target file (with the data received on the input port) is created. An absolute path of the target directory or a path relative to the directory specified in Compute Paths relative to Directory can be specified here. While specifying a directory as the Target Directory, make sure that you have permissions to create/modify files present in this directory.
If Is configured for different machine? is disabled, clicking the ellipses button will open a file dialog, , where the directory can be chosen from the file system. Otherwise the file path is written in the text editor.

Icon
  • If this folder does not exist, FileWriter creates it while processing the input message.
  • If the property Use file details from message headers is enabled, the directory specified here would be used only if the directory property is not present in the incoming message headers. FileWriter throws an exception if no directory is specified both in the CPS and in the message headers.
Working directory

The path of the directory which should hold the files during intermediate processing. Either an absolute path or a path relative to the directory specified in the Compute Paths relative to Directory can be provided.

If Is configured for different machine? is disabled, clicking the ellipses button will open a file dialog, as shown in Figure 2, where the directory can be chosen from the file system. Otherwise, a text editor pops up where the path of the directory needs to be typed in. Shown in Figure 3.

Icon
  • When Output mode is Append and close on timeout or Append and close on event, Working directory holds the files until the timeout or CLOSE_EVENT occurs.
  • If this directory does not exist, FileWriter creates it while processing the input message.
  • FileWriter requires write permissions on Working and Error directories.
Error directory

Path of the directory which should hold the files for which the processing has not been successful.

Icon
  • Either an absolute path or a path relative to the directory specified in the Compute Paths relative to Directory can be provided.
  • If this directory does not exist, FileWriter creates it while processing the input message.
  • For any file, when the processing is successfully finished, FileWriter moves the file from Working directory to Target directory. If the processing is not successful, the file gets retained in the Working directory itself. When FileWriter receives data which is to be written to the file that already exists in the Working directory, FileWriter moves the existing file in the Working directory to Error directory and then creates a new file with the input data. Every file that moves to the Error directory will have appended to its name, the time (in milliseconds) at which it is moved to the Error directory.
  • FileWriter requires write permissions on Working and Error Directories.

Use file details from message headers

Specify if the file details are to be taken from the header of the input message.

  • If enabled, the name of the target file would be the value of the header property FileName present on the input message and the target directory would be the value of the header property directory.
  • If disabled, the value specified for the CPS property Filename is used.
     
Icon

If Use file details from message headers is enabled and if the property FileName is not found in the message headers, the File name from the CPS is used. Similarly, the directory specified in the CPS (Target Directory) is used as the target directory if the property directory is not found in the message headers.

Append timestamp?

Specifies whether a timestamp is to be appended to the name of the target file.

Timestamp format

Specify the format in which the timestamp is to be appended to the name of the target file. Figure 23 shows the descriptions for the symbols that could be used in the Timestamp format.


Figure 5: Symbols used in Timestamp format.

Example: If Test.txt is the filename to which the data is to be written, the target file created could be Test_02042008_183950765.txt when the default format (ddMMyyyy_HHmmssSSS) is used.

Icon

This property is visible only when Append timestamp? is enabled.

Append Counter?

  • If enabled, it appends a counter to the name of each file processed by the FileWriter in addition to the timestamp. The name of the file would look like <filename><time stamp><counter>. Appending counter to file names ensures that no two files created can have the same name.
  • If disabled, no counter is appended to the target file processed by the component FileWriter.

Example: If Test.txt is the filename to which the data is to be written, the target file created could be Test_02042008_183950765_0.txt when AppendCounter? is enabled.

Icon

This property is visible only when Append timestamp? is enabled.

Output Mode

Specify the way in which the output is to be created with the received data. Figure 5 shows the output formatting modes.


Figure 6: Output Mode

New file for each message

This option tells the FileWriter to create a new file for each input message that has been processed. When this output mode is being used, timestamp and counter can be appended to the filename using the properties Appendtimestamp? and Appendcounter?. The Appendtimestamp? option will be visible only when this option is selected as the OutputMode.

Icon

If the same File name is specified for two different input messages and no time stamp or counter is appended, the existing file is overwritten.

Append and close on timeout

This output mode is used for appending the content of all messages received till timeout, to a single file. During this time interval, the file is present in the Working directory. When the timeout occurs, the file is closed and is moved to the Target directory. Selecting this option will show the property FileTimeout(min) which can be used to set the timeout. Another property 'FileTimeout' will be visible when this mode is chosen.

Icon
  • Only one file holds the content of all messages received during the configured time interval. The name of this file would be the value specified for the Header property FileName on the first message received in this time interval, if Use file details from message header? is enabled. If not, the file name would be the value of the property File Name specified in CPS.
  • If, for any reason, the component is stopped/relaunched before the specified timeout, further messages will be processed into a new file
Append Line Separator

Enable to append the text data with a line separator.

File Timeout (min)

The time for which the component has to wait before closing and moving the file from Working directory to the Target directory is specified using this property. This is visible only when 'Append and close on timeout' is selected.

Icon

File timeout cannot be a fraction. Hence, the minimum timeout that can be specified is 1 minute.

Timeout after last message

Messages will be appended until timeout between two successive messages meets the timeout specified in the File TimeOut property. 

Append and close on event

This output mode is used for appending the content of all received messages to a single file until CLOSE_EVENT occurs. When a message with the header property CLOSE_EVENT set to true is received, the content of this message is appended to the file, the file is closed and is moved from Working directory to Target directory.

Icon
  • The file will continue to be in the working directory till it receives a closing event.
  • Only one file holds the content of all messages received until CLOSE_EVENT occurs. The name of this file would be the value specified for the Header property FileName on the first message received, if Use file details from message header? is enabled. Otherwise, the file name would be the value of FileName specified in CPS
Don't write to file but send to output

The received data is sent to the output port instead of writing into a file. Figure 6 and Figure 7 show the snapshots of the text and binary data sent to output port. 

Icon

If Is Input Binary? has to be enabled for treating the input as binary.



Figure 7: Text data received on output port.


Figure 8: Binary data received on output port.

Icon

Selecting the "Do not write to file but send to output" option hides the property Return data on Output? since the output will definitely be sent to the output.

Append if exists

If the file to which the data is to be written already exists, data is appended to the content in the existing file. The file being processed will be moved to the Working directory and content received in the input message will be appended to the existing file until FileWriter receives a message with a property COMPLETE set to true. (JMS function setStringProperty() can be used to set the value of a JMS property on a message). 

Icon

Until FileWriter receives a message with this property COMPLETE set to true, it keeps the file in the Working directory.

File Encoding

The encoding to be used while writing the file. The following encodings can be used. Figure 8 shows all the encodings that can be used.


Figure 9: Different types of File Encoding

Code TypeDescription
ASCII

A coding standard used to represent plain text. It is based on the order of English Alphabet.

Cp1252This is a character encoding of the Latin alphabet.
UTF8A variable-length character encoding for Unicode.
UTF-16This is a variable-length character encoding for Unicode. The encoding form maps each character to a sequence of 16-bit words.
ISO8859_1 ISO 8859-1, more formally cited as ISO/IEC 8859-1 is part 1 of ISO/IEC 8859, a standard character encoding of the Latin alphabet.

EUC_KR
EUC_JP
EUC_CN
EUC_TW

Multi-byte character encoding systems used for Korean, Japanese, Simplified Chinese, and Traditional Chinese languages respectively.

Monitoring Configuration

For the Monitoring configuration description, please refer the respective section in the Common Configurations page.

Expert Properties

These properties are meant for advanced users.


Figure 10: Interaction Configurations panel with the Expert Properties option enabled

Icon

For descriptions of Expert properties given below, please refer the Interaction Configurations section in the Common Configurations page:

  • Pre Processing XSL Configuration
  • Post Processing XSL Configuration
  • Process Message Based On a Property
  • Validate Input
  • Target Namespace.

PostProcessing Command

Script or a Command that is to be executed after the file processing is finished. A command can be specified by simply typing it in the text area provided against this property. To provide a script file, the file dialog which is shown by clicking the ellipses button can be used.

By default, the component appends the absolute path of the target file to this script/command that is. the absolute path of the target file would be the first argument to this script/command. More arguments for this command could be specified using the property PostProcessing Arguments.

The final command formed by the FileWriter would be:

<PostProcessing Command> + <Absolute path of the target file> + <PostProcessing Arguments>

PostProcessing Arguments

Arguments that are passed to postprocessing script or command.

Sample Scenario

Copying all the files present in Error directory to a backup location after the file is processed.

Solution

A batch file copyerrors.bat with content copy C:\FileWriter\ErrorDir %2 is written and is placed in C:\. The path of this batch file is specified for the property PostProcessing Command. The backup location (C:\ProcessingFailures) is specified as the value for PostProcessing Arguments.

Let C:\FileWriter\TargetDir\test.txt be the target file. With this configuration, the command formed by FileWriter would be C:\copyerrors.bat C:\FileWriter\TargetDir\test.txt C:\ProcessingFailures. The copy command executed finally would be copy C:\FileWriter\ErrorDir C:\ProcessingFailures which moves all the files in C:\FileWriter\ErrorDir to the backup location C:\ProcessingFailures.

Time interval for PostProcessing script

The maximum interval of time for Post Processing Script to get finished; the value is in milliseconds.

Return data on Output?

Determines if the data written to the file is to be sent onto the output port instead of sending out an XML message containing the details of the file to which the content has been written. Figure 6 and Figure 7 show sample views of the text and binary data sent to the output port. As shown in the figures, enabling this property will send the data in the output message. However, the file details can still be fetched from the message headers of the output message. Refer Table 1 for the description of header properties.

Icon

This property is not visible when Output mode is set to "Don't write to file but send to output".

Header Properties

Table 1 shows the descriptions of header properties set by the component on the output message when binary/flat content is processed.

Type of data received on input port

Header Property

Description

Flat/Binary

 

 

 

 

 

 

 

FileName

Name of the file to which the data is being written.

FilePath

Path of the directory which holds the destination file.

FullName

Absolute path of the destination file. For a binary file, this property appears only on the message which represents the last chunk of the file.

Size

Determines the final size of the destination file.

ReadAccess/ WriteAccess

Determines if the destination file is readable/writable. For a binary file, these properties appear only on the message which represents the last chunk of the file.

START_EVENT

Value of the header property START_EVENT present on the input message to the component. An input message with this property set indicates that this is the first message whose content is to be written to the file represented by the property FileName.

RECORD_INDEX

Value of the header property RECORD_INDEX present on the input message to the component. A value 'n' for this property indicates that this is the nth message whose content is to be appended to the file represented by the property FileName

CLOSE_EVENT

Value of the header property CLOSE_EVENT present on the input message to the component. An input message with this property set indicates that this is the last message whose content is to be appended to the file represented by the property FileName.

Flat

Type

File/Directory

Binary

 

 

 

NEW

Value of the header property NEW present on the input message to the component. An input message with this property set to true indicates that this message holds the first chunk of data to be written to the file represented by the property FileName

COMPLETE

Value of the header property COMPLETE present on the input message to the component. An input message with this property set to true indicates that this message holds the last chunk of data to be appended to the file represented by the property FileName

START_INDEX

Value of the header property START_INDEX present on the input message to the component. This value represents the offset of the first byte of the chunk which has been currently written to the destination file.

END_INDEX

Value of the header property END_INDEX present on the input message to the component. This value represents the offset of the last byte of the chunk which has been currently written to the destination file.

Table 1: Header Properties

Move file to working directory on start?

If a file exists in the target directory, choosing this option would move the file to the working directory and appends the incoming messages to the file.

Icon

This property is visible only if Show Expert Properties is selected and Output Mode property is one of the following:

  • Append and close on timeout
  • Timeout after the last message
  • Append and close on event

Elements to Decrypt

Select elements to decrypt in the Input Message.

Refer to the Encrypt Decrypt Configuration section in the Common Configurations page for details.

Input and Output

Input

No schema is set on the input port. If any XML message has to be written into a file then the XML message is directly sent as input message.

Output

When a file is written successfully, FileWriter sends out the file information onto the output port. Figure 9 shows the schema of the output XML message. Table 2 shows the description of the schema elements.


Figure 11: Schema on the output port

Schema Element

Description

FullName

Path of the file to which the data has been written

FileName

Name of the file to which the data has been written

FilePath

Path of the directory which holds the output file

Type

The type of output

ReadAccess

Specifies if the output file has read access

WriteAccess

Specifies if the output file has write access

Size

Size of the output file in bytes

Table 2: Description of Output schema elements

Testing the Interaction Configurations

Interaction configurations can be tested from the CPS by clicking the Test button. Figure 11 and Figure 12 shows the sample input and the corresponding output message respectively.


Figure 12: Sample input


Figure 13: Output generated for input shown in Figure 10.

Functional Demonstration

Scenario

Writing the input message into to a file and displaying the response contents.
Configure the FileWriter as shown below.


Figure 14: Sample Configuration of FileWriter

Use a Feeder and a Display component to send sample input and check the response respectively.


Figure15: Demonstratingscenario1withsampleinputandoutput

Input Message

Input Text

Output Message

Use Case Scenario

In a revenue control packet scenario, if an error occurs while parsing the transaction data, an error message is written to a file.


Figure 16: Revenue Control Packet Scenario.

The Event Process demonstrating this scenario is bundled with the installer.

Documentation of the scenario and instructions to run the flow can be found in the Help tab of the flow present in eStudio.

Icon

To understand the service better, refer to the REST Attachments example which demonstrates FileWriter service features.

Adaptavist ThemeBuilder EngineAtlassian Confluence