Troubleshooting production issues for highly critical production applications is a frequent challenge for Low Code developers.
Here in this blog, we have attempted to compile an extensive guide for some useful tricks and best practices for troubleshooting process modeling.
Process errors
Process errors can be caused by a problem with the process properties that affect the entire process model, or by a problem within a single node. The most common issues are caused by insufficient privileges, invalid node or expression configuration, or a node evaluation timeout.
These errors will cause an email alert to be sent to specific users (such as your system administrator or process model administrators) informing them of the problem in your process. The email will include a link to the process instance’s error in the Monitor view, allowing you to see where the problem occurred, why it occurred, and when it occurred.
The Alerts tab of the process model properties allows you to specify who should be notified of process errors.
When a node triggers a process error, the process will pause and cannot continue until an administrator investigates the problem. Most problems will arise in your development environment and can be resolved by changing the configuration of your process model and restarting it.
There are, however, some errors that can occur in your production environment. In such cases, it may be necessary to modify the process while it is running and restart or resume any affected nodes. This allows the process to continue without having to restart it from the beginning.
More information on the various types of issues and possible solutions can be found in the section below.
Unexpected issues
There are times when there are no process errors but the process model still does not execute as expected. A process model, for example, may assign a specific user to a task, but the user is unaware of the new task. Perhaps a gateway did not route a workflow to the correct outflow.
When these problems occur, they are most likely the result of an incorrect configuration somewhere in your process. In the preceding examples, the problems could be caused by a missing process variable, the user not having permission to view the interface or incorrect data entry.
We’ve provided a list of possible issues you might encounter during development that do not trigger errors in the Unexpected issues that do not return process errors section below
Issues that return process errors
The section that follows discusses some common process errors and how to fix them. This is not an exhaustive list, but it does cover some of the most common errors.
Go to the Monitor view in your application and select Process Activity to quickly see all process errors that have occurred. You can view a list of all unresolved process errors here, as well as review resolved process issues.
When a process is completed or canceled, or when you manually start a process from a paused node and it succeeds, the error is resolved.
Insufficient object permissions
Each node is assessed in the context of a user. This means that if a node is started by a user who does not have the necessary permissions to perform a node’s action, the node will fail.
Assume a user has permission to initiate a process that creates a folder within a knowledge center but does not have access to that knowledge center. The process would fail on the node that creates the new folder in this case.
Resolution
Check that any objects referenced in your process model (such as a record type, group, or expression rule) have appropriate object security, including the process model itself.
To begin the process model, a user must have at least Initiator permissions. When a process is triggered by a timer or as a subprocess, it is executed as the user who put the process model into production. As a result, ensure that this user account has the necessary permissions on all objects referenced in the process model.
Examine the process model security to ensure that all appropriate users can begin and interact with the process, or use the Modify Process Security Smart Service to grant a user the necessary permissions through a process.
You should also go over the security role map for each object in your process to ensure users have the appropriate level of access. In the preceding example, this means that users must have at least Editor permissions to modify objects within a knowledge center.
Incorrect user type
In addition to object-level security, users must be the correct user type to complete certain tasks.
For example, if the process is initiated by a Basic User but uses the Remove Group Members smart service, which requires the user to be a System Administrator, the process will fail.
Resolution
Ensure that only System Administrators have access to processes that involve the creation, modification, or deletion of users.
Unable to write data
process models are frequently used to add new data to a database using the Write Records, Write to Data Store Entity, or Write to Multiple Data Store Entities smart services,
A write operation, however, may fail for the following reasons:
- Incorrect smart service configuration- The input in the smart service is misconfigured. For example, in the Write Records smart service, this would happen when the input is using an unsupported record type, or there is an error in the expression calling the process model.
- There is a mismatch between the source and the node input trying to pass in data.
- The node input is the wrong data type.
Database configurations that impact your process:
-
- A null value is passed, but the field is not nullable.
- Auto-increment is not set on the primary key column and a value has not been provided for that field.
- A value exceeds the field’s maximum length.
- Unavailable source- The record type or data store entity is unavailable.
If you are updating data that is used as the source of a record type and the smart service fails, the record data will be unavailable until the next successful full sync.
Resolution
To ensure your smart services successfully write to your database:
Review your smart service configuration:
- When using the Write Records smart service, ensure you are only referencing database-backed record types with data sync enabled.
- Make sure that you are capturing all of the necessary values before reaching the smart service.
- If you are a Write to Datastore Entity smart service, you must supply values for each field in your CDT; otherwise, a null value will be written to any blank fields.
- If needed, cast node input values to the proper data type using the cast() function.
Add validations to your start forms:
- Prevent users from supplying null values or values greater than the field’s maximum length by adding a custom validation on your interface.
Modify your database table or CDT:
- If you must pass null values, modify the affected column so null is set to true.
- If you are not providing the database table with a primary key value, ensure that auto-increment is set for the table in your database.
- Adjust the table column definition to support the type of incoming data.
Consider using the @Column JPA annotation with the length attribute in your CDTs when using the Write to Data Store Entity smart service to control the maximum number of characters a column can hold.
Expression evaluation errors
Process models, like other design objects in Appian, frequently make use of expressions. A processing error can occur if there is a runtime error where the expression is valid but there are invalid rule inputs or parameter values.
These errors can occur in any configuration of a process node or the process model properties, but they are most commonly found in a node’s input or output.
Expression evaluation errors are often caused by issues such as:
- Syntax errors like missing commas, parentheses, or operators, or invalid function or variable references.
- Casting errors when trying to cast from one data type to another.
- Calling functions that cannot be used in a process model, such as a! save(), custom field functions, or smart service functions.
Resolution
Each expression evaluation error will produce an error message containing information on how to resolve the error. Often, you can resolve the error by replicating it within an expression rule and determining which expression changes will fix it.
Required node inputs are missing or of the incorrect type
Some process nodes require a value or a specific type for certain inputs to function properly. The records node input of the Write Records smart service, for example, requires an input of type Record Type.
If no value or the incorrect type is provided, the node will pause and cannot continue until the issue is resolved.
Resolution
Examine the node to see if any inputs are required. Required inputs are always denoted by an asterisk (*). Also, look at the node’s input and make sure the value you provide matches it or can be cast to the correct type.
A node or expression references an object that does not exist
When the process tries to reference an object that does not exist, the process will pause. For example, if a script task refers to a deleted group earlier in the process, the process will pause.
This problem can be caused by a variety of Appian objects, including:
- Constants
- Connected systems
- Data store entities
- Documents
- Folders
- Groups
- Users
- Process models (called a subprocess)
- Record types
- Rules
Resolution
Make sure your expressions and configurations point to objects that exist. Also, before deleting an object, ensure that it does not have any dependencies.
A node with multiple node instances has zero nodes
Multiple node instances are a property that allows a node to be executed multiple times to achieve parallelization, such as sending tasks to multiple users at the same time. The property requires an additional configuration to determine how many times the node should be executed. The node will pause if the number of nodes to execute is 0 (possibly because an expression evaluates to 0).
Resolution
Always ensure that the number of nodes to execute is greater than or equal to one. To ensure that at least one node is executed, add a gateway before the node executes. If not, the gateway can be configured to bypass the node.
Unexpected issues that do not return process errors
The section that follows discusses some issues that you may encounter while developing your process and how to resolve them. The following issues will not produce a process error and are most likely the result of incorrect configuration somewhere in your process.
Unable to start the process model
You will be unable to start the process model if the required process information is missing or invalid. For example, if a required process variable is not given a value, or if an expression evaluation occurs in a required process configuration, the process cannot be started.
Resolution
Review all process information that is required, such as process properties, process variables, and default alerts.
Although this problem will not cause a process error, you will receive an error message with more information about the problem and specific resolution steps.
User cannot see their assigned task
A single user or a group of users can be assigned tasks. If a task is assigned to a user but that user is unable to see it, it could be because:
- 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 record types.
- The assignment of the task is being handled through process data, which is not getting the correct values.
Resolution
To ensure the assigned user can see their task:
If the task is assigned to a group, make sure the user is a member of that group.
Ensure the User Input Task is not configured as a quick task:
1. Open the User Input Task.
2. On the General tab, ensure the Quick Task checkbox is deselected.
3. If the task is assigned via a process variable, ensure that the variable has the correct value set before the user input task.
The user cannot open a task
If a user receives an error when attempting to open a task, it is most likely due to a problem with the interface or how the interface is linked to the task.
For example, the form could be mapped to an invalid value. Perhaps there is a bug in the interface that prevents it from rendering.
Resolution
To ensure users can open the task:
- 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 parameters. If a null value is not allowed to be passed into the interface, ensure that there’s a value present.
A gateway did not send a process to the correct outflow
Gateway nodes allow you to evaluate various criteria to determine which path your workflow should take. When a gateway fails to send a workflow to the expected outgoing path, the following could be the cause:
- A Condition value is not properly captured or is misconfigured.
- The gateway Results are misconfigured.
- For XOR and Complex gateways configured as XORs, the order of the conditional checks is incorrect.
Resolution
To ensure the gateway sends the process to the correct outgoing path:
- Review the process history to ensure the value you intend to compare is set.
- Ensure that your Result is going to the correct outgoing path.
- Ensure that each expression you’re evaluating triggers a value of truth with the appropriate value. It is often useful to test the condition independently using an expression rule.
- Within XOR conditions, make sure that there is no overlap in the outcomes of each condition. For example, you’d want to avoid two conditions pv! value > 5 and pv!value > 10 since a value of 15 would still cause the first condition to execute.
A gateway has not been completed but no errors have occurred
If a gateway node is incorrectly configured, the gateway may run out of paths to execute, causing the process to pause indefinitely.
This can occur for one of two reasons:
- When using an OR gateway, if none of the conditions evaluate to be true, then the node cannot execute any of the results.
- When using an OR or XOR gateway, if multiple paths enter the gateway, only the first path will execute the gateway. Any subsequent paths that enter the gateway will pause the node.
Resolution
To ensure that a gateway is completed successfully:
- When using an OR gateway, at least one condition must evaluate to true to ensure the node completes.
- When using an OR or XOR gateway, ensure that there is only one path that enters the gateway.
An activity in a subprocess is not getting the parent’s values
When working with subprocesses, both the parent process model and the subprocess must be configured.
If either of the following is true, your subprocess may not function properly:
- The subprocess’s process variables are not set as parameters.
- The subprocess activity in the parent model’s input data mapping is not configured properly.
Resolution
To ensure that a subprocess activity receives the parent’s values:
- In the subprocess 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/subprocess data mapping is correct.
Smart service is inserting a new row of data instead of updating an existing one
The smart services Write Records, Write to Data Store Entity, and Write to Multiple Datastore Entities can all create and update data in a database.
If, on the other hand, the smart service creates data when you expect it to update existing data, it’s most likely because the record or value being passed to the node does not have a value set for the primary key field.
Resolution
To ensure that you are updating existing data rather than creating a new row of data, follow these steps:
- Ensure that the process is supplied with the primary key value for the row of data you want to update.
- If the update is occurring in the same process model after the row is created:
- For Write Records, ensure that you are capturing the result of the Records Updated output parameter in the record process variable.
- For Write to Data Store Entity and Write to Multiple Datastore Entities, ensure that you are capturing the result of the insert activity in the CDT process variable from the Stored Values output.
Changes to the process model do not appear when running the process
If you’ve made changes to your process model but they’re not showing up when you start debugging or when an end user runs the process, it’s most likely because the process model hasn’t been published since the changes were made.
Someone else may have published a newer version of the process model than the one you’re using. Fortunately, both are easily remedied.
Resolution
To have your process changes appear when running the process; Publish the process model:
- In the process model, go to File > Save & Publish.
- Check that your process model version is the most recent. If not, refresh your process model and try running the process again.
Unable to display a process model in a site
When you configure your sites, you can include actions as a page type. This page type enables users to begin a process, such as submitting a new service request.
If you are unable to select a specific process model for your action, it is because that process model does not have a start form.
Resolution
Only if the process model has a start form can actions be used in a site. This is because the form will appear when an action page is selected. Modify your process model to include a start form, or select another process model.
A user does not see a start form upon starting an action
Typically, when beginning an action, a user will fill out the information on a form that is required for the process. If the start form does not appear, the input task is not properly configured could also be the reason.
Resolution
Examine the start form configuration in the Process start form tab of the Process Model Properties dialogue to ensure the form appears when the action is launched.
If you use a User Input Task, ensure that there is activity chaining from the start form to the user input task.
A process node is skipped
If you expect a node to execute but the process does not complete it, it is likely that the node is not properly connected or that the process model has not been published.
Resolution
Check that the node is connected. Notice that the script task does not have an arrow entering the node in the image below. This happens because the node is above the path but not connected to it.
Also, ensure that the process model is published. This ensures that the process runs with the most recent version, which should include any node updates.
To publish a process model- In the process model, go to File > Save & Publish.
A node doesn’t execute when the process flow reaches that step
When a process flow reaches a node, it will attempt to execute and should be green when active. However, there are a few reasons why the node might not start right away, such as being scheduled or failing to meet a starting condition.
Resolution
Examine whether the node has been scheduled for a future time. The node will not begin until that time is reached.
Remember that the time it is executed is determined by the time zone of the process model, which is usually inherited from the default time zone of the process model’s designer.
The process does not complete when it reaches an end node
To complete a process, all active flows must reach an end node. This means that if there are multiple active flows, even if only one of them reaches an end node, the process is still considered active.
Resolution
To begin, ensure that the process is set up so that all active flows reach an end node.
On your end node, you should also add a Terminate trigger. When this trigger is used, any node that reaches this end node completes the process, even if other flows are active.
It is recommended that most end nodes be set to terminate unless the process expects multiple active flows.
A process variable used in the output of a node is not updated correctly
A node’s outputs are used to capture changes from the node and store the results in process variables that can be used later in the process. If the inputs or outputs are incorrectly configured, the output may not save the correct data.
Resolution
When saving data into an output variable, ensure that the same variable is not being updated by the Save Into parameter on the input. When the node is finished, the inputs tab results are saved after the outputs tab results.
Check that the output expression returns the correct result if you have a custom output. Testing this expression in an expression rule outside of the process model is frequently beneficial.
Conclusion
Process modeling is indeed a great way to illustrate how value is produced, accumulated, and delivered within an organization. They are simple to read and have emerged as crucial resources for projects involving workflow system configuration, user education, and business process improvement. Successful process modeling adds value to the organization in a sustainable way.
We at Scadea make sure that our analytical and graphical representations are accurate, impartial, thorough, and accessible to everyone by using standardized techniques like Business Process Modeling Notation (BPMN), flowcharts, Gantt charts, data flow diagrams, and UML diagrams.
Every step of the way, our team of developers and consultants will be by your side to help you model your current processes, deconstruct them, and move them from the state they are in now to the state you want them to be. They identify inefficiencies, duplications, and inconsistencies and offer opportunities for automation and improvement.
