Skip to content

Sample Action Codeunit

Codeunit 5138156 "SIM_DPS Sample CU" demonstrates how a Business Central codeunit can provide custom action logic to Business Portals. The sample uses SIM_DPS OL as its source table and covers function discovery, action execution, frontend event handling, and navigation to source or newly created records.

The codeunit is a reference implementation. Copy the required patterns into a customer-specific codeunit and replace the sample sales logic, messages, input field codes, and calculations with the requirements of the solution.

Available functions

When Business Portals runs the codeunit without an action context, OnRun uses GETFUNCTIONS and returns the following comma-separated values in Rec."Function List":

Function Purpose
MakeOrderFromQuote Updates the quote lines from portal input and converts the sales quote into a sales order.
MakeOrderFromItem Creates a sales order with one line for the selected item.
MakeQuoteFromItem Creates a sales quote with one line for the selected item.

These values are the parameters that can be selected when the codeunit is assigned to an action or process status.

AL
'GETFUNCTIONS':
    Rec."Function List" := 'MakeOrderFromQuote,MakeOrderFromItem,MakeQuoteFromItem';

Execution flow

The OnRun trigger is the dispatcher for all calls to the sample codeunit.

  1. For a normal action call, it reads the dataset-table action and its action setup. A process action takes its parameter from the next status; other action types take the parameter from the action.
  2. For a sub-function call, it reads the action assigned to the head table and appends a suffix derived from Rec."Sub Function Execute".
  3. The resulting value is handled by the final case statement.

The dispatcher recognizes these sub-function values:

Sub Function Execute Appended suffix Intended use
SAVE Save Save-related custom logic.
CHECK Check Validation before execution.
EVENT Event Process a frontend event and return event data.
HASEVENT HasEvent Tell the frontend whether an event is implemented.
OPENDOCPAGE OpenDocPage Open the record represented by the dataset row.
OPENNEWPAGE OpenNewPage Open the record created by the action.
BASKETCHECK BasketCheck Validate a basket operation.

For example, the function parameter MakeOrderFromQuote and sub-function EVENT produce the dispatch value MakeOrderFromQuoteEvent.

Only the following sub-function handlers contain logic in this sample:

  • MakeOrderFromQuoteEvent
  • MakeOrderFromQuoteHasEvent
  • MakeOrderFromQuoteOpenDocPage
  • MakeOrderFromQuoteOpenNewPage
  • MakeOrderFromItemOpenDocPage
  • MakeOrderFromItemOpenNewPage
  • MakeQuoteFromItemOpenDocPage
  • MakeQuoteFromItemOpenNewPage

The Save, Check, and BasketCheck branches, together with the event branches for the item-based functions, are placeholders. Add code to those branches only when the corresponding portal behavior is required.

Sales document examples

Convert a quote into an order

MakeOrderFromQuote receives the current dataset record through a RecordRef. Before conversion, it finds the associated line entries in SIM_DPS OL, reads the QUANTITY input value, and updates the related sales lines. An empty quantity defaults to 1.

The procedure then:

  1. Runs the standard pre-post approval check for the quote.
  2. Asks for confirmation when a user interface is available.
  3. Runs the standard Sales-Quote to Order codeunit.
  4. Copies the Business Portals order number to Your Reference on the new sales order.
  5. Stores the new record ID and the Sales Order page ID so that Business Portals can open the result later.

Create an order or quote from an item

MakeOrderFromItem and MakeQuoteFromItem use the selected item and the business number mapped to the Business Portals order. Each procedure creates a sales header and one item line, reads the portal's QUANTITY input, and defaults an empty quantity to 1.

The new document is linked back to Business Portals by storing its record ID and page ID. For process actions, this information is written to the matching SIM_DPS OL Status record. For other action types, it is written directly to SIM_DPS OL.

Frontend events

The quote-to-order example supports the following line events:

Event Sample behavior
SELECTLINE Returns the record IDs of sales lines in the same document that have the same quantity as the selected line.
UNSELECTLINE Returns the same group of record IDs so that the frontend can clear the related selection.
INPUTLINE Reads QUANTITY, BRUTTO, NETTO, and PRICE input values and returns calculated values for the triggering line.

MakeOrderFromQuoteHasEvent sets Sub Function Has Event to true for these three event names. This allows the frontend to check support before requesting event processing.

The event handler reads XML from the Sub Function Event Data BLOB. It takes EVENTVALUE from ROOT/EVENT, interprets it as a Business Central record ID, and writes the response XML to Sub Function Event Return with UTF-8 encoding.

The INPUTLINE calculation is intentionally illustrative:

  • PRICE is quantity multiplied by the sales line's unit price.
  • BRUTTO is quantity multiplied by 10.
  • NETTO is quantity multiplied by 5.
  • Empty numeric input is treated as zero.

For focused event examples, see Select Line Event, Unselect Line Event, and Input Line Event.

Opening Business Central pages

OpenDocPage opens the record referenced by Dataset Table Record. It uses the page configured on the dataset table and attempts to determine a page when no page number is configured.

OpenNewPage opens the record produced by an action. Process actions read the new record ID and page ID from SIM_DPS OL Status; other actions read them from SIM_DPS OL. The three main sample functions populate this information when they successfully create a sales document.

Page opening requires a Business Central user interface. It is not suitable for headless processing such as background sessions or web-service calls.

Implementation considerations

Before adapting the sample, consider the following points:

  • Keep TableNo = "SIM_DPS OL"; Business Portals passes its execution context through Rec.
  • Add every selectable base function to the GETFUNCTIONS list and add matching branches to the dispatcher.
  • A sub-function branch must use the exact base parameter plus suffix naming convention shown above.
  • Validate all required Business Portals, customer, item, quote, and status records for the target solution. Several lookups in the sample deliberately omit explicit error handling.
  • Replace the hard-coded event messages, field codes, and BRUTTO/NETTO multipliers.
  • Use localized labels for user-facing confirmation and event text in production code.
  • The document procedures call Commit after storing the new-record link. Review this transaction boundary before adding further processing or error handling.
  • When many lines can match an event, return only the required records and move suitable calculations to the client to reduce response time.

Configuration summary

To use the pattern in a Business Portals setup:

  1. Create or select the dataset tables for the source records.
  2. Create an action or process status and assign the custom codeunit.
  3. Select one of the function parameters returned by GETFUNCTIONS.
  4. Assign the action to the required dataset table.
  5. Configure the relevant input field codes, page IDs, and frontend event behavior.
  6. Test normal execution, every enabled sub-function, process-status tracking, cross-company access, and execution without a graphical user interface.