FileWriter

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. 
  
  

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.

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.

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

Is Input Base64 Encoded?

Specifies if the input is base64 encoded. The component will decode the base64 input before further processing.

This property gets displayed when the Is input Binary? is enabled.

Figure 2: "Is Input Base64 Encoded?" property

FileWriter Configuration

Click the FileWriter Configuration ellipses button to set these 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 4: Choosing directory path using File Dialog
  
  

  

  
  Figure 5: 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.

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.

• 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

• 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

• 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.

• 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.
   

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.

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.

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.

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.

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.

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.

• 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.
• For any reason, if 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 the Working directory to the Target directory is specified using this property. This is visible only when 'Append and close on timeout' is selected.

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.

• 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. 

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

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 in the Target/Destination directory, 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). 

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.

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.

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

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 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.

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.

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.

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.

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.

Functional Demonstration

Scenario

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

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

Input Message

Output Message

<?xml version="1.0" encoding="UTF-8"?>
<ns1:Result xmlns:ns1="http://www.fiorano.com/fesb/activity/FileWriter1">
   <ns1:FileInfo>
      <FullName>/home/geetha/backup/Target/out_10032009_142102262_0.txt</FullName>
      <FileName>out_10032009_142102262_0.txt</FileName>
      <FilePath>/home/geetha/backup/Target</FilePath>
      <Type>File</Type>
      <ReadAccess>true</ReadAccess>
      <WriteAccess>true</WriteAccess>
      <Size>10</Size>
   </ns1:FileInfo>
</ns1:Result>

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.

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.

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