Create, search, and configure expressions

There are two main steps to create an expression, configure the expression and build the expression. First, you need to open the Expression new section.

To create an expression

1. From the Administration menu, select Application > Expression builder.

2. Select New.

   

You can search for any existing expression.

To search for an expression

1. From the Administration menu, select Application > Expression builder.

2. Select Search.

3. Enter search criteria and then select Submit.

Before you start to build the expression, configure the expression basics including the expression name, the target scope, and how to execute the expression.

To configure the expression

1. Enter an Expression name to describe the purpose of the expression.

   This field allows up to 60 characters, including spaces.

2. Select the Target portlet where users access the expression.

3. Select any other associated fields that appear with the Target portlet you selected, for example, Custom fields group, Custom list subgroup, Attribute template, etc. These associated fields contain the criteria you want use in your expression.

   You can hover over Custom Fields Group to see a list of record types relevant to the group.

   Target portlet	Associated field types	Executable in Civic Platform?	Executable in Citizen Access?
   Custom fields	Custom Fields Group	Y	Y
   Custom lists	Custom Fields Group and Custom List Subgroup	Y	Y
   Address	Custom Fields Group	Y	Y
   Applicant	Custom Fields Group, Contact Type, Contact Template, and Template Table if any associated with the selected contact template	Y	N
   Asset	Attribute Template, and Attribute Table if any associated with the selected attribute template	Y	N
   Asset condition assessment	Condition Assessment	Y	N
   Authorized service customer	-	N	Y
   Authorized service customer address	-	N	Y
   Condition	Custom Fields Group, Template Form, and Template Table if any associated with the selected template form	Y	N
   Condition of approval	Custom Fields Group, Template Form, and Template Table if any associated with the selected template form	Y	N
   Contact (and Contact 1, 2, 3)	Custom Fields Group, Contact Type, Contact Template, and Template Table if any associated with the selected contact template	Y	Y
   Contact address	Custom Fields Group	Y	Y
   Fees	Custom Fields Group	Y	Y
   Parcel	Custom Fields Group	Y	N
   Payment	Custom Fields Group	Y	N
   Professional	Custom Fields Group	Y	Y
   Record detail	Custom Fields Group	Y	N
   Reference address	-	Y	N
   Reference condition	Condition Entity, Template Form, and Template Table if any associated with the selected template form	Y	N
   Reference contact	Contact Type, Contact Template, and Template Table if any associated with the selected contact template	Y	Y
   Reference contact address	-	Y	Y
   Reference parcel	-	Y	N
   Workflow	Custom Fields Group, Workflow, Process, Task Specific Info	Y	N

4. Define the order in the Execute order field to trigger the expressions that work on the same field.

5. From the Execute expression in area, select what type of user to whom you want to expose the expression:

   Field	Description
   ACA Only	Both registered users and anonymous Citizen Access users can access the expression.
   Civic Platform only	Only Civic Platform users can access the expression.
   Both	Exposes the expression to both Citizen Access and Civic Platform users.

   Citizen Access supports expressions for fields from Custom Fields, Custom Lists, Contacts (including generic template fields, template table fields, and people template fields), Fees, and Licensed Professionals.

6. Select the Edit mode. The Edit Mode determines whether you edit the expression by wizard or EMSE script.

   • The Wizard Mode displays the Expressions and Criteria wizard to assist you in building the expressions. See Build the expression in wizard mode section below.

   • The Script Mode displays the Expression script text area in which you can edit the EMSE script manually. See the Accela Civic Platform Scripting Guide.

   You can switch back and forth between modes, as appropriate.

7. Select the Status of the expression. All expressions are active by default. If you set the status of an expression to inactive, the expression does not execute when the expression criteria are met.

8. Select the Execute fields picker and select one or more fields. When the user tabs or moves focus off of an Execute field, the expression executes.

   1. Select the (+) sign to expand the list of items.

      

   2. Select an item to add it to the Execute fields list.

      The selected Custom fields group activates and filters the Custom lists subgroup list. The Additional options list provides the possible events that can trigger the expression:

   • onLoad executes the expression when you create a new record that meets the expression criteria. The onLoad event occurs immediately when a page loads. For example, default the status to Accepted when a user creates a new Building Record Type.

   • onSubmit executes the expression upon saving a record. The onSubmit event occurs when the user selects Submit on the form. For example, if the user changes the status to Accepted by entering “A” in the appropriate field.

   • onPopulate executes the expression when data in the selected field populates based on a search result. It is available when Professional, Contact Address, or Reference Contact Address is the selected target portlet. For example, the following actions can trigger the expression: when the user searches for and selects a Licensed Professional in an application, or when the user selects the Validate button in the contact address form and selects an address to add in the form.

     The following standard choices must be have the indicated configurations in order for the onPopulate option to be available for the professional portlet:

     Standard choice	Setting
     NEW_SPEAR_FORM_ENABLE	Enabled
     MULTIPLE_LICENSE_PROFESSIONAL	Disabled
     MULTIPLE_APO_GIS_SELECTION	Disabled

   • onASITRowSubmit.This event is available only when Custom Lists is the target portlet, and only works in Citizen Access. When a public user submits a new or updated Custom List table row in Citizen Access, if the criteria of an onASITRowSubmit expression are all met, Citizen Access triggers the expression. If you define an onASITRowSubmit expression which sets the blockSubmit property of the Custom List table form to true under certain criteria, Citizen Access can block the submission of Custom List table rows when the criteria are met.

If you select wizard mode to build the expression, you can complete the field names, corresponding expressions, and criteria values in the Expressions and Criteria areas of the wizard.

To build the expression in wizard mode

1. Use the Expressions area to define the field in the expression, and define the way the expression works on the field.

   

   If you specify Custom List as the target portlet for the expression, or select a Custom List Subgroup or attribute table in the target scope, you can only build the expression for the selected table. For a detailed use-case of this feature, see Expression builder scenarios.

   1. Select the field on which the expression affects. You can only select a target portlet field.

   2. Expand the plus sign next to the target portlet in the Variables navigation tree to locate a variable.

      

   3. Select the variable. The variable populates in the Field name.

      You can select “FORM” to execute the expression on the whole target portlet. You can also select a field to change the property of the field.

   4. Specify a Property type for the field. The Property field identifies the type of expression. For example, if you set the field to read-only, the property becomes read-only.

      Property	Description
      Value	Assigns the value in the Calculate expression field to the field.
      Required	Sets the field to required. The Calculate expression field defaults to True, and cannot be changed.
      Read-only	Sets the field to read-only. The Calculate expression field defaults to True, but you can change it to False.
      Message	If you add “FORM” in the Field name, it displays a message in the target portlet. If you add a field in the Field name, it displays a message next to the field.
      blockSubmit	If you add “FORM” in the Field name, this property is available for blocking the submission of the target portlet.

      There is a limitation with contact expressions in Citizen Access. If you are using a contact expression to display a message on the contact form, the “Execute Fields” box of the expression must contain the “onSubmit” option for the message to display when users submit the form. Otherwise, the message cannot display.

   5. Select the Calculate expression field and then, as required for the expression, navigate to the Variables, Operators, or Standard choices navigation trees to locate the field, operator, or value to add to the expression.

      The Variables navigation tree includes Session variables which are the frequently used runtime variables that are standard with Civic Platform. Session variables are available in the WHERE clause of a statement. Session variables display between sets of double dollar signs, for example,

      [$$capID1$$]

      See the Variable table in Step 2c below.

      Use the Operators navigation tree to calculate the expression.

      Operators	Description
      Math operators	Lists mathematical symbols [+], [-]. [*], [/] for operation. The “%” is the modulus, it divides one operand by another and returns the remainder as its result.
      String operators	Joins two strings.
      Custom fields table-lookup() function	Populates fields in the expression with columns from Custom fields lookup tables.
      Aggregate Function	Aggregates multiple values from the Custom fields table, fees, the condition template table, or the asset attribute table.
      fireEMSE function	Fires an EMSE script.
      addDate(Date, int) function	Returns the date appended with a certain date interval.
      diffDate(Date, Date)	Returns the interval between two dates.

   6. The Standard choices navigation tree lists each standard choice available in Civic Platform along with its values that you can use in calculating the expression. The navigation tree lists both enabled and disabled standard choices. For example, if you want to create an action based on when the Status is Completed, locate the standard choice “STATUSCOMPLETED” and use its value in your expression.

   7. To add more expression lines, select Add expression line in the Expressions area.

      To remove an expression line, select it, and select Delete criteria line.

2. Use the Criteria area to define the expression criteria.

   

   1. Select Add criteria line in the Criteria area to add criteria lines.

   2. Select the Field name. Civic Platform uses the field name in the criteria for the expression.

   3. Locate a variable in the Variables navigation tree and then select it. The variable populates in the Field name.

      Variable	Name	Description
      $$ID$$	ID1	Retrieves the record ID from a specific portlet.
      $$ID$$	ID2	Retrieves a second record ID from a specific portlet.
      $$capID1$$	CAPID1	Retrieves the first 5 characters of the record ID from a specific portlet. Example: CAPID1 = 01BLD-00000-00018
      $$capID2$$	CAPID2	Retrieves the second 5 characters of the record ID from a specific portlet. Example: CAPID2 = 01BLD-00000-00018
      $$capID3$$	CAPID3	Retrieves the last 5 characters of the record ID from a specific portlet. Example: CAPID3 = 01BLD-00000-00018
      $$department$$	Department	Retrieves the department of the current user.
      $$firstName$$, $$lastName$$,$$middleName$$	First Name Last Name Middle Name	Obtains first, last, middle name.
      $$gaUserID$$	GA User ID	Retrieves the ID of the current user.
      $$module$$	Module	Retrieves the module from a specific portlet.
      $$portletID$$	Portlet ID	Retrieves information on a portlet, such as a field name.
      $$publicuser_email$$	The public user email id used in ACA.	Retrieves the public user email.
      $$servProvCode$$	Service Provider Code	Retrieves the ID for the agency.
      $$today$$	Today	Retrieves today’s date. The workstation's system date determines this date. You can use this variable parameter in calculations to specify a date range. For example, enter $Today$ -7 to query for all records over the last week.
      $$userfullname$$	User Full Name	Retrieves the user’s full name.
      $$userGroup$$	User Group	Retrieves the group of the logged-in user.
      $$userID$$	User ID	Retrieves the ID of the logged-in user.

   4. Select a logical operator from the Operator drop-down list to identify the criteria for the expression.

   5. Specify the Value for the criteria. You can set this to a static field value, a value from the Custom Fields lookup table, a standard choice value, or a session variable.

      See Custom fields for information on Custom fields lookup tables.

      You can use standard choice values here as static values.

      To look up a Session variable and its value, select the Value field in the Criteria section, navigate to the Session variables navigation tree, and select the value you want. The variable populates in the Value field for the Criteria.

   6. The Prefix is the starting parenthesis in a criteria line (also called “condition”). For Example:

      (Due Date <= $$TODAY$$ AND 
       Status = Approved) OR (Est Date > $$TODAY$$) 

      Both embedded conditions and parallel conditions work in the criteria. You can type one or more “(“ characters as the prefix, or leave it blank.

      Embedded condition: (...(…)…)

      Parallel condition: (..)…(..)

   7. The Suffix is the end parenthesis in a criteria line (also called “condition”). For Example:

      (Due Date <= $$TODAY$$ AND 
       Status = Approved) OR (Est Date > $$TODAY$$) 

      You can type one or more “)” characters as the prefix, or leave it blank.

   8. Select AND/OR options to connect multiple criteria lines.

3. Select Validate to review the expression for errors.

   The Validate button verifies that the syntax is correct. The Validate button does not test field data types or the fields used in the expression.

4. Select Submit to save the new expression in wizard mode.

For information on building expressions using script mode, see the Accela Civic Platform Scripting Guide.