# Custom Functions

Exago comes with a number of functions that can be used to make formulas in the Formula Editor. Administrators may create additional custom functions, using high level coding languages, which will be accessible to end-users of the report designer. Functions can be added to a preexisting folder or a function can be put into a new custom folder.

Functions can be written in C#, VB.NET, or JavaScript (Windows only). Functions can take as many input arguments as needed.

Functions can get and set elements of the current session state of Exago such as Parameter values. See SessionInfo for more information.

# Creating Functions

To create a custom function, select 'Functions' in the Admin Console 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, you can supply an Id from a language file instead of a static string. For more information, see Multi-Language Support.

### Minimum Number of Arguments

(pre-v2017.2) The minimum number of values that an end user must enter in the function separated by commas.

### Maximum Number of Arguments

(pre-v2017.2) The maximum number of values that an end user may enter in the function separated by commas.

> Note: Arguments are passed to the code as an array of generic objects, accessed as args[ ].

### 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 will be new Category with the specified name.

> Note: To support multi-language functionality, you can supply an Id from a language file instead of a static string. For more information, see Multi-Language Support.

### Language

The high-level language of the code for the function. Can be C#, VB.NET, or JavaScript (Windows only).

### Reference

A semicolon-separated list of any DLLs that need to be referenced by the Custom Function. The DLLs must be present in the \bin folder of the Exago web application, as well as any scheduler bin folders, and the web service API if applicable.

> 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: To use a .NET Assembly for custom functions, first add it to the applicable \bin folders. Then add the assembly as a reference in the Custom Code window, and invoke the method, e.g.
> `return Extensions.Functions.DayBefore(args);`

## Arguments

Starting with version 2017.2 there are several enhancements to the way function arguments are implemented and used. See Formula Editor for details on how argument and function information will appear for end-users.

Click Edit Argument Info to show a dialog for managing arguments. Then click Add Argument for each argument the function will have. Arguments have the following properties:

### Name

The name of the argument, which will appear as a placeholder in the function parentheses and in the function's description tooltip.

### Description

A description for what the argument is used for. You should mention the expected data type, if it is not obvious. This will appear in a tooltip when the placeholder name is selected.

Can also be a language file ID.

### Optional

Whether this argument is required or optional. Optional arguments are surrounded by brackets [ ] in the function's description tooltip.

### Variable Argument Count

If selected, the last argument in the list accepts more than one value. Variable arguments are followed by an ellipsis (...) in the function's description tooltip.

# Exago Session Info

Custom Functions can access the Exago session state through a "sessionInfo" object. 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.

## Properties

### 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

A direct pointer to the companyId Parameter value.

### UserId

A direct poitner to the userId Parameter value.

## Methods

### 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.

> E.g. 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.

> E.g. 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 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 Stored 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 Stored Value. Passing 'null' to newValue 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().

# Examples

The following are two examples of Custom Functions. The first is written in JavaScript, the second in C#.

## JavaScript Example

Reverses characters in the input string.

    return args[0].split("").reverse().join("");

## C# Example

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.

    // 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;

# Default Custom Functions

Starting with version 2017.2, Exago BI ships with several built-in custom functions. These are functions that are common in many reporting environments, but the manner in which they work may be different depending on locality, time zone, or other factors. For this reason, these functions have been exposed in the Admin Console so that administrators may change how they work.

> Note: If these functions are unavailable, such as on an upgrade, you can use the following setting to restore them to the configuration:
> ( Filter Settings ) Restore All Default Formula Functions

The following custom functions ship with Exago BI:

## MonthName

Given a date value, returns the name of the month of the date. The month name is retrieved from the active language dictionary. So, for example, given the date "01/01/2017", MonthName will return "January" in an English-speaking environment, and "Enero" in a Spanish-speaking one.

## QuarterName

Given a date value, returns the fiscal quarter of the date, as "Q1", "Q2", "Q3", or "Q4". By default, Q1 encompasses January 01 - March 31, Q2 encompasses April 01 - June 30, Q3 encompasses July 01 - Sept 30, and Q4 encompasses Oct 01 - Dec 31. But since different countries or financial landscapes may use different systems of quarters, the behavior of the function is exposed and customizable.

## QuarterNumber

Given a date value, returns the fiscal quarter of the date, as "1", "2", "3", or "4". Otherwise, this function has the same behavior as QuarterName.