Scroll

Custom Functions

Exago comes with a large number of predefined functions that can be used to make formulas in the Formula Editor. As an administrator you may create additional custom functions using high level coding languages. Custom functions will be accessible to users in the Formula Editor or by typing their name into a cell of a report. Functions can be added to a preexisting function category or a function can be put into a new custom category.

Functions can be written in C#, JavaScript or VB. Net. Functions can take as few or many arguments as inputs, provided that the max number of arguments is greater than or equal to the minimum number of arguments.

Functions written in C# and VB.Net can get and set elements from the current session of Exago such as Parameter values. See Exago Session Info for more information.

Creating Functions

To create a custom function, select ‘Functions’ in the Main Menu and click the 'Add' button. This will open a Custom Function tab.

Each Custom Function has the following properties:

Name

A name for the function that will be displayed to the end users.

Description

A description of the function that will be displayed to the end users.

NOTE. To support multi-language functionality, if the description matches the Id of any element in the language files, then the string of that language element will be used instead of the description. For more information see Multi-Language Support.

Minimum Number of Arguments

The minimum number of values that an end user must enter in the function separated by commas.

Maximum Number of Arguments

The maximum number of values that an end user may enter in the function separated by commas.

NOTE. Arguments are passed to your code as an array of generic objects so there can be as many arguments as desired. The argument array is accessed by args[ ]. Arguments are passed into the function as objects.

Category

A way of grouping similar functions. You can assign custom functions to an existing Exago Category or create a new Category. To create a new Category, select “Other”. An input field will appear. Leaving this field blank will assign your Function to the “Other” Category in the Exago Formula Editor. A non-empty value in this field tells Exago to create a new Category with the specified name.

NOTE. To support multi-language functionality, if the custom category matches the Id of any element in the language files, then the string of that language element will be used instead of the description. For more information see Multi-Language Support.

Language

The high-level language of the code for the function. Can be C#, JavaScript or VB.Net.

Reference

A semicolon-separated list of any dlls that need to be referenced by the Custom Function. If the dlls are not accessible in the GAC then the dlls must be copied to the Bin folder of Exago or the reference should point to their physical path.

NOTE. System.dll does not need to be listed as a reference as it is already available.

Program Code

The program code for your Custom Function. Press the green check mark to verify the code executes properly.

NOTE. Parameters may be referenced within custom functions by placing their name between @’s.

Exago Session Info

Custom Functions can access the Exago session state through a “sessionInfo” variable. Access to sessionInfo allows powerful new capabilities such as the ability to persist values across function invocations, allowing each invocation to be aware of previous calls and behave accordingly.

NOTE. sessionInfo can also be accessed in Server Events, Action Events, and Assembly Data Sources.

The second example in the next section provides a function that returns the line number of the report being written by creating and incrementing a Stored Value which exists only for the report execution.

The following properties are available:

PageInfo

This is the parent of all information in the current session. Included is the active Report and SetupData objects.

NOTE. Since the Report and SetupData objects are accessed frequently, direct pointers are included for these objects.

Report

An object that contains all of the report’s Data Object, sort, filter, and layout information.

SetupData

An object that contains all of the session’s configuration setting including Filters, Parameters, Data Objects, Joins, Roles, etc.

CompanyId

Contains the value specified by the companyId Parameter.

UserId

Contains the value specified by the userId Parameter.

 

The following methods are available:

GetReportExecuteHtml (string reportName)

A method that executes the specified report and returns its html output. This could be used to embed a report within a cell of another report.

NOTE. The 'reportName' is relative to the session’s report path.

GetParameter (string parameterName)

A method that returns the specified Parameter Object. 'GetParameter' first looks in the Report Parameter collection, parameters being utilized by the report, and then in the Config Parameter collection, as well as other parameters such as hidden parameters or multi-tenant values.

GetReportParameter (string parameterName)

A method that returns the specified Parameter object that is utilized by the report being executed.

Ex. If a parameter is prompting a user for a value it will be available with the prompted value.

GetConfigParameter (string parameterName)

A method that returns the parameter object stored in the default configuration.

Ex. Any parameter that is not being utilized by the report being executed.

WriteLog (string text)

A method that writes the specified text to the Exago’s log file.

NOTE. The following methods utilize Stored Values which are objects that can be created and set by custom functions during report execution to pass data between custom function calls. Stored Values only exist for the duration of report execution.

GetStoredValue (string valueName, object initialValue = null)

A method that retrieves a Store Value. If a there is no Stored Value with the specified valueName, then one will be created with the specified initialValue.

SetStoredValue (string valueName, object newValue)

A method that sets the value of a Store Value. Setting newValue to 'null' will delete the Stored Value.

Calling Exago Functions

Cases may arise where you want to call an existing function within your Custom Function. Using the class CellFormula and returning the method CellFormula.Evaluate().

Example

The following are two examples of Custom Functions.

Name – ReverseString

Description – Reverses characters in the input string

  • Minimum Number of Arguments – 1
  • Maximum Number of Arguments – 1
  • Language – C#
  • Category – Other
  • Program Code –
string inputString = args[0].ToString();

char[] inputChars = inputString.ToCharArray();

System.Text.StringBuilder reverseStringSb = new System.Text.StringBuilder("");

for (int i = inputChars.Length - 1; i >= 0; i--)
{
   reverseStringSb.Append(inputChars[i]);
}
return reverseStringSb.ToString();

Name – LineNumber

Description – Displays the number of the line of the report.

  • Minimum Number of Arguments – 0
  • Maximum Number of Arguments – 0
  • Language – C#
  • Category – Other
  • Program Code –
// this function creates a Stored Value and increments the value by 1 each time the value is rendered on a report
int i = (int)sessionInfo.GetStoredValue("IncrementNumber", 0);

// increment the value by 1 and return
sessionInfo.SetStoredValue("IncrementNumber", ++i);
return i;

Hidden Article Information

Article Author
Alex Agoado
created 2015-12-03 20:20:22 UTC
updated 2017-06-20 19:44:13 UTC

Labels
creating functions, creating custom functions, session info, sessionInfo,
Have more questions? Submit a request