Troubleshoot Workflows
Note: Many workflow activities rely on authenticated CampusLink API calls and keys.
-
Prior to Anthology Student 22.0, authentication for API calls required entries in the SyRegistry tables and synchronized passwords and permissions for the API user and staff user. For more information, see API Errors with SyRegistry Authentication in Workflow help.
-
Anthology Student 22.0 introduces an alternate method for the authentication of CampusLink API calls. The new authentication method does not use the SyRegistry table. For more information, see Authentication for CampusLink API Calls in Workflow help.
Exception Handling
The user who creates workflows is responsible for catching exceptions. Any unexpected and uncaught exceptions will abort workflows. For the guidelines on exception handling within workflows, refer to Recommended Coding for Activity Errors in Workflow Help.
Workflow Definition Is Not Displayed
If you try to open the workflow definition for a sequence and a message similar to the following is displayed, the Forms Builder Contracts package has not been installed in Workflow Composer.
To correct this, launch Workflow Composer directly (not from Sequence Designer), select Package Manager, and install add the appropriate Forms Builder Contracts package for your environment (see Set Up the Database Environment).
Workflow Error Indication on Rendered Forms
When a server-side error occurs during the processing of a rendered sequence that cannot be corrected via form resubmission, an error message is displayed. The default message text is "Unable to process form. Please contact your administrator for assistance."
You can edit the message text on the Settings tile in Form Designer and save your custom message. You can use HTML markup to encode a URL or email address if desired.
|
By design, the error details will only be captured in the log files. You need to check the log files to troubleshoot the error. For more information, see Log Files. |
Common Workflow Errors
Always check the Error List tab in Workflow Composer to obtain more details about an error.
Always clear persisted workflows before enabling a new version of a workflow.
Common errors are spelling and syntax errors in argument and variable names, values, and expressions. Be mindful of case sensitivity.
|
|
Important Arguments that will be bound to values in Forms Builder are case sensitive. If they are not bound, they are not case sensitive. Variables should not be case sensitive. |
Many errors can be avoided by taking advantage of IntelliSense features. For example, type a period (.) or press Ctrl+J to obtain the valid members from a list. Press Space to select a list member.
Mismatch Between State and Form Names
When editing a workflow definition, keep in mind that a state in the state machine workflow equates to a form within the sequence. The name of a State must match the name of a Form to be rendered properly. If Renderer encounters a State in workflow definition that does not match name of any Form created in Form Designer, an error similar to the following will be generated.
When entering attributes for entities in workflow activities on objects that can be null, users often forget to select the ".Value" attribute. If an object might be null, HasValue in an If/Else Condition can check if there is a Value before trying to use it, otherwise it will cause an error. To clear the error, use IntelliSense to find the dot (.) Value.
Undeclared Variables and Incorrect Variable Types
Undeclared Variable
Incorrect Variable Type
Incorrect Notation for Variables
Array variables in the Property Settings pane of Form Designer use AngularJS notation with "square brackets" [].
Example
Array variables in Workflow Composer require VB.NET notation with "rounded brackets" ().
Example
If you use "rounded brackets" () in Form Designer, rendering of the sequence will fail, and the browser Developer Tools will show the following error:
SaveDocument Does Not Produce Expected Updates
Anthology Student allows administrators to specify document policies that define which users can assign, read, edit, and close particular kinds of documents. The policies also define which document status changes are permitted. The document policies are assigned to staff users.
Check your document policy settings for allowed document status changes if the workflow for a form sequence includes a SaveDocument activity but does not produce the expected document updates.
NullReferenceException in Log Files
Your workflow will abort if it throws exceptions (and could leave stale persisted instances). One very common exception is a NullReferenceException found in the log file. This occurs when you try to reference a property and its value on an object, but the object is null.
Example 1
myInt is defined as a Nullable<Int32> type.
Since you know you must access the value with a myInt.Value property, you log a line or use it in a workflow without checking whether it is actually null first. If myInt is null, myInt.Value will throw that exception and abort your workflow!
Example 2
myEntity is an entity you are using. It has many properties. If you reference any of those properties but myEntity has not been defined yet, again it will throw that exception. Likewise, if any of its properties are nullable and you try to use that property, Example 1 applies.
A NullReferenceException can also occur if you attempt to assign a value to an entity type object that has not yet had an associated GetEntity or CreateEntity activity.
Example 3
myObj is an object of some type. It has not been defined. You execute myObj.ToString or reference myObj.myProperty. Either will also throw that exception.
Remedy
-
Here is a cautious way to log myInt by using the VB.Net ternary operator.
If (myInt.HasValue, “This is my value “ & myInt.Value.ToString, “My value was null, and I did not expect that”)
If you are using other complex properties and you are assigning from a nullable type to a non-nullable type, you need to make sure it is checked.
In an assign statement
myNonNullableIntType = if (myInt.HasValue, myInt.Value, -1)
The value -1 could be any real integer that would signify that there was no actual value. Note that if this is an entity and that happened to be a child id, an invalid value could throw other exceptions when an attempt was made to store it in the database. In that case an “If” activity, which takes some other action (such as sending back a validation error), is more appropriate.
-
myEntity should be checked for null before using it by using an “If” activity, unless you know it cannot be null.
if (myEntity is Nothing)
-
myObj should be checked whether it is null when logging (unless you know it can’t be), and myProperty should also be checked if it is nullable.
if (myObj is Nothing, “myObj was null”, if (myObj.myProperty.HasValue, myObj.myProperty.Value.ToString, “myObj.myProperty was null”))
Error Converting Null Object When Using Drop-down List Component
When the Model property in a Drop-down List component is bound to an integer value and the selection of a value is optional, the following errors occur if the variable is not defined as Nullable<Int32> in Workflow Composer.
|
|
For more information, see Drop-down List component.
Validation Messages
In activities that provide a ValidationMessages field, you can specify the value formInstance.ValidationMessages. The in/out argument formInstance is available with every form. It provides a set of attributes including ValidationMessages.
You can also specify conditions such as formInstance.ValidationMessages.HasErrors or not formInstance.ValidationMessages.HasErrors and proceed as needed depending on the result of the expression.
Print an Array of Validation Messages
If you are trying to print validation messages from an array (validationMessages(0).item), the following error may appear in the log file:
Cmc.Nexus.FormsBuilder.Renderer.Web.Services.FormInstanceService System.NullReferenceException: Object reference not set to an instance of an object. at lambda_method(Closure , ActivityContext )
Before attempting to print an item in an array that may never have been initialized, ensure that the workflow contains the If/Then condition "validationMessages.HasErrors". Another way to define the condition is “If Not ArrayVariable is Nothing”.
Assign Ids
Some entities in the Anthology object model require an Id value in order to save the entity. If the Id is not entered on a form, the associated SaveEntity activity in the workflow will fail, unless the Id is assigned within the workflow.
Example
A form collects relationship address data for a student who logged into Portal. The workflow contains a SaveEntity activity for the StudentRelationshipAddressEntity. When the form sequence is rendered, the following error occurs: The student records you are trying to access are invalid.
To resolve this error, ensure the workflow assigns a StudentId and not just the new values for the new address before the SaveEntity<StudentRelationshipAddressEntity> activity. The Value field in the Assign activity could contain a variable (studentId) that is populated based on the LookupUser activity.
SQL Query to Determine the UserName for a Persisted Workflow
The Instance Id of a persisted workflow can be used to query the SQL database to determine which student each of the workflow instances applies to.
You can run the following SQL query to determine the UserName associated with the persisted workflow. Replace the highlighted section with the InstanceId from Workflow Composer.
SELECT ipp.Value2 as UserName
FROM [System.Activities.DurableInstancing].[InstancePromotedPropertiesTable] ipp
INNER JOIN [System.Activities.DurableInstancing].[InstancesTable] i ON ipp.SurrogateInstanceId = i.SurrogateInstanceId
WHERE i.Id = 'cc11c1c5-7a2d-45c2-ba1e-55f3bd273210'
If the user is a GUID, then the sequence was anonymous.
