3 Installing Workbench

This chapter describes how to install Workbench.

Before you install Workbench, you must ensure that your environment includes the software and hardware required to run it. (See 2 Before You Install .)

LiveCycle processes can be upgraded to AEM Forms applications using the Upgrade Wizard. See Upgrading legacy artifacts documentation in Workbench Help for more information.

You can optionally add the Workbench feature to Eclipse. You can add Workbench after you have installed Workbench. For example, for JBoss the following location contains the file:

• Workbench_DVD/additional/eclipse

  Download and install Eclipse 3.6 from www.eclipse.org/downloads/.

To use Workbench, you must have an instance of AEM Forms running, typically on a separate computer. You must have a user name and password to log in to AEM Forms , as well as details about the location of the server.

By default, Workbench times out after two hours, regardless of activity or inactivity. To edit the time-out setting, see “Configuring User Management > Configure advanced system attributes” in the administration console Help.

To connect Workbench to a AEM Forms server over HTTPS, you must ensure that the certificate authority (CA) that issued the public key will be recognized as being trusted by Workbench. If the certificate is not recognized as coming from a trusted source, you must update the cacert file located in the [Workbench_HOME]/workbench/jre/lib/security directory.

Ensure that you connect to HTTPS by using the name that is specified in the certificate. This name is typically the fully qualified host name.

The following aspects of cache operation should be considered if your application generates unique templates on the fly by automatically updating XFA content. In effect, each transaction uses a new, unique template.

When forms generator or output searches for, or updates, entries in the cache for a specific form template, it uses several key values to locate the specific cache entry that will be accessed.

• Template file name : The location and filename of the template used as the primary unique identifier of the cached form.

• Timestamp : The template file contains a timestamp used to determine the last update time of the form.

• Template UUID : Designer inserts in each template a unique identifier (UUID) for the form and its version. Each time the form is updated, the embedded UUID is updated. For example, an XDP template might show the following content:

  <?xml version="1.0" encoding="UTF-8"?>

  <?xfa generator="AdobeAEM formsDesignerES_V8.2"

  APIVersion="2.6.7185.0"?><xdp:xdp xmlns:xdp=http://ns.adobe.com/xdp/

  timeStamp="2008-07-29T21:22:12Z"

  uuid="823e538f-ff6c-4961-b759-f7626978a223"><template xmlns="http://www.xfa.org/schema/xfa- template/2.6/">

• Render options : Within the rendered form cache, the cache contents are stored separately for each set of unique render options.

The Forms service receives templates by reference to filename or repository location, or by value as a XML object in memory.

• Templates passed by reference : Uses the content root and the form name. If unique templates with different filenames are passed in every request using this method, the disk cache will grow endlessly and will never be reused. To prevent this, unique templates should be passed with same filename to ensure that same cache is updated for all requests.

• Templates passed by value : Uses template bytes passed along with the data using theinDataDoc parameter. If unique templates with different UUID are passed using this method, the disk cache will grow endlessly and will never be reused. To prevent this, the UUID attribute should be stripped from all templates to ensure that no cache is created for the template. Alternatively, passing the same non-null UUID allows the cache objects to be created, but ensures that the same cache is updated with each request.

As well, in order to prevent the cache from growing endlessly, consider the following factors for rendering dynamically generated templates using the new AEM Forms APIs, those being renderHTMLForm2 and renderPDFForm2 .

When using the new APIs, the template is passed as a document object, which is handled in the Forms service based on whether it is passivated or not:

For passivated documents in which the UUID and content root serve as the cache key, consider the following aspects:

• The cache is not created for passivated input templates with no UUID.

• If more than one passivated input template having the same UUID and content root are passed, then the same cache is overwritten.

For non-passivated documents in which the filename and content root serve as the cache key, consider the following aspect:

• For non-passivated input templates, caching depends on the content root and filename from which the document was generated. The same cache will be used only for requests with the same content root and template filename.

  The following best practices will ensure that the cache does not grow endlessly when dynamically generated templates are passed to the Forms service:

  • Strip the UUID or pass the same UUID in all dynamically generated templates.

  • Generate the document either from template bytes or from the same filename on disk.

Use the Add or Remove Programs function in the Control Panel to start the Uninstaller. The Workbench and Designer applications have separate uninstall programs.