Integrating with CA Workflow › How to Configure CA Workflow Approval and Fulfillment › Frequently Asked Questions

Frequently Asked Questions

Question:

How do I change the text of emails sent from CA Workflow?

Answer:

The text of the emails sent during the approval and fulfillment phase of a request's life cycle are set in the associated CA Workflow process definition. The first step is to determine which process definition is sending the email whose text you want to change.

To change the text of an email sent from CA Workflow

1. Start the Workflow Process Definition Tool (IDE) by clicking the Administration Quick Start, CA Workflow link.
2. The CA Workflow IDE appears.
3. Click the Process Manager tab, Process Definitions menu icon.

   The list of process definitions appears.

4. Double-click the process definition that is sending the email whose text you want to change.
5. Identify the activity node sending the email. These are typically named something like “Email User” or “Email Approver”.
6. Double-click the activity node sending the email.

   The Activity screen appears.

7. Click on the Workitem tab. The emails sent from CA Workflow use the CA Service Catalog Request web service sendRequestEmail operation.
8. Scroll down the list of Input Parameters until you see the entries for emailSubject and emailMessage.
9. To change the text of the email subject or email message, click the Value Expression field for the corresponding parameter.
10. You can either change the text in place or click the ellipsis “…” button that appears in the Value Expression column. Clicking the button displays the Expression Builder window which can make it easier to edit the text used.
11. Save and test the process definition.

Considerations for message text and CA Workflow

The Value Expression field must contain a valid XPath expression.

You can use HTML in the email message text to format the email.

A common cause of problems in CA Workflow process definitions is syntactical errors in XPath expressions. If your process instance is suspended, view the process instance history by double-clicking the process instance and selecting the History tab. The Event column shows the details of the execution of each node in the process instance. If there is an error in an XPath expression, you will see an Exception in the Event column that will help you identify the node in error. This exception may not be associated with the node in error but the Event column will reference the label of the node in error.

For example, the following message may appear on a Start or Timer node, but the Event text shows that the error occurred on the node labeled Email User:

Exception: Error parsing expression: concat(“x”,”y”,z) at node Activity: Email User

Question:

How can I tune CA Workflow?

Answer:

Several settings can be used to tune CA Workflow's ability to handle larger workloads.

First, ensure that the server where CA Workflow is running meets the specifications in the Release Notes. If you adjust the configuration settings mentioned here, the Workflow-related processes may use more memory.

After making any of the changes recommended below, restart the Service Fulfillment service.

Workflow Server

Using the Process Definition Tool (IDE), Server Configuration screen you can adjust the following settings.

• EnginePools (default 50) is the number of Process Manager engines available to handle process instance activity. The number of process instances that can be executing concurrently is determined by the number of process engines available within the Process Manager server.
• Note: The number of instances that exist in the CA Workflow server is not limited by this number, since an instance gives up its engine from time to time during its execution.
• Raising this number may help with throughput and reduce errors in starting process instances, but it may also consume large amounts of memory because each engine holds a process definition. When increasing EnginePools, you should also increase the Tomcat connection pool.
• MaxWorkItems (default 2500) is the number of workitems per process instance that are kept in memory before being stored in the database. This setting generally needs to be increased only if using very large process definitions or those that include a very large number of iterations.
• TimeOut (default 3000) is the number of milliseconds (default 3 seconds) that the Process Manager waits for an engine to become available before failing requests for work to be done (related to the number of engines specified in EnginePools). A Worklist user will receive a “Process Engine Busy” message and may just repeat the attempted action. An API caller will receive a “Process Exception”, and should be able to handle this exception and retry the action, if appropriate.
• WebServiceTimeout (default 600) is the number of seconds (default 10 minutes) a web service activity in a process instance will wait for a response from the called server before declaring an actor fault. Reducing this timeout may cause service requests to fail that would otherwise succeed. Increasing the timeout slows the responsiveness of the server to web service failures.

Workflow Process Definition Tool (IDE)

The IDE can be started either from the Start menu on the server where the Service Fulfillment server is running or from the CA Workflow link on the CA Service Catalog GUI.

Using a text editor such as Notepad you can adjust the following setting in the ide.bat file in the USM_HOME\fulfillment\CA Workflow\Client folder to raise the amount of memory allocated to the Java virtual machine used by the IDE. The ide.bat file is used when the IDE is started from the Start menu on the Workflow server.

• set VMARGS=-Dsun.java2d.noddraw=true -Xmx###m
• Where ### is the number of bytes of memory allocated.

Using a text editor such as Notepad you can adjust the following setting in the wfide.xsl file in the USM_HOME\view\webapps\usm\explorer\workflow folder to raise the amount of memory allocated to the Java virtual machine used by the IDE. The wfide.xsl file is used when the IDE is started from the CA Workflow link in the CA Service Catalog GUI and uses Java Web Start.

• <j2se version="1.4" java-vm-args="-Xmx###m"/>
• Where ### is the number of bytes of memory allocated.

Extract the ide.jsp file from the usm_idews.war file in the USM_HOME\fulfillment\CA Workflow\Client folder. Using a text editor such as Notepad you can adjust the following setting in the ide.jsp file to raise the amount of memory allocated to the Java virtual machine used by the IDE. Update the ide.jsp file in the usm_idews.war file. The ide.jnlp file is used when the IDE is launched from a URL and uses Java Web Start.

• <j2se version="1.4" java-vm-args="-Xmx###m"/>
• Where ### is the number of bytes of memory allocated.

Application Server Context Database Connection Pool

The number of database connections available to CA Workflow is set in the pm.xml and wl.xml files located in the USM_HOME\fulfillment\webapps folder. These files configure the Process Manager and Worklist contexts and can be edited using a text editor such as Notepad.

• maxIdle (default 30) is the number of connections that will be in the pool even if none are being used. Pre-allocate a larger number if you expect to hit the server with many simultaneous process instances immediately upon start-up.
• maxActive (default 100) is the maximum number of connections that will be obtained before errors result. Set maxActive to provide at least two database connections for each engine in the EnginePools setting.

Application Server Tuning for Tomcat

The Tomcat servlet container offers several settings that can be adjusted to maximize throughput of CA Workflow. High values use more memory.

The settings in the server.xml file in the USM_HOME\fulfillment\conf folder control how many incoming requests for service Tomcat can handle. A request for service in CA Workflow terminology means a web service request coming from the outside world or from CA Workflow itself. Once acceptCount is exceeded, then the requester gets a “Connection refused” error returned.

• minProcessors=5 is the minimum number of threads Tomcat keeps available for use in processing incoming requests for service
• maxProcessors=75 is the maximum number of threads Tomcat will make available for use in processing incoming requests for service
• acceptCount=100 is the number of unprocessed incoming requests that will remain queued before Tomcat starts rejecting requests for service

The settings in the FulfillmentService.conf file in the USM_HOME\fulfillment\conf folder control how much memory is allocated to the Java virtual machine associated with the Service Fulfillment service (CA Workflow process manager).

• wrapper.java.initmemory=128 is the amount of memory in megabytes initially made available to the Java heap
• wrapper.java.maxmemory=512 is the maximum amount of memory in megabytes allocated to the Java heap

Note: For Windows the maximum amount of memory able to be allocated to a Java virtual machine is about 1 GB regardless of the amount of memory on the server.

To determine the maximum heap size that can be allocated for Windows

1. From a DOS window, run the following command:

   java -Xmx1000m
   

2. Keep raising the numeric value until an error occurs like this:

   java -Xmx2000m
   Error occurred during initialization of VM
   Could not reserve enough space for object heap
   Could not create the Java virtual machine
   

Note: Specify a value less than the amount of RAM in your system, so that the operating system and non-Java applications will have enough memory to run. If you do not, the system will use its disk-based swap space, and therefore overall performance will degrade, often severely. Some sources recommend allocating 80% of a machine's RAM to the Java heap, but this assumes almost complete dedication of the machine to the use of the Java virtual machine.

For more information on tuning, see Sun's Java Tuning White Paper on the Sun web site, sun.com.

For comprehensive Tomcat tuning options, see the Tomcat web site, tomcat.apache.org.

Question:

How do I debug my Workflow process definitions?

Answer:

There are several sources of information when debugging CA Workflow process definitions, as indicated in the following text.

Process instance list

The list of process instances is displayed in the Workflow IDE, Process Instance menu option. The IDE is accessed by clicking the CA Workflow link from the Administration Quick Start menu.

You can display the process instances based on their start date and the name of the process definition on which they are based. Click the Refresh Definitions List double arrow icon to refresh the drop-down list of process definition names. Click the Run Query green icon to refresh the list of running process instances based on the selection criteria.

The process instance list shows the current status of each process instance: Running, Suspended, Terminated or Completed.

Running or Completed are typically normal status values. Suspended usually indicates a problem and Terminated may or may not indicate a problem depending of the behavior expected. For example, if a request is deleted, all associated process instances will be terminated and therefore Terminated is an expected status in this case.

The process instance list also displays the values for any external attributes. For the process definitions provided with CA Service Catalog, there is usually an external attribute named RequestID to help determine which request is affected by the process instance. In addition, there are two error-related external attributes which can help diagnose a problem. These two attributes are named ErrorDesc and ErrorInfo.

Note: ErrorDesc and ErrorInfo may be populated, indicating there was an error at some point in the process instance. If the logic of the process definition determines that this error was not critical to the execution of the business process, the process definition may continue. For example, if sending an email to the user indicating an approval task was assigned fails because there is no email address for the user, the ErrorDesc and ErrorInfo fields will be populated but the process instance will not stop.

Process instance definition

For more details about a process instance, double-click its name in the process instance list. Doing so displays the Process Designer view of the process instance. Using this view you can:

• Examine the details about each node by double-clicking it.
• View the attribute values by clicking on the Attributes tab.
• View the history of the process instance by clicking on the History tab.

Process instance history

The process instance History tab shows each event for each executed node in the process instance. Depending on the type of node, you may see multiple history entries.

For example, for an activity node that assigns a task to a user, you may see history events such as the following:

• Workitem created
• Workitem dispatched
• WorkItem Info: Assigned to users:jmanager
• WorkItemInfo: Completed By:jmanager
• Workitem completed

The Event column of the History tab will show an exceptions encountered by the process instance. Depending on the exception handling logic of the node encountering an exception, the process instance may remove the problem workitem and continue on.

Errors in XPath expressions

A frequent cause of exceptions when developing and testing new or changed process definitions is an error in an XPath expression. These types of errors are also reported in the History tab but will not necessarily be associated with the node which uses the XPath expression in error. Instead, you may see the error associated with a Start or Timer node.

For example, the following message may appear on a Start or Timer node, but the Event text tells you that the error occurred on the node labeled Email User:

Exception: Error parsing expression: concat(“x”,”y”,z) at node Activity: Email User

Process instance attributes

The process instance Attributes tab shows all the attributes associated with the process definition and the current values for the process instance. Each attribute may have the property of Input, Output and/or External or none of these. The Input attributes are those passed to this process instance. The External attributes are those shown on the process instance list. The Output attributes are those available to be retrieved from a calling process instance.

Note: The values of the Input attributes may not reflect the value passed to the process instance because the logic of the process instance may have caused these values to change during execution.

CA Service Catalog Alerts

The process definitions provided with CA Service Catalog attempt to post a system alert when there is an error in a process instance.

For example, if the process instance tries to send an email to an approver but there is no email address for the approver, the process instance will continue, because this error is not a critical, however it will also post an alert.

Alerts will also be posted for critical errors. Viewing the alert may help you identify more details about the problem encountered in the process instance.

Alert messages can be viewed by using the Messages, Alerts menu option. Clicking the Show Summary icon displays detailed information about the alert.

Note: To post an alert, the process instance must be able to communicate with the CA Service Catalog web services.

If a rule action cannot start a process instance, an alert will be generated that uses the Type WFFAILED_ACTION. The Alerts screen enables you to show only these alerts for the filter specified by clicking List All Failed Actions. From the list of failed rule actions, you can attempt to start a failed rule action.

CA Service Catalog log files

If problems are encountered related to using CA Service Catalog web services, these messages will appear in the USM_HOME\logs\view.log file.

CA Workflow log files

Messages from Tomcat will appear in the USM_HOME\logs\fulfillment\FulfillmentService.log file. Check this file for messages related to Service Fulfillment service start-up and shut-down messages and Tomcat problems.

CA Workflow writes log files to the USM_HOME\logs\fulfillment folder. There are several types of log files produced. The file names in the following table will also be used for previous days' logs by including a date stamp in the file name.

Question:

How do I cause CA Workflow to recognize a change in the WSDL for a web service actor?

Answer:

Follow these steps:

1. From the CA Service Catalog home page, select Administration, Configuration, CA Workflow.
2. Update the required attributes.
3. Recycle Catalog Component.
4. Click Configure.

The CA Workflow actors are updated with the new WSDL URL.

Note: If the signature for a web service operation that you are using in your process definitions changes, examine the process definition nodes that use the web service operation and retest the process definitions.

Question:

Can I cause CA Workflow to replace a current actor or process definition?

Answer:

Yes, follow the same steps from the answer to the previous question.