The Appian process modeler can capture business processes of nearly any complexity, which can make debugging 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.
There’s two things you need to know when testing and debugging your process models: (1) where to go to investigate process issues and (2) what types of issues you might see.
By the end of this, you will have a better understanding of what features to use to test and debug your process models.
Where to Look to Investigate Problems
There are several environment interfaces available to different kinds of persona (i.e. User, Designer, and Administrator). Specific to resolving process issues, the Processes and Notifications interface is of particular importance.
You can access the process and notifications interface by navigating to /designer or selecting the Runtime Data on your user profile menu. When it comes to debugging your processes, the alerts link in this interface is one of the the most important places to look.
The alerts link will contain, among other type of notifications, information about problems with tasks and processes.
When designing your process models, it helps to make the activity names unique, which allows us to quickly find the alert that our process generated
You're not always going to be in the Processes and Notifications Interface. If an alert is generated, here are some of the more common ways you will be notified:
- If your environment is setup to send emails, you will get an e-mail saying there's a problem.
- If you're currently monitoring a process, and one the activities is cancelled by exception.
- 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're not seeing that change, goto to alerts tab first.
If you do not see a particular process in your alerts, 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.
Once you have clicked on an alert, you’ll see something that looks like this:
The description of this alert has most of the important information, but we can also see details about the problem, recommended actions, and priority as well as a link to the process details for this particular process.
Reading the description you can see three things that can help:
- Where the problem occurred - at the "Write Product Info to RDBMS" Activity
- What occurred - An error occurred while trying to convert the given data to the type of the specified entity "product" ...
- Why it occurred - The Activity Class Parameter "product" could not cast from Text to CSM_product.
Now that we know a little bit more about alerts, 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 interface inputs maps to a 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 Sub-Process is not Getting the Parent’s Value(s)
When dealing with process to process messaging through sub-processes, its important to remember setup is required in both the parent and child process model. Ensure that:
- The child sub-process process variables are not set as parameters.
- The sub-process 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 sub-process 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 primary key.
- Ensure that whatever method is used to select the record (ex. Related action on 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 SAIL form.
Symptom: A Process Model Need 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.