Module: formula

Enumeration: OpNotation

Operator Notation defines an operator's lexical classification; often just referred to as a "type" of operator.

None	0	no operator for this function; it must be written as a function call eg SUM(x, y, z)
Infix	1	the operator appears between two operands; eg X + Y
Prefix	2	the operator appears before a single operand; eg -X
Postfix	3	the operator appears after its operand; eg X²
Grouping	4	the operator groups an expression; eg the parens in (X + Y) * 2
Postcircumfix	5	the operator follows a term (presently symbols/function names only) and encloses another term
Separator	6	the operator is used to separate arguments in a list

Enumeration: OpName

Add	1
Subtract	2
Multiply	3
Divide	4

Typedef: NumberToken

Base type: string

A Number token represents a numeric value input by the user. Depending on what is in this token, it will be an integer or floating point value

Typedef: StringToken

Base type: string

A String token represents a string value in a formula; this can contain any unicode character

Typedef: Symbol

Base type: string

A symbol represents a function name and should match something from the getOperations endpoint

Struct: OpSignature

Key	Field	Type	Description	Requiredness	Default value
1	returnType	field_data.FieldType	the return type of the function when called in this way	default
2	argTypes	list<field_data.FieldType>	an acceptable list of argument types	default
3	varArgs	bool	the function can take a variable number of arguments/terms; the final argument can be provided 0 or more times.	default	false

An "OpSignature" is one set of valid argument types for a function. eg, for a given set of argument types, it will return the given type. Many functions will have a single signature only. Infix operators will always have two arguments, prefix and postfix always one.

Struct: Operation

Key	Field	Type	Description	Requiredness	Default value
1	operationName	OpName		default
2	description	string	a short description of the operation eg "add two numbers together" (localized) - intended for tooltips etc	default
3	notation	OpNotation	the "notation" defines where the operator appears in relation to its arguments	default
4	precedence	i32	in the absense of parentheses, this indicates the priority of the operator. Lower numbers mean more tightly binding (eg, × has a lower value than +)	default	-1
5	signatures	list<OpSignature>	valid types for the arguments and return values of this operation	default

An operation is either a function or an operator. An operator may be sent in function style, or it can be sent using its operator name according to its allowable notation. Many facts included here are simple to provide, and while not useful to simple interfaces are invaluable for ones which want to do things like context-aware completion or restriction of arguments to relevant types.

Struct: FieldReference

Key	Field	Type	Description	Requiredness	Default value
1	fieldType	field_data.FieldType	the type of the field, the same as the type on the field.Field	default
2	fieldClientId	string	in template authoring, this field contains the referenced field using the client Id	optional
3	fieldId	string	specifying field by step.Field.id instead. Always set on steps in materialized jobs	optional
4	fieldTitle	string	set on the template version of a formula; this is the title of the input referred to. Broken references retain this value.	optional
5	stepClientId	string		optional
6	jobBaseStepId	string		optional
7	stepTitle	string	set on the template version of a formula with inter-step references; this is the title of the step referred to. Broken references retain this value.	optional

Union: FormulaToken

Key	Field	Type	Description	Requiredness	Default value
1	op	OpName		default
2	num	NumberToken		default
3	str	StringToken		default
4	ref	FieldReference		default
5	sym	Symbol		default

A formula token is something that can be entered or selected by a user and appear in a formula input box.

Union: NodeContent

Key	Field	Type	Description	Requiredness	Default value
1	value	field_data.ExecutionData	the value is an "immediate" value, and re-uses the type of field execution data	default
2	fieldRef	FieldReference	the value is a reference to another field's input value	default
3	operationName	OpName	the value is a result of calling the named function	default

A formula term represents an parameter/argument to a formula function at a particular location.

Struct: FormulaNode

Key	Field	Type	Description	Requiredness	Default value
1	content	NodeContent	the content of this node - string or reference	default
2	nodeType	field_data.FieldType	the return type of this formula node	default
3	funcArgs	list<FormulaNode>	if a function node, the parameters/arguments to the function	default

A formula Node is an "Operation Tree" (usually just called OpTree) representation of a formula expression. Valid formulae will have one of these once they are compiled from the list of tokens. Each node represents a single function call or operator, and the result of the entire expression is obtained by recursively evaluating from the deepest node upwards.

Struct: FormulaError

Key	Field	Type	Description	Requiredness	Default value
1	errorMessage	string	localized message	default
2	errorPos	i32	position in the list of tokens where the error is	optional

A formula error contains details of a problem with a formula. It typically indicates the first problem detected, not all possible problems with the formula.

Struct: Formula

Key	Field	Type	Description	Requiredness	Default value
1	formulaTokens	list<FormulaToken>	list of tokens for expression	default
2	expr	FormulaNode	compiled form (set if valid)	optional
3	error	FormulaError	lerror description (if not valid)	optional

A Formula is the container structure for a formula on a field. You create a formula by sending a list of tokens and attaching it. The response will have expr set if valid, and error set if not valid.

Struct: ValidateResult

Key	Field	Type	Description	Requiredness	Default value
1	error	FormulaError		optional

Function: FormulaService.getOperations

list<Operation> getOperations(common.UUID teamId)
    throws common.SystemException

Get a current list of available formula operations. This includes functions and operators. It's generally fixed across all teams, except for functions still in beta testing. You can omit teamId to only get production-ready operations available to everyone.

Function: FormulaService.validateFormula

ValidateResult validateFormula(list<FormulaToken> formulaTokens)
    throws common.SystemException