Custom Actions in Designer
Overview
The Custom Action Designer allows you to define custom actions with custom action hooks. In a dedicated server environment, custom actions in designer 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.
Custom Action Hook Types
When a button event is triggered (i.e. a button is clicked), there are currently four places a 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 response for 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.
These ten locations also define different Custom Action Hook types.
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
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 CalculationRequest 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 CalculationRequest parameter and a CalculationResponse 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
This interface exposes a method with a CalculationRequest parameter and a CalculationResponse parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately before a save action occurs.
IAfterSave Interface
This interface exposes a method with a CalculationRequest parameter and a CalculationResponse parameter and returns an ActionableResponse object. Action hooks associated with this interface will be executed immediately after a save action is completed.
IBeforePrint Interface
This interface exposes a method with a CalculationRequest parameter, a CalculationResponse parameter and a PrintProcessInfoparameter 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 CalculationRequest parameter, a CalculationResponse 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 CalculationRequest parameter, a CalculationResponse and a 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 CalculationRequest parameter, a CalculationResponse parameter and a 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 CalculationRequest
parameter, a CalculationResponse
parameter and a 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 CalculationRequest
parameter, a CalculationResponse
and a ExcelExportOutput
parameter and returns an StandardResponse
object. Action hooks associated with this interface will be executed immediately after each Excel export process.
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 or Cancel subsequent actions.
CalculationRequest Class
Each Custom Action Hook method will have access to the CalculationRequest object, which can be used to examine the request contents that are going to be sent to the calculation engine. The CalculationRequest class includes all of the input information coming from the user interface, as well as all of the requested outputs. Custom 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.
CalculationResponse Class
Each Custom Action Hook method (except BeforeCalculate) will have access to the CalculationResponse object, which can be used to examine the response contents that have come back from the calculation engine. Custom 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.
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 the output file contents and the file name of the print process. 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.