Creating Expressions

You can create new expressions or modify existing expressions. Expression Builder provides a wizard for building new expressions. You can also use scripts to build new expressions. Refer to the Accela Civic Platform Scripting Guide. To learn about specific uses of Expression Builder and its effect on the Civic Platform daily users, see the several scenarios introduced in Demonstrating Expressions with Scenarios.

Topics

Accessing the Expression Creation Portlet

You can access the expression creation portlet from the Administration Setup portlet.

To access the expression creation portlet in Expression Builder

  1. Access the Expression Builder portlet (Accessing the Expression Builder Portlet).

  2. Click New to create a new expression.

    Civic Platform displays the expression creation portlet.



Configuring the Expression

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 a brief name to best describe the function or purpose of the expression. The Expression Name field can have up to 60 characters, including spaces.

  2. Specify the Target Portlet where users access the expression.

  3. Specify the ASI Group, ASI table subgroup, or the template attributes that associate with the target portlet and contain the fields you want to place the expression in.

    For the types of fields that you can specify with a target portlet, see Associated Field Types for Expression Creation in Target Portlet.

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

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

  5. From the Execute Expression Inarea, choose what type of user you want to expose the expression:

    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.
    Note:

    Citizen Access supports expressions for fields from ASI, ASI Table, Contact (including generic template fields, template table fields, and people template fields), Fee, and Licensed Professionals.

  6. Select an 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 Building the Expression in Wizard Mode.

    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. Click 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. Click the (+) sign to expand the list of items.

      The fields within each portlet, the associated fields, and Additional Options for onLoad and onSubmit display.



    2. Click an item to add it to the Execute Fields list.

      The selected ASI group activates and filters the ASI subgroup drop‑down list. Additional Options provide 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 clicks Submit on the form. For example, if the user changes the status to Accepted by entering “A” in the ASI 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 clicks 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:

      NEW_SPEAR_FORM_ENABLE Enabled
      MULTIPLE_LICENSE_PROFESSIONAL Disabled
      MULTIPLE_APO_GIS_SELECTION Disabled
    • onASITRowSubmit.This event is available only when ASI Table is the target portlet, and only works in Citizen Access. When a public user submits a new or updated ASI 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 ASI table form to true under certain criteria, Citizen Access can block the submission of ASI table rows when the criteria are met.

      Table 1. Associated Field Types for Expression Creation in Target Portlet
      Target Portlet Associated Field Types Executable in Civic Platform? Executable in Citizen Access?
      ASI ASI Group Y Y
      ASI Table ASI Group, and ASI Table Subgroup Y Y
      Address ASI Group Y Y
      Applicant ASI 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 ASI Group, Template Form, and Template Table if any associated with the selected template form Y N
      Condition of Approval ASI Group, Template Form, and Template Table if any associated with the selected template form Y N
      Contact (and Contact 1, 2, 3) ASI Group, Contact Type, Contact Template, and Template Table if any associated with the selected contact template Y Y
      Contact Address ASI Group Y Y
      Fees ASI Group Y Y
      Parcel ASI Group Y N
      Payment ASI Group Y N
      Professional ASI Group Y Y
      Record Detail ASI 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 ASI Group, Workflow, Process, Task Specific Info Y N

Building the Expression in Wizard Mode

If you select Wizard Mode to build the expression, you can fill 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.



    Note:

    If you specify the ASI table as the target portlet for the expression, or select an ASI table subgroup, or attribute table in the target scope in , you can only build the expression for the selected table. For a detailed use-case of this feature, see Adding a Row in an Asset Attribute Table.

    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.

      The variables navigation tree displays the available fields for your selection.



    3. Click 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.

      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, but you can change it to False.
      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, displays a message in the target portlet. If you add a field in the Field Name, 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.
      Note:

      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. Click 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 Session Variables.

      Use the Operators navigation tree to calculate the expression.

      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.
      Lookup ASI Table-lookup() Function Populates fields in the expression with columns from ASI lookup tables. For more details on using the ASI Lookup Tables, see Creating ASI Lookup Tables and Populating Fields in ASI Section.
      Aggregate Function Aggregates multiple values from the ASI 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 click Add Expression Line in the Expressions area.

      To remove an expression line, select it, and then click Delete Criteria Line.

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



    1. Click Add Criteria Line in the Criteria area to add criteria lines.

    2. Click 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 click it. The variable populates in the Field Name.

    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 ASI lookup table, a Standard Choice value, or a session variable.

      See Defining Custom Fields (Application Specific Information) for information on ASI lookup tables.

      You can use Standard Choice values here as static values.

      To look up a Session Variable and its value, click the Value field in the Criteria section, navigate to the Session Variables navigation tree, and then click 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. Click 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. Click Submit to save the new expression in wizard mode.

    Table 2. Session Variables
    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 NameLast NameMiddle Name Obtains first, last, middle name.
    $$gaUserID$$ GAUserID 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$$ ServiceProviderCode 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$$ UserFullName Retrieves the user’s full name.
    $$userGroup$$ UserGroup Retrieves the group of the logged-in user.
    $$userID$$ UserID Retrieves the ID of the logged-in user.