T270: WorklfowAPI
Version: 2025R1
Category: Technical
How to Use This Course
The T270 Workflow API training course shows how to create a workflow for a data entry form by using Workflow API
of Acumatica Framework. The course describes in detail how to define and customize a workflow to change the
state of an entity in Acumatica ERP.
This course is intended for application developers who are starting to learn how to customize Acumatica ERP.
The course is based on a set of examples that demonstrate the general approach to customizing Acumatica ERP. It
is designed to give you ideas about how to develop your own embedded applications through the customization
tools. As you go through the course, you will continue the development of the customization for the cell phone
repair shop, which was performed in the T200 Maintenance Forms, T210 Customized Forms and Master-Detail
Relationship, and T220 Data Entry and Setup Forms training courses.
Aer you complete all the lessons of the course, you will be familiar with the programming techniques for the
definition of custom workflows and the customization of existing workflows in Acumatica ERP.
We recommend that you complete the examples in the order in which they are provided in the course,
because some examples use the results of previous ones.
What the Course Prerequisites Are
To complete this course, you should be familiar with the basic concepts of Acumatica Framework and Acumatica
Customization Platform. We recommend that you complete the T200 Maintenance Forms, T210 Customized Forms
and Master-Detail Relationship, and T220 Data Entry and Setup Forms training courses before you begin this course.
To complete the course successfully, you should have the following required knowledge:
- Proficiency with C#, including but not limited to the following features of the language:
- Class structure
- OOP (inheritance, interfaces, and polymorphism)
- Usage and creation of attributes
- Generics
- Delegates, anonymous methods, and lambda expressions
- Knowledge of the following main concepts of ASP.NET and web development:
- Application states
- The debugging of ASP.NET applications by using Visual Studio
- The process of attaching to IIS by using Visual Studio debugging tools
- Client- and server-side development
- The structure of web forms
- Experience with SQL Server, including doing the following:
- Writing and debugging complex SQL queries (WHERE clauses, aggregates, and subqueries)
- Understanding the database structure (primary keys, data types, and denormalization)
- The following experience with IIS:
- The configuration and deployment of ASP.NET websites
- The configuration and securing of IIS
What Is in a Part
The first part of the course explains how to create a workflow for a custom data entry form.
How to Use This Course | 6
The second part of the course shows how to incorporate an existing workflow into a custom workflow. The third part of the course describes the customization of a workflow of a predefined Acumatica ERP form. Each part of the course consists of lessons you should complete.
What Is in a Lesson
Each lesson is dedicated to a particular development scenario that you can implement by using Acumatica ERP customization tools and Acumatica Framework. Each process lesson imparts the concepts that you need to learn to implement the development scenario and includes at least one activity that you have to complete in your Acumatica ERP instance.
Where the Source Code Is
You can find the source code of the customization described in this course and code snippets for the course in the WorkflowDevelopment\T270 folder of the Help-and-Training-Examples repository in Acumatica GitHub.
What the Documentation Resources Are
The complete Acumatica ERP and Acumatica Framework documentation is available at https://help.acumatica.com/ and is included in the Acumatica ERP instance. While viewing any form used in the course, you can click the Open Help button in the top pane of the Acumatica ERP screen to bring up a form-specific Help menu; you can use the links on this menu to quickly access form-related information and activities and to open a reference topic with detailed descriptions of the form elements.
Which License You Should Use
For the educational purposes of this course, you use Acumatica ERP under the trial license, which does not require activation and provides all available features. For the production use of the Acumatica ERP functionality, an administrator has to activate the license the organization has purchased. Each particular feature may be subject to additional licensing; please consult the Acumatica ERP licensing policy for details. Getting Started with Workflow API: General Information | 7
Getting Started with Workflow API: General Information A workflow is a depiction of the ways the state of a record created on a particular form changes as a result of specific user interactions on the form and other events. You can use Workflow API to design and tailor the workflows of forms to meet your company's needs.
Learning Objectives
In this topic, you will learn what workflows are and how you can use them.
Applicable Scenarios
You might need to create or customize workflows if the movement of records in the company follows an established sequence of operations. By customizing predefined workflows to represent this sequence, you can automate the company’s processes, which can speed the processing of records. You may want to instead develop new workflows if the predefined workflows are not similar enough to the way the entity is processed in your company or the form does not already have a workflow.
Advantages of Workflows
Before workflows were introduced, similar logic was implemented in one of the following ways:
- By using automation steps. This functionality has been deprecated since 2023 R1.
- Through complex logic in graph code. Developers used a set of flags to track the record status and implemented event handlers, such as RowSelected. In the event handlers, they changed the properties of different elements of the screen, such as fields and actions, depending on the flags’ values. Workflows provide the following advantages over the previous approaches:
- Shorter, more readable code: You can use Workflow API to declaratively describe complicated logic that was previously in RowSelected event handlers. This makes it much easier to understand the structure and modify the logic—for example, to enable an action for a particular status.
- Support for no-code customization: When you implement logic by using Workflow API, users (customizers) can later view and customize it from the Customization Project Editor without coding.
- Custom actions without changing graph code: With Workflow API, you can define actions without changing the graph code. Such actions are created within the workflow. Users (customizers) can even create workflow actions in the Customization Project Editor without coding.
- Conditions: Workflows introduce conditions. You can change action and field properties dynamically depending on conditions.
- No-code dialog boxes: Worfklows introduce a type of dialog boxes that does not require additional code in the graph or on the frontend. Compared to automation steps, workflows are much easier to modify—for example, when adding a new state. Also, when a default workflow is updated, you can still apply customizations of the workflow unless they introduce breaking changes.
States and Transitions
A workflow can be described as a state machine, with transitions showing the movement of the record through its processing in the system as the corresponding work is performed in the company. For example, a workflow can involve the changing of the status of an opportunity based on user interactions on the Opportunities (CR304000) form to reflect the progress made with the potential customer that represents an opportunity. Getting Started with Workflow API: General Information | 8
For details on defining states, see Defining Workflow States. For details on defining transitions, see Implementing Transitions.
Actions and Fields
You can configure action and field properties for a form and its workflows at the same time, depending on the conditions specified for the form when a record is in any workflow state or in a particular workflow state. For details on actions and their properties, see Implementing Workflow Actions.
Conditions
Conditions can be used in the properties of actions and fields at the form level (that is, for all workflows of a particular form). At the workflow level, conditions can be used to determine whether transitions are performed. Also, conditions can be used to determine whether actions are performed automatically. For details on defining and using conditions, see Defining Conditions.
Customization and Creation of Workflows
You can customize predefined workflows for forms that have them; the resulting customized workflows are sometimes referred to as inherited because they inherit all modifications of the predefined workflow. You can also create custom workflows that are not based on existing workflows. For details on customizing a predefined workflow, see Customizing a Predefined Workflow. You can define a single workflow for the whole form or multiple workflows, one for a record with each value of the specific field that identifies the workflow state, such as the record type. You can configure the settings, such as field properties, conditions, and actions, for the whole form. For each of the workflows of the form, you can specify the properties of actions and fields for every workflow state. These properties determine the appearance of the form when the record is in a particular workflow state. Company Story and Customization Description | 9
Company Story and Customization Description
In the activities of this training course, you will develop a customization project to support the cell phone repair shop of the Smart Fix company. Parts of this customization were developed in the T200 Maintenance Forms, T210 Customized Forms and Master-Detail Relationship, and T220 Data Entry and Setup Forms training courses. The activities of this guide use the customization project that you can get as a result of completing these courses. You will deploy this project in Test Instance for Workflow Customization: To Deploy a Test Instance. The T200 Maintenance Forms training course describes the creation of the following simple maintenance forms:
- Repair Services (RS201000): The Smart Fix company uses this form to manage the list of the repair services the company provides.
- Serviced Devices (RS202000): On this form, the Smart Fix company manages the list of the devices serviced by the company. The T210 Customized Forms and Master-Detail Relationship course covers the creation of another maintenance form, Services and Prices (RS203000), and the customization of the Stock Items (IN202500) form of Acumatica ERP. The Services and Prices (RS203000) form provides users with the ability to define and maintain the price for each repair service the company provides. The Stock Items (IN202500) form has been customized to give users the ability to mark particular stock items as repair items—that is, items that are used for repair services. In the T220 Data Entry and Setup Forms course, the Repair Work Orders (RS301000) data entry form, which is used to create and manage work orders for repairs, is created. The course also covers the creation of the Repair Work Order Preferences (RS101000) setup form, on which an administrative user specifies the company’s preferences for the repair work orders. In the activities of this training course, you will implement a workflow on the Repair Work Orders (RS301000) form. The workflow will change the state of a record created on the form—that is, the status of the repair work order and the related properties of the fields and actions on the form. You will also customize the workflow on the Invoices (SO303000) form by doing the following:
- Adding an action that opens the Repair Work Orders form. You will make the action available for an invoice in one status.
- Adding the new workflow state, Postponed, to a composite state of the workflow, a transition from the Postponed workflow state, and an action that triggers the transition.
Types of Repair Work Orders
A repair work order may be created for the following types of services, which are defined on the Repair Services (RS201000) form:
- Battery Replacement
- Liquid Damage
- Screen Repair
As specified on the Repair Services (RS201000) form, the Battery Replacement service does not require a
prepayment. The total cost of the order must be paid in full aer the repair is completed.
The Liquid Damage service requires prepayment. The percent of the prepayment is specified on the Repair Work
Order Preferences (RS101000) form.
In the activities of this training course, you will implement the changing of the status for the Battery Replacement
and Liquid Damage services.
The activities do not cover the implementation of the changing of the status for the Screen Repair service. You can do this as a self-guided exercise.
Company Story and Customization Description | 10
Business Process Overview
The workflow to be used for repair work orders created on the Repair Work Orders (RS301000) form will differ slightly depending on the particular service being performed, which can be Battery Replacement, Liquid Damage, or Screen Repair. This topic describes how the workflow will work for a repair work order for the Battery Replacement and Liquid Damage service.
The Battery Replacement Service
When a user creates a repair work order for the Battery Replacement service on the Repair Work Orders (RS301000) form, the order will have the On Hold status. To change the order’s status to Ready for Assignment, a user will click the Remove Hold button on the form toolbar. Then a user will click the Assign button and specify the assignee in the Select Assignee dialog box. The order’s status will be changed to Assigned. When work on the order is completed, a user will complete the assigned order by clicking the Complete button, which will give the order the Completed status. Aer that, a user creates an invoice for the order. When the invoice is fully paid, the system will assign the Paid status to the repair work order. Thus, based on this workflow, a repair work order for the Battery Replacement service will be able to have the following statuses:
- On Hold A newly created order has this status by default.
- Ready for Assignment This status will be assigned when a user clicks the Remove Hold button.
- Assigned This status will be assigned when a user clicks the Assign button.
- Completed This status will be assigned when a user clicks the Complete button on the Labor tab.
- Paid The system will assign this status to the order when the order is fully paid. The following diagram shows the planned workflow for a repair work order for the Battery Replacement service. The system actions that have been or will be implemented in the PhoneRepairShop customization project are shown in the middle column. Company Story and Customization Description | 11
The Liquid Damage Service
When a user creates a repair work order for the Liquid Damage service on the Repair Work Orders (RS301000) form, the order has the On Hold status. To cause the system to change the order’s status to Pending Payment, a user will click the Remove Hold button on the form toolbar. This status indicates that a user needs to create, release, and apply a prepayment. Company Story and Customization Description | 12
A repair work order for the Liquid Damage service requires prepayment if the Requires Prepayment
check box is selected on the Repair Services (RS201000) form. The required percent to be prepaid
has been specified in the Prepayment Percent box of the Repair Work Order Preferences (RS101000)
form.
To create and apply the prepayment, a user should first create an invoice for the repair work order, and then create, release, and apply the prepayment on the Payments and Applications (AR302000) form; the repair work order’s status will be changed to Ready for Assignment. Then a user will assign the order to an employee, and the order’s status will be changed to Assigned. When work on the order is completed, a user can complete the assigned order by clicking the Complete button on the Labor tab, which will cause the order to be assigned the Completed status. Aer that, a user will apply the rest of the payment to the invoice created for the order. When the invoice is fully paid, the system will assign the Paid status to the repair work order. Thus, based on this workflow, a repair work order for the Liquid Damage service will be able to have the following statuses:
- On Hold A newly created order has this status by default.
- Pending Payment This status will be assigned when a user clicks the Remove Hold button on the form toolbar.
- Ready for Assignment This status will be assigned to an order when a prepayment for it has been created, released, and applied, and the prepayment percent is greater than or equal to the required prepayment percent.
- Assigned This status will be assigned when a user clicks the Assign button.
- Completed This status will be assigned when a user clicks the Complete button on the Labor tab.
- Paid The system will assign this status to the order when the order is fully paid. The payment will be applied to the same invoice to which the prepayment was applied. The following diagram shows the planned workflow for a repair work order for the Liquid Damage service. The system actions that have been or will be implemented in the PhoneRepairShop customization project are shown in the middle column. Company Story and Customization Description | 13
Customization Description
This topic describes the changes that will be implemented as part of the customization for the Smart Fix company.
Custom Workflow for the Repair Work Orders Form
A review of the company's business processes has illustrated that the workflow for both services (one of which requires prepayment and one of which does not) can be united into a single workflow, which is shown in the following diagram. In the activities of this training course, you will implement this workflow for the Repair Work Orders (RS301000) form. Company Story and Customization Description | 14
Figure: The workflow on the Repair Work Orders form
In the workflow, you will implement the following items:
- The following states of the workflow, which correspond to the noted statuses of a repair work order:
- WorkOrderStatusConstants.OnHold (On Hold)
- WorkOrderStatusConstants.PendingPayment (Pending Payment)
- WorkOrderStatusConstants.ReadyForAssignment (Ready for Assignment)
- WorkOrderStatusConstants.Assigned (Assigned)
- WorkOrderStatusConstants.Completed (Completed)
- WorkOrderStatusConstants.Paid (Paid)
- The following actions, which trigger the transitions of a repair work order and correspond to the noted command and button on the UI:
- ReleaseFromHold (Remove Hold), which triggers a transition from the OnHold state to the PendingPayment or ReadyForAssignment state
- Assign (Assign), which triggers a transition from the ReadyForAssignment state to the Assigned state
- Complete (Complete), which triggers a transition from the Assigned state to the Completed status You will also define the CreateInvoice action, which generates an invoice for the repair work order.
- The transitions between states of the workflow
- A dialog box that is shown when a user clicks the Assign action
- The following workflow event handlers, which trigger transitions for a repair work order:
- OnInvoiceGotPrepaid, which triggers a transition from the PendingPayment workflow state to the ReadyForAssignment workflow state
- OnCloseDocument, which triggers a transition from the Completed workflow state to the Paid workflow state
- The conditions that determine for a record created on the form to which workflow state the system should
transit from the OnHold workflow state
Company Story and Customization Description | 15
You will also customize an existing Acumatica ERP graph to implement a transition in your custom workflow. The resulting Repair Work Orders (RS301000) form will appear as shown in the following screenshot.
Figure: The resulting form
Customized Workflow for the Invoices Form
To continue working on a repair work order aer an invoice has been prepaid, a user needs an action that opens the corresponding repair work order from the Invoices (SO303000) form. Accordingly, you need to customize the predefined workflow of that form. The command corresponding to the action should be named View Repair Work Order and should be displayed on the More menu under the Repair Work Orders category, as shown in the following screenshot.
Figure: The View Repair Work Order action Company Story and Customization Description | 16
To implement this task, you will extend the graph to define the action and customize the predefined workflow of the Invoices (SO303000) form. In the customized workflow, you will do the following:
- Define the workflow action
- Define the action category
- Add the action to the workflow state Preparing an Instance for Workflow Customization | 17
Preparing an Instance for Workflow Customization
You need to perform the prerequisite actions before you start to complete the course.
Test Instance for Workflow Customization: To Deploy a Test Instance
The following activity will walk you through the process of preparing and deploying an Acumatica ERP instance that you can use to test workflow customization.
Story
Suppose that you need to perform customization tasks for the Smart Fix company, as described in Company Story and Customization Description. You need to deploy an instance of Acumatica ERP with the PhoneRepairShop customization project published.
Process Overview
In this activity, you will install tools that will help you to perform customization tasks and then deploy the instance of Acumatica ERP with the dataset from the T220 Data Entry and Setup Forms course.
Step 1: Preparing the Environment To prepare the environment, do the following:
- Make sure that the environment that you are going to use conforms to the System Requirements for the Acumatica ERP Installation.
- Make sure that the Web Server (IIS) features that are listed in Configuration of IIS Web Server Features are turned on.
- Install the Acuminator extension for Visual Studio.
- Clone or download the customization project and the source code of the extension library from the Help- and-Training-Examples repository in Acumatica GitHub to a folder on your computer.
- Install Acumatica ERP. On the Main Soware Configuration page of the Acumatica ERP Setup wizard, select
the Install Acumatica ERP and Install Debugger Tools check boxes.
If you have already installed Acumatica ERP without debugger tools, you should remove Acumatica ERP and install it again with the Install Debugger Tools check box selected. The reinstallation of Acumatica ERP does not affect existing Acumatica ERP instances. You can also install the Acumatica ERP Tools separately. For details, see Acumatica ERP Installation On- Premises: To Install the Acumatica ERP Tools (Optional).
Step 2: Deploying the Instance To perform customization for the Smart Fix company as described in Company Story and Customization Description, you need deploy an instance of Acumatica ERP and publish the customization project prepared for the T270 Workflow API training course on the instance. You deploy an Acumatica ERP instance and configure it as follows:
- Open the Acumatica ERP Configuration wizard, and do the following:
Preparing an Instance for Workflow Customization | 18
a. Click Deploy a New Acumatica ERP Instance for T-Series Developer Courses. b. On the Instance Configuration page, do the following: a. In the Training Course box, select T270 Workflow API. b. In the Local Path to the Instance box, select a folder that is outside of the C:\Program Files (x86), C:\Program Files, and C:\Users folders. (We recommend that you store the website folder outside of these folders to avoid an issue with permission to work in these folders when you customize the website.) c. On the Database Configuration page, make sure the name of the database is SmartFix_T270. The system creates a new Acumatica ERP instance, adds a new tenant, loads the data to it, and publishes the customization project that is needed for activities of this training course. - Make sure that a Visual Studio solution is available in the App_Data\Projects\PhoneRepairShop
folder of the Acumatica ERP instance folder.
This is the solution of the extension library that you will modify in the activities of this training course. - Sign in to the new tenant by using the following credentials:
- Username: admin
- Password: setup Change the password when the system prompts you to do so.
- In the top right corner of the Acumatica ERP screen, click the username, and then click My Profile. The User Profile (SM203010) form opens. On the General Info tab, select YOGIFON in the Default Branch box; then click Save on the form toolbar. In subsequent sign-ins to this account, you will be signed in to this branch.
- Optional: Add the Customization Projects (SM204505) and Generic Inquiry (SM208000) forms to your favorites. For details about how to add a form to your favorites, see Favorites: General Information.
Test Instance for Workflow Customization: To Turn On Workflow Validation
The following activity will walk you through the process of preparing an instance of Acumatica ERP for the validation of a workflow that you create by using Workflow API. The code written by using Workflow API is declarative. As a result, the usual approaches to debugging do not work with the workflow code. To catch errors that occur in a workflow, you need to turn on workflow validation. This way, when an error occurs on a form that uses the workflow, you can see detailed information about the error on the System Events tab of the System Monitor (SM201530) form of Acumatica ERP.
Story
Suppose that you need to develop a workflow by using Workflow API. In this case, you need to learn how to debug the code and catch errors.
Process Overview
You will enable workflow validation in the Web.config file of your instance.
Step: Enabling Workflow Validation To enable workflow validation, do the following:
- In the instance folder, open the Web.config file. Preparing an Instance for Workflow Customization | 19
- In the appSettings tag of the file, find the EnableWorkflowValidationOnStartup key, and set its
value to True, as the following code shows.
<add key="EnableWorkflowValidationOnStartup" value="True" /> - Save your changes.
Test Instance for Workflow Customization: To Configure the Instance
Based on the Customization Description, you need to configure the instance to be able to test the logic you implement while completing the activities in this training course.
Story
In the Smart Fix company, there are no shipments or sales orders associated with repair work orders. Therefore, you need to configure Acumatica ERP so that during the creation of an SO invoice on the Invoices (SO303000) form, stock items can be added directly to the SO invoice without sales orders and shipments being processed. Aer you perform the customization tasks, you will be testing your changes, including the Create Invoice button or command (which corresponds to the CreateInvoice action that you will create) of the Repair Work Orders (RS301000) form. If you click the button multiple times during testing, you may run into an issue with insufficient stock items in a warehouse. When an SO invoice is released, the quantity of stock items included in the invoice is checked, and if there are not enough stock items in a warehouse, an invoice cannot be created. You need to prevent this issue from occurring.
Process Overview
You will enable the Advanced SO Invoices feature on the Enable/Disable Features (CS100000) form to make it possible to process repair work orders. On the Item Classes (IN201000) form, you will also change the STOCKITEM item class to allow negative quantities for the stock items. This will prevent possible issues during the testing of the Create Invoice action. You will also specify accounts receivable preferences.
Step 1: Turning on the Feature To turn on the feature, on the Enable/Disable Features (CS100000) form, do the following:
- On the form toolbar, click Modify.
- Select the Advanced SO Invoices check box.
- Click Enable on the form toolbar.
Step 2: Allowing Negative Quantities for Stock Items To allow negative quantities for stock items, do the following:
- On the Item Classes (IN201000) form, in the Item Class Tree, select STOCKITEM. All the stock items used in the activities of this training course belong to this class.
- On the General tab (General Settings section), select the Allow Negative Quantity check box, as shown in
the following screenshot.
Preparing an Instance for Workflow Customization | 20
Figure: Item Classes form - On the form toolbar, click Save.
Step 3: Specifying Accounts Receivable Preferences Specify accounts receivable preferences as follows:
- Open the Accounts Receivable Preferences (AR101000) form.
- On the Data Entry Settings section of the General tab, clear the Validate Document Totals on Entry and Require Payment Reference on Entry check boxes. This will make it possible for users to skip entering values during the release of an invoice.
- On the form toolbar, click Save. Part 1: Creating a Custom Workflow | 21
Course Structure
Part 2: Incorporating an Existing Workflow into a Custom Workflow......................................................... 63
Part 3: Customizing an Existing Workflow...............................................................................................84
Part 1: Creating a Custom Workflow
- Lesson 1.1: Set Up the Basic Parts of the Workflow
- Lesson 1.2: Implement a Workflow Action
- Lesson 1.3: Define States of the Workflow
- Lesson 1.4: Implement a Simple Transition
- Lesson 1.5: Implement a Group of Transitions
- Lesson 1.6: Implement a Transition with a Dialog Box
- Lesson 1.7: Implement Transitions and Configure Actions