# Custom Workflows

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:

```csharp
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`**.&#x20;

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

See below for an **example**:

```csharp
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&#x20;
  * **Help Text**- The help text of the input
  * **Placeholder Text** - The placeholder text of the input

<details>

<summary>Explain the WorkflowField parameter in further detail</summary>

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.

</details>

### 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.&#x20;

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:

```csharp
_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.

<pre class="language-csharp"><code class="lang-csharp"><strong>EquateFormsConstants.WorkflowItems.NextPageUrl
</strong></code></pre>

{% tabs %}
{% tab title="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.
{% endtab %}

{% tab title="BeforeFormSubmission" %}
If the workflow item is added to a workflow that executes before form submission, then the form does not submit but takes them to a new page and preserves its data.
{% endtab %}
{% endtabs %}

***

**Message**

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

```csharp
EquateFormsConstants.WorkflowItems.Message
```

{% tabs %}
{% tab title="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.
{% endtab %}

{% tab title="BeforeFormSubmission" %}
If the workflow item is added to a workflow that executes before form submission, then the specified message will show at the top of your form, only if validation occurs.
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://equatedigital.gitbook.io/equateforms/advanced/custom-workflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.