Maintaining AEM forms

Overview
User Management
Log files
Running AEM forms in maintenance mode
Monitoring AEM forms deployments
- Monitoring using MBeans
Work Manager and throttling

Overview

User Management allows administrators to maintain a database for all users and groups that are synchronized with one or more third-party user directories. User Management provides authentication and authorization for your activated AEM forms modules. For more information, see User Management .

In addition, to keep your AEM forms system running optimally, you should perform these maintenance tasks:

Weekly:

Check for stalled processes. (See Working with stalled operations and branches .)
Check log files for errors. (See Log files .)

Monthly:

Check peak CPU usage.
Verify that database backups are occurring regularly. (See AEM forms Backup and Recovery .)
Check that disk space limits are adequate.
Apply any outstanding AEM forms and OS patches.

User Management

User Management allows you to enable single sign-on (SSO) between AEM forms modules and Netegrity SiteMinder-protected applications by using Security Assertion Markup Language (SAML). When SSO is implemented, the AEM forms user login pages are not required and are not displayed if the user is already authenticated through the company portal.

For information about improving the database and directory sync performance for DB2, see IBM DB2 database: Running commands for regular maintenance .

Configuring User Management for an SSL-enabled LDAP server

If you have an SSL-enabled LDAP server, configure User Management to work with it. (See Configure User Management for an SSL-enabled LDAP server .)

Setting user privileges for use with Document Security

Create an administrator user who has the appropriate privileges for creating users and groups. If your AEM forms environment includes Document Security, grant the privilege to manage invited and local users to a user who will be the administrator for these users. Also assign the administration console User role to provide the user with access to administration console. (See Creating and configuring roles .)

To view users and groups in selected domains during policy user searches, a super administrator or policy set administrator must select and add domains (created in User Management) to the visible user and group list for each policy set created.

The visible user and group list is visible to the policy set coordinator and is used to restrict which domains the end user can browse when choosing users or groups to add to policies. If this task is not performed, the policy set coordinator will not find any users or groups to add to the policy. There can be more than one policy set coordinator for any given policy set.

Note: Creating domains must be done before any policies can be created.

Set visible users and groups

After you install and configure your AEM forms environment with Document Security, set up all appropriate domains in User Management.

In administration console, click Services > Document Security> Policies and then click Policy Sets tab.
Select Global Policy Set and then click Visible Users And Groups tab.
Click Add Domain(s) and add existing domains as required.
Navigate to Services > document security > Configuration > My Policies and click Visible Users And Groups tab.
Click Add Domain(s) and add existing domains as required.

Administrator user restrictions

Users with certain types of administrator privileges cannot access the Workspace end-user web pages for security reasons. Because these web pages can exist outside a firewall, permitting administration-level tasks could pose a security risk. Only users who have the Workspace Administrator or Workspace User privileges can access the end-user web pages.

Note: The Flex Worksapce is deprecated for AEM forms release.

Log files

Events such as run-time or startup errors are recorded to the application server log files. If you have any problems deploying to the application server, you can use the log files to help you find the problem. You can open the log files using any text editor.

(JBoss) The following log files are located in the [appserver root] /server/ [server] /log directory:

boot.log
server.log. [yyyy-mm-dd]
server.log

(WebLogic) Domain log files are located in the [appserverdomain] directory, and server log files are located in the [appserverdomain]/servers/[appserver name]/logs directory:

access.log
[appserver name] .log
[appserver name] .out. [incremental number]

(WebSphere) The following log files are located in the [appserver root] /profiles/default/logs/ [appserver name] directory:

SystemErr.log
SystemOut.log
StartServer.log

Running AEM forms in maintenance mode

Maintenance mode is useful when performing tasks such as patching a DSC, upgrading AEM forms, or applying a service pack.

Avoid invoking any processes while the server is in maintenance mode. This is what happens if a process is invoked while the server is in maintenance mode:

If the process is long-lived, it is added to the job database, but is not started. When you exit maintenance mode, AEM forms processes the long-lived jobs in its queue, even if the server was restarted while in maintenance mode.
If the process is short-lived, it is processed right away.

Put AEM forms in maintenance mode

In a web browser, enter:

http:// [hostname] : [port] /dsc/servlet/DSCStartupServlet?maintenanceMode=pause&user= [administrator username] &password= [password]

A "now paused" message is displayed in the browser window.

Note: If you shut down the server while it is maintenance mode, it will still be in maintenance mode when it is restarted. You must turn off maintenance mode when you are finished your maintenance tasks.

Check whether AEM forms is running in maintenance mode

In a web browser, enter:

http:// [hostname]:[port] /dsc/servlet/DSCStartupServlet?maintenanceMode=isPaused&user= [administrator username] &password= [password]

The status is displayed in the browser window. A status of "true" indicates that the server is running in maintenance mode, and "false" indicates that the server is not in maintenance mode.

Turn off maintenance mode

In a web browser, enter:

http:// [hostname]:[port] /dsc/servlet/DSCStartupServlet?maintenanceMode=resume&user= [administrator username] &password= [password]

A "now running" message is displayed in the browser window.

Monitoring AEM forms deployments

You can monitor AEM forms deployments from both a system level and an internal level. You can use specialist management tools such as HP OpenView, IBM Tivoli, and CA UniCenter and a third-party JMX monitor called JConsole to specifically monitor Java activity. Implementation of a monitoring strategy improves availability, reliability, and performance of your AEM forms deployments.

For more information about monitoring AEM forms deployments, see A technical guide for monitoring AEM forms deployments .

Monitoring using MBeans

AEM forms provides two registered MBeans that provide navigation and statistic information. These are the only MBeans that are supported for integration and inspection:

ServiceStatistic: This MBean provides information about Service name and its version.
OperationStatistic: This MBean provides the statistic of every forms server’s service. This is where administrators can get information about a particular service such as invocation time, number of errors, and so on.

ServiceStatisticMbean public interfaces

These public interfaces of ServiceStatistic MBean can be accessed for testing purposes:

public String getServiceId();  
public int getMajorVersion();  
public int getMinorVersion();

OperationStatisticMbean public interfaces

These public interfaces of OperationStatistic MBean can be accessed for testing purposes:

// InvocationCount: The number of times the method is invoked.  
public long getInvocationCount();  
// InvocationStartTime: The time at which the method started to execute.  
public long getInvocationStartTime();  
// InvocationEndTime: The time at which the method finished execution.  
public long getInvocationEndTime();  
// InvocationTime: The time taken for the execution of the method.  
public long getInvocationTime();  
// LastSamplingDateTime: Convert InvocationStartTime to a formatted string  
public String getLastSamplingDateTime();  
// MaxInvocationTime: The maximum time taken for the execution of the method.  
public long getMaxInvocationTime();  
// MinInvocationTime: The minimum time taken for the execution of the method.  
public long getMinInvocationTime();  
// AverageInvocationTime: the averege execution time taken for the execution of the method.  
public double getAverageInvocationTime();  
// ExceptionCount: The number of times the method has thrown an Exception.  
public long getExceptionCount();  
// ExceptionMessage: The message of the last exception occurred.  
public String getExeptionMessage();  
public void setExceptionMessage(String errorMessage);

MBean Tree & Operation Statistics

Using a JMX console (JConsole), statistics from OperationStatistic MBean are available. These statistics are MBean's attributes, and can be navigated under the following hierarchy tree:

MBean tree

Adobe Domain Name:: Depends on Application Server. If the Application Server does not define the domain, the default is adobe.com.
ServiceType:: AdobeService is the name used to list all services.
AdobeServiceName:: Service Name, or Service ID.
Version:: Version of the service.

Operation Statistics

Invocation Time:: Time taken for the execution of the method. This does not include the time the request is serialized, transferred from client to server, and deserialized.
Invocation count:: The number of times the service is invoked.
Average invocation time:: Average time of all invocations that have executed since the server was started.
Max invocation time:: The duration of the longest invocation that has executed since the server was started.
Min invocation time:: The duration of the shortest invocation that has executed since the server was started.
Exception Count:: Number of invocations that have resulted in failures.
Exception Message:: The error message of the last exception that occurred.
Last Sampling Date Time:: The date of the last invocation.
Time Unit:: Default is millisecond.
To enable JMX monitoring, the application servers typically need some configuration. See your application server documentation for the specifics.

Examples of how to set up open JMX access

JBoss 4.0.3/4.2.0 - configure the JVM startup

To view MBeans from JConsole, configure the JBoss application server’s JVM startup parameters. Ensure JBoss is started from the run.bat/sh file.

Edit the run.bat file that is located under InstallJBoss/bin.

Find the JAVA_OPTS line and add the following:

-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9088 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false

WebLogic 9.2 /10 - configure the JVM startup

Edit the startWebLogic.bat file that is located under [WebLogic home] /user_projects/domains/Adobe_Live_Cycle/bin.

Find the JAVA_OPTS line and add the following:

-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9088 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false

Restart WebLogic.

Note: For WebLogic, you can access the MBean using either remote or IIOP.

Access the MBean remotely

Launch JConsole for new connection and click remote tab.
Enter the hostname and port (9088, the number you specify during the start up options of JVM).

Websphere 6.1 - configure JVM startup

On the admin console (Application server > server1 > Process Definition > JVM), add the following line into the field for Generic JVM Argument:
```
-Djavax.management.builder.initial= -Dcom.sun.management.jmxremote 
```

Add or uncomment the following three lines in the /opt/IBM/WebSphere/AppServer/java/jre/lib/management/management.properties file (or <Your Websphere JRE>/ lib/management/management.properties):

com.sun.management.jmxremote.port=9999 //any port you like, but make sure you use this port when you connect  
com.sun.management.jmxremote.authenticate=false  
com.sun.management.jmxremote.ssl=false

Restart WebSphere.

Work Manager and throttling

AEM forms (and earlier versions) used JMS queues to execute operations asynchronously. In AEM forms, JMS queues have been replaced by Work Manager. This document provides background information on Work Manager, and provides instructions on configuring Work Manager throttling options.

About long-lived (asynchronous) operations

In AEM forms, operations performed by services can be either short-lived (synchronous) or long-lived (asynchronous). Short-lived operations complete synchronously on the same thread from which they were invoked. These operations wait for a response before continuing.

Long-lived operations may span systems or even extend beyond the organization, such as when a client must complete and submit a loan application form as part of a larger solution that integrates multiple automated and human tasks. Such operations must continue while awaiting a response. Long-lived operations perform their underlying work asynchronously, permitting resources to be otherwise engaged while awaiting completion. Unlike a short-lived operation, Work Manager does not consider a long-lived operation complete once it is invoked. An external trigger, such as a system requesting another operation on the same service or a user submitting a form, must occur to complete the operation.

About Work Manager

AEM forms (and earlier versions) used JMS queues to execute operations asynchronously. AEM forms uses Work Manager to schedule and execute asynchronous operations via managed threads.

Asynchronous operations are handled in this manner:

Work Manager receives a work item for execution.
Work Manager stores the work item in a database table and assigns a unique identifier to the work item. The database record contains all of the information required to execute the work item.
Work Manager threads pull in work items when the threads become free. Before pulling in the work items, threads can check whether the required services are started, whether there is enough heap size to pull in the next work item, and whether there are enough CPU cycles to process the work item. Work Manager also evaluates attributes of the work item (such as its priority) when scheduling its execution.

AEM forms administrators can use Health Monitor to check Work Manager statistics, such as the number of work items in the queue and their statuses. You can also use Health Monitor to pause, resume, retry, or delete work items. (See View statistics related to Work Manager .)

Configuring Work Manager throttling options

You can configure throttling for Work Manager, so that work items are scheduled only when there are enough memory resources available. You configure throttling by setting the following JVM options in your application server.

Property	Description
adobe.work-manager.queue-refill-interval	Specifies the time interval, in milliseconds, that Work Manager uses when checking for new items in its queue. The value for this option is an integer. The default value is `1000` milliseconds (1 second). If the volume of asynchronous invocations is low, you can increase this value. For example, you could increase it to somewhere between 2000 and 5000 (2 to 5 seconds). If the volume of asynchronous invocations is high, the default value should be sufficient, but you can use a lower value if necessary. Decreasing this value too much (for example, below 50, which results in a poll frequency of 20 times per second) causes a substantial overhead on the system.
adobe.workmanager.debug-mode-enabled	Set this option to `true` to enable debug mode, or to false to disable it. In debug mode, messages regarding Work Manager policy violations and Work Manager pause/resume actions are logged. Set this option to true only when troubleshooting.
adobe.workmanager.memory-control.enabled	Set this option to `true` to enable throttling based on the memory-control settings described below, or to `false` to disable throttling.
adobe.workmanager.memory-control.high-limit	Specifies the maximum percentage of memory that can be in use before Work Manager throttles incoming jobs. The default value for this option is `95` . This value should be fine for most systems. Increase it only if your system needs to push through to its maximum capacity. But note that as you increase this value, the risk of Out of Memory issues also increases. If you are running AEM forms in a clustered environment, you may want to set the memory control limit settings differently on different nodes of the cluster. For example, you could have a lower high-limit on nodes A and B, which are programmed in your load balancer for interactive work. And you could have higher high-limits set on nodes C and D, which are not used by the load balancer, but reserved for asynchronous work.
adobe.workmanager.memory-control.low-limit	Specifies the maximum percentage of memory that can be in use before Work Manager stops throttling incoming jobs. The default value for this option is `20` . This value should be fine for most systems.
Dadobe.workmanager.allocate.max-batch-size	Specifies the maximum batch size for workmanager. The default batch size is 10. If the status of a process in the workmanager is not updated even after the task is complete, then set the batch size to 1.

Add Java options to JBoss

Stop the JBoss application server.
Open the [appserver root] /bin/run.bat (Windows) or run.sh (Linux or UNIX) in an editor and add any of the Java options as required, in the format -Dproperty=value .
Restart the server.

Add Java options to WebLogic

Start the WebLogic Administration Console by typing http:// [host name] : [port] /console in a web browser.
Type the user name and password that you created for the WebLogic Server domain and click Log Under Change Center, click Lock & Edit.
Under Domain Structure, click Environment > Servers and, in the right pane, click the managed server name.
On the next screen, click the Configuration tab > Server Start tab.
In the Arguments box, append the arguments you require to the end of the current content. For example, to disable Health Monitor, add:

-Dadobe.healthmonitor.enabled=false disables Health Monitor.
Click Save and then click Activate Changes.
Restart WebLogic managed server.

Add Java options to WebSphere

In the WebSphere Administrative Console navigation tree, click Servers > Server Types > WebSphere application servers.
In the right pane, click the server name.
Under Server Infrastructure, click Java and forms workflow > Process Definition.
Under Additional Properties, click Java Virtual Machine.
In the Generic JVM arguments box, type the arguments you require.
Click OK or Apply, and then click Save directly to the master configuration.