Unlock Dynamics GP: Program Custom Actions on SOP Entry Forms with Dexterity

Table of Contents

This article delves into the process of leveraging Dexterity code to customize the behavior of the Actions button found on the SOP_Entry form within Microsoft Dynamics GP 10.0. Customizing this button is a key aspect of adapting the system to specific business requirements and workflows. Understanding how to interact with this central control is essential for developers working with this version of Dynamics GP.

Introduction to the Actions Button in Dynamics GP 10.0¶

In Microsoft Dynamics GP version 10.0, a significant change was introduced to the user interface for Sales Order Processing (SOP) entry. Actions that were previously represented by individual buttons on the form were consolidated under a single Actions button. This design change aimed to streamline the interface, especially as the number of potential actions for a document could grow, depending on its state and type. The Actions button presents a dropdown menu containing a dynamic list of valid actions available for the currently displayed SOP document, such as posting, voiding, transferring, and others.

This consolidation meant that developers accustomed to attaching Dexterity code directly to individual button clicks in older versions needed to adapt their approach. Instead of writing trigger scripts for distinct buttons like “Void Button” or “Post Button”, customization now centers around intercepting the selection made within the Actions button’s dropdown menu. This requires understanding how Dexterity interacts with dropdown controls and trigger mechanisms associated with focus changes or clicks on such consolidated elements.

The Shift from Dynamics GP 9.0¶

Prior to Dynamics GP 10.0, forms like SOP Entry featured a row of distinct buttons for common actions. Buttons such as Save, Delete, Void, Post, Transfer, Purchase, Confirm, and Copy each had their own dedicated presence on the form. These buttons were enabled or disabled dynamically by the core application logic based on the document type, status, and relevant business rules. Customizing the behavior of these actions involved writing Dexterity triggers directly on the click events of these individual buttons.

This direct approach was straightforward for developers but could lead to crowded forms. The move in GP 10.0 to the consolidated Actions button, alongside the persistent Save button and the new Submit for Approval workflow button, represented a shift towards a cleaner, more context-sensitive interface. While simplifying the user view, it introduced a new challenge for developers: how to intercept and potentially modify or prevent actions selected from a single dropdown list rather than distinct buttons. This necessitates a different triggering mechanism and a method for identifying which action was selected from the list.

Customizing the Actions Button with Dexterity¶

To programmatically interact with the actions selected via the Actions button in Dynamics GP 10.0 using Dexterity, you must register a trigger on the button itself. Since selecting an item from the dropdown is perceived by Dexterity somewhat differently than a simple button click, the focus change or a similar event associated with interacting with the dropdown list is often the appropriate target for customization triggers. This allows your Dexterity code to execute before the standard action associated with the selected item takes place, giving you the opportunity to perform custom validation, display warnings, or even prevent the action entirely.

Understanding Dexterity Triggers¶

Dexterity’s extensibility model relies heavily on triggers. Triggers allow developers to attach custom scripts to standard events that occur within the application, such as opening a form, saving a record, changing the value of a field, or interacting with a control like a button. There are different types of triggers, including form, window, field, and global triggers, each responding to specific types of events (e.g., focus changes, value changes, pre/post events for procedures). For controlling actions initiated from a button, especially one that presents a list of options, triggers associated with focus or command execution are typically used. The key is to find the trigger point that fires reliably when an action is selected and before the default processing occurs.

Analyzing the Startup Procedure Code¶

The first step in many Dexterity customizations that involve modifying standard form behavior is to register the necessary triggers when the form is loaded or the application starts. The provided Dexterity code snippet for the Startup procedure demonstrates this:

{ Startup procedure }
local integer l_result;

l_result = Trigger_RegisterFocus(anonymous('Action Button' of window SOP_Entry of form SOP_Entry),
 TRIGGER_FOCUS_CHANGE, TRIGGER_BEFORE_ORIGINAL, script MBS_SOP_Entry_Action_PRE);
if l_result <> SY_NOERR then
 warning "SOP Entry Action PRE Trigger registration failed.";
end if;

This code registers a trigger on the ‘Action Button’ control within the SOP_Entry window of the SOP_Entry form. Let’s break down the key components:
- Trigger_RegisterFocus: This function is used to attach a script to events related to the focus of a control. Although the user clicks the button and selects an item, this interaction often involves focus changes or command executions that can be intercepted. Registering on focus change before the original script allows intervention.
- anonymous('Action Button' of window SOP_Entry of form SOP_Entry): This identifies the specific control the trigger is attached to. It uses the anonymous keyword to create a reference to the ‘Action Button’ control on the specified window and form at runtime.
- TRIGGER_FOCUS_CHANGE: This specifies the type of event that will fire the trigger. In this context, it captures the event occurring when the focus interacts with the button, likely as an item is selected from its dropdown.
- TRIGGER_BEFORE_ORIGINAL: This crucial parameter dictates when the custom script should run relative to the standard Dexterity script associated with the control. TRIGGER_BEFORE_ORIGINAL means the custom script (MBS_SOP_Entry_Action_PRE) will execute before the default Dynamics GP code that handles the selected action. This allows the custom script to potentially override or stop the original process.
- script MBS_SOP_Entry_Action_PRE: This specifies the name of the Dexterity script that should be executed when the trigger fires. This script contains the custom logic to handle the action selection.

The if l_result <> SY_NOERR then... block is standard error handling, checking if the trigger registration was successful. If not, it issues a warning.

Examining the Action Button Trigger Script¶

The script MBS_SOP_Entry_Action_PRE is the core of the customization. This script executes when the trigger registered in the startup procedure fires. Its purpose is to identify which action the user selected from the Actions dropdown and then apply custom logic based on that selection.

{ MBS_SOP_Entry_Action_PRE Procedure }
case itemdata('Action Button' of window SOP_Entry of form SOP_Entry, 'Action Button' of window SOP_Entry of form SOP_Entry)
 in [ACTION_POST of form SOP_Entry]
 in [ACTION_TRANSFER of form SOP_Entry]
 in [ACTION_PURCHASE of form SOP_Entry]
 in [ACTION_CONFIRMPICK of form SOP_Entry]
 in [ACTION_CONFIRMPACK of form SOP_Entry]
 in [ACTION_CONFIRMSHIP of form SOP_Entry]
 in [ACTION_COPY of form SOP_Entry]
 in [ACTION_DELETE of form SOP_Entry]
 in [ACTION_VOID of form SOP_Entry]
 warning "Void is disabled";
 reject script;
 abort script;
 else
end case;

This script uses a case statement to evaluate the selected item.
- itemdata('Action Button' of window SOP_Entry of form SOP_Entry, 'Action Button' of window SOP_Entry of form SOP_Entry): This Dexterity function call retrieves the data associated with the selected item in the ‘Action Button’ dropdown list. The ‘Action Button’ control itself is also specified as the second parameter, which is typical syntax for listbox/dropdown controls to get the selected item’s data. The data associated with each action item is a predefined constant value specific to that action (e.g., ACTION_POST, ACTION_VOID).
- in [...]: The case statement checks if the retrieved item data matches any of the listed action constants.
- The list [ACTION_POST of form SOP_Entry] ... [ACTION_VOID of form SOP_Entry] includes the constants representing various standard SOP actions. Note that of form SOP_Entry is used to qualify these constants, ensuring the correct values defined within the SOP_Entry form’s dictionary are referenced.
- The code block following the in [...] list executes if the selected action’s data matches any of the constants in the list. In the example provided, the same code block is applied to a wide range of actions including Post, Transfer, Purchase, various Confirms, Copy, Delete, and Void. This implies the intent of this specific script is to perform the same action (or prevent it) for all these listed operations.

In this particular example, the code block within the case statement is:

 warning "Void is disabled";
 reject script;
 abort script;

- warning "Void is disabled";: This line displays a warning message box to the user indicating that the action (in this case, contextually implying “Void is disabled” based on the message text, though the case statement matches many actions) cannot be performed.
- reject script;: This command is used within a TRIGGER_BEFORE_ORIGINAL script to signal to Dexterity that the original, default script for the triggered event should not be executed. This effectively cancels the standard action selected by the user.
- abort script;: This command immediately stops the execution of the current Dexterity script (MBS_SOP_Entry_Action_PRE).

Therefore, this specific script, when any of the listed actions (Post, Transfer, etc., including Void) are selected from the Actions button dropdown, will display a warning and prevent the selected action from proceeding. While the warning text “Void is disabled” is specific, the logic in [...] applies the reject script; abort script; to all listed actions. A more typical use case would be to have separate in clauses for different actions, allowing specific logic for each, or to apply the reject script only under certain conditions (e.g., if value of field "SOP Type" <> C_SOP_TYPE_ORDER then reject script;).

Contrasting with Dynamics GP 9.0 Customization¶

The fundamental difference in customization between GP 9.0 and 10.0 for these actions lies in the target of the trigger and the method of identifying the specific action.

Feature	Dynamics GP 9.0	Dynamics GP 10.0
Action Buttons	Separate buttons for each action	Consolidated “Actions” button with dropdown menu
Trigger Target	Click event on individual buttons	Focus Change/Command event on the “Actions” button
Action Identification	Implicit by button clicked	Explicitly check itemdata of selected dropdown item
Customization Script	Trigger script on button click	Trigger script on Actions button, using case statement to parse itemdata

In GP 9.0, disabling the Void button, for instance, would involve finding the ‘Void Button’ control on the form and writing a TRIGGER_BEFORE_ORIGINAL script on its click event that simply contains reject script;. This was straightforward but required managing triggers for numerous controls.

In GP 10.0, disabling the Void action selected from the dropdown requires registering one trigger on the ‘Actions Button’, and then, within the triggered script, checking if the selected item’s data matches the ACTION_VOID constant using a case statement before executing the reject script;. This approach centralizes the action handling logic in one script but requires understanding the item data constants.

Implications for Customization and Development¶

The shift to the Actions button in GP 10.0 had significant implications for Independent Software Vendors (ISVs) and developers who had built customizations around the SOP Entry form in previous versions. Existing customizations that relied on triggers attached to individual action buttons needed to be re-architected to work with the new consolidated button and its dropdown. This involved:

1. Identifying the correct trigger: Determining which trigger event on the ‘Actions Button’ reliably fires when an item is selected.
2. Parsing the selected action: Writing code (like the case itemdata(...)) to determine which specific action was chosen by the user from the dropdown list.
3. Migrating custom logic: Adapting the custom business logic that was previously associated with individual button triggers to execute conditionally within the single script based on the selected action.

This required a deeper understanding of how Dexterity handles dropdown lists and the specific data values assigned to each action item within the SOP_Entry form definition.

Advanced Customization Possibilities¶

Beyond simply disabling actions as shown in the example, customizing the Actions button allows for more complex scenarios:

• Custom Validation: Before allowing an action (e.g., Posting), the Dexterity script can perform additional checks beyond the standard GP validation. For example, verifying custom fields, checking related records, or validating against external data sources.
• Logging Actions: Record who performed which action and when, potentially with additional details, into a custom log table.
• Triggering Workflows: Initiate custom workflows or processes before or after a standard action completes.
• Modifying Data: Adjust document data based on the selected action and specific business rules before the action is processed.
• Adding Custom Actions: Although more complex, it is possible to programmatically add custom items to the Actions dropdown list and handle their selection in the trigger script, effectively adding new functionality to the SOP Entry form accessible via the Actions button.

These advanced scenarios require careful planning, robust error handling, and a thorough understanding of both Dexterity and the Dynamics GP SOP data structure.

Best Practices for Dexterity Customization¶

When customizing standard Dynamics GP forms using Dexterity triggers, especially for critical areas like SOP Entry actions, several best practices should be followed:

• Use TRIGGER_BEFORE_ORIGINAL cautiously: While necessary to intercept and prevent actions, ensure your script executes quickly and does not introduce performance bottlenecks. Be mindful of the impact on the user experience.
• Isolate Custom Logic: Keep your custom logic within dedicated scripts (like MBS_SOP_Entry_Action_PRE) rather than embedding large amounts of code directly in form scripts. This improves readability and maintainability.
• Use Constants: Refer to actions using the predefined constants (ACTION_VOID, ACTION_POST, etc.) rather than hardcoding values. This makes the code more readable and resilient to potential internal changes in value assignments (though less likely for core constants).
• Error Handling: Implement robust error handling within your scripts. If your custom script encounters an error, ensure it handles it gracefully and doesn’t crash the application or leave the system in an inconsistent state. Log errors appropriately.
• Testing: Rigorously test your customizations in various scenarios, including different document types, statuses, and user permissions, to ensure they behave as expected and do not negatively impact standard functionality. Test both positive cases (where the action should proceed) and negative cases (where it should be prevented).
• Documentation: Document your triggers and scripts thoroughly, explaining their purpose, the events they respond to, and the logic they implement. This is crucial for future maintenance and troubleshooting.
• Compatibility: Be aware that customizations using triggers, especially TRIGGER_BEFORE_ORIGINAL, can sometimes conflict with other customizations or third-party products that also trigger on the same events. Test for compatibility in your environment.

Conclusion¶

The consolidation of action buttons into a single Actions button in Dynamics GP 10.0 presented a new challenge for developers customizing the SOP Entry form using Dexterity. By understanding how to register triggers on the Actions button and parse the selected item using itemdata within a case statement, developers can effectively intercept, control, and customize the behavior of these critical sales order processing functions. While the approach differs from earlier versions, it provides a centralized mechanism for managing action-based logic. Mastering this technique is vital for adapting Dynamics GP 10.0 to meet specific business needs and workflows.

Do you have experience customizing the Actions button in Dynamics GP using Dexterity? Share your insights, challenges, or alternative approaches in the comments below!