Managing Endpoints

Types of endpoints

Before a service can be used, you must configure and enable an endpoint. An endpoint specifies how a service is to be invoked.

Note: In Workbench, endpoints are called start points.

The following types of endpoints can be added to services. Not all services support all endpoints:

Email:
Enables a user to invoke a service by sending an email message with one or more file attachments to a specified email account. Before you configure an email endpoint, you must configure the required email accounts. (See Configuring email endpoints .)

Watched Folder:
Enables a user to invoke a service by placing a file in a folder, which is scanned at a defined interval. (See Configuring watched folder endpoints .)

TaskManager:
Enables a Workspace user to invoke the service.

Remoting:
Enables an application built with Flex to invoke the service using (Deprecated for AEM forms) AEM forms Remoting. A remoting endpoint is automatically created for each activated service. A Flex destination that has the same name as the endpoint is created, and Flex clients can create remote objects that point to this destination to invoke operations on the relevant service.

SOAP:
Enables a client application developed using the AEM forms programming APIs to invoke the service using SOAP mode. A SOAP endpoint is automatically created for each activated service.
Note: Security can be removed from document security documents when the SOAP endpoint is used while viewing the documents in Adobe Acrobat or Adobe Reader. For details on how to disable SOAP enpoints on your LCRM documents, see Disable SOAP endpoints for Document Security documents

EJB:
Enables a client application developed using the AEM forms programming APIs to invoke the service using Enterprise JavaBeans (EJB) mode. An EJB endpoint is automatically created for each activated service.

WSDL:
Enables a client application developed using the AEM forms programming APIs to invoke the service using Web Service Definition Language (WSDL). The Core Configurations page contains an option to enable WSDL generation for all services that are part of AEM forms. (See Configure general AEM forms settings .)

REST:
Processes created in Workbench can be configured so that you can invoke them through Representational State Transfer (REST) requests. REST requests are sent from HTML pages. That is, you can invoke a AEM forms process directly from a web page using a REST request.

The Email, TaskManager, Watched Folder, and Remoting endpoints expose only a specific operation of the service. Adding these endpoints requires a second configuration step to select a method to invoke the service, setting configuration parameters, and specifying input and output parameter mappings.

Adding, enabling, modifying, or removing endpoints

Add an endpoint to a service

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

Note: It is recommended that you use unique names when adding endpoints.
  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.

Enable or disable an endpoint

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.

Modify an endpoint

Note: The changes you make to an endpoint configuration using administration console are not reflected in the design-time copies of your applications. If you redeploy an application, any change that you made to its endpoints using administration console will be lost.
  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.

Remove an endpoint

  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.

Configuring email endpoints

Email endpoints enable users to invoke a service by sending one or more documents (as email attachments) to a specified email account. The email inbox acts as a collecting point for the attachments. The service monitors the inbox and processes the attachments. The results of the conversion are forwarded to the user defined in the endpoint.

For an email endpoint, authorized users can invoke a process by emailing files to the appropriate account. The results will be returned to the submitting user (by default) or to the user defined in the endpoint settings.

Before you configure an email endpoint, create a POP3 or IMAP email account for use by the endpoint. Set up a separate account for each type of conversion. For example, one account can be configured to generate standard PDF documents from incoming file attachments, and another account can be configured to generate secure PDF documents.

Important: Each email address must map to only one email endpoint. You cannot configure multiple email endpoints to a single email address, even if the additional email endpoints are disabled.

All email endpoints are configured with an authorized user name and password for the email inbox, which are required when invoking the service. The email account is protected by the mail server system on which it is configured.

If your users send documents with Western European language characters in file and conversion path names, they must use an email application that supports the required encoding types (Latin1 [ISO-8859-1], Western European [Windows], or UTF-8). For more information, see the Installing and Deploying AEM forms document for your application server.

Before you configure an email endpoint, configure the Email service. (See Configure default email endpoint settings .) The Email service’s configuration parameters have two purposes:

  • To configure attributes that are common for all email endpoints

  • To provide default values for all the email endpoints

Configure SSL for an email endpoint

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.

Configure default email endpoint settings

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 .

Change the default values for email endpoints

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

  2. On the Service Management page, click Email: 1.0 (the Component ID is com.adobe.idp.dsc.provider.service.email.Email).

  3. On the Configuration tab, specify the default email endpoint settings and then click Save.

Default email endpoint settings

Cron Expression:
The cron expression as used by quartz to schedule the polling of the input directory.

Repeat Interval:
The number of times the directory polling is repeated. The default repeat interval is in seconds if this value is not specified in the endpoint configuration. The default value is 10. This value cannot be less than 10.

Repeat Count:
The number of times the input directory is polled. The default repeat count to use if this value is not specified in the endpoint configuration. A value of -1 indicates indefinite scanning of the directory. The default value is -1 .

Delay when job starts:
The default value, in seconds, for the delay before the job starts to scan the endpoint. The default value is 0 .

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 .

Asynchronous:
Identifies the invocation type as asynchronous or synchronous. Transient and synchronous processes can only be invoked synchronously. The default value is asynchronous .

Domain Pattern:
The domain name pattern that is used to filter incoming emails. For example, if adobe.com is used, only email from adobe.com will be processed; email from other domains is ignored.

File Pattern:
The incoming file attachment patterns that the provider accepts. This includes files that have specific extensions (*.dat, *.xml), specific names (data), and composite expressions in the name and extension (*.[dD][aA][Tt]). The default value is *.* .

Successful Job’s Recipients:
One or more email addresses that are used to send emails to indicate successful jobs. By default, a successful job message is always sent to the sender of the initial job. Up to 100 recipients are supported. To turn off this setting, leave this field blank.

Failed Job’s Recipients:
One or more email addresses that are used to send emails to indicate failed jobs. By default, a failed job message is always sent to the sender who sent the initial job. Up to 100 recipients are supported. To turn off this setting, leave this field blank.

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

Inbox Port:
The inbox port number for the email provider to scan. If the value is 0 , the default IMAP or POP3 port will be used.

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

Inbox Time Out:
Specifies the amount of time the endpoint will wait before canceling when attempting to connect to the inbox. If a connection is not acquired before the time-out value is reached, the inbox will not be polled.

Inbox User:
The user name required to log in to the email account. Depending on the email server and configuration, this name may only be 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:
When selected, enables SSL.

SMTP Host:
The host name of the mail server that the email provider uses to send results and error messages. For example, mail.corp.example.com .

SMTP Port:
The port that is used to connect to the mail server. The default value is 25 .

SMTP User:
The user account for the email provider to use when it sends email for 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:
When selected, enables SSL over SMTP.

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.

Character Set Encoding:
The encoding format to use for the email message. The default is UTF-8, which most users outside Japan will use. Users in a Japanese environment may choose ISO2022-JP.

Failed Email Sent Folder:
Specifies a directory in which to store results if the SMTP mail server is not operational.

Email endpoint settings

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).

Create an Email endpoint for the Complete Task service

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.

Configuring watched folder endpoints

An administrator can configure a network folder, known as a watched folder , so that when a user places a file (such as a PDF file) in the watched folder, a configured service operation is invoked and manipulates the file. After the service performs the specified operation, it saves the modified file in a specified output folder.

Configuring the Watched Folder service

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 .

Creating a watched folder

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.

Chaining together watched folders

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).

How users interact with watched folders

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.

Important: Ensure that the application server has deleted access to the files in the watched folder. If AEM forms cannot delete the files from the input folder after they are scanned, the associated process will be invoked indefinitely.

Watched folder output

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.

How Watched Folder works

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.

How Watched Folder processes an invocation request

The Watched Folder service handles the creation, update, and deletion of the endpoints. After the administrator creates the endpoints, they are scheduled to be triggered by the Scheduler service based on the specified repeat interval or cron expression.

This diagram illustrates how Watched Folder processes an invocation request.

The process of invoking a service using watched folders is as follows:

  1. A client application places files or folders in the watched folder input folder.

  2. When the job scan interval occurs, the Scheduler service invokes the provider.file_scan_service to process the files or folders in the input folder.

  3. The provider.file_scan_service performs these tasks:

    • Scans the input folder for files or folders that match the include file pattern and excludes files or folders for the specified exclude file pattern. The oldest files or folders are picked up first. Files and folders that are older than the wait time are also picked up. In one scan, the number of files or folders that are processed are based on the batch size. For information about file patterns, see About file patterns . For information about setting the batch size, see Watched Folder service settings .

    • Picks up the files or folders for processing. If the files or folders are not completely downloaded, they are picked up in the next scan. To make sure that folders are completely downloaded, administrators should create a folder with a name by using the exclude file pattern. After the folder has all the files, it must be renamed to the pattern specified in the include file pattern. This step ensures that the folder has all the necessary files needed for invoking the service. For more information about ensuring that folders are completely downloaded, see Tips and tricks for watched folders .

    • Moves the files or folders to the stage folder after selecting them for processing.

    • Converts the files or folders in the stage folder to the appropriate input based on the endpoint input parameter mappings. For examples of input parameter mappings, see Tips and tricks for watched folders .

  4. The target service configured for the endpoint is invoked either synchronously or asynchronously. The target service is invoked using the user name and password configured for the endpoint.

    • Synchronous invocation calls the target service directly and immediately handles the response.

    • For asynchronous invocation, the target service is called through the Job Manager service, which places the request in a queue. The Job Manager Service, in turn, calls the provider.file_write_results_service to handle the results.

  5. The provider.file_write_results_service handles the response or failure of the target service invocation. When successful, the output is saved to the result folder based on the endpoint configuration. The provider.file_write_results_service also preserves the source if the endpoint is configured to preserve the results upon successful completion.

    When the invocation of the target service results in a failure, the provider.file_write_results_service logs the reason for the failure in a failure.log file and places that file in the failure folder. The failure folder is created based on the configuration parameters specified for the endpoint. When the administrator sets the Preserve On Failure option for the endpoint configuration, the provider.file_write_results_service also copies the source files into the failure folder. For information about recovering files from the failure folder, see Failure points and recovery .

Watched folder endpoint settings

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.

About file patterns

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 .

About throttling

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.

Note: Throttling does not scale with a cluster. When throttling is enabled, the cluster as a whole will not process more than the number of jobs specified in the Batch Size at any given time. This limit is cluster-wide, and not specific to each node in the cluster. For example, with a Batch Size of 2, the throttling limit could be reached with a single node processing two jobs, and no other nodes would poll the input directory until one of the jobs is completed.

How throttling works

Watched Folder scans the input folder at each Repeat Interval, picks up the number of files specified in the Batch Size, and invokes the target service for each of these files. For example, if the Batch Size is four, at each scan, Watched Folder will pick up four files, create four invocation requests, and invoke the target service. Before these requests are completed, if Watched Folder is invoked, it will again start four jobs regardless of whether the previous four jobs are completed.

Throttling prevents Watched Folder from invoking new jobs when the previous jobs are not completed. Watched Folder will detect jobs in progress and process new jobs based on the batch size minus jobs in progress. For example, in the second invocation, if the number of jobs completed is only three and one job is still in progress, Watched Folder invokes only three more jobs.

  • Watched Folder relies on the number of files present in the stage folder to find out how many jobs are in progress. If files remain unprocessed in the stage folder, Watched Folder will not invoke any more jobs. For example, if the batch size is four and three jobs are stalled, Watched Folder will invoke only one job in subsequent invocations. There are multiple scenarios that can cause files to remain unprocessed in the stage folder. When jobs are stalled, the administrator can terminate the process on the forms workflow administration page so that Watched Folder moves the files out of the stage folder.

  • If the forms server goes down before Watched Folder can invoke the jobs, the administrator can move the files out of the stage folder. For information, see Failure points and recovery .

  • If the forms server is running but Watched Folder is not running when the Job Manager service calls back, which occurs when services do not start in the ordered sequence, the administrator can move the files out of the stage folder. For information, see Failure points and recovery .

Performance and scalability

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.

Watched folders in a cluster

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.

Synchronous watched folder in a cluster

For synchronous invocations, the Quartz load balancer decides which node will get the polling event. The node that gets the polling event will perform all the tasks: scan the folder, invoke the target service, and handle the results.

For synchronous invocations, when one node fails, the Quartz scheduler sends new polling events to other nodes. Invocations that were started on the failed node will be lost. For more information about how to recover the files associated with the failed job, see Failure points and recovery .

Asynchronous watched folder in a cluster

For asynchronous invocations, the Quartz load balancer decides which node will get the polling event. The node that gets the polling event will scan the input folder and invoke the target service by placing the request in the Job Manager service queue. The Job Manager service load balancer, in turn, is responsible for deciding which node will process the invocation request. It is possible that even though node A created the invocation request, node B ends up processing the request. Or the node that started the invocation request may also end up processing the request.

For asynchronous invocations, when one node fails, the Quartz scheduler sends new polling events to other nodes. Invocation requests that were created on the failed node will be in the Job Manager service queue and will be sent to other nodes for processing. Files for which invocation requests are not created will remain in the stage folder. For more information about how to recover the files associated with the failed job, see Failure points and recovery .

Failure points and recovery

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.

Recovering unprocessed source files in the stage folder

When Watched Folder cannot process the source files in the stage folder, you can recover the unprocessed files.

  1. Restart the application server or node.

  2. (Optional) Stop Watched Folder from processing new input files. If you skip this step, it will be much harder to determine which files are unprocessed in the stage folder. To prevent Watched Folder from processing new input files, do one of the following tasks:

    • In Applications and Services, change the Include File Pattern parameter for the watched folder endpoint to something that will not match any of the new input files (for example, enter NOMATCH ).

    • Suspend the process that is creating new input files.

    Wait until AEM forms recovers and processes all of the files. The majority of the files should be recovered and any new input files processed correctly. The length of time you wait for Watched Folder to recover and process the files will depend on the length of the operation to invoke and the number of files to recover.

  3. Determine which files cannot be processed. If you waited an appropriate amount of time and completed the previous step, and there are still unprocessed files left in the stage folder, go to the next step.

    Note: You can look at the date and time stamp of the files in the stage directory. Depending on the number of files and normal processing time, you can determine which files are old enough to be considered stuck.
  4. Copy the unprocessed files from the stage directory to the input directory.

  5. If you prevented Watched Folder from processing new input files in step 2, change the Include File Pattern to its previous value or re-enable the process that you disabled.

Security considerations for watched folders

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.

Tips and tricks for watched folders

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.

Service-specific recommendations for watched folders

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.

Generate PDF service recommendations

  • The Generate PDF service can convert only one file at a time for these file types: Microsoft Word, Microsoft Excel, Microsoft PowerPoint, Microsoft Project, AutoCAD, Adobe Photoshop®, Adobe FrameMaker®, and Adobe PageMaker®. These are long running jobs; therefore, make sure you keep the batch size to a low setting. Also increase the repeat interval if there are more nodes in the cluster.

  • For PostScript (PS), Encapsulated PostScript (EPS), and image file types, the Generate PDF service can process several files in parallel. You should carefully tune the session bean pool size (which governs the number of conversions that will be done in parallel) depending on the capacity of your server and the number of nodes in the cluster. Then increase the batch size to a number that is equal to the session bean pool size for the file types you are trying to convert. The polling frequency should be dictated by the number of nodes in the cluster; however, because the Generate PDF service processes these kinds of jobs quite fast, you could configure the repeat interval to a low value such as 5 or 10.

  • Even though the Generate PDF service can convert only one OpenOffice file at a time, the conversion is quite fast. The above logic for PS, EPS, and image conversions also applies to OpenOffice conversions.

  • To enable uniform load distribution in the cluster, keep the batch size low and increase the repeat interval.

barcoded forms service recommendations

  • For best performance when processing barcoded forms (small files), enter 10 for Batch Size and 2 for Repeat Interval.

  • When many files are placed in the input folder, errors with hidden files called thumbs.db may occur. It is therefore recommended that you set the Include File Pattern for the include files to the same value specified for the input Variable (for example, *.tiff ). This prevents Watched Folder from processing the DB files.

  • A Batch Size value of 5 and Repeat Interval of 2 is normally sufficient because the Barcoded Forms service usually takes about .5 seconds to process one barcode.

  • Watched Folder does not wait for the Process Engine to finish the job before it picks up new files or folders. It keeps scanning the watched folder and invoking the target service. This behavior can overload the engine, causing resourcing issues and time-outs. Ensure that you use repeat interval and batch size to throttle the Watched Folder input. You can increase the repeat interval and reduce the batch size if more watched folders exist or enable throttling on the endpoint. For information about throttling, see About throttling .

  • Watched Folder impersonates the user specified in the user name and domain name. Watched Folder invokes the service as this user if invoked directly or if the process is short-lived. For a long-lived process, the process is invoked with the System context. Administrators can set operating system policies for Watched Folder to determine which user to allow or deny access to.

  • Use file patterns to organize result, failure, and preserve folders. (See About file patterns .)

  • Watched Folder relies on the Quartz scheduler for scanning the watched folders. The Quartz scheduler has a thread pool to scan them. If the repeat interval for the watched folder is very low (< 5 seconds) and the batch size is high (> 2), a race condition can occur. When this condition occurs, one file is picked up by two Quartz threads:

    • One of the threads successfully finds the file and invokes the target service with the file.

    • The second thread sees the file but fails when it tries to find out if the file is valid (read or write file), which causes false failures that indicate that the file cannot be processed because it is read-only. This happens only with a low repeat interval and a high batch size.

Configuring Task Manager endpoints

Task Manager endpoints enable Workspace users to invoke the service.

Task Manager endpoint settings

Use the following settings to configure a Task Manager endpoint.

Name:
(Mandatory) Identifies the endpoint. The name is displayed in the card view in Workspace. 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.

Task Instructions:
Instructions for the user who starts this workflow.

Process Owner:
The name of the person who is responsible for the process.

User Can Forward Task:
Allows the user to forward the initial task.

Show Attachment Window:
Allows the user to see the attachment window.

Allow Attachment Adding:
Allows the user to add attachments and notes.

Task Initially Locked:
Locks the initial task.

Add ACLs for Shared Queues:
The initial task is created with ACLs for shared queue users.

Categorization:
(Mandatory) The category in which the user will see the form in Workspace. Select a category from the list, or select New Category to add a category.

Operation Name:
(Mandatory) A list of operations that can be assigned to the endpoint.

Configuring Remoting endpoints

A remoting endpoint enables an application built with Flex to invoke the service using (Deprecated for AEM forms) AEM forms Remoting. A remoting endpoint is automatically created for each activated service. A Flex destination that has the same name as the endpoint is created, and Flex clients can create remote objects that point to this destination to invoke operations on the relevant service.

Remoting endpoint settings

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.

// Ethnio survey code removed