Environment Methods

Environment Methods

There are two different types of script environments available in the addon system. There is the Form Script Environment, which is used for addons that require a user interface consisting of forms and form elements, and the System Script Environment, which is used for addons that are meant to be executed by services or run silently without user interaction in a form-based application. The two different types of script environments each have their own set of methods that are available for use by addon scripts, in addition to several methods that are common to all script environments. Below, you will find links to a list of methods available for each script environment type, as well as a list that represents the methods that are available to all script environments.

Common Environment Methods

This section details the list of methods that are common to all script environments.

  • CreateDatabaseConnection(string connectionFileName): Creates an external database connection that can be used to query a data source.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    connectionFileName

    The name of the connection file to use when creating the connection. This can contain a path, either rooted or relative to the addon's folder.

    Output

    DatabaseConnection



  • CreateManagedDatabaseConnection(): Creates a managed database connection that allows access to the database used by the host application.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Output

    ManagedDatabaseConnection



  • ExecuteCommand(string commandName, object args): Executes a form command supported by the current form using the provided args. The args parameter can be either a single value or a Lua table of values (ie: {"Detail", 0, ...}).

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    commandName

    The name of the command to execute

    Input

    args

    Any data needed by the command being executed

  • GetFieldValue(string fieldSource, string fieldName): Retrieves the value of a field (fieldName) on a data source (fieldSource) exposed by the current form.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    fieldSource

    The name of the data source containing the field

    Input

    fieldName

    The name of the field to retrieve

    Output

    object



  • GetSetting(string settingName): Retrieves the value of the specified setting from the addon settings. The setting value will automatically be converted to the correct type based on the type specified in the setting's definition.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    settingName

    The name of the setting to be retrieved

    Output

    string, bool, or double



  • GetStaticValue(string name): Retrieves the value of the specified static value from the internal static value storage collection.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    name

    The name of the static value to be retrieved

  • LogDebug(string message): Writes the message to the debug log.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    message

    The message to be logged

  • Print(DataTable table, string dataSource, string templateDocuments): Prints data from an addon provided table using the provided data source and template documents.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    table

    The table of information that should be printed

    Input

    dataSource

    The name of the xls file the data should be added to when printing

    Input

    templateDocuments

    The documents that should be merged with the xls file when printing

  • SetFieldValue(string fieldSource, string fieldName, object value): Sets the value of a field (fieldName) on a data source (fieldSource) exposed by the current form to the given value.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    fieldSource

    The name of the data source containing the field

    Input

    fieldName

    The name of the field to set

    Input

    value

    The new value of the field

Form Script Environment Methods

The Form Script Environment is used for addons that have a Type of "Addon".

  • GetClientImage(string Name): Retrieves an Image object corresponding to the name provided from the application resources file.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    name

    The name of the image to retrieve.

    Input

    image



  • GetInterfaceManager(): Retrieves the ScriptInterfaceManager associated with the current script.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Output

    ScriptInterfaceManager



  • GetLocalImage(string path): Retrieves an Image object based on the file provided by the path argument. The path can be either rooted or relative to the script file's location.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    path

    The path to the image file to load.

    Output

    Image



System Script Environment Methods

The System Script Environment is used for addons that have a type of "System" or "Server", with the exception of the ProcessDataContexts method, which can only be used with server addons. 

  • ProcessDataContexts(string contextIDType, object contextIDs, string methodName): Initiates iterative processing of a list of data contexts that match the parameters specified by the contextIDType and contextIDs. The third parameter, methodName, represents the name of a callback method that is called for each data context. Inside of the callback method, all methods that operate on a script-managed data source (GetFieldValue, SetFieldValue, and SaveDataSource) will operate on the data context currently being processed. Data contexts can include multiple pieces of information such as the Transaction, User, and Lender associated with a given transaction number. The list of valid context id types will vary based on the context in which the addon is running. An example of how this method is used, as well as a list of the context types allowed can be found by referencing the Processing Data Contexts topic. The contextIDs parameter can be either a single value or a Lua table of values (ie: {15631, 19867, ...}).

    The ProcessDataContexts method can only be used with server addons. It is not compatible with system addons.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    contextIDType

    The context ID type that should be used when retrieving the list of data contexts to be processed.

    Input

    contextIDs

    A context ID or list of context IDs that should be used when retrieving the list of data contexts to be processed.

    Input

    methodName

    The name of the Lua method that should be used as the callback method for processing each data context.

  • RegisterSystemEventHandler(string eventName, string handlerName): Registers the method identified by the handlerName parameter as an event handler for the system event identified by the eventName parameter.  Registered handlers will be called each time the host application fires the handler's corresponding event.  When an event is fired, any pieces of data related to the event are treated as system managed data sources and can be modified using the same methods as other system managed data sources (GetFieldValue, SetFieldValue and SaveDataSource). For a list of events for which addons may register, see the Handling System Events topic. Only one addon with a type of system can register for a given system event. Attempting to register for an event for which another system addon is already registered will result in an error. Server addons are not subject to this limitation.

    The RegisterSystemEventHandler method can only be used within an addon's Init function.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    eventName

    The name of the event for which to register.

    Input

    handlerName

    The name of the Lua method that will act as the event handler.

  • SaveDataSource(string dataSource): Saves a modified system managed data source.

    Direction

    Name

    Description

    Direction

    Name

    Description

    Input

    dataSource

    The name of the data source to be saved.