Processing Forms: General Information

On a processing form, a user can invoke an operation to be performed on multiple selected records at once. For instance, a processing operation can be a procedure that modifies the status of documents.

Learning Objectives

In this chapter, you’ll learn how to create a simple processing form—that is, one with no selection criteria (filtering parameters) defined.

Applicable Scenarios

You implement a processing form to give users the ability to perform an operation on multiple records at once.

Processing Forms

Processing forms look similar to inquiry forms. A processing form usually has the following components:

• A table that displays the list of records retrieved by the processing data view. The table includes:
  • A column with an unlabeled check box, which gives the user the ability to select one record or multiple records in the grid for processing.
  • Additional columns that contain key settings of each listed record, including its ID or number.
  • Optional: A redirection button or link that can be clicked to open the data entry form for any selected record.
• A form toolbar that includes the Process, Process All, and Cancel buttons.
• Optional: An area that provides selection criteria (for narrowing the records that are listed and may be processed) or configuration settings—or both—for the processing method.

Naming Conventions for Processing Forms

Processing forms have IDs that start with a two-letter abbreviation (indicating the functional area of the form) followed by 50 (indicating a processing form), such as RS501000.

The names of the graphs that work with processing forms have the Process suffix. For instance, RSSVAssignProcess will be the name of the graph for the Assign Work Orders (RS501000) form.

For more details about these naming conventions, see Form and Report Numbering and Graph Naming.

Implementation of the Processing Action

Generally, the action that you want to use on a processing form has already been implemented for a data entry form as a workflow action or graph action. To use this action on a processing form, you need to make the following changes to it:

• For a graph action, you implement the action handler as follows:
  • You move the code from the action handler to the separate static method.
  • You change the signature of the action handler so that it returns IEnumerable. If you use the void action handler instead, the processing of the long-running operation and its result will not be displayed in the UI.
  • You replace the PXButton attribute with the PXProcessButton attribute to indicate that the action will be used on the processing form.
  • To run the processing method within the action handler, you invoke the PXLongOperation.StartOperation() method, which starts the execution of the processing method in a separate thread. The use of the PXLongOperation.StartOperation() method is the only way to execute the processing method asynchronously in MYOB Acumatica Framework.

    Before you run the operation, you invoke a method to save the last changes made on the data entry form. This ensures that you’re processing the latest version of the record.

    Attention:

    You need to call Save.Press() instead of Actions.PressSave() in an action that is used in a workflow and that starts a long-running operation.
• In the separate static method, you make the following changes to the code of the graph action:
  • You modify the code so that it works with the list of records obtained from the input parameter of the method.
  • You add the isMassProcess parameter to the method. isMassProcess = true means that the method is invoked from a processing form. With this value, you can return a successful processing message to the UI by using the static PXProcessing<T>.SetInfo() method.
  • To handle any errors that might occur during processing, you enclose the processing code in the try statement. If any error occurs, in the catch statement, you use the static PXProcessing<T>.SetError() method to return the processing result for each record to the UI.
• If the action is used in a workflow, you modify the action definition in the workflow so that the action can be used on the processing form.

  In this action definition, you call the MassProcessingScreen<>() method with the processing graph as the type parameter. You also call the InBatchMode() method if the workflow action works with the list of records.

For more information, see Processing Forms: Implementation of Processing Operations.

Definition of the Processing Graph and Data View

To configure the graph that works with the processing form, you do the following:

• You define the data view for the processing form.

  To do this, you use the SelectFrom<Table>.ProcessingView class. This class is derived from the PXProcessingBase<Table> class, which is a base class for the data views of processing forms.

  Tip:

  You can also use one of the types that use the traditional BQL style of data queries, such as PXProcessing or PXProcessingJoin.
• You add the Cancel action to the processing graph.

  You do this by using the PXCancel class. If the processing form does not have a filter, you use the main DAC of the processing data view as the type parameter, as shown in the following code.

  // Definition of the Cancel button for processing without filtering
  public class SalesOrderProcess : PXGraph<SalesOrderProcess>
  {
      public SelectFrom<SalesOrder>.ProcessingView SalesOrders;
      // Main DAC of the processing data view
      public PXCancel<SalesOrder> Cancel;
  }

• You add the processing actions to the processing graph.

  By default, any form that has a data view of a type derived from PXProcessingBase<Table> has the Process and Process All buttons on the form toolbar. You can replace the names of the default buttons in the graph constructor. To override the button captions, you use the SetProcessCaption() and SetProcessAllCaption() methods.

• You specify the action to be used for processing.

  If you use a workflow action, in the RowSelected event handler, you specify the workflow action that the processing form should use for processing by invoking the SetProcessWorkflowAction<>() method of the data view.

  Note:

  We recommend that you not call the SetProcessWorkflowAction<>() method in the graph constructor because this could cause incorrect initialization of the workflow.

  For the forms that don’t use workflow actions for processing, you must specify the processing delegate by using one of the SetProcessDelegate methods.

Controls for the Processing Form

You add the unbound Selected data field of the Boolean type to the DAC that provides the records to process for the processing form and then add the column for this field to the form. If a user doesn’t want to process all listed records, the user will select the check box in this column for each record to be processed. You define the Selected data field as unbound by using the PXBool type attribute. (Unlike the PXDBBool attribute, the PXBool attribute does not have DB in its name. DB indicates a bound data type.)

You make all columns in the grid (except for the column that corresponds to the Selected field) unavailable for editing by specifying the Processing preset for the grid. For the Selected field, you set the allowCheckAll property to true. This lets users select all records on the current page of the table for processing by selecting the check box in the column header.

Implementation Summary and Diagram

For a simple processing form that displays data to be processed and provides processing actions, you usually define the following:

• In the processing graph, the specific SelectFrom<Table>.ProcessingView (derived from PXProcessingBase) data view type to provide data records for the form
• In the graph constructor, the names of the processing buttons
• In the RowSelected event handler, the workflow action to be used for processing
• In the DAC, the unbound Selected data field, which is used to indicate the records to be processed
• In the TypeScript file, the Selected field with the allowCheckAll property set to true in the columnConfig decorator