File System Adapter

Use the File System adapter to collect files within a business process, extract files to the file system from a business process, or collect files and then start a new business process.

The following table provides a high-level overview of the File System adapter:

System name	File System
Graphical Process Modeler (GPM) category	All Services
Description	Collects (imports) files from the file system and extracts (exports) files to the file system. The collected file becomes the primary document in a business process for file collection. A primary document is input to the File System adapter for file extraction.
Business usage	To read files from disk or write files to disk.
Usage example	Commonly used at the beginning of a business process to bootstrap a workflow by reading one or more files from disk and starting a business process. Another common use is to write files to disk for some external purpose. Note: The term bootstrap is used in the Graphical Process Modeler to indicate that the File System adapter is used to start a business process after file collection.
Preconfigured?	No
Requires third party files?	None
Platform availability	All supported platforms for Sterling B2B Integrator
Related services	None
Application requirements	None
Initiates business processes?	Yes, if you define a business process to start when you configure the File System adapter. The business process starts once files are collected.
Invocation	Normally, only the extraction side of the File System adapter is used in a business process, because you can configure the collection side of the File System adapter to start (“bootstrap”) a business process. However, you can include the File System adapter directly in a business process to perform an explicit collection of files.
Business process context considerations	None
Returned status values	Returned status values: Success - File System collection or extraction was successful. Error - File System collection or extraction was unsuccessful.
Restrictions	You must have read access to files and directories for file collection and write access to directories for file extraction.
Persistence level	System Default (Full)
Testing considerations	The best (and easiest) way to test this adapter is to set up a business process that only performs a file system extraction and specify that business process as the initial workflow to start (bootstrap).

How the File System Adapter Works

Use the File System adapter to collect (import) files from a file system into a business process and extract (export) files from a business process to a file system. You can configure the File System adapter to start a business process after files are collected from the file system or include the File System adapter in a business process flow. In addition, you can schedule the File System adapter to run at specific time intervals.

You can create multiple File System adapter configurations, one for each of several collection folders. Alternatively, you can use a single File System adapter configuration to point to different directories by specifying the directories for file collection and extraction explicitly in a business process. See Usage Examples.

The following sections describe a business scenario in which you could use the File System adapter, along with some sample solutions.

Business Scenario

Your company receives a purchase order from a trading partner in EDI file format and the file is stored on the internal file system. You need to translate the EDI file into XML format and write the translated file to a local directory.

Business Solution Example

The following approaches are used to solve the above business scenario.

Configure a File System adapter instance to be included in a business process to perform a file extraction.
Create a business process that translates the EDI file to XML format and then uses the File System adapter instance configured above to extract the resultant XML data to the file system
Configure a separate File System adapter instance to start the business process created in the previous step after an EDI file is detected in the collection folder. This File System adapter instance is also scheduled to run at 30-minute intervals.

This business solution is described for both the Graphical Process Modeler (GPM) and the Business Process Modeling Language (BPML).

Graphical Process Modeler (GPM) Example

The following example shows a simple solution to the above business scenario using the GPM.

Business Process Modeling Language (BPML) Example

The following example shows the corresponding business process solution using BPML.

Implementing the File System Adapter

You can implement the File System adapter in three ways:

Collect files within a business process.
Extract files to the file system from a business process.
Collect files and then start a new business process.

The information in this section applies to all three implementations.

Before you begin to implement a File System adapter, you need to collect the following information:

The name of the business process (if the adapter is to start a business process)
The directory path from which files are collected
The directory path to which files are extracted

Process Overview

To implement the File System adapter, complete the following tasks:

Create a File System adapter configuration.
Configure the File System adapter.
Create a business process to run after the File System adapter collects files, or create and enable a business process that includes the File System adapter (collecting or extracting files).
Test the business process and the adapter.
Run the business process.

Configuring the File System Adapter

To create a File System adapter configuration, specify field settings in Sterling B2B Integrator and in the GPM.

File System Configuration

The following table describes the fields used to configure the File System adapter in the Sterling B2B Integrator.

Note: The field names in parentheses represent the corresponding field names in the GPM. This information is provided for your reference.

Field	Description
Name	Unique and meaningful name for the service configuration. Required.
Description	Meaningful description for the service configuration, for reference purposes. Required.
Select a group	Group to associate with the adapter. Valid values: None - No group is selected Create New Group - Allows the creation of a new group Select Group - Select from a list of available groups
Collection folder (collectionFolder)	The name of the folder or subfolder on the same computer where Sterling B2B Integrator is installed and where it collects (or picks up) files as part of a business process. If the path for the folder is not included as part of the name, the folder is assumed to be in the Sterling B2B Integrator working directory. Required. Note: The deleteAfterCollect parameter in the GPM defaults to Yes. If you do not change the default value to No, files that are collected are deleted from the Collection Folder. The File System adapter does not copy the files it collects for processing. See Graphical Process Modeler Configuration for information about the deleteAfterCollect parameter. The collectionFolder parameter is read-only in the GPM. However, you can override this parameter using BPML.
Filename filter (filter)	Collect only files that match a specified filter within the collection folder. Optional. Examples include: .txt (collects only .txt files) .dat (collects only .dat files) EDI.* (collects only files named EDI with any file extension) EDI.txt (collect only files named EDI with a file extension of .txt) Note: If there are multiple files in the collection folder and you leave this field blank, one of the following occurs: If the adapter is configured to start a business process, it processes all files placed in the collection folder. If the adapter is within a business process, it collects only the first file in the collection folder. Note: If you specify this option using the File System adapter configuration, you cannot override the value using the GPM filter parameter. However, you can override this parameter using BPML.
Collect files from subfolders within and including the collection folder? (useSubFolders)	Whether to scan for files in subfolders of the collection folder. Required. Valid values: Yes - Collects files in the specified folder and all subfolders. No - Collects files in the specified folder only. Note: This parameter is read-only in the GPM.
Use the absolute file path name for the document name? (keepPath)	Whether to keep the absolute path name of the files collected when assigning the document name. Required. Valid values: Yes - The absolute file path name is kept with the document in the business process. Choose this value if your business process requires the path information to precede the file name. No - Only the file name is kept with the document in the business process. Note: An absolute path is a path that points to the same location regardless of the working directory or combined paths. It is usually written in reference to a root directory. For example, `c:\dir1\subdir1\somefile.txt (Windows) and /home/dir1/subdir1/somefile.txt (UNIX) are examples of absolute paths to the file somefile.txt.` Note: This parameter is read-only in the GPM.
Start a business process once files are collected? (bootstrap)	Whether to start a business process using the File System adapter after files are collected. Required. Valid values: Yes - Starts the business process specified from the business process drop-down list. Note: An instance of the business process is started for every file that matches the filtering criteria specified for file collection until the number of threads specified on the maxThreads parameter is reached. See Graphical Process Modeler Configuration for information about the maxThreads parameter. No - No business process will be started. Note: This parameter is read-only in the GPM.
Business Process (initialWorkFlowId)	The business process to start after files are collected. Required when Start a business process is set to Yes. Valid values: Name of the business process to start Not Applicable Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify a business process using the configuration, you cannot override this value using the GPM initialWorkFlowId option. If you select Not Applicable, a business process can be selected in the GPM. In either case, you can override this parameter using BPML.
Document storage type (docStorageType)	Defines how the document will be stored in the system. Required. Valid values: System Default Database File System Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM DocStorageType option. However, you can override this parameter using BPML. Note: For more information about document storage types, see Selecting a Document Storage Method for Bootstrap Adapters.
Obscure File Contents? (obscure)	Specifies whether to obscure the file contents when collecting. Does not work with “attachFile” or “importFile”. Yes - File contents will be obscured No - File contents will not be obscured Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM Obscure option. However, you can override this parameter using BPML.
User Parameter 1 (userParm1)	A user parameter that is passed to the bootstrapped workflow and placed in process data as UserParm1. For more information, see Example of Using User Parameters in a Business Process. Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM userParm1 option. However, you can override this parameter using BPML.
User Parameter 2 (userParm2)	A user parameter that is passed to the bootstrapped workflow and placed in process data as UserParm2. Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM userParm2 option. However, you can override this parameter using BPML.
User Parameter 3 (userParm3)	A user parameter that is passed to the bootstrapped workflow and placed in process data as UserParm3. Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM userParm3 option. However, you can override this parameter using BPML.
User Parameter 4 (userParm4)	A user parameter that is passed to the bootstrapped workflow and placed in process data as UserParm4. Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM userParm4 option. However, you can override this parameter using BPML.
User Parameter 5 (userParm5)	A user parameter that is passed to the bootstrapped workflow and placed in process data as UserParm5. Note: This field only displays as an option if Start a business process once files are collected is set to Yes. Additionally, if you specify this parameter using the configuration, you cannot override this value using the GPM userParm5 option. However, you can override this parameter using BPML.
Run As User	Applies to the scheduling of the business process. The Run As User field only displays as an option if Start a business process once files are collected is set to Yes. Type the user ID to associate with the schedule, or click the icon and select a user ID from the list. Valid value is any valid Sterling B2B Integrator user ID. Note: This parameter allows someone who does not have rights to a specific business process to run it. If you select Admin as the user ID, you will inherit administrative rights (for this run of the business process only), and can enable the scheduled run.
Use 24 Hour Clock Display	If selected, the adapter will use the 24-hour clock instead of the default 12-hour clock.
Schedule	Information about scheduling the business process after the File System adapter collects files. The Schedule field only displays as an option if Start a business process once files are collected is set to Yes. Valid values: Do not use schedule If you select this field, the adapter does not start a business process and does not run on a schedule. Run based on timer Valid values are the hour and minutes at which to run the adapter. If you choose to select a time interval, the valid values are the hours and minutes for the intervals. Add or delete selections as necessary. Specify any schedule exclusions or date exclusions. Indicate whether you want the adapter to run at startup. Run daily Valid values are the hour and minutes at which to run the adapter, daily. If you choose to select a time interval, the valid values are the hour and minute for the interval. Add or delete selections as necessary. Specify any date exclusions. Indicate whether you want the adapter to run at startup. Run based on days of the week Valid values are the day of the week, the hour, and the minute that specify when to run the adapter. If you choose to select a time interval, the valid values are the hours and minutes for the intervals. Add or delete selections as necessary. Specify any date exclusions. Run based on days of the month Valid values are the day of the month, hour, and minute that specify when to run the adapter. If you choose to select a time interval, the valid values are the hours and minutes for the intervals. Add or delete selections as necessary. Specify any date exclusions.
Extraction folder (extractionFolder)	The name of the folder or subfolder on the same computer where Sterling B2B Integrator is installed and where it extracts (or writes) data from the primary document as part of a business process. If you do not include the file path for the folder as part of the name, the folder is assumed to be the Sterling B2B Integrator working directory. Required. Note: This parameter is read-only in the GPM.
Unobscure File Contents? (unobscure)	Whether to unobscure the file contents when extracting. Does not work with “exportFile”. Valid values: Yes - File contents will be unobscured No - File contents will not be unobscured Note: This parameter is read-only in the GPM.
Filenaming convention (assignFilename)	Whether to override the document file name and use the assigned file name. Required. Valid values: Use the original file name as the extracted file name - Keeps the names of the files. Note: If the primary document has no document name, the adapter will use a default filename in the form of `nodename`_yyyyMMddHHmmssSSS.dat. Assign a specific name - Gives you the option to navigate to a screen and specify a different filename for the file extracted to the file system. Note: This parameter is read-only in the GPM.
Filename (assignedFilename)	File name you want to assign, including the file name extension. The Filename field only displays if the Filenaming convention is set to Assign a specific name. Required. This field cannot be left blank. You can use “%^” to assign a unique file name in the format `nodename`_yyyyMMddHHmmssSSS. For example, specifying %^.dat as the Filename assigns the name `nodename`_20040203114020982.dat to the file. Note: This field can also be assigned in the GPM. If you select a filename using the File System adapter configuration, you cannot override it using the GPM assignedFilename parameter. However, you can override it using BPML.
Enable Service for Business Processes	Whether to enable the service for use by business processes. If not selected, the service will be disabled. For more information, see Managing Services and Adapters.

Example of Using User Parameters in a Business Process

The user parameters User Parameter 1 (UserParm1) through User Parameter 5 (UserParm5) in the File System adapter are places to store hard-coded values for use by other services. They are simple assign statements in the BPML.

For example, the Document Extraction service requires the following parameters when used for EDI XML extraction:

XMLEDIEnvelopeStandard
XMLRootTag
XMLSenderIDPath
XMLReceiverIDPath
XMLAccepterLookupAliasPath

The File System adapter could be used in an intermediate business process to pass the parameters to the Document Extraction service through the use of User Parameters. The values for the above parameters would be stored in User Parameter 1 through User Parameter 5 in the File System adapter. The following assign statements would then be entered in the BPML code:

UserParm1 = XMLEDIEnvelopeStandard
UserParm2 = XMLRootTag
UserParm3 = XMLSenderIDPath
UserParm4 = XMLReceiverIDPath
UserParm5 = XMLAccepterLookupAliasPath

The values stored in the User Parameters would be passed through to the Document Extraction service under the assigned parameter names.

Graphical Process Modeler Configuration

The following screen shows the graphical view of the GPM parameters for the File System adapter. The dimmed values have been specified using the File System adapter configuration. The active fields are fields that cannot be configured in the Sterling B2B Integrator or those that are being overridden. There are no fields to be configured on the Message From Service tab.

Screen 1 of 3

Screen 2 of 3

Screen 3 of 3

The following example shows the corresponding BPML parameters for the File System adapter GPM parameters.

<process name="ExampleFileCollection"> 
	<operation name="File System Adapter"> 
 	<participant name="ExampleCollectionFSA"/> 
 	<output message="FileSystemInputMessage"> 
	 	<assign to="." from="*"/> 
	 	<assign to="Action">FS_COLLECT</assign> 
	 	<assign to="collectZeroByteFiles">false</assign> 
	 	<assign to="deleteAfterCollect">false</assign> 
	 	<assign to="fileModTimeThreshold">60</assign> 
	 	<assign to="filter">*.po</assign> 
	 	<assign to="initialWorkFlowId">FIND_MESSAGE_CONSUMER</assign> 
	 	<assign to="maxThreads">10</assign> 
	 	<assign to="noFilesSetSuccess">false</assign> 
 	</output> 
 	<input message="inmsg"> 
	 	<assign to="." from="*"/> 
 	</input> 
	</operation> 
</process>

The following table describes the fields used to configure the File System adapter in the GPM. This table contains only the fields that are configured in the GPM. The values in parentheses represent the corresponding BPML values. This information is provided for your reference.

Field	Description
Config (participant name)	Name of the adapter configuration. Required. No default .
Action	Action that the File System adapter is to perform. Required. No default. Valid values: Collection (FS_COLLECT) - Files are collected or picked up from the specified folder. Extraction (FS_EXTRACT) - Files are extracted or written to the specified folder.
appendOnExtract	Whether to append the data if the extract file already exists. Normally, files are overwritten when extracting. This parameter allows you to append the data to the existing files instead. Valid values: Yes (true) - Data is appended to existing files. No (false) - Existing files are overwritten. Default
attachFile	Used to attach a file to a workflow as the primary document. The adapter does not perform any I/O and does not delete the file. Any valid filename is a valid value.
checkDelete	Determines if checking for deletion is possible before collecting files. Valid values: Yes (true) - Default No (false)
collectMultiple	Used to collect multiple files in non-bootstrap mode. Collected files are placed into process data. Yes (true) No (false) - Default
collectMultiplePDname	Used when collecting multiple files to specify which file will be the primary document. Any valid filename is a valid value.
collectMultiplePrefix	Specifies a prefix to be added to the document name. When multiple documents are created in process data, the documents are named Document1 through DocumentX. Multiple instances could overwrite the documents. You can use this prefix to differentiate the documents in different instances. For example, One instance could use the prefix Inst1_ and another instance could use the prefix Inst2_. The first instance would produce files named Inst1_Document`X` and the second instance would produce files named Inst2_Document`X`. The actual file name is placed as an attribute (filename=) in the document tag. The default value is FSA_.
collectZeroByteFiles (true/false)	Whether to collect zero-byte files. Valid values: Yes (true) - Zero-byte files are collected. No (false) - Zero-byte files are ignored. Default.
concatenateFiles	Used when the collectMultiple option is true and when the File System adapter is set in a non-bootstrap mode. The content of multiple non-zero byte files are concatenated into a single file, and is placed as the primary document. Optional. Valid values: Yes (true). Default. No (false)
dbCollect	If you set this field to true and the field deleteAfterCollect is set to true (which is the default), a database record will be written for every file collected. Before a file is collected, the database is checked to see if the file has already been collected. Optional. Valid values are Yes (true) and No (false). Default is No (false).
dbPurgeCollectMin	Used when dbCollect is set to Yes (true) to specify the number of minutes, from the time the database record is written, before the record is purged. Set this value slightly higher than the scheduled collection interval to prevent duplication before purging. Optional. Valid value is any valid (positive) integer value. Default is 1440 (one day).
deleteAfterCollect	Whether to delete the file after collection. Valid values: Yes (true) - File is deleted from the Collection folder after it is collected. Default. No (false) - File is left in the folder after it is read into Sterling B2B Integrator.
fileModTimeThreshold	Sets the file modification time threshold (in seconds) for files to be collected. A file is collected only if the modification time of the file is older than the number of seconds specified. This prevents premature collection of a file. Defaults to 30 seconds if you do not specify a value.
filter	Collect only files that match a specified filter within the collection folder. Optional. Examples include: .txt (collects only .txt files) .dat (collects only .dat files) EDI.* (collects only files named EDI with any file extension) EDI.txt (collect only files named EDI with a file extension of .txt) Note: If there are multiple files in the collection folder and you leave this field blank, one of the following occurs: If the adapter is configured to start a business process, it processes all files placed in the collection folder. If the adapter is within a business process, it collects only the first file in the collection folder. Note: If you specified this option using the File System adapter configuration, this field will be read-only. However, you can override this parameter using BPML.
genReport	Determines whether a workflow status report is generated for all files regardless of whether they were successfully collected or not. Optional. Valid values: Yes (true) - Status report will be generated whether file collection was successful or unsuccessful. Default No (false) - Status report will only be generated if file collection is unsuccessful.
maxCollect	Sets the maximum number of files to collect. The default is -1 (unlimited).
maxThreads	Used for performance tuning to set the maximum number of threads used when collecting files. The default is ten threads.
noFilesSetSuccess	Used to determine the workflow status when no files are available to collect in non-bootstrap mode. Optional. Valid values: Yes (true) - The workflow status is set to Success even if no files exist in the specified collection folder during collection. No (false) - The workflow status is set to Error if no files exist in the specified collection folder during collection. The default is No (false)
sortBy	When collectMultiple option is true and the File System Adapter is configured in a non-bootstrap mode, the files are sorted by File name or Modified date as selected in the GPM. The default setting places the files the way they were placed in the Collection folder. Optional. Valid Values: none.
streamBufSize	Used for performance tuning to override the default buffer size of 5k (5120). Optional. Valid value is any integer.
subCharsOnExtract	If the document name contains illegal filename characters, you can use this field to have them replaced with something else. An example would be if the document name was a GUID that contains colons ‘:' which are illegal in a Windows filename. In this case you would enter “:_” to replace all occurrences of the colon with an underscore. Optional. Must be entered in two character pairs with no delimiters or spaces. The first character is the one to be replaced, the second is the replacement itself.

Usage Examples

This section contains additional examples using the File System adapter for collecting and extracting files. Examples are included using both the GPM and BPML.

File Collection

The following example using the GPM illustrates a business process that performs a file collection operation when the business process is started.

The following example illustrates the same business process using BPML.

File Extraction

The following example using the GPM illustrates a business process that performs a file extraction operation when the business process is started. You could configure a File System adapter to start this business process after files are collected.

The following example illustrates the same business process using BPML.