Configuring Forms

Overview

The Forms service enables you to create interactive data capture client applications that validate, process, transform, and deliver forms typically created in Designer. Form authors develop a single form design that the Forms service renders in various formats:

  • as PDF in Adobe Reader or in a browser

  • as HTML in various browser environments including a compliant XHTML 1.0 rendering

  • as form Guides in various browser environments that support Adobe Flash Player.

For additional information about the Forms service, see Services Reference .

Using the Forms page in administration console, you can configure the behavior of the Forms service. These settings apply to all invocations of the service. Any parameters sent through the AEM forms SDK override the settings set in administration console; however, they affect only that particular invocation.

After you change the Forms settings in administration console, click Save. You do not need to restart the server for the changes to take effect. However, you may need to stop and restart the Forms service when configuring cache mode settings. (See Starting and stopping services .)

Configuring form output

Specify the type of HTML output returned to the web browser

  1. In administration console, click Services > forms.

  2. Under Form Output, in the Output type list, select one of the following options:

    Full HTML: To render the form within full HTML tags (a complete HTML page). This value is the default.

    Form body: To render the form within <BODY> tags (not a complete HTML page).

  3. Click Save.

Specify the location where PDF content is rendered

  1. Under Form Output, in the Render at list, select one of the following options:

    Client: To render PDF forms within Adobe Acrobat or Adobe Reader. Client-side rendering improves the performance of AEM forms and applies only to PDFForm transformation.

    Server: To render PDF forms on the application server.

    Auto: To render the PDF form in the location specified by the dynamicRender configuration value of the XDP file. This value is the default.

  2. Click Save.

Configuring invocation of custom scripts before form submit

Perform the following steps to enable the feature:

  1. Login to the administration console.

  2. Go to Services > forms .

  3. Specify the Output type as Form Body .

  4. Save the settings.

  5. Declare a JavaScript variable, __CUSTOM_SCRIPTS_VERSION, in the head section of the HTML code and set its value to 1.
    Note: To disable the feature, you can remove the JavaScript variable or set its value to 0.

Configuring validation messages

For forms that are rendered as HTML, form validation errors that occur are displayed for the user. You can customize how validation messages are displayed. Depending on where the validation messages are displayed, you can also control the location of the message in the form and the size of the frame border.

Specify how validation messages are displayed

  1. In administration console, click Services > forms.

  2. Under Validation Output, in the Reporting list, select one of the following options:

    Message box: To display validation messages in a separate dialog box.

    Frame: To display validation messages within a frame of the same window.

    No Frame: To display validation messages in the same window. This value is the default.

    Via API (with data): To return the validation messages through the API (with data). The validation messages are not displayed on the screen.

    Via API (with form): To return the validation messages through the API (with the form). The validation messages are not displayed on the screen.

    None: To not display validation messages.

  3. Click Save.

Specify the location of validation messages relative to the form returned in the web browser

When Reporting is set to Frame or No Frame, you can specify the location of validation messages.

  1. Under Validation Output, in the Position list, select one of the following options:

    Left: To display validation messages on the left side of the web browser.

    Right: To display validation messages on the right side of the web browser.

    Top : To display validation messages at the top of the web browser. This value is the default.

    Bottom : To display validation messages at the bottom of the web browser.

  2. Click Save.

Specify the frame border size

When Reporting is set to Frame, you can specify the frame border size.

  1. Under Validation Output, in the Border Size box, type the size of the frame border, in pixels.

    The border size must be equal to or greater than 0. The default value is 1.

  2. Click Save.

Setting internationalization options

Specify the locale used to render forms

You can specify the locale used when rendering a PDF form. The fields on a PDF form use the specified locale to display data. For example, if the locale is set to German, the form uses German decimal separators for numeric values. The locale is also used to send validation messages to client devices, such as web browsers, as part of HTML transformations.

  1. In administration console, click Services > forms.

  2. Under Internationalization, in the Language list, select the locale used to render a form. The default value is English (United States).

  3. Click Save.

Specify the character set used to encode the output stream

  1. Under Internationalization, in the Character Set list, select a character set. This setting is dependent on the API used, either renderHTMLForm or renderPDFForm. To specify a character set other than those listed, select Custom and specify an encoding value in the box that is displayed.

    For HTML transformations, AEM forms supports character encoding values defined by the java.nio.charset package. To view a list of supported values, go to http://download.oracle.com/javase/6/docs/technotes/Guides/intl/encoding.doc.html .

    If sFormPreference is PDFForm, only specific character sets are supported.

    The character set must be a valid canonical name. The default value is ISO-8859-1.

  2. Click Save.

Configuring locations for Forms

You can specify the URL, URI, and file locations of attributes such as the web root, the location of the forms to be retrieved, the seed PDF file that is used in PDFForm transformations, and the cache location.

  1. In administration console, click Services > forms.

  2. Under Locations, specify the appropriate options. The options are described below.

  3. Click Save.

Locations settings

Base URL:
The base URL where form resources such as images and scripts are located. This value is required for HTML transformations that include HREF references to external dependencies, such as images or scripts. One such script is xfasubset.js, which is required for HTML forms to perform XFA intelligence. This value must be the HTTP equivalent of the content root URI.
Note: Base URL supports only HTTP or repository protocols. It does not support protocols such as file:///. If you need to access a resource such as a custom CSS or digital signature URI, use the appropriate API parameter value to specify the absolute location.

When a dependency path is absolute, the Base URL value is ignored. Otherwise, the dependency path is combined with the base URL.

The default value is an empty string.

The following example points to the same content (using Content Root URI and Base URL):

(ContentRootURI)/subdir/image1.jpg

(BaseURL)/subdir/image1.jpg

FS Web Root URI:
The URL of the Forms web application. You can leave this box empty if the Forms web application and the client application are deployed on the same application server; the Forms API web root URL will be used.

If the Forms web application and the client application are not deployed to the same application server, provide the URL for the Forms web application in this box, as shown in this example:

http://<host name>:<port>/FormServer

Where host name and port are the server name and port number of the server that is hosting the Forms web application.

The default value is an empty string.

Web Root URI:
The application’s web root. This value is combined with the sTargetURL parameter (when sTargetURL is provided as relative), specified through the AEM forms SDK, to construct an absolute URL to access application-specific web content.

The default value is an empty string.

Content Root URI:
The URI or absolute location that forms are retrieved from. This value is combined with the sFormQuery parameter, specified through the API, to construct the absolute path to the form that is retrieved. This value can reference a directory or a web location that is accessible using HTTP.

The default value is an empty string.

XCI Configuration URI:
The relative or absolute location in which the XCI file used for rendering is found. For a relative value, it is assumed that the XCI file resides in the deployable AEM forms EAR file.

The default value is com/adobe/formServer/PA/pa.xci .

Font Map URI:
The relative or absolute location of the font-mapping file. For a relative value, it is assumed that this file resides in the deployable AEM forms EAR file.

The font-mapping file is used to create custom font mappings for HTML transformations in forms, therefore allowing you to specify which font will be substituted when a font is not available on the client’s computer.

The default value is com/adobe/formServer/client-font-map.properties .

The following entry is an example of an entry in the font-mapping file:

Arial=Arial,Helvetica,sans-serif

Seed PDF File:
The initial PDF file that is used in a PDFForm transformation to optimize delivery. The seed PDF file specifies a customized PDF file (containing only XFA stream, image, and font resources) that is appended with the form design and data. The form is rendered by Acrobat 7 or later and applies to PDFForm transformation.

The default value is an empty string.

Cache Location:
Specifies the location of the Forms disk cache. When you change this setting, all existing cache information from the current location is reset and a new cache is created at the new location. Select one of the following options:
Default Location:
This is the default selection. When this option is selected, the cache is created at a location that is dependent on the application server you are using:

  • JBoss: [JBoss Home] \server\ [install type] \svcdata\FormServer\Cache

  • WebLogic: [WebLogic Home]\user_projects\domains\ [aem-forms Domain Name] \adobe\ [forms server name] \FormServer\Cache

  • WebSphere: [IBM Home] \WebSphere\AppServer\installedApps\adobe\server1\FormServer\Cache

LC Temp Directory:
The cache is created in a subdirectory of the AEM forms temp directory, which is specified in the administration console under Settings > Core System Settings > Configurations > Location of Temp Directory. The subdirectory is named adobeform_ [servername] .

Important: If you are using a temp cleaning utility, be aware that while deleting these directories does not affect functionality, it can significantly impact performance for a short time until the new cache is created. To avoid this issue, do not delete these directories while clearing the AEM forms temp directory.

Configuring caching for Forms

The Forms service takes form designs that were created in Designer and renders them in various formats.

The Forms page in administration console contains settings that control the way the Forms service caches items. You can adjust these settings to optimize the performance of the Forms service.

The Forms service caches the following items:

  • form designs: The Forms service caches form designs that it retrieves from the repository or from HTTP sources. This caching improves performance because for subsequent render requests, the Forms service retrieves the form design from the cache instead of from the repository.

  • fragments and images: The Forms service can cache fragments and images used in form designs. When the Forms service caches these objects, it improves performance because the fragments and images are only read from the repository on the first request.

  • forms: The Forms service caches the forms that it renders. This type of caching improves performance because the Forms service does not need to resolve and render the same form in subsequent requests.

Forms stores the cache in two locations:

  • in memory: Items are stored in memory for quick access. The in-memory cache has a limited size and is deleted when you restart the server.

  • on disk: Items are stored in the server’s file system. The disk cache has a larger capacity than the in-memory cache and it is retained when you restart the server. The location of the disk cache depends on your application server. For information on changing the location of the disk cache, see Configuring locations for Forms .

Specifying the cache mode

Forms supports two modes of caching:

  • unconditional

  • using the cache check point

If you switch between cache modes, restart the Forms service for the change to take effect. To restart this service, either use Workbench or see Start or stop the services associated with AEM forms modules for instructions.

The cache check point time is reset automatically when you switch between modes.

Using unconditional caching

In this mode, when the Forms service receives a request, it validates the resources (forms design and any related assets such as fragments and images) that are required. The Forms service compares the timestamp of the resources in the repository to the timestamp of the resources in the cache. If the resource in the cache is older, the Forms service updates it.

This cache mode guarantees that the most recent resources are used. However, performance is affected because the Forms service validates the cached items against the repository with each request. This cache mode is suitable for development and staging environments where resources are updated frequently and performance is not a primary concern.

Specify unconditional caching

  1. In administration console, click Services > forms.

  2. Under Forms Cache Control Settings, select Unconditionally and click Save.

Use the cache check point

In this mode, the Forms service only checks the repository for newer versions of resources when the timestamp of the cached resource is older than the cache check point time. The last cache check point time is displayed on the Forms page in Administration Console.

Use this cache mode in high-performance production environments where performance is a concern and changes to resources are infrequent. You can reset the cache check point time when you want to deploy any changes made to the repository resources.

Specify the use of a cache check point

  1. In Administration Console, click Services > forms.

  2. Under Forms Cache Control Settings, select Only If Their Last Validation Was Done Prior To Cache Check Point Time and click Save.

Reset the cache check point

  1. In administration console, click Services > forms.

  2. Under Forms Cache Control Settings, click Cache Check Point.

Reset the cache contents

You can clear the contents of the cache at any time. After a cache reset, the first request for each form is slower because the Forms service performs a complete rendering and creates new cache content.

  1. In administration console, click Services > forms.

  2. Under Forms Cache Control Settings, click Reset Cache.

Configuring cache settings

You can specify settings that Forms uses for caching, which can optimize the performance of your AEM forms environment.

To access these settings, in administration console, click Services > forms.

Note: Disk requirements for the cache should be equal to the repository.

Specifying global cache settings

The settings in the Global Cache Settings area affect all types of caches. If you change either of these settings, restart the Forms service for the change to take effect. To restart this service, either use Workbench or see Start or stop the services associated with AEM forms modules for instructions.

Max Cache Document Size (KB):
The maximum size, in kilobytes, of a form design or other resource that can be stored in any in-memory cache. This is a global setting that applies to all in-memory caches. If a resource is larger than this value, it is not cached in memory. The default value is 1024 kilobytes. This setting does not affect the disk cache.

Form Rendering Cache Enabled:
By default, this option is selected, which means that rendered forms are cached for subsequent retrieval. This setting improves performance because the Forms service only has to render a particular form once, and then it uses the cached version. This option works with the form design’s caching property. For information about configuring this value in the form design, see Designer Help .

Caching form designs

When the Forms service receives a render request, it retrieves the form design from the repository and caches it. This caching improves performance because for subsequent render requests, the Forms service retrieves the form design from the cache instead of from the repository.

The Forms service always caches form designs on disk. If form designs are stored on the server, those files are considered the disk cache. The Forms service also caches form designs in memory, according to the setting in the In Memory Template Cache area. If you change any of these settings, restart the Forms service for the change to take effect. To restart this service, either use Workbench or see Start or stop the services associated with AEM forms modules for instructions.

Template Configuration Cache Size:
The maximum number of template configuration objects to keep in memory. The default value is 100. It is recommended that you set this value greater than or equal to the Template Cache Size value. This setting does not affect the disk cache.

Template Cache Size:
The maximum number of template content objects to keep in memory. The default value is 100. This setting does not affect the disk cache.

Enabled:
By default, this check box is selected, meaning that form templates are cached in memory. When this option is not selected, form templates are cached only on disk.

Caching rendered forms

The Forms service caches rendered forms so that it does not need to resolve and render the same form in subsequent requests. Rendered forms are cached both on disk and in memory.

These settings are located in the In Memory Form Rendering Cache area. If you change either of these settings, restart the Forms service for the change to take effect. To restart this service, either use Workbench or see Start or stop the services associated with AEM forms modules for instructions.

Cache Size:
Specifies the maximum number of rendered forms that can reside in the in-memory cache. The default value is 100. This setting does not affect the disk cache.

Enabled:
By default, this option is selected, meaning that rendered forms are cached in memory. When this option is not selected, rendered forms are cached only on disk.

Caching fragments and images

The Forms service caches fragments and images use in form designs on disk. This improves performance because the fragments and images are only read from the repository on the first request. Then on subsequent requests, the Forms service reads fragments and images from the disk cache. Fragments and images are cached only on disk, and not in memory.

You can use the following settings to control the on-disk caching of fragments and images. These settings are located in the Template Resource Cache Settings area:

Resource Caching
Select one of the following options from the list:
Enabled for fragments and images:
The Forms service caches fragments and images. This is the default option.

Enabled for fragments:
The Forms service caches fragments, but not images.

Disabled:
The Forms service does not cache fragments or images.

Cleanup Interval (Seconds):
Specifies how often the Forms service removes old invalid cache files. The Forms service does not remove valid cache files. If you change the cleanup interval, restart the Forms service for the change to take effect. To restart this service, either use Workbench or see Start or stop the services associated with AEM forms modules for instructions. The default value is 600 seconds.

Clustering considerations for caches

In a clustered environment, each node maintains its own in-memory and disk cache. The cache contents on each node depends on which forms have been rendered on that node.

The location of the cache must be identical (same disk and path) on each node of the cluster. Do not place the cache on shared storage.

If you use the Forms page in administration console to change the cache settings for a particular node, the cache settings on other nodes are updated when a request goes to that node. This behavior also applies to the Reset Cache button. If you click the Reset Cache button for one node, the cache is immediately removed from that node. The cache on other nodes is cleared when a request goes to that node.

Specifying fonts to embed

You can specify which fonts are always embedded or never embedded with the forms that the Forms service generates. Embedding fonts increases the file size of the forms. Embed unusual fonts that users rarely have on their systems. Do not embed common fonts that they typically have installed.

Note: If you have specified a custom XCI file for Forms, the embed font option in the XCI file overrides these settings. (See Configuring locations for Forms .)

  1. In administration console, click Services > forms.

  2. Under Font Embedding Settings, in the Always Embed Fonts box, type the names of the fonts to embed with the forms, separated by commas. The fonts that you specify are only embedded in the generated form if they are used in the form. This setting is ignored if the embed font option has been turned on in the XCI file passed to the service because in that case, all fonts used in the PDF are always embedded.

  3. In the Never Embed Fonts box, type the names of the fonts not to embed with the forms, separated by commas. The fonts that you specify are not embedded in the PDF, even if they are used in the generated PDF. This setting is ignored if the embed font option has been turned off in the XCI file passed to the service because in that case, none of the fonts used in the PDF are embedded.

  4. Click Save.

Specifying XCI configuration options

Forms enables you to specify a custom XCI file that it will use for rendering. (See Configuring locations for Forms .) By default, Forms overrides some of the options specified in the XCI file, including the following:

  • config/present/xdp/packets

  • config/present/pdf/creator

  • config/present/pdf/producer

  • config/present/pdf/compression/compressObjectStream

You can select options that cancel the override for the options listed above, in which case Forms will use the values specified in the custom XCI file.

  1. In administration console, click Services > forms.

  2. Select or deselect the Use System Default XCI Options check box. When this option is selected, Forms uses its default values for the packets, creator, producer, and compressObjectStream settings. When this option is deselected, Forms uses the values specified in the custom XCI file.

  3. Click Save.

Specifying security settings

Forms enables you to control whether external entities in XML inputs are resolved. By default, they are resolved, but you can change this behavior to increase the security of your AEM forms system.

Prevent the processing of XML data files that contain references to external entities

  1. In administration console, click Services > forms.

  2. Clear the Resolve External Entities check box.

  3. Click Save.

// Ethnio survey code removed