Managing Endpoints

Endpoints can be added only to services. An endpoint cannot exist alone; it must be associated with a service.

1. In administration console, click Services > Applications and Services > Service Management.

2. On the Service Management page, click the service to configure.

3. In the list on the Endpoints tab, select the type of endpoint to add and click Add.

4. Depending on the endpoint type, configure additional endpoint settings.

   Watched folder endpoint settings

   Email endpoint settings

   Configuring Task Manager endpoints

   Remoting endpoint settings

5. Click Add.

By default, new endpoints are automatically enabled. But if you have disabled an endpoint, you will need to enable it for it to be operational.

If you are experiencing problems with services, disable the associated endpoints to better troubleshoot the problem. You may also want to disable endpoints during regular system maintenance or when upgrading a service.

1. In administration console, click Services > Applications and Services > Endpoint Management.

2. On the Endpoint Management page, select the check box for the endpoint to enable or disable and click Enable or Disable.

1. In administration console, click Services > Applications and Services > Endpoint Management.

2. On the Endpoint Management page, click the endpoint to modify.

3. On the Update Endpoint page, modify the endpoint name, description, and settings.

   Note: Do not include a < character in the name or description because it will truncate the name or description displayed in Workspace.

4. To save your changes, click Update.

You can also do this task from the Service Management page by selecting a service and then clicking the Endpoints tab.

1. In administration console, click Services > Applications and Services > Endpoint Management.

2. On the Endpoint Management page, select the check box for the endpoint to remove and click Remove. The endpoint is no longer displayed.

You can configure POP3, IMAP, or SMTP to use Secure Sockets Layer (SSL) for an email endpoint.

1. On the email server, enable SSL for POP3, IMAP, or SMTP according to the manufacturer’s documentation.

2. Export a client certificate from the email server.

3. Use the keytool program to import the client certificate file to the application server’s Java Virtual Machine (JVM) certificate store. The procedure for this step will depend on the JVM and client installation paths.

   For example, if you are using a default Oracle WebLogic Server installation with JDK 1.5.0 on Microsoft Windows Server® 2003, type the following text in a command prompt:

   keytool -import -file client_certificate -alias myalias -keystore BEA_HOME\jdk150_04\jre\security\cacerts

4. When prompted, enter the password (for Java, the default password is changeit ). You will receive a message stating that the certificate was imported successfully.

5. Use administration console to add the email endpoint to the service.

6. Create the email endpoint in administration console. When configuring the endpoint settings, select POP3/IMAP SSL Enabled for incoming messages and SMTP SSL Enabled for outgoing messages, and change the port properties accordingly.

Tip: If you experience problems when using SSL, use an email client such as Microsoft Outlook to check whether it can access the email server using SSL. If the email client cannot access the email server, the issue is related to the configuration of either your certificate or your email server.

You can use the Service Management page to configure attributes that are common for all email endpoints, and to provide default values for all the email endpoints.

For forms workflow to receive and handle incoming email messages from users, you need to create an email endpoint for the Complete Task service. This email endpoint requires additional settings, as described in Create an Email endpoint for the Complete Task service .

Use the following settings to configure an email endpoint.

Name:

A mandatory setting that identifies the endpoint. Do not include a < character because it truncates the name displayed in Workspace. If you’re entering a URL as the name of the endpoint, ensure that it conforms with the syntax rules specified in RFC1738 .

Description:

A description of the endpoint. Do not include a < character because it truncates the description displayed in Workspace.

Cron Expression:

Enter a cron expression if the email must be scheduled by using a cron expression.

Repeat Count:

Number of times the email endpoint scans the folder or directory. A value of -1 indicates indefinite scanning. The default value is -1.

Repeat Interval:

The scanning rate that the receiver uses for checking for incoming mail.

Delay when job starts:

The time to wait to scan after the scheduler starts.

Batch Size:

The number of emails the receiver processes per scan for optimum performance. A value of -1 indicates all emails. The default value is 2.

User Name:

A mandatory setting, which is the user name that is used when invoking a target service from email. The default value is SuperAdmin.

Domain Name:

A mandatory setting, which is the user’s domain. The default value is DefaultDom.

Domain Pattern:

Specifies the domain patterns of incoming email that the provider accepts. For example, if adobe.com is used, only email from adobe.com is processed; email from other domains is ignored.

File Pattern:

Specifies the incoming file attachment patterns that the provider accepts. This includes files that have specific extensions (*.dat, *.xml), specific names (data), or composite expressions in the name and extension (*.[dD][aA][Tt]).

Successful Job’s Recipients:

An email address to which messages are sent to indicate successful jobs. By default, a successful job message is always sent to the sender. If you type sender , email results are sent to the sender. Up to 100 recipients are supported. Specify additional recipients with email addresses, separated by commas (,).

To turn off this setting, leave the setting blank. In some cases, you want to trigger a process and do not want an email notification of the result.

Failed Job’s Recipients:

An email address to which messages are sent to indicate failed jobs. By default a failed job message is always sent to the sender. If you type sender , email results are sent to the sender. Up to 100 recipients are supported. Specify additional recipients with email addresses, separated by commas (,).

To turn off this setting, leave the setting blank. In some cases, you want to trigger a process and do not want an email notification of the result.

Inbox Host:

The inbox host name or IP address for the email provider to scan.

Inbox Port:

The port that the email server uses. The default value for POP3 is 110 and the default value for IMAP is 143. If SSL is enabled, the default value for POP3 is 995 and the default value for IMAP is 993.

Inbox Protocol:

The email protocol for the email endpoint to use to scan the inbox. The values are IMAP or POP3. The inbox host mail server must support these protocols.

Inbox Time Out:

The time-out, in seconds, for the email provider to wait for inbox responses.

Inbox User:

The user name that is required to log in to the email account. Depending on the email server and configuration, this value may be only the user name portion of the email or it may be the full email address.

Inbox Password:

The password for the inbox user.

POP3/IMAP SSL Enabled:

Select this setting to force the email provider to use SSL to scan the inbox. Ensure that your mail server supports SSL.

SMTP Host:

The host name of the mail server the email provider uses to send results and error messages.

SMTP Port:

The default value for the SMTP port is 25.

SMTP User:

The user account for the email provider to use when it sends email notifications of results and errors.

SMTP Password:

The password for the SMTP account. Some mail servers do not require an SMTP password.

Send From:

The email address (for example, user@company.com) used to send email notifications of results and errors. If you do not specify a Send From value, the email server attempts to determine the email address by combining the value specified in the SMTP User setting with a default domain configured on the email server. If your email server does not have a default domain and you do not specify a value for Send From, errors may occur. To ensure that the email messages have the correct from address, specify a value for the Send From setting.

SMTP SSL Enabled:

Select this setting to force the email provider to use SSL to scan the inbox. Ensure that your mail server supports SSL.

Failed Email Sent Folder:

Specifies a directory in which to store results if the SMTP mail server is not operational.

asynchronous:

When set to synchronous, all input documents are processed and a single response is returned. When set to asynchronous, a response is sent for each document that is processed.

For example, an email endpoint is created for a service that takes a single Word document and returns that document as a PDF file. An email can be sent to the endpoint’s inbox that contains multiple (3) Word documents. When all three documents are processed, if the endpoint is configured as synchronous, a single response email is sent with all three documents attached. If the endpoint is asynchronous, a response email is sent after each Word document is converted to PDF. The result is three emails, each with a single PDF attachment.

The default value is asynchronous.

Include the original email body as an attachment:

By default, when you send an email to the forms server, the original text of the message is included in the body of the message. To instead include the text as an attachment, select this option.

Use the original subject line for result emails:

By default, forms server uses the values specified in the Success Email Subject and Error Email Subject settings as the subject line when sending result email messages. To instead use the same subject line as the original email sent to the server, select this option.

Success Email Subject:

After you send an email to an email endpoint to start or continue a process, you receive a return email message from the AEM forms server. If your email succeeds, you receive a success email. If your email fails, you receive a failure email informing why it failed. This setting enables you to specify the subject line of success email messages sent for this endpoint.

Success Email Body:

Enables you to specify the body text of success email messages sent for this endpoint.

Error Email Subject Prefix:

Enables you to specify the text used at the beginning of the subject line of failure email messages sent for this endpoint.

Error Email Subject:

Enables you to specify the subject line of failure email messages sent for this endpoint. This text is displayed after the Error Email Subject Prefix.

Error Email Body:

Enables you to specify the first line in the body text of failure email messages sent for this endpoint.

Email Summary Info:

Each success or failure message includes a section containing the original email text that you sent to the forms server. This setting specifies the text that appears above that section.

Validate Inbox before creating/updating this endpoint:

When this option is selected, the forms server checks whether your SMTP/POP3 settings are correct before creating the endpoint. When you click Add, a message displays, stating whether the inbox account is valid. If this option is not selected, the AEM forms server creates the endpoint without validating the inbox.

Operation Name:

This setting is mandatory. A list of operations that can be assigned to the email endpoint. The operation that you select here determines which fields are displayed in the Input Parameter Mappings and Output Parameter Mappings sections.

Input Parameter Mappings:

Used to configure the input that is required to process the service and operation. The two types of input are literal and variable:

Literal:

The email uses the value that is entered in the field as it is displayed.

Variable:

You can map a string from the email subject, body, header, or sender's email address. To do this, use one of the following keywords: %SUBJECT%, %BODY%, %HEADER%, or %SENDER%. For example, if you use %SUBJECT%, the email subject content is used as the input parameter. To pick up attachments, enter a file pattern that the email endpoint can use to select the attached documents. For example, entering *.pdf selects any attached document that has a .pdf filename extension. Entering * selects any attached document. Entering example.pdf selects any attached document named example.pdf.

Output Parameter Mappings:

Used to configure the output of the service and operation. The following characters in the output parameter mapping values are expanded in the attachment filename:

%F

Represents the source file’s filename (not including an extension).

%E

Represents the source file’s extension.

\

Any occurrence of the backslash (\) is replaced with %%.

Note: If the service request message includes multiple file attachments, you cannot use the %F and %E parameters for the Output Parameter Mappints property of the endpoint. If the services response returns multiple file attachments, you cannot specify the same file name for more than one attachment. If you do not follow these recommendations, the invoked service create the names for the returned files, and the names are not predictable.

The following values are available:

Single Object:

The email provider does not have the source folder destination; results are returned as attachments. The pattern is Result/%F.ps and returns Result%% sourcefilename.ps as the filename attachment.

List:

The pattern is Result/%F/ and returns Result%% sourcefilename %%file1 as the filename attachment.

Map:

The pattern is Result/%F/ and the source destination is Result%% sourcefilename %%file1 and Result%% sourcefilename %%file2 . If the map contains more than one object and the pattern is Result/%F.ps , the response file attachments are Result%% sourcefilename 1 .ps (output 1) and Result%% sourcefilename2.ps (output 2).

For forms workflow to receive and handle incoming email messages from users, you need to create an email endpoint for the Complete Task service.

1. In administration console, click Services > Applications and Services > Service Management.

2. On the Service Management page, click the Complete Task service.

3. On the Endpoints tab, select Email from the drop-down list and click Add.

4. In the Inbox Host box, type the host name or IP address of the mail server.

5. In the Inbox User box, type the user name required to log in to the email account that you created to handle form submissions. Depending on the email server and configuration, this name may be only the user name portion of the email or it may be the full email address.

6. In the Inbox Password box, type the password for the Inbox User.

7. In the SMTP Host box, type the host name or IP address of the mail server from which the email provider sends results and error messages.

8. In the SMTP User box, type the user account for the email provider to use when it sends out email for results and errors. This user account can be the same value you used for Inbox User.

9. In the SMTP Password box, type the password for the SMTP account.

10. In the Operation Name list, select invoke.

11. In the attachmentMap list, select Variable and type *.* in the adjacent box. This sends all attachments from the inbound mail messages to a map variable for the Complete Task process.

12. In the mailBody list, select variable and type %BODY% in the adjacent box.

13. In the mailFrom list, select Variable and type %SENDER% in the adjacent box. This maps the sender address to the Complete Task process data.

14. In the results box, type results . This causes the Complete Task or Start Process to return a result string.

15. Click Add.

Before you configure a watched folder endpoint, configure the Watched Folder service. The Watched Folder service’s configuration parameters have two purposes:

• To configure attributes that are common for all watched folder endpoints

• To provide default values for all the watched folder endpoints

After configuring the Watched Folder service, you add a Watched Folder endpoint for the target service. When adding the endpoint, you set values, such as the service name and operation name to invoke when files or folders are placed in the input folder of the configured Watched Folder service. For details on configuring the Watched Folder service, see Watched Folder service settings .

You can create a watched folder in the following two ways:

• When configuring the settings for a watched folder endpoint, type the full path to the parent directory in the Path box and append the name of the watched folder to be created, as shown in this example:

      C:\MyPDFs\MyWatchedFolder

  Because the MyWatchedFolder folder does not already exist, AEM forms attempts to create it at that location.

• Create a folder on the file system prior to configuring a watched folder endpoint, and then type the full path in the Path box.

In a clustered environment, the folder that will be used as a watched folder must be accessible, writable, and shared on the file system or network. In this scenario, each application server instance of the cluster must have access to the same shared folder.

In Windows, if the application server is running as a service, it must be started with appropriate access to the shared folder in one of the following ways:

• Configure the application server service Log On Asparameter to start asa specific user with appropriate access to the shared watched folder.

• Configure the application server service Start as Local System option to Allow Service to Interact with the desktop. This option requires that the shared watched folder is accessible and writable to everyone.

Watched folders can be chained together so that a result document of one watched folder is the input document of the next watched folder. Each watched folder can invoke a different service. By configuring watched folders in this manner, multiple services can be invoked. For example, one watched folder could convert PDF files to Adobe PostScript® and a second watched folder could convert the PostScript files to PDF/A format. To do this, simply set the result folder of the watched folder defined by your first endpoint to point to the input folder of the watched folder defined by your second endpoint.

Output from the first conversion would go to \ path \result. Input for the second conversion would be \ path \result, and output from the second conversion would go to \ path \result\result (or the directory you define in the Result Folder box for the second conversion).

For a watched folder endpoint, users can invoke by copying or dragging input files or folders from their desktops to a watched folder. The files will be processed in the order in which they arrive.

For watched folder endpoints, if the job requires only one input file, the user can copy that file to the root of the watched folder.

If the job contains more than one input file, the user must create a folder outside the watched folder hierarchy that contains all required files. This new folder should include the input files (and optionally a DDX file if required by the process). After the job folder has been constructed, the user copies it into the watched folder’s input folder.

When the input is a folder and the output consists of multiple files, AEM forms creates an output folder with the same name as the input folder and copies the output files into that folder. When the output consists of a document map containing a key-value pair, such as the output from an Output process, the key will be used as the output file name.

The output file names that result from an endpoint process cannot contain characters other than letters, numbers, and a period (.) before the file extension. AEM forms converts other characters to their hexadecimal values.

Client applications pick up the result documents from the watched folder result folder. Process errors are logged in the watched folder failure folder.

The Watched Folder module contains these services:

• Watched Folder service

• provider.file_scan_service

• provider.file_write_results_service

In addition to the services listed above, Watched Folder also depends on other services, including the Scheduler service for scheduling the jobs and the Job Manager service to support asynchronous invocation of target services.

Use the following settings to configure a watched folder endpoint.

Name:

(Mandatory) Identifies the endpoint. Do not include a < character because it will truncate the name displayed in Workspace. If you’re entering a URL as the name of the endpoint, ensure that it conforms with the syntax rules specified in RFC1738 .

Description:

A description of the endpoint. Do not include a < character because it will truncate the description displayed in Workspace.

Path:

(Mandatory) Specifies the watched folder location. In a clustered environment, this setting 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. The default value is asynchronous. Asynchronous is recommended for long-lived processes, while synchronous is recommended for transient or short-lived processes.

Cron Expression:

Enter a cron expression if the watched folder must be scheduled by using a cron expression. When this setting is configured, Repeat Interval is ignored. For details about configuring the cron expression see Class CronTrigger . When this setting is configured, the Repeat Interval is ignored.

Repeat Interval:

The interval in seconds for scanning the watched folder for input. Unless the Throttle setting is enabled, Repeat Interval should be longer than the time to process an average job; otherwise, the system may become overloaded. The default value is 5. See the description for Batch Size for additional information.

Repeat Count:

Number of times the watched folder scans the folder or directory. A value of -1 indicates indefinite scanning. The default value is -1.

Throttle:

When this option is selected, it limits the number of watched folder jobs that AEM forms processes at any given time. The maximum number of jobs is determined by the Batch Size value. (See About throttling .)

User Name:

(Mandatory) The user name that is used when invoking a target service from the watched folder. The default value is SuperAdmin.

Domain Name:

(Mandatory) The user’s domain. The default value is DefaultDom.

Batch Size:

The number of files or folders to be picked up per scan. Use to prevent an overload on the system; scanning too many files at one time can cause a crash. The default value is 2.

The Repeat Interval and Batch Size settings determine how many files Watched Folder picks up in every scan. Watched Folder uses a Quartz thread pool to scan the input folder. The thread pool is shared with other services. If the scan interval is small, the threads will scan the input folder often. If files are dropped frequently into the watched folder, then you should keep the scan interval small. If files are dropped infrequently, use a larger scan interval so that the other services can use the threads.

If there is a large volume of files being dropped, make the batch size large. For example, if the service invoked by the watched folder endpoint can process 700 files per minute, and users drop files into the input folder at the same rate, then setting the Batch Size to 350 and the Repeat Interval to 30 seconds will help Watched Folder performance without incurring the cost of scanning the watched folder too often.

When files are dropped into the watched folder, it lists the files in the input, which can reduce performance if scanning is happening every second. Increasing the scan interval can improve performance. If the volume of files being dropped is small, adjust the Batch Size and Repeat Interval accordingly. For example, if 10 files are dropped every second, try setting the Repeat Interval to 1 second and the Batch Size to 10.

Wait Time:

The time, in milliseconds, to wait before you scan a folder or file after it is created. For example, if the wait time is 3,600,000 milliseconds (one hour) and the file was created one minute ago, this file will be picked up after 59 or more minutes have passed. The default value is 0.

This setting 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 prevents the watched folder from scanning the file if it is not ten minutes old.

Exclude File Pattern:

A semi-colon (;) delimited list of patterns that a watched folder uses to determine which files and folders to scan and pick up. Any file or folder with this pattern will not be scanned for processing.

This setting is useful when the input is a folder with multiple files. The contents of the folder can be copied into a folder with a name that will be picked up by the watched folder. This prevents the watched folder from picking up a folder for processing before the folder is completely copied into the input folder.

You can use file patterns to exclude:

• Files with specific filename extensions; for example, *.dat, *.xml, .pdf, *.*

• Files with specific names; for example, data.* would exclude files and folders named data1 , data2 , and so on.

• Files with composite expressions in the name and extension, as in these examples:

  • Data[0-9][0-9][0-9].[dD][aA][tT]

  • *.[dD][Aa][Tt]

  • *.[Xx][Mm][Ll]

For more information about file patterns, see About file patterns .

Include File Pattern:

(Mandatory) A semi-colon (;) delimited list of patterns that the watched folder uses to determine which folders and files to scan and pick up. For example, if the Include File Pattern is input*, 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 * and indicates all files and folders.

You can use file patterns to include:

• Files with specific filename extensions; for example, *.dat, *.xml, .pdf, *.*

• Files with specific names; for example, data.* would include files and folders named data1 , data2 , and so on.

• Files with composite expressions in the name and extension, as in these examples:

  • Data[0-9][0-9][0-9].[dD][aA][tT]

  • *.[dD][Aa][Tt]

  • *.[Xx][Mm][Ll]

For more information about file patterns, see About file patterns .

Result Folder:

The folder where the saved results are stored. 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. This value can be an absolute or relative path with the following file patterns:

• %F = filename prefix

• %E = filename extension

• %Y = year (full)

• %y = year (last two digits)

• %M = month

• %D = day of month

• %d = day of year

• %H = hour (24-hour clock)

• %h = hour (12-hour clock)

• %m = minute

• %s = second

• %l = millisecond

• %R = random number (between 0 and 9)

• %P = process or job id

For example, if it is 8 PM on July 17, 2009 and you specify C:/Test/WF0/failure/%Y/%M/%D/%H/ , the result folder is C:/Test/WF0/failure/2009/07/17/20 .

If the path is not absolute but relative, the folder will be created inside the watched folder. The default value is result/%Y/%M/%D/, which is the Result folder inside the watched folder. For more information about file patterns, see About file patterns .

Note: The smaller the size of the result folders, the better Watched Folder performance will be. For example, if the estimated load for the watched folder is 1000 files every hour, try a pattern like result/%Y%M%D%H so that a new subfolder is created every hour. If the load is smaller (for example, 1000 files per day), you could use a pattern like result/%Y%M%D .

Preserve Folder:

The location where files are stored after successful scanning and pick-up. The path can be an absolute, a relative, or a null directory path. You can use file patterns, as described for Result Folder. The default value is preserve/%Y/%M/%D/.

Failure Folder:

The folder where failure files are saved. This location is always relative to the watched folder. You can use file patterns, as described for Result Folder.

Read-only files are not processed and will be saved in the failure folder.

The default value is failure/%Y/%M/%D/.

Preserve On Failure:

Preserve input files in case of failure to execute the operation on a service. The default value is true.

Overwrite Duplicate Filenames:

When set to True, files in the results folder and preserve folder are overwritten. When set to False, files and folders with a numeric index suffix are used for the name. The default value is False.

Purge Duration:

(Mandatory) Files and folders in the result folder are purged when they are older than this value. This value is measured in days. This setting is useful in ensuring that the result folder does not become full.

A value of -1 days indicates to never delete the results folder. The default value is -1.

Operation Name:

(Mandatory) A list of operations that can be assigned to the watched folder endpoint.

Input Parameter Mappings:

Used to configure the input required to process the service and operation. The settings available depend on which service is using the watched folder endpoint. Here are the two types of inputs:

Literal:

The watched folder 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 to 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, in the case of the encrypt password service, where the input document must be a PDF file, the user can use *.pdf as the file pattern. The watched folder will pick up all files in the watched folder that match this pattern and invoke the service for each file. When a variable is used, all input files are converted to documents. Only APIs that use Document as the input type are supported.

Output Parameter Mappings:

Used to configure the outputs of the service and operation. The settings available depend on which service is using the watched folder endpoint.

Watched Folder output can be a single document, a list of documents, or a map of documents. These output documents are then saved in the result folder, using the pattern specified in the Output Parameter Mapping.

Note: Specifying names that result in unique output filenames improves performance. For example, consider the case where the service returns one output document and the Output Parameter Mapping maps it to %F.%E (the file name and extension of the input file). In this case, if users drop files with the same name every minute, and the result folder is configured to result/%Y/%M/%D , and the Overwrite Duplicate Filename setting is off, Watched Folder will try to resolve the duplicate file names. The process of resolving duplicate file names can affect performance. In this situation, changing the Output Parameter Mapping to %F_%h_%m_%s_%l to add hours, minutes, seconds, and milliseconds to the name, or ensuring that dropped files have unique names may improve performance.

Administrators can specify the type of file that can invoke a service. Multiple file patterns can be established for each watched folder. A file pattern can be one of the following file properties:

• Files with specific file name extensions; for example, *.dat, *.xml, .pdf, *.*

• Files with specific names; for example, data.*

• Files with composite expressions in the name and extension, as in these examples:

  • Data[0-9][0-9][0-9].[dD][aA][tT]

  • *.[dD][Aa][Tt]

  • *.[Xx][Mm][Ll]

The administrator can define the file pattern of the output folder in which to store the results. For the output folders (result, preserve, and failure), the administrator can specify any of these file patterns:

• %Y = year (full)

• %y = year (last two digits)

• %M = month,

• %D = day of month,

• %d = day of year,

• %h = hour,

• %m = minute,

• %s = second,

• %R = random number between 0-9

• %J = Job name

For example, the path to the result folder may be C:\Adobe\Adobe_Experience_Manager_forms\BarcodedForms\%y\%m\%d .

Output parameter mappings can also specify additional patterns, such as these:

• %F = Source Filename

• %E = Source Filename Extension

If the output parameter mapping pattern ends with “File.separator”, (which is the path separator), a folder is created and the content is copied into that folder. If the pattern does not end with “File.separator”, the content (result file or folder) is created with that name. For more information about output parameter mappings, see Tips and tricks for watched folders .

When throttling is enabled for a watch folder endpoint, it limits the number of watched folder jobs that can be processed at any given time. The maximum number of jobs is determined by the Batch Size value, also configurable in the Watched Folder endpoint. Incoming documents in the input directory of the watched folder will not be polled when the throttling limit has been reached. The documents will also remain in the input directory until other watched folder jobs have completed and another poll attempt is made. In the case of synchronous processing, all jobs processed in a single poll will count toward the throttling limit, even though the jobs are processed consecutively in a single thread.

Watched Folder can serve 100 folders in total on one single node. The performance of Watched Folder is dependent on the performance of the forms server. For asynchronous invocation, performance is more dependent on the system load and jobs that are in the Job Manager queue.

Watched Folder performance can be improved by adding nodes to the cluster. Watched Folder jobs are distributed across the cluster nodes by virtue of the Quartz scheduler and, in the case of asynchronous requests, by the Job Manager service. All the jobs are persisted in the database.

Watched Folder depends on the Scheduler service for scheduling, unscheduling, and rescheduling the jobs. Other services, such as Event Management service, User Manager service, and Email Provider service, are available that share the Scheduler service thread pool. This can affect Watched Folder performance. The Scheduler service thread pool tuning will be needed when all the services start using it.

In a cluster, Watched Folder depends on the Quartz scheduler and the Job Manager service for load balancing and failover. For more information about Quartz cluster behavior, see Quartz Documentation .

Watched Folder performs these three main tasks at each poll:

• Scan the folder

• Invoke the target service

• Handle the results

The load balancing and failover behavior changes depending on whether the watched folder is configured for synchronous or asynchronous invocation.

At each poll event, Watched Folder locks the input folder, moves the files that match the include file pattern to the stage folder, and then unlocks the input folder. Locking is needed so that two threads do not pick up the same set of files and process them twice. The chances of this happening increase with a small repeat interval and a large batch size. After files are moved to the stage folder, the input folder is unlocked so that other threads can scan the folder. This step helps provide high throughput because other threads can scan while one thread is processing the files.

After files are moved to the stage folder, invocation requests are created for each file and the target service is invoked. There may be cases where Watched Folder cannot recover the files in the stage folder:

• If the server goes down before Watched Folder can create the invocation request, the files in the stage folder remain in the stage folder and are not recovered.

• If Watched Folder has successfully created the invocation request for each of the files in the stage folder and the server crashes, there are two behaviors based on the invocation type:

Synchronous: If Watched Folder is configured to invoke the service synchronously, all the files in the stage folder remain unprocessed in the stage folder.

Asynchronous: In this case, Watched Folder relies on the Job Manager service. If the Job Manager Service calls back Watched Folder, the files in the stage folder are moved to the preserve or failure folder based on the results of the invocation. If the Job Manager service does not call back Watched Folder, the files will remain unprocessed in the stage folder. This situation happens when Watched Folder is not running when the Job Manager calls back.

Each watched folder is configured with a user name and password. These credentials are used when invoking the services. Watched Folder relies on the fact that the shared folder is protected with the underlying security file system so that only the owner of the watched folder can access the shared folder.

Here are some tips and tricks when configuring the Watched Folder endpoint:

• If you have a watched folder on Windows that is processing image files, specify values for the Include File Pattern or Exclude File Pattern option to prevent the Windows auto-generated Thumbs.db file from being polled by the watched folder.

• If a cron expression is specified, the repeat interval is ignored. The cron expression usage is based on the Quartz open source job-scheduling system, version 1.4.0. (See Class CronTrigger .)

• The batch size is the number of files or folders that will be picked up in each scan of the watched folder. If the batch size is set to two and ten files or folders are dropped in the watched folder input folder, only two will be picked up in each scan. In the next scan, which will happen after the time specified in the repeat interval, the next two files will be picked up.

• For file patterns, administrators can specify regular expressions with added support of wild card patterns to specify file patterns. Watched Folder modifies the regular expression to support wild card patterns such as *.* or *.pdf. These wild card patterns are not supported by the regular expressions.

• Watched Folder scans the input folder for the input and does not know if the source file or folder is completely copied to the input folder before it starts processing the file or folder. To ensure that the source file or folder is completely copied to the input folder of the watched folder before the file or folder is picked up, do these tasks:

  • Use Wait time, which is the time in milliseconds that Watched Folder waits from the last modified time. Use this feature if you have large files to process. For example, if a file takes 10 minutes to download, specify the wait time as 10*60 *1000 milliseconds. This will prevent Watched Folder from picking up the file if it is not as old as 10 minutes.

  • Use exclude file pattern and include file pattern. For example, if the exclude file pattern is ex* and the include file pattern is in* , Watched Folder will pick up the files that start with "in" and will not pick up the files that start with "ex". To copy large files or folders, first rename the file or folder so that the name starts with "ex". After the file or folder named "ex" is completely copied to the watched folder, rename it to "in*".

• Use purge duration to keep the result folder clean. Watched Folder cleans up all the files that are older than the duration mentioned in the purge duration. The duration is in days.

• When adding a Watched Folder endpoint, after selecting the operation name, the input parameter mapping is populated. For each input of the operation, one input parameter mapping field is generated. Here are examples of input parameter mappings:

  • For com.adobe.idp.Document input: If the service operation has an input of type Document , the administrator can specify the mapping type as Variable . Watched Folder will pick up the input from the watched folder’s input folder based on the file pattern specified for the input parameter. If the administrator specifies *.pdf as the parameter, each file that has an extension of .pdf will be picked up, converted to com.adobe.idp.Document , and the service invoked.

  • For java.util.Map input: If the service operation has an input of type Map , the administrator can specify the mapping type as Variable and enter a mapping value with a pattern like *.pdf . For example, a service needs a map of two com.adobe.idp.Document objects that represent two files in the input folder such as 1.pdf and 2.pdf. Watched Folder will create a map with the key as the filename and the value as com.adobe.idp.Document .

  • For java.util.List input: If the service operation has an input of type List, the administrator can specify the mapping type as Variable and enter a mapping value with a pattern like *.pdf . When PDF files are dropped in the input folder, Watched Folder will create a list of the com.adobe.idp.Document objects that represents these files and invoke the target service.

  • For java.lang.String : The administrator has two options. First, the administrator can specify the mapping type as Literal and enter a mapping value as a string, such as hello. Watched Folder will invoke the service with the string hello . Second, the administrator can specify the mapping type as a Variable and enter a mapping value with a pattern like *.txt . In the latter case, files with the .txt extension will be read as a document coerced as a string to invoke the service.

  • Java primitive type: The administrator can specify the mapping type as Literal and provide the value. Watched Folder will invoke the service with the value specified.

• Watched Folder is meant to work with documents. The supported outputs are com.adobe.idp.Document , org.w3c.Document , org.w3c.Node , as well as a list and map of these types. Any other type will result in a failure output in the failure folder.

• If the results are not in the result folder, verify the failure folder to see if a failure has occurred.

• Watched Folder works best if used in asynchronous mode. In this mode, Watched Folder places the invocation request into the queue and calls back. The queue is then processed asynchronously. When the Asynchronous option is not set, Watched Folder invokes the target service synchronously and the Process Engine waits until the service is done with the request and results are produced. If the target service takes a long time to process the request, Watched Folder may get time-out errors.

• The creation of watched folders for import and export operations does not allow filename extension abstraction. When invoking the Form Data Integration service using watched folders, the filename extension type for the output file may not match the intended output format for the document object type. For example, if the input file to a watched folder that invokes the export operation is an XFA form that contains data, the output should be an XDP data file. To obtain an output file with the correct filename extension, you can specify it in the output parameter mapping. In this example, you can use %F.xdp for the output parameter mapping.

• Watched Folder may process input files before they are completely copied to the folder. File locking is not mandatory on UNIX as it is on Windows. For this reason, when a file is being copied to a watched folder, Watched Folder may move the file to stage without waiting for the file copy to complete. This behavior causes only a portion of the input file to be processed. There are currently two workarounds:

  • Workaround 1

    1. Specify a pattern for Exclude File Pattern, such as temp*.ps.

    2. Copy files that begin with temp (for example, temp1.ps) to the watched folder.

    3. After the file has been completely copied to the watched folder, rename the file to correspond with the pattern specified for Include File Pattern. Watched Folder then moves the completed file to stage.

  • Workaround 2

    If you know the maximum length of time it will take to copy your files to a watched folder, specify the time in seconds for Wait Time. Watched Folder then waits the specified length of time before moving the file to stage.

    This is not an issue for files on Windows because Windows locks a file when one thread is writing. However, this is an issue for folders on Windows. For folders, you must follow the steps in Workaround 1.

• If the Preserve Folder Name endpoint attribute for Watched Folder is set to a null directory path, the staging directory is not cleaned out as it should be. The directory still contains the processed file and temporary folder.

For all services, you should adjust the batch size and repeat interval of the watched folder so that the rate at which Watched Folder picks up new files and folders for processing does not exceed the rate of the jobs that can be processed by the AEM forms server. The actual parameters to use may vary depending on how many watched folders are configured, which services are using watched folders, and how intensive the jobs are on the processor.

Flex Client Authentication Method:

Determines the type of response that the server sends back to the client when the invoked service is security enabled, the operation invoked does not support anonymous invocations, and the client passes in either no or invalid credentials.