Overview

The Custom Action Designer allows you to define custom actions with custom action hooks. In a dedicated server environment, this allows the end user to upload a compatible .NET assembly with custom code that will be executed during the regular execution of calculations.

This permits for a myriad of possibilities, such as pushing or pulling data to/from external systems, recursive calculations, custom complex validation mechanisms, and numerous other possibilities.

These hooks can then be associated with buttons and will execute at some point in the calculation process, based on the interfaces that the methods implement.

Custom Actions and Custom Action Hooks

A Custom Action is a collection of compiled C# code which can be used to run methods inside classes with predefined interfaces. An interface is an agreement which determines a minimum set of methods a class should implement.

Each method that complies with the predefined contract will be automatically recognized by the system and these methods will form Custom Action Hooks. Each Custom Action Hook can be thought as an individual process which can then be associated with a button event trigger.

The SpreadsheetWeb platform is built upon .NET Framework 4.8, so any Custom Action projects must also target .NET Framework 4.8.

Sample Code

You may find a sample scaffolding project that includes a single class with each custom action hook interface implemented available at our GitHub. You may use this as a seed project for developing custom actions. While you can use VS Code with the C# extension to develop these assemblies, we recommend using Visual Studio Community edition as an alternative, since it has better support for .NET Framework versions that are not forks of .NET Core.

Custom Action Hook Types

There are two main types of custom actions. These are button triggered custom actions and custom action lifecycle events.

Button Triggered Custom Actions

When a button event is triggered (i.e. a button is clicked), there are currently ten places a button triggered custom action can be executed. These are:

Before Calculate: After the calculation request has been generated based on the application's requirements, but before the calculation request has been sent to the calculation engine. This provides for a moment to modify the calculation request before it is sent, as well as validate and cancel subsequent actions.
After Calculate: After the response from the calculation has been received but before all subsequent processes, such as save, print, and email generation. This provides for a moment to modify the results from the calculation response before they are processed, as well as validate and cancel subsequent actions. This will be executed even if there is no save action associated with the button.
Before Save: After the response from the calculation has been received but before all subsequent processes, such as save, print, and email generation. This provides for a moment to modify the results from the calculation response before they are processed, as well as validate and cancel subsequent actions. This will not be executed if there is no save action associated with the button.
After Save: After the response from the calculation has been received and the save action has been performed (i.e. all requested save data has been stored in the database), but before all subsequent processes, such as print and email generation. This provides for a moment to modify the results from the calculation response before they are used in subsequent processing, as well as validate and cancel subsequent actions. This will not be executed if there is no save action associated with the button.
Before Print: After the response from the calculation has been received and the save action has been performed before each print process. This provides for a moment to modify the results from the calculation response, as well as validate and cancel current print process. This will not be executed if there is no print action associated with the button.
After Print: After each print process is completed. This provides for a moment to modify the results from the calculation response and use print process output for further processing. This will not be executed if there is no print action associated with the button.
Before Email: After the response from the calculation has been received and the save action has been performed before each email process. This provides for a moment to modify the results from the calculation response and email request, as well as validate and cancel current email process. This will not be executed if there is no email action associated with the button.
After Email: After each email process is completed. This provides for a moment to modify the results from the calculation response and use email responsefor further processing. This will not be executed if there is no email action associated with the button.
Before Excel Export: After the response from the calculation has been received and the save action has been performed before each Excel export process. This provides for a moment to modify the results from the calculation response, as well as validate and cancel current Excel export process. This will not be executed if there is no Excel export action associated with the button.
After Excel Export: After each Excel export process is completed. This provides for a moment to modify the results from the calculation response and use Excel export process output for further processing. This will not be executed if there is no Excel export action associated with the button.

Custom Action LifeCycle Events

Custom action lifecycle events do not require an Action Button to be executed. If active, they execute every time at predefined points during when calculations are running. There are 2 places where a Custom action lifecycle event can be executed. These are:

Before All Calculations: After the calculation request has been generated based on the application settings, but before the calculation request has been sent to the calculation engine. This means that the calculation request can be modified before it's sent to the server, and can also validate or cancel subsequent actions.
After All Calculations: After the response from the calculations has been received, but before all subsequent processes, such as save, print, and email generation. This means that the results from the calculation response can be modified before they are processed, and can also validate and cancel subsequent actions. This will be executed even if there is no save action associated with the Action button.

Custom Action Interfaces

A custom action must be compiled to a Dynamic Link Library (DLL) file and the custom action code should have a predefined structure that will be used to automatically detect custom action hooks. Each custom action hook is defined by a namespace, a class and a method name. Each custom action hook method is an implementation of the four different methods enclosed in the following interfaces:

IBeforeCalculation
IAfterCalculation
IBeforeSave
IAfterSave
IBeforePrint
IAfterPrint
IBeforeEmail
IAfterEmail
IBeforeExcelExport
IAfterExcelExport
IBeforeAllCalculations
IAfterAllCalculations

For access to the external interfaces required in defining custom action hooks, please reach out to a Pagos Representative by email at support@pagos.com.

A custom action class should implement at least one of these interfaces. These classes should not be static and they should have include an empty constructor. A custom action class can implement more than one interface and there can be multiple action hooks of the same type in the custom action code residing in different classes.

IBeforeCalculation Interface

This interface exposes a method with a single INamedRangesCache parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately before the calculation request is sent.

IAfterCalculation Interface

This interface exposes a method with a INamedRangesCache parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately after a calculation is completed and before any save occurs.

IBeforeSave Interface

IAfterSave Interface

You can use below properties to access record info
request.DataRecordInfo.Id Saved record's id. For new records default value will be 1
request.DataRecordInfo.EditId Saved record's edit id. For new records default value will be 1

IBeforePrint Interface

This interface exposes a method with a INamedRangesCache parameter and a PrintProcessInfo parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately before each print process.

IAfterPrint Interface

This interface exposes a method with a INamedRangesCache parameter and a PrintProcessOutput parameter and returns an StandardResponse object. Action hooks associated with this interface will be executed immediately after each print process.

IBeforeEmail Interface

This interface exposes a method with a INamedRangesCache parameter and an EmailRequest parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately before each email process.

IAfterEmail Interface

This interface exposes a method with a INamedRangesCache parameter and an EmailResponse parameter and returns an StandardResponse object. Action hooks associated with this interface will be executed immediately after each email process.

IBeforeExcelExport Interface

This interface exposes a method with a INamedRangesCache parameter and an ExcelExportInfo parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately before each Excel export process.

IAfterExcelExport Interface

This interface exposes a method with a INamedRangesCache parameter and an ExcelExportOutput parameter and returns a StandardResponse object. Action hooks associated with this interface will be executed immediately after each Excel export process.

IBeforeAllCalculations Interface

IAfterAllCalculations Interface

Custom Action Parameter Classes

Custom action interface methods accept different classes of parameters that can be used during method execution and can be changed accordingly if required.

StandardResponse Class

IAfterPrint and IAfterEmail custom action hook methods return an object of type ActionableResponse. The StandardResponse class has a list of ResponseMessage class, which can be used to transmit messages from the custom action code back to the user interface.

ActionableResponse Class

Each Custom Action Hook method other than IAfterPrint and IAfterEmail returns an object of type ActionableResponse. ActionableResponse Class derives from StandardResponse class. The ActionableResponse class has a ResponseAction enumeration member that can be used to determine whether to Continue, Recalculate or Cancel subsequent actions.

Name	Value	Description
Continue	0	Executes the Custom Action
Cancel	1	Cancels the Custom Action
Recalculate	2	Triggers a calculation action after executing the Custom Action

Recalculate action works under IAfterCalculate. It will flag the request to make one additional calculation after the IAfterCalculation custom actions are executed. The purpose of this functionality is to allow the user to trigger an additional calculation request after an existing calculation request in order to re-calculate the workbook with any modifications made through the IAfterCalculate.

INamedRangesCache Interface

Each Custom Action Hook method will have access to an object that implements INamedRangesCache interface. An object implementing this interface has access to the following methods:

RangeReference GetNamedRange(string name): Get named range information for a given name.
void UpdateNamedRange(string name, CellValue[][] values): Update named range value using a CellValue array for a given name
void UpdateNamedRange(RangeReference range): Update a specific named range value using a RangeReference object
ApplicationSchemaState GetState(): Access the ApplicationSchemaState object which can be used to get information on the current application state.

PrintProcessInfo Class

BeforePrint Custom Action Hook method has access to the PrintProcessInfo object, which contains information on the current print process. BeforePrint action hooks can use the information from this object during method execution.

PrintProcessOutput Class

AfterPrint Custom Action Hook method has access to the PrintProcessOutput object, which contains print process identifier, the output file contents, the file name of the print process and print mode. AfterPrint action hooks can use the information from this object during method execution.

EmailRequest Class

BeforeEmail Custom Action Hook method has access to the EmailRequest object, which contains email request information for the current email process. BeforeEmail action hooks can use the information from this object during method execution and it is possible to make changes to this object inside the method body.

EmailResponse Class

AfterEmail Custom Action Hook method has access to the EmailResponse object, which contains email response information for the current email process. AfterEmail action hooks can use the information from this object during method execution.

ExcelExportInfo Class

BeforeExcelExport Custom Action Hook method has access to the ExcelExportInfo object, which contains information on the current Excel export process. BeforeExcelExport action hooks can use the information from this object during method execution.

ExcelExportOutput Class

AfterExcelExport Custom Action Hook method has access to the ExcelExportOutput object, which contains Excel export identifier, the output file contents and the file name of the Excel export process. AfterExcelExport action hooks can use the information from this object during method execution.

Custom Action Designer

Table of Contents

Related Pages