Troubleshooting Process Models
The Appian process modeler can capture business processes of nearly any complexity, which can make troubleshooting them challenging. This article provides guidance on how to resolve some of the most common issues, and help you get the information you need to deal with the rest.
- See the Monitoring view page for detailed reference information about monitoring the process activity on your system in Appian Designer.
- To learn more about how to interact with specific processes, see the Monitoring, Debugging, and Editing Processes page.
- For more details on the types of process errors that you could encounter, see the Process Errors reference page.
There are several things you need to know when troubleshooting your process models:
- Where to go to investigate process issues
- What types of issues you might see
- How to analyze the performance of your process models
Where to Look to Investigate Problems
If a process error occurs, here are the ways you can be notified about it:
- You expect something to happen, but it doesn't. For example, if a process is supposed to write data to a relational database, and you do not see that change, your first action should be to go to the Monitoring view in Appian Designer.
- If your environment is set up to send emails, you will get an e-mail saying there's a problem. The email will link you directly to that process instance's error in the Monitoring view.
- If you do not receive an email about a process error, chances are you are not in the security role designated to see those process alerts. Within the process model, verify that you are in one of the groups specified on the alerts tab.
- If you're currently monitoring a process in the modeler, and one of the activities is canceled by exception. Clicking on the affected node will open the Node Properties dialog with details about the error that occurred.
When designing your process models, it helps to make the activity names unique, which allows us to quickly find the error that our process generated
Once you have navigated to the instance's error, you’ll see something that looks like this:
This is the Process Errors dialog in the Monitoring view. From looking at the dialog, you can see several pieces of helpful information:
- Where the problem occurred - The Node column in grid shows you that the "Add User as Member" node did not run successfully.
- Why it occurred - The Error column displays the error message that describes what happened. In this case, the process initiator did not have the appropriate privileges to add members to a specific group. You can open the instance by clicking its name in the dialog to find out which group was being updated and make sure that the user has the right permissions to that object.
- When it occurred - The Occurred column displays the date and time when the error occurred.
Now that we know a little bit more about error messages, let take a look at how to resolve some more common issues.
While there are a number of reasons for problems in your processes, some of the more common issues appear below:
Symptom: My Process Was Supposed to Do X, but That Never Happened
When Appian attempts to execute the expressions within an activity or smart service all of that node's expressions must evaluate without error. Whenever this happens, check to alerts to ensure that no errors occurred while evaluating any expressions. Some of the things that might cause expression errors include:
- One of the expressions used in the activity listed has an undefined parameter.
text(pv!date) would be missing the second parameter.
- One of the values being passed into a function is null and that function does not accept null values.
- One of the values being passed into an expression is the wrong data type.
- Ensure that all required parameters are configured when using functions or rules.
- Ensure that all variables have the expected values prior to this activity.
- If it’s not a guarantee that a value will always be present, use the
if() function to conditionally handle null values.
- Ensure that the expression is using the appropriate data types.
- Ensure that the parameters passed into the correct inputs by using keywords.
Symptom: User X Was Able to Do Something, but User Y Was Not
Every activity is evaluated in the context of a user, including unattended nodes. If an activity is started by a user that does not have the appropriate permission, that node will throw an error. Some of the things that might cause this include:
- The initiator of the process does not have the sufficient privileges at the object-level to perform the smart service operation.
- Example: A user has permission to start a process that creates a folder within a knowledge center, but does not have access to that knowledge center.
- The initiator of the process is a Basic User, but something in that process can only be done as an Administrator.
- Check the Security of the object or parent object referenced by the activity.
- For folders, the activity initiator needs at least editor rights to modify objects within that knowledge center or parent folder.
- For groups, the activity initiator needs to be in the Administrators role of that group.
- For user creation or modification, ensure that the activity initiator is a system administrator.
- Use the Modify Process Security Smart Service to give a user the appropriate permissions.
Symptom: After Submitting a Form, the Data Should Have Been Sent to a Database Table, but Was Not
Process models are often used to get data into relational database management systems. When this does not happen, the following causes may be the reason for this:
- There is a mismatch between the data type used to create the data store entity and the activity class trying to pass in data.
- A null value is trying to be passed into a table, but that particular column has null set to false.
- Auto-Increment is not set on the primary key column and a value has not been provided for that field.
- The activity class parameter configured in the Write to Data Store Entity smart service is the wrong data type.
- The value passed into one of the columns exceeds it’s max column length.
- Ensure you are capturing all of the necessary values prior to reaching the write to data store entity smart service.
- If you are not using provide the database table with a primary key value, ensure that auto-increment is set using the
@GeneratedValue JPA annotation within the CDT.
- Modify the data being passed into the format the database column needs. Alternatively, adjust the RDBMS column definition to support the data coming in.
- Use the
@Column JPA annotation with the length attribute to control the maximum number of characters a column can hold.
Problems That Do Not Show Up as an Alert
It's important to remember that alert will only show if the process or activity has a problem. However, problems can show up that do not throw these exceptions. If the process model does not do what you intend it to do, there’s a bug. Some of these more common issues appear below:
Symptom: Someone Should Be Seeing a Task, but They Are Not
Tasks can be assigned to a single user or a group of users. Problems with assignment can occur when:
- The logged in user is not the person or a member of the group that's assigned the task.
- The user input task has been configured as a quick task. Quick tasks appear as related actions on process-backed records.
- The assignment of the task is being handled through process data, which is not getting the correct values.
- Make sure the user who needs to see the task is assigned the task.
- If the task is assigned to a group, make sure the user is a member of that group.
- On the General tab of the User Input Task, uncheck the Quick Task checkbox to make those tasks appear on the task tab of Tempo.
- If the task is assigned via a process variable, ensure that variable has the correct value set before the user input task.
Symptom: When Someone Tries to Open a Task They Get an Error Message
When dealing with activities that depend on an interface for its form, problems can be created between that connection. Typically, these occur when:
- The Form is mapped to a value that does not exist.
- There is an error within the interface that is preventing it from rendering.
- Verify that all rule inputs map to an existing parameter or value.
- Within the form interface, ensure that there are no expression errors with test data present.
- Check the value of your process variables and/or activity class parameter. If a null value is not allowed to be passed into the interface, ensure that there’s a value present.
Symptom: A Gateway Did Not Send a Process to the Correct Outflow
Gateways take process data and determine the best workflow to continue down. When a gateway does not send a workflow to the appropriate outflow, generally the problem occurs because:
- The value being evaluated in the conditions is not properly captured.
- The gateway results are misconfigured.
- The condition has been misconfigured.
- For XOR and Complex Outflows configured as XORs, the order of the conditional checks are incorrect.
- Review process history to ensure the value you intend to compare is set.
- Ensure that your Result is going to the correct outflow.
- Ensure that each expression you’re evaluating triggers a value of
true with the appropriate value.
- Within XOR conditions, for values that could be true for multiple conditions, ensure the order of the conditions is correct.
Symptom: An Activity in a Subprocess is not Getting the Parent’s Value(s)
When dealing with process-to-process messaging through subprocesses, it's important to remember setup is required in both the parent and child process model. Ensure that:
- The child subprocess process variables are not set as parameters.
- The subprocess activity in the parent model's input data mapping is not configured properly.
- In the child process model, ensure that all of the process variables that need data from the parent process are configured as parameters.
- In the parent model, within the subprocess activity, check the input variables section to ensure all parent/child data mapping is correct.
Symptom: A Write to a Data Store Entity is Inserting a New Row of Data instead of Updating an Existing One
The Write to Data Store Entity and Write to Multiple Data Store Entity smart services are able to perform both inserts and updates to a data store entity. However, if that activity is not updating, it's generally because:
- The process variable that is being written to the relational database management system, does not have a value set for the primary key.
- Ensure that whatever method is used to select the record (ex. Related action on an entity-backed record, dropdown field on a form, etc.) is supplying the process with the primary key as well.
- If this update is occurring in the same process model as a previous insert activity, ensure that you are capturing the result of the insert activity back into the CDT process variable.
Symptom: Changes to a Process Model, Is Not Showing up When Running It
This problem is always scary when it's seen, but easily correctable:
- The process model has not been published since the changes were made.
- Someone else has published a newer version of the model.
- Publish the process model.
- Check that your process model version is the most recent.
Related Actions show up as a result of security and visibility settings. If a related action is not showing up, it might be because:
- The process model security is not correctly set.
- Related action visibility is not configured properly.
- The process model has a Tempo-enabled form start form configured.
- The related action started does not have a start form, nor is it chained to the first attended node.
- Ensure the user that needs to see the related action has at least initiator right to the process model.
- Ensure that the group evaluated within the related actions visibility expression has the logged in user as a member.
- If this process model was created before 17.1, ensure that a legacy forms designer form is not being used as a start form. If it is, replace it with an equivalent interface.
Symptom: A Process Model Needs to Show in a Site, but does not Appear While Configuring It
- There is no Start Form associated with that process model.
- Actions can only be used in a site if the process model has a start form. This is because the form will show up when an action page is selected. Modify your process model to include a start form.
Analyzing Process Model Performance
You can evaluate the design performance of your process model by displaying a historical execution report that is overlaid on the process model.
When editing a process model, it is often useful to view metrics on past performance of each node in the process model. Similarly, when making run-time changes to an active process, it can also be useful to view useful metrics about the performance of the process and the underlying process model as a whole. These metrics can often serve as barometers when it comes to identifying bottlenecks in a process model and can be used to fine tune a process model for optimal performance.
Editing Process Optimization Reports
Two reports are used to generate metrics that can be displayed in the process modeler.
- Default Process Model Optimization Metrics
- Default Process Optimization Metrics
These reports can be found in the Objects View by searching for them by name.
Default Process Model Optimization Metrics
- Select this report. The Select a Process Model dialog is displayed, which lists the process model folders, that you can view.
- Select a process model.
- Click OK. All columns configured for this report can be displayed as metrics within the process modeler. By default, this report includes three columns of data:
- Avg Lag
- Avg Completion
Default Process Optimization Metrics
- Select this report. The Select a Process dialog is displayed, which lists the processes that have been started in the system that you can view.
- Click OK. All columns configured for this report, along with the columns configured for the Default Process Model Optimization Metrics report, can be viewed as metrics within the process modeler. By default, this report displays three columns of data:
- Actual Lag
- Actual Completion
To configure either of these reports, click the Edit toolbar button. The Report Options dialog is displayed. From here, existing data can be edited and new columns can be added. Once changes have been made to the report, save the report to apply your changes.
See also: Editing a Report.
Only system administrators can save the report template. Saving a report template results in the change being applied system-wide.
The data displayed within the report is grouped by the Node Name. Therefore, if two activities have the same name the same data is displayed for both objects. See also: Process Metrics
Viewing Lag and Completion Times in the Process Modeler
To view metrics in the process modeler:
- Open a process model.
- Click the View Metrics button on the toolbar. — or —
- Select View > Show Node Metrics.
When viewing a process model, all columns configured through the Default Process Model Optimization Metrics report appear as a metric for each node in the process model. When editing a running process, all columns configured for both the Default Process Model Optimization Metrics and the Default Process Optimization Metrics reports are displayed as metrics for each node in the process. A maximum of 20 metrics can be displayed for a node on the designer canvas. If more than 20 columns are configured, only the first 20 columns appear in the modeler.
All columns configured in the report are displayed in the same order in which they appear in the report. Each column of data is aggregated. If no data is available for a particular metric,
n/a appears next to the metric for the given node. All formatting applied to the data in the report is preserved when it is displayed as metric in the process modeler.