Supported Utility Functions in Python Code Fields
When calculations or special logic are required by agency entities and agency views, the calculations must be entered in the appropriate field by using utility functions and Python syntax. The system supports full IronPython functionality. In addition to IronPython, you can also incorporate custom Python modules, and use code utilities supplied with the system.
These functions, modules, and utilities can be used to perform field validations by entering code in the Value field for the calculation validation rule on the Agency Field Summary. They can also be used to perform calculations and special logic in the On Save field on the Agency Entity Summary and in the On Create field on the Agency View Summary.
Note: The On Save, On Create, and graphic Code fields include a text editor that enables you to indent lines by using the Tab key. As a result, you cannot use the Tab key to navigate out of these fields as you can in other fields. Conversely, you cannot use the Tab key to indent lines in the Value field, but must instead type four spaces to indent lines of code.
When referencing a field from a Parent AgencyEntity instead of a ParentEntity, the value for ParentEntity is not defined until the record is saved. In order to detect this condition, check if ParentEntity is available in the set of local variables. For example:
if 'ParentEntity' in locals():
<your calculation here>
System Utility Functions
The following is a sample list of functions available to use with IronPython.
String Manipulation Functions |
||||
|
Method Name |
Parameters |
Return Type |
Description |
Integer |
(str numStr) |
int |
Converts string to an integer |
|
IsNull |
(str src) |
bool |
Value is null |
|
LeftTrim |
(str src) |
str |
Removes spaces from beginning of the string |
|
Len |
(str src) |
int |
Length of the string |
|
Match |
(str sub, str str) |
int |
Determines whether a string's value contains a particular pattern of characters |
|
Replace |
(str src, int start, int length, str replacement) |
str |
Replaces a portion of one string with another |
|
Right |
(str src, float length) |
str |
Obtains a specified number of characters from the end of a string |
|
RightTrim |
(str src) |
str |
Removes spaces from end of the string |
|
SafeStr |
(str? val) |
str |
Gets the String Val or defaults to Empty String if Val is None |
|
SafeStr |
(str? val, str defaultValue) |
str |
Gets the String Val or Default Value if Val is None |
|
String |
(float num) |
str |
Coverts to string value |
|
Substr |
(str src, float start, float length) |
str |
Substring of a string value |
|
Trim |
(str scr) |
str |
Removes leading and trailing spaces from a string |
|
Upper |
(str scr) |
str |
Uppercase letters |
|
Math and Number Based Functions |
||||
Method Name |
Parameters |
Return Type |
Description |
|
Abs |
(float src) |
float |
Absolute value |
|
ACos |
(float src) |
float |
Arc cosine of an angle |
|
ASin |
(float src) |
float |
Arc sine of an angle |
|
ATan |
(float src) |
float |
Arc tangent of an angle |
|
Avg |
(float[] list) |
float |
Average of the values of the column |
|
Ceiling |
(float value, float significance) |
float |
Smallest whole number that is greater than or equal to a specified limit |
|
Cos |
(Number src) |
float |
Cosine of an angle |
|
Count |
(float[] list) |
int |
Total number of row |
|
Exp |
(float src) |
float |
Exponential (to the specified power) |
|
Fact |
(int factor) |
int |
Factorial of a number |
|
IsNumber |
(str numStr) |
bool |
Value is valid number |
|
Log |
(float src) |
float |
Natural logarithm of a number |
|
LogTen |
(float src) |
float |
Base 10 logarithm of a number |
|
Max |
(float[] list) |
float |
Maximum value |
|
Median |
(float[] list) |
float |
Median of the values |
|
Min |
(float[] list) |
float |
Minimum value |
|
Mod |
(int num, int den) |
int |
Remainder (modulus) of a division operation |
|
Number |
(str numStr) |
float |
Converts the string to valid number |
|
Pi |
() |
float |
Multiplies pi by a specified number |
|
Round |
(float src, float decimals) |
float |
Rounds a number to the specified number of decimal places |
|
SafeNum |
(float? val) |
float |
Gets the Number Val or defaults to 0 if Value is None Note: The SafeNum function returns a zero or a default number if the field referenced is null. In order to skip the calculation using a field when it is null, a conditional statement can be used. For example: If Entity.Field is not None: <your calculation here> |
|
SafeNum |
(float? val, float defaultValue) |
float |
Gets the Number Val or Default Value if Val is None Note: The SafeNum function returns a zero or a default number if the field referenced is null. In order to skip the calculation using a field when it is null, a conditional statement can be used. For example: If Entity.Field is not None: <your calculation here> |
|
Sin |
(float src) |
float |
Sine of an angle |
|
Sqrt |
(float src) |
float |
Square root of a number |
|
StDev |
(float[] measurements) |
float |
Standard deviation of a data set |
|
StDevP |
(float[] measurements) |
float |
Standard deviation of a population from which your data is a sample |
|
Sum |
(float[] list) |
float |
Sum of the values |
|
Tan |
(float src) |
float |
Tangent of an angle |
|
Trunc |
(float value, float places) |
float |
Truncates a number to the specified number of decimal places |
|
Var |
(float[] measurements) |
float |
Variance for the specified column |
|
Date Time Functions |
||||
Method Name |
Parameters |
Return Type |
Description |
|
Date |
(int year, int month, int day) |
DateTime |
Valid date to a value of data type date |
|
DateTime |
(int year, int month, int day, int hour, int minute, int second) |
DateTime |
Date and a time value into a DateTime value |
|
IsDate |
(str dateStr) |
bool |
Value is valid date |
|
IsTime |
(str timeStr) |
DateTime |
Value is valid time |
|
Now |
() |
DateTime |
Current time |
|
Today |
() |
DateTime |
System date and time |
|
Data Access FunctionsFor the methods listed in the following table, the notation [T] is used to represent .NET generic types in Python. The notation "*str" represents an optional list of strings. A parameter "dict filter" is a key value pair python object, for example: filter = { 'fieldName': somevalue, 'IsBoolField': True } |
||||
Method Name |
Parameters |
Return Type |
Description |
|
Retrieve[T] |
(dict filter, *str includes) |
T |
Returns one entity of the type T that matches the key value pair filter provided. Includes is used to load associated entities during the same call. This parameter is optional. |
|
RetrieveById[T] |
(number id) |
T |
Returns one entity of type T that matches the system ID provided. |
|
RetrieveByName[T] |
(str name, *str includes) |
T |
Returns one entity of type T that matches the Name provided. Includes is used to load associated entities during the same call. This parameter is optional. |
|
List[T] |
(dict filter, *str includes) |
[] of T |
Returns an array of models of type T that match the key value pair filter provided. Includes is used to load associated entities during the same call. This parameter is optional. |
|
LoadProperty[T] |
(T entity, str navigation property) |
No return type (void) |
Loads a child entity onto the entity that is passed in (T entity). |
|
Custom Python Modules
Perform the following steps to create and use a custom Python module script:
Have a known directory that is readable from the WCF site (we will assume C:\CustomScripts\).
Create the Python file, and be specific about the name (we will assume C:\CustomScripts\CustomModule.py).
Begin the file with a function with correct Python syntax:
def SampleFunc(Repo, Entity, ParentEntity, passStr, failStr):
# The pound symbol is used for comments.
# Remember the colon at the end of the function definition.Add the code from the agency entity that you would like to move into a reusable Python module function.
Note: Be certain to account for all variables. In the previous example, Repo, Entity, and ParentEntity are system objects, and passStr/failStr are variables extracted from function.To call the module function from the Code, On Save, or On Create fields, use code similar to the following line and a module function call:
import sys; sys.path.append('C:\CustomScripts'); import CustomModule; CustomModule.SampleFunc(Repo, Entity, ParentEntity, "Pass String", "Fail string")You can now test the code on a sample agency view to check for errors. The code from the script can be updated and edited without further modifying the agency entity, and the code changes will be immediately reflected in the associated agency view.
Related topics:
