uCosminexus Service Platform, Reception and Adapter Definition Guide

[Contents][Glossary][Index][Back][Next]

3.3.11 Defining file operations adapters

This section describes the method of defining file operations adapters. Note that for details on definition examples in case of using file transformation operation, see Appendix E Example for defining file operations adapter.

Organization of this subsection
(1) Creating a message format
(2) Operations to be performed on the service adapter settings screen
(3) Creating and editing the file operations adapter definition file
(4) Points to be considered when using the file transformation operation

(1) Creating a message format

For the message format definition file of file operations adapters, use the schema provided by the service platform. Therefore, you need not create the message format definition file.

The contents of the message format used by file operations adapters are described here.

The storage location for the file is "Installation directory of the service platform\CSC\schema\adpfop".

(a) Request message format for file operations adapters

The operation-wise request message format for file operations adapters is described here.

[Figure]File transformation operation
The following table describes the request message format to be passed on from a business process to a file operations adapter. The file name is "adpfop_transform_request.xsd". The name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/transform_request".

Table 3-56 Request message format (file transformation operation)

Tag name Occurrence count# Description
<request> 1 time -
<request-id> 0 or 1 time Specifies a request ID created in the FTP reception. Use this ID to generate the path of a working folder. You can omit this tag, if you do not specify a working folder in the input folder and the output folder.
<input-folder-name> 1 time Specify a folder in which the file to be transformed is stored.
  • When specifying a working folder
    Specify common="false" in tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in tag attribute and specify name of the common folder definition in the value.
<input-file-name> 1 time Specify the name of the file to be transformed.
You can use a slash (/) only at the beginning of a file name. Also, the slash (/) set at the beginning of a file name is ignored.
Following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.
<output-folder-name> 1 time Specify a folder to which the transformed file is to be output.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<output-file-name> 0 or 1 time Specify name of the transformed file.
However, if the output destination of the transformed file is a working folder (if common="false" is specified in the attribute of the output-folder-name tag), the specification is ignored, since a unique file is created in the working folder using createTempFile() of java.io.File.
You can use a slash (/) only at the beginning of a file name. Also, the slash (/) set up at the beginning of a file name is ignored.
Following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File replication operation
The following table describes the request message format to be passed on from a business process to a file operations adapter. The file name is "adpfop_copy_request.xsd". Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/copy_request".

Table 3-57 Request message format (file replication operation)

Tag name Occurrence count# Description
<request> 1 time -
<request-id> 0 or 1 time Specifies a request ID created in the FTP reception. Use this ID to generate the path of a working folder. You can omit this tag, if you do not specify a working folder in the input folder and the output folder.
<input-folder-name> 1 time Specify the folder in which the file to be copied is stored.
  • When specifying a working folder
    Specify common="false" in tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in tag attribute and specify the name of the common folder definition in the value.
<input-file-name> 1 time Specify the name of the file to be copied.
You can use a slash (/) only at the beginning of a file name. Also, the slash (/) set at the beginning of a file name is ignored.
Following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.
<output-folder-name> 1 time Specify the folder to which the copied file is to be output.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<output-file-name> 0 or 1 time Specify the name of the copied file.
However, if the output destination of a transformed file is a working folder (if you specify common="false" in the tag attribute of output-folder-name), the specification is ignored, since a unique file is created in the working folder using createTempFile() of java.io.File.
You can use a slash (/) only at the beginning of a file name. Also, the slash (/) set at the beginning of a file name is ignored.
Following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File and folder deletion operation
The following table describes the request message format to be passed on from a business process to a file operations adapter. The file name is "adpfop_delete_request.xsd". Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/delete_request".

Table 3-58 Request message format (file and folder deletion operation)

Tag name Occurrence count# Description
<request> 1 time -
<request-id> 0 or 1 time Specifies a request ID created in the FTP reception. Use this ID to generate the path of a working folder. You can omit this tag, if you do not specify a working folder in the input folder and the output folder.
<folder-name> 1 time Specify the folder in which the file to be deleted is stored or specify the folder to be deleted.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<file-name> 0 or 1 time Specify the name of the file to be deleted.
However, if the output destination of the file to be deleted is a working folder (if the attribute value of folder-name is common="false"), specification of the <file-name> element is ignored.
You can use a slash (/) only at the beginning of a file name. Also, the slash (/) set at the beginning of a file name is ignored.
Following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File compression operation
The following table describes the request message format to be passed on from a business process to a file operations adapter. The file name is "adpfop_compress_request.xsd". The name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/compress_request".

Table 3-59 Request message format (file compression operation)

Tag name Occurrence count#1 Description
<request> 1 time -
<request-id> 0 or 1 time Specifies a request ID created in the FTP reception. Use this ID to generate the path of a working folder. You can omit this tag, if you do not specify a working folder in the input folder and the output folder.
<input-folder-name> 1 time Specify the folder in which the file to be compressed is stored.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<input-files> 1 time -
<input-file> 1 to 999 times -
<input-file-name> 1 time Specify the name the file to be compressed.
The following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes name of a reserved device.
<entry-name> 1 time Specify the entry name after the compression of a file specified in the input-file-name tag in the same input-file tag. If you specify null, the value of the input-file-name tag in the same input-file tag is specified. Here, entry name is not changed.
The following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.
<output-folder-name> 1 time Specify the folder to which the compressed file is to be output.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify name of the common folder definition in the value.
<output-file-name> 0 or 1 time Specify the name of the compressed file.
However, if the output destination of the compressed file is a working folder (if you specify common="false" in the attribute of output-folder-name tag), specification is ignored, since a unique file is created in the working folder using createTempFile() of java.io.File.
The following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes name of a reserved device.

Legend:
-: There is no corresponding item.

Note#1
If the specified occurrence count is exceeded, the operation is not guaranteed.

Note#2
Specify a file name by considering that input-file-name tag is case-insensitive. If the same file name is specified multiple times, the operation is not guaranteed.

Note#3
When extracting a compressed file in Windows, the file name might be same, since the name of the extracted file is case-insensitive. Specify the entry name by considering this point.

[Figure]File extraction operation
The following table describes the request message format to be passed on from a business process to a file operations adapter. The file name is "adpfop_extract_request.xsd". The name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/extract_request".

Table 3-60 Request message format (file extraction operation)

Tag name Occurrence count# Description
<request> 1 time -
<request-id> 0 or 1 time Specifies a request ID created in the FTP reception. Use this ID to generate the path of a working folder. You can omit this tag, if you do not specify a working folder in the input folder and the output folder.
<input-folder-name> 1 time Specify the folder in which the file to be compressed is stored.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
Specify common="true" in the tag attribute and specify name of the common folder definition in the value.
<input-file-name> 1 time Specify the name of the file to be extracted.
The following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.
<output-folder-name> 1 time Specify the folder to which the extracted file is to be output.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify name of the common folder definition in the value.
<output-file-prefix-name> 0 or 1 time Specify the prefix of the name of the extracted file.
  • If the output destination of the transformed file is a common folder (If you specify common="true" in the attribute of output-folder-name tag)
    File name is automatically given by using this specified tag.
  • If the output destination of the transformed file is a working folder (If you specify common="false" in the attribute of output-folder-name tag)
    The specification is ignored, since a unique file is created in the working folder using createTempFile() of java.io.File.
The following are the limitations for Windows:
  • Case-insensitive.
  • You cannot specify a file name in UNC format.
  • You cannot specify a stream name of NTFS.
  • You cannot specify a file name that includes the name of a reserved device.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]If a file operations adapter fails to acquire a request message
An error message (KDEC80002-E) is to be output and the process is to be terminated.
(b) Response message format for file operations adapters

The operation wise response message format for file operations adapters is described here

[Figure]File transformation operation
The following table describes the format of a response message, which is returned to the calling business process by a file operations adapter. The file name is "adpfop_transform_response.xsd". The name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/transform_response".

Table 3-61 Response message format (file transformation operation)

Tag name Occurrence count# Description
<response> 1 time -
<output-folder-name> 1 time The folder to which the transformed file is to be output is set.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<output-file-name> 1 time The name of the transformed file is set.
<output-file-size> 1 time The size of the transformed file (byte) is set.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File replication operation
The following table describes the format of a response message, which is returned to the calling business process by a file operations adapter. The file name is "adpfop_copy_response.xsd". The name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/copy_response".

Table 3-62 Response message format (file replication operation)

Tag name Occurrence count# Description
<response> 1 time -
<output-folder-name> 1 time The folder to which the copied file is to be output is set.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
Specify common="true" in the tag attribute and specify the name of the common folder definition in the value
<output-file-name> 1 time The name of the copied file is set.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File and folder deletion operation
The following table describes the format of a response message, which is returned to the calling business process by a file operations adapter. The file name is "adpfop_delete_response.xsd". The name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/delete_response".

Table 3-63 Response message format (file and folder deletion operation)

Tag name Occurrence count# Description
<response> 1 time -
<folder-name> 1 time The name of the folder in which the deleted file is stored is set.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<file-name> 1 time The name of the deleted file is set.
The file name is null, if you delete a working folder.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File compression operation
The following table describes the format of a response message, which is returned to the calling business process by a file operations adapter. The file name is "adpfop_compress_response.xsd". Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/compress_response".

Table 3-64 Response message format (file compression operation)

Tag name Occurrence count# Description
<response> 1 time -
<output-folder-name> 1 time The name of the folder in which the compressed file is stored is set.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value
<output-file-name> 1 time The name of the compressed file is set.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]File extraction operation
The following table describes the format of a response message, which is returned to the calling business process by a file operations adapter. The file name is "adpfop_extract_response.xsd". Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/fileoperation/extract_response".

Table 3-65 Response message format (file extraction operation)

Tag name Occurrence count# Description
<response> 1 time -
<output-folder-name> 1 time The name of the folder in which the extracted file is stored is set.
  • When specifying a working folder
    Specify common="false" in the tag attribute and specify null in the value.
  • When specifying a common folder
    Specify common="true" in the tag attribute and specify the name of the common folder definition in the value.
<output-files> 1 time -
<output-file> 1 to 999 times -
<output-file-name> 1 time The name of the extracted file is set.
<entry-name> 1 time The entry name prior to extraction of the file set in output-file-name tag is set.

Legend:
-: There is no corresponding item.

Note#
If the specified occurrence count is exceeded, the operation is not guaranteed.

[Figure]If a file operations adapter fails to generate a response message
An error message (KDEC80003-E) is to be output and the process is to be terminated.

(2) Operations to be performed on the service adapter settings screen

The procedure for defining file operations adapters is as follows:

  1. Display the service adapter settings screen.
    For details on how to display the service adapter settings screen, see 3.3.1(4) Displaying the service adapter settings screen.
  2. Set up the definition information in the service adapter settings screen (basic) and the service adapter settings screen (details).
    For details on the items to be set up in each operation, see the following locations:
    Also, for details on the service adapter settings screen (basic), see 1.2.2 Service adapter settings screen in the manual Service Platform Reference Guide.
    Reference note
    You can save, edit, and validate the file operations adapter which is created, if necessary.
    For details on how to edit a file operations adapter, see 3.5 Editing Adapters. For details on how to validate a file operations adapter, see 3.6 Validating Adapters.

(3) Creating and editing the file operations adapter definition file

Types of the definition file to be created and edited are as follows:

The procedures for creating and editing the definition file used by a file operations adapter are as follows:

(a) Procedure for creating a file operations adapter runtime-environment property file

The procedure for creating a file operations adapter runtime-environment property file is as follows:

  1. Copy the template file (Installation directory of the service platform\CSC\config\adpfop\templates\adpfop.properties), and save this file in the following directory:
    Installation directory of the service platform\CSC\config\adpfop
  2. Change the name of the template file, which is copied as "<Service ID>.properties".
    A service ID is any string to be specified when adding a new file operations adapter.
  3. Edit and save the definition contents.
    For details on the items which you can edit in the file operations adapter runtime-environment property file, see File operations adapter runtime-environment property file in the manual Service Platform Reference Guide.

The file operations adapter runtime-environment property file is reflected in the runtime-environment, when starting a file operations adapter. To change the contents of the file operations adapter runtime-environment property file, stop the file operations adapter and perform the operation. If you restart the file operations adapter, the changed contents are reflected in the execution environment.

(b) Procedure for editing the file operations adapter definition file

The procedure for editing the file operations adapter definition file is as follows:

  1. Select "cscFileOperation.properties" in the "Self-defined file" of the service adapter settings screen (details),and click the [Edit] button.
    The editor used for editing the file operations adapter definition file starts.
  2. Edit the file operations adapter definition file using the editor.
    For details on the file operations adapter definition file, see File operations adapter definition file in the manual Service Platform Reference Guide.
  3. Select [File] - [Save] from the Eclipse menu, and save the definition contents.

If you start a file operations adapter, the contents set in the file operations adapter definition file become valid.

(4) Points to be considered when using the file transformation operation

When you select the segmentation method in the file transformation operation and handle an input file in the linefeed separator format, do not set LineFeed in the separator of the complex content element of the following files:

If you set LineFeed, a message (KDEC80043-E) is output, and the process after file transformation is canceled.

The following figure shows an example of the separator settings screen in which correct settings are performed:

Figure 3-21 Example of separator settings screen (without LineFeed settings)

[Figure]

Figure 3-22 Example of the separator settings screen (for CSV format)

[Figure]

[Contents][Back][Next]

[Trademarks]

All Rights Reserved. Copyright (C) 2015, Hitachi, Ltd.