Lesson 1: Defining an Action and the Associated Button for

a Form In this lesson, on the Repair Work Orders (RS301000) form, you will create an action, along with its associated button on the form toolbar and the equivalent command on the More menu. You will also configure the visibility and availability of this button and the corresponding command on the More menu.

Action Definition: General Information

To provide users with functionality that is specific to their business needs, you can create actions and make the associated buttons and commands available on the UI. You implement the actions in a graph. You can configure the availability and visibility of the buttons and commands based on specific criteria.

Learning Objectives

In this lesson, you will learn how to do the following:

Create an action, the associated button on the form toolbar, and the equivalent command on the More menu
Configure the availability and visibility of the button and command depending on field values on the form

Applicable Scenarios

You implement an action in the following cases:

You want to redirect a user to a specific form or report.
You want to modify or validate data records and save changes to the database.
You want to start a background operation, which is executed on a separate thread.

Action Declaration in a Graph

The declaration of an action in a graph consists of the following:

A field of the PXAction<> type, which is declared as follows. public PXAction CancelShipment;

    In the PXAction<> type parameter, you should specify the main DAC of the primary data view. Otherwise,
    the button corresponding to the action cannot be displayed on the form toolbar (and the corresponding
    command cannot be displayed on the More menu).

A method that implements the action; this method has the PXButton and PXUIField attributes. This method has the following forms of declaration:
Without parameters and returning void: This standard form of declaration is shown in the following code example. PXButtonPXUIField(DisplayName = "Cancel Shipment") protected virtual void cancelShipment() { ... Lesson 1: Defining an Action and the Associated Button for a Form | 12
```
        }

       This type of declaration is used for an action that is executed synchronously and is not called from a
       processing form.
```
With a parameter of the PXAdapter type and returning IEnumerable: You can see an example of this form of declaration in the following code. PXButtonPXUIField(DisplayName = "Release") protected virtual IEnumerable release(PXAdapter adapter) { ... return adapter.Get(); }
```
       This type of declaration should be used when the action initiates a background operation or is called
       from a processing form.
```
The field and the method should have the same name, diﬀering only in the capitalization of the first letter.
```
        A graph includes the Actions collection of all PXAction<> objects defined in the graph.
```

Callback on the Action

When a user invokes an action through a button or command on the UI, the page sends a request to the server side of the application (that is, it executes the callback). By default, for a button or command, the callback is always executed—that is, the CommitChanges property of the PXButton attribute is true. If you do not need the form to send the recent changes made on the form, set the CommitChanges property of the PXButton attribute to false as follows.

[PXButton(CommitChanges = false)]

The CommitChanges property must be always set to true for the actions that cause changes to be saved to the database.

Configuration of the Button and Command Associated with an Action

You can adjust the availability and visibility of a button or command (or both, if applicable) on the UI that is associated with an action at runtime (for example, to make the button or command unavailable or hidden) by using event handlers, attributes, or Workflow API. For details, see Action Customization: Disabling or Enabling of an Action and Action Customization: Visibility of an Action. The following code example show how to set the availability of a button inside an event handler. To do this, you should use the methods of the PXAction<> class, as the following code example shows.

// Disabling the CancelShipment action
CancelShipment.SetEnabled(false);

You do not use the static methods of the PXUIField attribute, because these methods work only with the attribute copies stored in PXCache objects. For more information about actions and how to customize them, see Action Customization: General Information. Lesson 1: Defining an Action and the Associated Button for a Form | 13

Activity 1.1: To Define an Action for a Form

The following activity will walk you through the process of implementing an action for a form. The action will be represented by a button on the form toolbar of the form and the equivalent command on the More menu.

Story

Suppose that you are a customizer working on the Repair Work Orders (RS301000) form in the PhoneRepairShop customization project. You need to create an action that gives users the ability to assign the selected repair work order to themselves and add the corresponding button to the form toolbar. You need to define an action in the graph of the form and configure the associated button (on the form toolbar) and the equivalent command (on the More menu). The button and command will be visible only if the repair work order has the On Hold or Ready for Assignment status and available if the Assignee box does not already contain the current user's name. When the user clicks the button or command, the contact ID associated with the current user, which is specified in the Linked Entity box of the Users (SM201010) form, will be inserted into the Assignee box. (If the user has selected an assignee before clicking the button or command, it will be overridden.) The clicking of the button or command will not aﬀect the status of the repair work order.

Process Overview

In this activity, you will implement an action on the form toolbar by performing the following steps:

Creating the AssignToMe action, the associated Assign to Me button on the form toolbar, and the command with the same name on the More menu
Configuring the availability and visibility of the Assign to Me button and the corresponding command on the More menu
Testing the Assign to Me button and the associated action

Step 1: Implementing the AssignToMe Action In this step, you will implement the AssignToMe action. The associated button will be placed on the form toolbar and the equivalent command on the More menu (under the default Other category).

          Commands on the More menu are listed under categories. You can change the category of the
          command by changing the value of the Category property of the PXButton attribute.

To implement the AssignToMe action, do the following:

In Visual Studio, open the RSSVWorkOrderEntry.cs file.

Aer the Graph constructor region of the RSSVWorkOrderEntry class, insert the following code.

              #region Actions
              public PXAction<RSSVWorkOrder> AssignToMe = null!;
              [PXButton]
              [PXUIField(DisplayName = "Assign to Me", Enabled = true)]
              protected virtual void assignToMe()
              {
                  // Get the current order from the cache.
                  RSSVWorkOrder row = WorkOrders.Current;

                   // Assign the contact ID associated with the current user

Lesson 1: Defining an Action and the Associated Button for a Form | 14

                      row.Assignee = PXAccess.GetContactID();

                      // Update the data record in the cache.
                      WorkOrders.Update(row);

                      // Trigger the Save action to save changes in the database.
                      Actions.PressSave();
                 }
                 #endregion


                 There is no need to set the CommitChanges property of the PXButton attribute to True
                 because CommitChanges is True by default for PXButton.

3. Save your changes.

Step 2: Specifying the Availability and Visibility of the Assign to Me Button and Command (with RowSelected) The Assign to Me button on the form toolbar (and the equivalent command on the More menu) should be visible for only orders with the On Hold or Ready for Assignment status and available if the Assignee box does not already contain the employee name of the user who is currently signed in. To satisfy these conditions, you should specify the Enabled and Visible properties of the AssignToMe action. To use these properties to specify the availability and visibility of the Assign to Me button (and the equivalent command), do the following:

In Visual Studio, open the RSSVWorkOrderEntry.cs file.

Add the handler for the RowSelected event for the RSSVWorkOrder DAC, as shown in the following code.

              // Manage visibility and availability of the actions.
              protected virtual void _(Events.RowSelected<RSSVWorkOrder> e)
              {
                  if (e.Row == null) return;
                  RSSVWorkOrder row = e.Row;
              }

In the _(Events.RowSelected e) event handler, add the following code to the end of the method.

                   AssignToMe.SetEnabled((row.Status ==
                       WorkOrderStatusConstants.ReadyForAssignment ||
                       row.Status == WorkOrderStatusConstants.OnHold) &&
                       WorkOrders.Cache.GetStatus(row) != PXEntryStatus.Inserted);

   In the code above, you have disabled the Assign to Me button and command until the repair work order is
   saved in the database by checking the WorkOrders object status in the PXCache.

In the _(Events.RowSelected e) event handler, add the following code to the end of the method.

                   AssignToMe.SetVisible(row.Assignee != PXAccess.GetContactID());

Save your changes.
Rebuild the project. Lesson 1: Defining an Action and the Associated Button for a Form | 15

Step 3: Testing the Assign to Me Button and the Associated Action To test the AssignToMe action and the Assign to Me button, do the following:

In Acumatica ERP, open the Repair Work Orders (RS301000) form.
Create a work order, and specify the following values:

Customer ID: C000000001
Service: Battery Replacement
Device: Nokia 3310
Description: Battery replacement, Nokia 3310

Save your changes. The 000003 repair work order has been created. Notice that the Assign to Me button is displayed on the form toolbar, as shown in the following screenshot.
```
   Figure: The Assign to Me button on the Repair Work Orders form
```
On the form toolbar, click the Assign to Me button. In the Assignee box, notice that the employee name associated with the current user is now specified; the employee name associated with the user was copied from the Linked Entity box of the Users (SM201010) form. Also, notice that the Assign to Me button is no longer displayed on the form toolbar. Lesson 1: Defining an Action and the Associated Button for a Form | 16
```
  Figure: The employee name in the Assignee box
```

Lesson Summary

In this lesson, you have learned how to define an action in Acumatica Framework and display the corresponding button on the form toolbar and command on the More menu. You have implemented the action, configured the availability of the button and command, and tested the action and button. To define an action, you have added the field of the PXAction<> type and an action method with the PXButton and PXUIField attributes to the RSSVWorkOrderEntry graph. To configure the availability and visibility of the corresponding command, you have used the SetEnabled and SetVisible methods in the RowSelected event handler of the RSSVWorkOrderEntry graph. The following diagram shows the changes that you have made in this lesson. Lesson 1: Defining an Action and the Associated Button for a Form | 17 Lesson 2: Defining an Action and the Associated Button for a Table | 18