Adding Watched Folder Endpoints

Summary of steps
Add a Watched Folder endpoint using the Java API
Watched folder configuration values constant file

You can programmatically add a Watched Folder endpoint to a service by using the LiveCycle Java API. By adding a Watched Folder endpoint, you enable users to place a file (such as a PDF file) in a folder. When the file is placed in the folder, the configured service is then invoked and manipulates the file. After the service performs the specified operation, it saves the modified file in a specified output folder. A watched folder is configured to be scanned at a fixed rate interval or with a cron schedule, such as every Monday, Wednesday, and Friday at noon.

For the purposes of programmatically adding a Watched Folder endpoint to a service, consider the following short-lived process named EncryptDocument . (See Understanding LiveCycle Processes .)

View full size graphic

This process accepts an unsecured PDF document as an input value and then passes the unsecured PDF document to the Encryption service’s EncryptPDFUsingPassword operation. The PDF document is encrypted with a password, and the password-encrypted PDF document is the output value of this process. The name of the input value (the unsecured PDF document) is InDoc and the data type is com.adobe.idp.Document . The name of the output value (the password-encrypted PDF document) is SecuredDoc and the data type is com.adobe.idp.Document .

Note: You cannot add a Watched Folder endpoint by using web services.

Summary of steps

To add a Watched Folder endpoint to a service, perform the following tasks:

Include project files.
Create an EndpointRegistryClient object.
Set Watched Folder endpoint attributes.
Specify configuration values.
Define input parameter values.
Define an output parameter value.
Create a Watched Folder endpoint.
Enable the endpoint.

Include project files

Include the necessary files in your development project. If you are creating a client application by using Java, include the necessary JAR files. If you are using web services, make sure that you include the proxy files.

The following JAR files must be added to your project’s class path:

adobe-livecycle-client.jar
adobe-usermanager-client.jar
adobe-utilities.jar (required if LiveCycle is deployed on JBoss Application Server)
jbossall-client.jar (required if LiveCycle is deployed on JBoss Application Server)

For information about the location of these JAR files, see Including LiveCycle Java library files .

Create an EndpointRegistry Client object

To programmatically add a Watched Folder endpoint, you must create an EndpointRegistryClient object.

Set Watched Folder endpoint attributes

To create a Watched Folder endpoint for a service, specify the following values:

Connector identifier : Specifies the type of endpoint that is created. To create a Watched Folder endpoint, specify WatchedFolder .
Description : Specifies the description of the endpoint.
Name : Specifies the name of the endpoint.
Service identifier : Specifies the service to which the endpoint belongs. For example, to add a Watched Folder endpoint to the process that is introduced in this section (a process becomes a service when activated using Workbench), specify EncryptDocument .
Operation name : Specifies the name of the operation that is invoked by using the endpoint. Typically, when creating a Watched Folder endpoint for a service that originated from a process created in Workbench, the name of the operation is invoke .

Specify configuration values

You must specify configuration values for a Watched Folder endpoint when programmatically adding a Watched Folder endpoint to a service. These configuration values are specified by an administrator if a Watched Folder endpoint is added by using administration console.

The following list specifies configuration values that are set when programmatically adding a Watched Folder endpoint to a service:

url : Specifies the watched folder location. In a clustered environment, this value must point to a shared network folder that is accessible from every computer in the cluster.
asynchronous : Identifies the invocation type as asynchronous or synchronous. Transient and synchronous processes can only be invoked synchronously. The default value is true. Asynchronous is recommended.
cronExpression : Used by quartz to schedule the polling of the input directory. For details about configuring the cron expression, see http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html .
purgeDuration : This is a mandatory attribute. Files and folders in the result folder are purged when they are older than this value. This value is measured in days. This attribute is useful in ensuring the result folder does not become full. A value of -1 days indicates to never delete the results folder. The default value is -1.
repeatInterval : The interval, in seconds, for scanning the Watched Folder for input. Unless throttling is enabled, this value should be longer than the time to process an average job; otherwise, the system may become overloaded. The default value is 5.
repeatCount : The number of times a Watched Folder scans the folder or directory. A value of -1 indicates indefinite scanning. The default value is -1.
throttleOn : Limits the number of Watched Folder jobs that can be processed at any given time. The maximum number of jobs is determined by the batchSize value.
userName : The user name used when invoking a target service from the Watched Folder. This value is mandatory. The default value is SuperAdmin.
domainName : The user’s domain. This value is mandatory. The default value is DefaultDom.
batchSize : The number of files or folders to be picked up per scan. Use this value to prevent an overload on the system; scanning too many files at one time can result in a crash. The default value is 2.
waitTime : The time, in milliseconds, to wait before scanning a folder or file after creation. For example, if wait time is 36,000,000 milliseconds (one hour) and the file was created one minute ago, this file is picked up after 59 or more minutes have passed. This attribute is useful to ensure that a file or folder is completely copied to the input folder. For example, if you have a large file to process and the file takes ten minutes to download, set the wait time to 10*60 *1000 milliseconds. This setting prevents the watched folder from scanning the file if it has not been waiting for ten minutes. The default value is 0.
excludeFilePattern : The pattern that a watched folder uses to determine which files and folders to scan and pick up. Any file or folder that has this pattern will not be scanned for processing. This setting is useful when the input is a folder that contains multiple files. The contents of the folder can be copied into a folder that has a name that will be picked up by the watched folder. This step prevents the watched folder from picking up a folder for processing before the folder is completely copied into the input folder. For example, if the excludeFilePattern value is data* , all files and folders that match data* are not picked up. This includes files and folders named data1 , data2 , and so on. Additionally, the pattern can be supplemented with wildcard patterns to specify file patterns. The watched folder modifies the regular expression to support wildcard patterns such as *.* and *.pdf . These wildcard patterns are not supported by regular expressions.
includeFilePattern : The pattern that the watched folder uses to determine which folders and files to scan and pick up. For example, if this value is * , all files and folders that match input* are picked up. This includes files and folders named input1 , input2 , and so on. The default value is * . This value indicates all files and folders. Additionally, the pattern can be supplemented with wildcard patterns to specify file patterns. The watched folder modifies the regular expression to support wildcard patterns such as *.* and *.pdf . These wildcard patterns are not supported by regular expressions. This value is a mandatory.
resultFolderName : The folder where the saved results are stored. This location can be an absolute or a relative directory path. If the results do not appear in this folder, check the failure folder. Read-only files are not processed and will be saved in the failure folder. The default value is result/%Y/%M/%D/ . This is the results folder inside the watched folder.
preserveFolderName : The location where files are stored after successful scanning and pickup. This location can be an absolute, a relative, or a null directory path. The default value is preserve/%Y/%M/%D/ .
failureFolderName : The folder where failure files are saved. This location is always relative to the watched folder. Read-only files are not processed and will be saved in the failure folder. The default value is failure/%Y/%M/%D/ .
preserveOnFailure : Preserve input files in case of failure to execute the operation on a service. The default value is true.
overwriteDuplicateFilename : When set to true, files in the results folder and preserve folder are overwritten. When set to false, files and folders that have a numeric index suffix are used for the name. The default value is false.

Define input parameter values

When creating a Watched Folder endpoint, you must define input parameter values. That is, you must describe the input values that are passed to the operation that is invoked by the watched folder. For example, consider the process introduced in this topic. It has one input value named InDoc and its data type is com.adobe.idp.Document . When creating a Watched Folder endpoint for this process (after a process is activated, it becomes a service), you must define the input parameter value.

To define input parameter values required for a Watched Folder endpoint, specify the following values:

Input parameter name : The name of the input parameter. The name of an input value is specified in Workbench for a process. If the input value belongs to a service operation (a service that is not a process created in Workbench), the input name is specified in the component.xml file. For example, the name of the input parameter for the process introduced in this section is InDoc .

Mapping type : Used to configure the input values required to invoke the service operation. There are two types of mapping types:

Literal : The Watched Folder endpoint uses the value entered in the field as it is displayed. All basic Java types are supported. For example, if an API uses input such as String, long, int, and Boolean, the string is converted into the proper type and the service is invoked.
Variable : The value entered is a file pattern that the watched folder uses to pick the input. For example, if you select Variable for the mapping type and the input document must be a PDF file, you can specify *.pdf as the mapping value.

Mapping value : Specifies the value of the mapping type. For example, if you select a Variable mapping type, you can specify *.pdf as the file pattern.

Data type : Specifies the data type of the input value(s). For example, the data type of the input value of the process introduced in this section is com.adobe.idp.Document .

Define an output parameter value

When creating a Watched Folder endpoint, you must define an output parameter value. That is, you must describe the output value that is returned by the service that is invoked by the Watched Folder endpoint. For example, consider the process introduced in this topic. It has an output value named SecuredDoc and its data type is com.adobe.idp.Document . When creating a Watched Folder endpoint for this process (after a process is activated, it becomes a service), you must define the output parameter value.

To define an output parameter value required for a Watched Folder endpoint, specify the following values:

Output parameter name : The name of the output parameter. The name of a process output value is specified in Workbench. If the output value belongs to a service operation (a service that is not a process created in Workbench), the output name is specified in the component.xml file. For example, the name of the output parameter for the process introduced in this section is SecuredDoc .

Mapping type : Used to configure the output of the service and operation. The following options are available:

If the service returns a single object (a single document), the pattern is %F.pdf and the source destination is sourcefilename.pdf. For example, the process introduced in this section returns a single document. As a result, the mapping type can be defined as %F.pdf ( %F means use the given file name). The pattern %E specifies the extension of the input document.
If the service returns a list, the pattern is Result\%F\ , and the source destination is Result\sourcefilename\source1 (output 1) and Result\sourcefilename\source2 (output 2).
If the service returns a map, the pattern is Result\%F\ , and the source destination is Result\sourcefilename\file1 and Result\sourcefilename\file2. If the map has more than one object, the pattern is Result\%F.pdf and the source destination is Result\sourcefilename1.pdf (output 1), Result\sourcefilenam2.pdf (output 2), and so on.

Data type : Specifies the data type of the return value. For example, the data type of the return value of the process introduced in this section is com.adobe.idp.Document .

Create a Watched Folder endpoint

After you set the endpoint’s attributes, configuration values, and define input and output parameter values, you must create the Watched Folder endpoint.

Enable the endpoint

After you create a Watched Folder endpoint, you must enable it. When the endpoint is enabled, it can be used to invoke the service. After you enable the endpoint, you can view it within administration console.

Add a Watched Folder endpoint using the Java API

Add a Watched Folder endpoint by using the LiveCycle Java API:

Include project files.

Include client JAR files, such as adobe-livecycle-client.jar, in your Java project’s class path.
Create an EndpointRegistry Client object.
- Create a ServiceClientFactory object that contains connection properties.
- Create an EndpointRegistryClient object by using its constructor and passing the ServiceClientFactory object.
Set Watched Folder endpoint attributes.
- Create a CreateEndpointInfo object by using its constructor.
- Specify the connector identifier value by invoking the CreateEndpointInfo object’s setConnectorId method and passing the string value WatchedFolder .
- Specify the description of the endpoint by invoking the CreateEndpointInfo object’s setDescription method and passing a string value that describes the endpoint.
- Specify the name of the endpoint by invoking the CreateEndpointInfo object’s setName method and passing a string value that specifies the name.
- Specify the service to which the endpoint belongs by invoking the CreateEndpointInfo object’s setServiceId method and passing a string value that specifies the service name.
- Specify the operation that is invoked by invoking the CreateEndpointInfo object’s setOperationName method and passing a string value that specifies the operation name. Typically, when creating a Watched Folder endpoint for a service that originated from a process created in Workbench, the name of the operation is invoke.
Specify configuration values.

For each configuration value to set for the Watched Folder endpoint, you must invoke the CreateEndpointInfo object’s setConfigParameterAsText method. For example, to set the url configuration value, invoke the CreateEndpointInfo object’s setConfigParameterAsText method and pass the following string values:
- A string value that specifies the name of the configuration value. When setting the url configuration value, specify url .
- A string value that specifies the value of the configuration value. When setting the url configuration value, specify the watched folder location.
Note: To see all the configuration values set for the EncryptDocument service, see the Java code example located at QuickStart: Adding a Watched Folder endpoint using the Java API .
Define input parameter values.

Define an input parameter value by invoking the CreateEndpointInfo object’s setInputParameterMapping method and pass the following values:
- A string value that specifies the name of the input parameter. For example, the name of the input parameter for the EncryptDocument service is InDoc .
- A string value that specifies the data type of the input parameter. For example, the data type of the InDoc input parameter is com.adobe.idp.Document .
- A string value that specifies the mapping type. For example, you can specify variable .
- A string value that specifies the mapping type value. For example, you can specify *.pdf as the file pattern.
Note: Invoke the setInputParameterMapping method for each input parameter value to define. Because the EncryptDocument process has only one input parameter, you need to invoke this method once.
Define an output parameter value.

Define an output parameter value by invoking the CreateEndpointInfo object’s setOutputParameterMapping method and pass the following values:
- A string value that specifies the name of the output parameter. For example, the name of the output parameter for the EncryptDocument service is SecuredDoc .
- A string value that specifies the data type of the output parameter. For example, the data type of the SecuredDoc output parameter is com.adobe.idp.Document .
- A string value that specifies the mapping type. For example, you can specify %F.pdf .
Create a Watched Folder endpoint.

Create the endpoint by invoking the EndpointRegistryClient object’s createEndpoint method and passing the CreateEndpointInfo object. This method returns an Endpoint object that represents the Watched Folder endpoint.
Enable the endpoint.

Enable the endpoint by invoking the EndpointRegistryClient object’s enable method and passing the Endpoint object that was returned by the createEndpoint method.

Watched folder configuration values constant file

The QuickStart: Adding a Watched Folder endpoint using the Java API uses a constant file that must be part of your Java project in order to compile the quick start. This constant file represents configuration values that must be set when adding a Watched Folder endpoint. The following Java code represents the constant file. For information about these configuration values, see Specify configuration values .

/** 
    * This class contains constants that can be used when setting Watched Folder  
    * configuration values 
    */ 
 
public final class WatchedFolderEndpointConfigConstants { 
         
        public static final String PROPERTY_FILEPROVIDER_URL = "url"; 
        public static final String PROPERTY_PROPERTY_ASYNCHRONOUS = "asynchronous"; 
        public static final String PROPERTY_CRON_EXPRESSION = "cronExpression"; 
        public static final String PROPERTY_PURGE_DURATION = "purgeDuration"; 
        public static final String PROPERTY_REPEAT_INTERVAL = "repeatInterval"; 
        public static final String PROPERTY_REPEAT_COUNT = "repeatCount"; 
        public static final String PROPERTY_THROTTLE = "throttleOn"; 
        public static final String PROPERTY_USERNAMER = "userName"; 
        public static final String PROPERTY_DOMAINNAME = "domainName"; 
        public static final String PROPERTY_FILEPROVIDER_BATCH_SIZE = "batchSize"; 
        public static final String PROPERTY_FILEPROVIDER_WAIT_TIME = "waitTime"; 
        public static final String PROPERTY_EXCLUDE_FILE_PATTERN = "excludeFilePattern"; 
        public static final String PROPERTY_INCLUDE_FILE_PATTERN = "excludeFilePattern"; 
        public static final String PROPERTY_FILEPROVIDER_RESULT_FOLDER_NAME =  "resultFolderName"; 
        public static final String PROPERTY_FILEPROVIDER_PRESERVE_FOLDER_NAME = "preserveFolderName"; 
        public static final String PROPERTY_FILEPROVIDER_FAILURE_FOLDER_NAME = "failureFolderName"; 
        public static final String PROPERTY_FILEPROVIDER_PRESERVE_ON_FAILURE = "preserveOnFailure"; 
        public static final String PROPERTY_FILEPROVIDER_OVERWRITE_DUPLICATE_FILENAME = "overwriteDuplicateFilename";      
       }