Defining a write file action for writing files

  1. Start ION.
  2. Click Connect > Connection Points
  3. Click New. Select File connection point.
  4. Click the Documents tab.
  5. Click Add. A new action is created and listed in the Action List.
  6. Select the action entry and specify the action type Write File to write a file based on the content of a BOD.
  7. In the File Format Template & Document Settings section specify the Document or File Format Template to use when writing files.
    1. Document Template, select from documents defined in ION Registry.
      File Format Template, select from already defined templates or click New to define a new file template. To view the details of the selected template, click Details.
      For more details, see File templates
    2. After the file template is specified, the BOD Noun that is associated with the specified template is filled. If the template does not have an associated BOD, then an error message is shown.
    3. Select which BOD Verb to use in the write action.
  8. When the write folder permissions do not allow to update or remove files, select the Enable support for write only permissions check box.

    The File Connection point does not create an "inprocess" file to write the file content to.

    Ensure that no other process interrupts the writing process, it can result in corrupted data.

    Keep this in mind:

    • The test function is not enabled.
    • If a file exists, then only an error can be thrown. "Overwrite" or "Append" options are not available.
    • It is still required to have permissions to write files, list files, read file attributes.
  9. Select the Create non-existing folder(s) check box to create the specified folder for Write automatically if it does not exist in the file server.
  10. In the Write File Settings section specify this information:
    Write Location
    Specify the write location on the file server in which the files are written. This is relevant to the hostname defined in the connection tab setting. This is a required field.
    Note: From ION version 12.0 you can also use a keyword to define a write location, see Keywords.

    For guidelines on how to define the correct location, see File share locations.

    File Name Pattern
    Specify the file name pattern that represents the name of the file that is written by that action. This field is case-sensitive. This does not allow the usage of wildcards such as * or ?, and other characters.

    See File name pattern restrictions

    You can use keywords to reference to fields that are defined within the file template and in message headers.

    For a complete list of keywords, see Keywords.

    If file exists
    Select which action to run if file exists. These options are available:
    • Overwrite: The created file replaces any existing file that was created in the Write Location with the same name.

      This is not available when the Enable support for write only permissions check box is selected.

    • Append: If a file with the same name existed in the Write Location, then the content is written at the end of the existing file content.

      This is not available when the Enable support for write only permissions check box is selected.

      You can add a line separator before the appended document. Select the check box with the same name and define the required format of the line separator.

      You can define the line separator as a combination of these escape sequences:

      • \t (tab)
      • \r (CR, Carriage return)
      • \n (LF, Line Feed)

      Most common types are \n for UNIX and UNIX-like systems and \r\n for Windows.

      The line separator is not added in case the existing file is empty, where it would be therefore the first character in the file.

      For files of type "XML", there is only one root level element allowed per file. Therefore, using the Append option for files of type 'XML' or Full BOD results in an invalid XML. In such situations you receive a warning to use the Overwrite option.

    • Error: The write action fails to create the file in case a file with the same name already existed in the Write Location. An error occurs and a Confirm BOD is generated.
    Compression
    Select which compression type is used for the files written to the location. These are the available options:
    • None: The input document is written to the location as is, without compression.
    • Deflate: The input document is compressed based on the deflate algorithm, as described in RFC 1951. A combination of the LZ77 algorithm and Huffman coding, wrapped inside the zlib data format, RFC 1950.
      Note: When using the document_id keyword in the New File Name Pattern, the file must be inflated in the File connection point to read the document ID property. This action can result in exceeding the ION message size limit.
  11. In the Polling Settings section, specify this information:
    1. Select the Sort By option that is used to retrieve files from the Read Location to start the reading action. Files are sorted in an ascending order by Name or Modification Date Time.
  12. After the configuration for the Write File action is finished, click Test.
    A test is run to check if the specified Write Location is accessible using the specified connection configuration. This also validates if the credentials that are provided have the required privileges. A message is displayed to inform you whether the test is successful or not.