Custom Workflows

A page detailing how to implement your own custom workflows into equate forms

A detail you might overlook when using Equate Forms is the ability to create custom workflows. You can achieve this by implementing the workflow interface provided by Equate Forms, known as IWorkflow

Below you can see the code for the IWorkflow interface:

using EquateForms.Core.Model;
using EquateForms.Core.Model.Workflows;
using EquateForms.Core.ViewModels;
using static EquateForms.Core.EquateFormsConstants;

namespace EquateForms.Core.Interfaces
{
    /// <summary>
    /// The main interface for custom workflows
    /// </summary>
    public interface IWorkflow
    {
        /// <summary>
        /// Executes a given workflow
        /// </summary>
        /// <param name="SubmissionInfo">The data used for the current submission</param>
        /// <param name="FieldValue">If a field is set within your workflow, the value of that field will be passed automatically</param>
        /// <returns></returns>
        public Task<WorkflowResponse> Execute(FormViewModel submissionInfo, String? fieldValue = null);
        /// <summary>
        /// Determines when to execute the workflow
        /// </summary>
        ExecuteWhen ExecuteWhen { get; }
        /// <summary>
        /// Determines the name of the workflow
        /// </summary>
        String Name { get; }
        /// <summary>
        /// Determines the description of the workflow
        /// </summary>
        String Description { get; }
        /// <summary>
        /// Determines the ID of the workflow
        /// </summary>
        String Id { get; }
        /// <summary>
        /// Determines the field inside a workflow
        /// For Example: if you have a workflow that sends an email, you need to specify a textbox field in 
        /// for the user to specify which email to send the mail too.
        /// </summary>
        WorkflowField? Field { get; }
    }
}

Creating your custom workflow

Lets start with creating a new class named ExampleWorkflow.cs that inherits the interface named IWorkflow.

Note: You can use any name for this workflow, but in this instance I've named mine "ExampleWorkflow".

See below for an example:

using EquateForms.Core.Interfaces;
using EquateForms.Core.Model.Submission;
using EquateForms.Core.Model.Workflows;

namespace EquateForms.Core.Workflows
{
    public class ExampleWorkflow : IWorkflow
    {
        public EquateFormsConstants.ExecuteWhen ExecuteWhen => throw new NotImplementedException();

        public string Name => throw new NotImplementedException();

        public string Description => throw new NotImplementedException();

        public string Id => throw new NotImplementedException();

        public WorkflowField? Field => throw new NotImplementedException();

        public Task<WorkflowResponse> Execute(FormResponse submissionInfo, string? fieldValue = null)
        {
            throw new NotImplementedException();
        }
    }
}

You can see that the interface requires a few parameters that you must specify for your workflow to behave correctly. Let me explain these in further detail:

• Execute When - Determines when the workflow should execute, below you can see the available options.

  • AfterFormSubmission - Executes your workflow after form submission

  • BeforeFormSubmission - Executes your workflow before form submission

• Name - The name of the workflow that will be displayed in the back office

• Description - Define a description for your workflow. if present, the description is displayed underneath the Name (In the back office).

• Id - For workflows to behave as intended a unique ID is required, I recommend using a GUID but any ID as long as it doesn't match any other Workflow IDs will work.

• Field - A WorkflowField object has a similar usage to the Field object in forms, although it only takes 3 of its original arguments, allowing you to specify any of the following parameters:

  • Label Text - The label of the input

  • Help Text- The help text of the input

  • Placeholder Text - The placeholder text of the input

Explain the WorkflowField parameter in further detail

The WorkflowField is designed to allow developers to retrieve specific information from the backoffice user during a workflow's execution. For example, if your workflow communicates with an API that requires a token, specifying a WorkflowField to capture that token is a recommended approach.

By doing this, the value entered in the field is passed to your workflow, allowing you to manage that data directly within the workflow method via the fieldValue parameter. This means you can send API calls from your form, each using its own unique token.

In short, specifying a WorkflowField creates a field in the backoffice under your workflow. If a value is entered, it will be saved until the workflow is either disabled or modified. Once the workflow is triggered, the field's value is passed to your workflow, enabling you to handle it as needed. This makes it especially useful for scenarios like creating email workflows or managing dynamic data.

Workflow Items

What are workflow items? Workflow items give you the ability to hook into certain events, if that's displaying a message after/before form submission or sending the user to a URL, we've got you covered.

To hook into these events, you need to parse IHttpContextAccessor into your workflows constructor. Then add any of the workflow items to your HttpContext items, As shown below:

_httpContext.HttpContext?.Items.Add(EquateFormsConstants.WorkflowItems.NextPageURL, fieldValue);

Equate forms will then check these items before proceeding with the rest of the code, if a value is present then the specified event is triggered.

List of available workflow items:

NextPageURL

In short, a next page URL item provides equate forms with a next page URL, depending on if its before or after submission the workflow(s) will behave differently. See below.

EquateFormsConstants.WorkflowItems.NextPageUrl

AfterFormSubmission

If the workflow item is added to a workflow that executes after form submission, then the form submits and redirects them to the specified page.

BeforeFormSubmission

---

Message

In short, a message item provides equate forms with a message to display either before/after form submission.

EquateFormsConstants.WorkflowItems.Message

AfterFormSubmission

If the workflow item is added to a workflow that executes after form submission and if no submission page is set, then the message will appear at the top of your form.

BeforeFormSubmission