User-defined functions (UDRs)

This page explains how to create and use user-defined functions (UDFs) in Simple Issue Language (SIL) programs to organize code into reusable components.

You can create and use user-defined functions in your SIL programs to encapsulate reusable logic. They help improve code organization, readability, and maintainability by breaking complex operations into smaller, manageable pieces.

Syntax and basic usage

A function is defined using the following syntax:

function <name>(<type> param1, <type> param2, ...) {
    Instruction1;
    ...
    InstructionN;
    return <value>;
}

When creating a function, keep in mind the following key points:

The <name> of the function cannot contain spaces, and it cannot start with a number.
Parameters can be any valid SIL type.
The return statement is optional.

On this page: 1 Syntax and basic usage 1.1 Example 2 Function definition 3 Parameters definition 3.1 Pass-by-value behavior 3.2 Constant parameters 3.3 Default parameters 4 Variable visibility in UDFs 4.1 Best practices for using variables in UDFs 5 Return value 5.1 Important notes about returns 5.2 Best practices for return values

Example

This example function calculates issue priority based on severity and environment. It uses conditional logic to demonstrate parameter passing.

function calculatePriority(string severity, string environment) {
    if (severity == "Critical" && environment == "Production") {
        return "Highest";
    } else if (severity == "Critical" && environment == "Development") {
        return "High";
    } else if (severity == "Major" && environment == "Production") {
        return "High";
    } else {
        return "Medium";
    }
}

// Usage examples:
string newPriority = calculatePriority("Critical", "Production");  // Returns "Highest"

Description

The function calculatePriority("Critical", "Production") receives "Critical" and "Production" as inputs and checks the first condition against an actual Jira issue. If the condition is met, it changes the priority of the Jira issue to Highest. If the condition is not met, the function continues by checking the next condition and so on.

This function can be reused throughout your SIL program whenever you need to calculate priority based on severity and environment; for example, when issues are created, when priority or environment fields are updated, as part of validation rules, or in bulk update operations.

Function definition

SIL has a strict rule about where function definitions can appear in your code. This rule helps ensure that all functions are available when needed and prevents potential issues with code organization and variable scoping.

All functions must be defined before any executable code.

The correct order must be:

Global variable declarations (with initialization if needed) and any constant declarations.
Function definitions
Executable code

Invalid definition example

// This is INVALID:
number i;                 // Variable declaration
const number pi = 3.14;   // Constant declaration
i = 0;                    // Error line, this is code execution - NOT ALLOWED HERE
function circleArea(number r) {
    return r * r * pi;
}

The error occurs because you can't have executable code (like i = 0; where i is initialized to a constant) before function definitions.

Valid definition example

// This is VALID:
number i = 0;            // Global variable declaration with initialization
const number pi = 3.14;  // Constant declaration

// Functions must be defined after declarations but before executable code
function circleArea(number r) {
    return (i + r) * (i + r) * pi;
}

// Executable code comes after all function definitions
number r = 10;
runnerLog("Area of radius " + r + " is " + circleArea(r));       //returns Area of radius 10 is 314
i++;
runnerLog("Area of radius " + (r + i) + " is " + circleArea(r));  // returns Area of radius 11 is 379.94

Running the above code in SIL Manager returns the following (in the Editor console):

The screenshot shows the results in the Editor console after the code is executed.

Parameters definition

Here’s what you need to know about parameters definition in a function:

Parameters can be of any valid SIL type (string, number, boolean, etc.)
Parameters are passed by value; changes inside the function don't affect the original variables.
The parameter list can be of any length; it can be empty.

Examples

This example illustrates how different parameter types are defined and used in a function.

// Function with no parameters
function zero() {
    return 0;
}

// Function showing different parameter types
function processData(
    string name,           // Single string parameter
    number age,            // Single number parameter
    number[] scores,       // Array of numbers
    boolean isActive,      // Boolean parameter
    string[] comments      // Array of strings
) {
    // Using the parameters
    runnerLog("Processing data for: " + name);
    runnerLog("Age: " + age);
    runnerLog("First score: " + scores[0]);
    runnerLog("Status: " + isActive);
    runnerLog("First comment: " + comments[0]);
}

// Example usage:
string studentName = "John";
number studentAge = 20;
number[] testScores = {95, 87, 92};
boolean active = true;
string[] feedback = {"Good work", "Needs improvement"};

processData(studentName, studentAge, testScores, active, feedback);

Running the example usage code in the SIL Manager returns the following result:

Pass-by-value behavior

Parameters in UDFs are passed by value in the following way:

A copy of the value is passed to the function.
Changes to the parameter inside the function don't affect the original variable.
The original variable keeps its value after the function exits.
Pass-by-value behavior is the same for all SIL basic types, arrays, and structs.

Example

This example demonstrates pass-by-value behavior for a UDF that takes a number parameter and adds 10 to it.

function updateScore(number score) {
    // Because of pass-by-value, 'score' is a local copy
    score = score + 10;                // Any changes to score parameter won't affect the original value
    runnerLog("Inside function, score is: " + score);
    return score;
}

// Test the function
number testScore = 75;       //testScore variable created and set to 75
runnerLog("Before function call: " + testScore); //shows 75

number newScore = updateScore(testScore);

runnerLog("After function call:");
runnerLog("Original score: " + testScore);   // Still 75 - unchanged
runnerLog("New score: " + newScore);         // 85 - returned value

If run in the SIL Manager, the function returns the following result:

Example description

First, the function gets a copy of the testScore = 75 value to work with.
Inside the function, it adds 10 to that copy, making it 85. The function prints this value: "Inside function, score is: 85"
After the function exits, both the original score (75) and the modified score (85) are printed.

Constant parameters

Parameters of UDFs can be made read-only by using the const keyword within the function.

Example

function f(const string s) {
	...
}

Default parameters

Parameters can have default values. The default value is used only when you don't provide a value for that parameter when calling the function. When you provide a value, it overrides the default.