You can use a user-defined action defined as a function, hereby called User Function, in the expressions of your eSpace, just like any other built-in function.

Although a query condition is a boolean expression where some built-in functions are allowed, it does not allow the use of User Functions.

How to use a User Function

  1. Launch the Expression editor to edit your expression. See About an Expression

  1. Put the cursor in the expression where you want to insert the function call.

  1. Expand the User Functions or the Referenced Functions folder in the Scope tree and double-click the desired User Function.

  1. Complete the invocation of the function by assigning values to its parameters, if any.

You can directly type the function invocation in the Expression editor canvas. Also, if you are editing a property that allows expressions, you can type inline the function invocation in the Properties window.

Function call syntax

Since user functions allow optional parameters, when invoking a function, the parameters' order is significant. However, you can map arguments with no specific order as long as you name the corresponding parameters. In any case, Service Studio will enforce the arguments' order to match the parameters' by automatically rearranging them in the expression.

If you're editing the expression in the Expression editor, this rearrangement occurs when you press the Verify or the Ok button.

The syntax to use the parameters' name in the function call is as follows:

function (<parameter name>: <value>) a e.g. TriangleArea (b:12, h:14)

As is, any argument with no parameter name will be mapped with the parameter that holds the same position in the user function declaration, in the eSpace tree. However, when you name argument x that occupies position i in the function declaration, if an unnamed argument is to follow, it will be mapped with a parameter in position i+1. For example, in the function call GetEmployee ("Department", 2, Vehicle:"Car", "Manager"), where the Vehicle position is actually the 8th, "Manager" will be mapped with the 9th parameter.

Using the function TriangleArea of the above example and assuming that parameters are ordered b first and then h, you have the following situations:

Correct

TriangleArea (12,14), TriangleArea (b:12,14), TriangleArea (12, h:14) or TriangleArea (h:14, b:12)

will all be correct and will do exactly the same.

Incorrect

TriangleArea (14, b:12)

will be incorrect because the first argument has already been mapped with b.

Whenever you change the parameters' position for the user function, in the eSpace tree, all function calls will be changed accordingly. However, if you delete a parameter of the function, to prevent loss of work, Service Studio will change all invocations of that function in all the expressions of the eSpace. It does so by placing the old arguments at the end of the function call, naming them if they weren't.

For example, if you delete parameter b of function TriangleArea above, the function call TriangleArea (12,14) will be changed to TriangleArea (14, b:12). As b no longer exists, the expression becomes invalid and the TrueChangeTM detects an expression error.

The text added to your function calls may be an annoyance if what you really want is to actually delete the parameter without further changes. As there may be a large number of expressions involved, Service Studio allows you to fix all at once (related to that particular parameter) in the TrueChangeTM tab of the Lower Pane.

Examples of function calls:

  1. User function BestEmployeeOf call

Input parameters

Output parameters

Function calls

  1. BestEmployeeOf (CriteriaId, "Week") a "Johnatan Doherty"

  2. BestEmployeeOf (IntegerToEntityRefInteger (5) , "Quarter") a "Mary Smith"

  3. BestEmployeeOf (CriteriaId) a "Anne Lloyd"

If you switch the parameters position of BestEmployeeOf(period,criteria), the above function calls will be automatically changed to:

  1. BestEmployeeOf ("Week", CriteriaId) a "Johnatan Doherty"

  2. BestEmployeeOf ("Quarter", IntegerToEntityRefInteger (5)) a "Mary Smith"

  3. BestEmployeeOf (criteria: CriteriaId) a "Anne Lloyd"

If you delete the parameter period of BestEmployeeOf, the same function calls would be automatically changed to:

  1. BestEmployeeOf (CriteriaId, period: "Week") a Error

  2. BestEmployeeOf (IntegerToEntityRefInteger (5) , period: "Quarter") a Error

  3. BestEmployeeOf (CriteriaId) a "Anne Lloyd"

  1. Varied functions calls

GetPriorityCustomers ()[i].Customer.Name a "Suzanne Commodore"

GetPriorityCustomers ().current.Customer.Name a "Suzanne Commodore"

GetSessionUser() a (a User record is retrieved to, for example, the property Source Record of a Show Record widget).

For function CalculateHigherExpectancy with parameters age,region (optional) and period, consider the following function calls after applying the specified operations in a sequence:

  1. CalculateHigherExpectancy(18,period:"Year") + 2 a 78

  2. (after switching the order of age with region) --> CalculateHigherExpectancy(age:18,period:"Year") + 2 a 78

  3. (after deleting parameter region) --> CalculateHigherExpectancy(age:18,period:"Year") + 2 a 78  

 

See Also

Expose an Action as a User Function | Action Properties | Expression Editor | Overview of Built-in Functions | Fix Expression Errors