Working with Asset Ratings

Topics

Creating a Rating Type
Editing a Rating Type
Searching for a Rating Type
Creating a Rating Formula

Creating a Rating Type

Different types of asset require different types of rating. For example, it is useful to have a structural rating for a water line but not for a vehicle. You can have a risk rating for a vehicle but not for a sidewalk. Accela Civic Platform - Asset enables you to create rating types you can use to rate various asset types, including evaluation of the largest or smallest observation scores. When an inspector creates an asset rating, the inspector must choose a rating type from a drop-down menu of possible rating types. You associate each rating type with an asset group, an asset type, and a condition assessment type so that only the relevant rating types appear in the inspector’s drop-down list of possible rating types. For example, you can do structural ratings of both waterlines and manholes. You can create one structural rating type and link it to the Waterlines asset type and another structural rating type that you link to the Manhole asset type. When an inspector wants to enter a structural rating for a manhole, only the structural rating type linked to the Manhole asset type appears on the drop-down list of rating types. An administrator sets the value range for each rating type.

You can assign ratings values manually or calculated by Civic Platform using an administrator-defined formula. If you allow manual entry of rating values for a rating type, you can choose whether to create a rating formula for that rating type. If you do not create a rating formula, inspectors must give ratings for that asset manually entering rating values. If you do create a rating formula, inspectors can add manual rating values in addition to the rating values generated by the formula. If you do not allow manual entry of rating values for a rating type, you must create a formula to calculate ratings. See Creating a Rating Formula.

Before you can create a rating type, you must create a condition assessment type and an asset type to associate to the rating type. For information on creating condition assessment types, see Creating a Condition Assessment Type. For information on creating an asset type, see Asset Types. To enable asset groups, configure the ASSET_GROUP Standard Choice. Refer to the Accela Civic Platform Configuration Reference.

To create a rating type

Access the Rating Type portlet (Navigating to the Setup Portlet).
Click New.

Civic Platform displays the following.

Complete these fields:

Rating Type	Enter a name for the rating type.
Asset Group	Select from a drop‑down list of available asset groups. The asset group determines which asset types you can choose from.
Asset Type	Select from a drop‑down list of available asset types. The asset type determines which asset fields are available to use as variables for the expression.
Upper Limit and Lower Limit	Enter the maximum and minimum possible rating values.

Select a condition assessment from the Condition Assessment drop‑down menu to assign the Rating Type to.
If you select the Manual Entry Rating Value option, you can either create a rating formula or leave the formula field blank. If you do create a formula, users can enter manual rating values in addition to the calculated rating values. If you do not create a formula, you must enter rating values manually.

If you do not select the Manual Entry Rating Value option, you must create a rating formula.

For information on creating a formula, see Creating a Rating Formula.
Click Submit.

Civic Platform adds the rating type to your Rating Type list.

Editing a Rating Type

After you have created a rating type and linked it to an asset group and an asset type, you cannot change its name or the link. You can change the condition assessment type for the rating type, as well as the upper and lower limits for the rating values. You can make the ratings read-only or enable users to enter new ratings.

To edit a rating formula

Access the Rating Type portlet (Navigating to the Setup Portlet).
Click the Rating Type link of the rating type you want to edit.

Civic Platform displays the Rating Type detail portlet.
Make the desired changes to the available fields.
Click Submit.

Civic Platform updates the Rating Type.

Searching for a Rating Type

To search for a rating type

Access the Rating Type portlet (Navigating to the Setup Portlet).
Click Search.

Civic Platform returns the Rating Type search fields.
Enter search criteria in any of the fields and click Submit.

Civic Platform returns a list of Rating Types that match your search parameters.

Creating a Rating Formula

You can define rating formulas for each condition assessment/asset type combination. The formula can calculate the rating based on a combination of many factors: condition assessments, work orders, service requests, direct updates, and the asset’s rating history. For example, administrators can use specific functions to get the largest or smallest observation scores on a condition assessment. The rating formula also has access to asset details, asset attributes, condition assessment details, and condition assessment attributes. See Rating Type Portlet.

You can manually calculate ratings and you can also set them up to trigger based on the completion of condition assessments. To ensure your rating formula is functional, validate it before applying it to asset records.

Civic Platform stores and date-stamps each rating entry, which enables users to view rating logs and generate graphs of an asset’s rating history. Users can also graph the average condition of a group of assets.

Before you create a rating formula, consider the following information:

You associate rating formulas to asset types, so determine the Asset Type for which you want to create a formula as well as the Asset Group to which it belongs.
You tie rating types to Condition Assessments, which you in turn tie to Asset Types. So in addition to Asset Type and Asset Group, you must know which Condition Assessment you want to contain the rating formula.
Expression criteria determine which records a formula evaluates. These criteria can use any type of field, numeric or alphabetic.
You can only include numeric fields in a formula, so when you determine which fields you want to include in your rating calculation, ensure their value is numeric.
Accela provides the Sum, Count, Average, Max and Min functions. You can use expressions that work with the functions to determine which records a formula evaluates. These criteria can use any type of field, numeric or alphabetic. To limit the records evaluated by a formula, consider creating an expression for the function.
Accela gives you options to create either a classic style or EMSE style formula. The classic style only supports simple scripting while the EMSE style allows rather complicated EMSE script. Please read the steps in this section before deciding which option to take.

Figure: Rating Type Portlet

To add a rating formula to a rating type

Find the Rating Type for which you want to create a formula. See Searching for a Rating Type.

Civic Platform displays the rating detail portlet as shown in Rating Type Portlet
If you select the Manual Entry Rating Value option for the rating type, you can either create a rating formula or leave the formula field blank. If you do create a formula, users can enter manual rating values in addition to the calculated rating values. If you do not create a formula, you must enter rating values manually.

If you do not select the Manual Entry Rating Value option, you must create a rating formula.
Select the Script Style, and define the rating formula.

Classic Style

In the classic style formula, you must directly specify a field value, or an expression, or a mathematical calculation as the rating value. Although you can use IF-ELSE statement, the statement syntax must stick to either of the following formats:
```
if($$CRITERIA$$){} else{} 
```
```
if($$CRITERIA$$){} else if($$CRITERIA$$){} else{} 
 
```
EMSE Style

EMSE Style supports normal EMSE scripts. You can define variables and functions, and use complex IF-ELSE statements in the formula. If you use EMSE style, you must add the following function to set the rating value:
```
ratingFormula.setReturnRating(returnValue)
```

Create a rating formula in the Formula text area that meets the script style you select in .

In the following sub steps, to are applicable to both the classic style and EMSE style; to are only applicable to EMSE style.

Select a variable from the Variables navigation tree to add to the formula.

The variables navigation tree lists all the asset fields and condition assessment fields for the rating type. Use the + and - buttons to expand the navigation tree, find the variable, and then click the variable name to add it in the formula.

Civic Platform adds the field to the rating formula.
Click one of the Math operators from the Operators section to apply it to the rating formula. You can choose from the basic mathematical symbols, including [+], [-], [*], [/], and [%].

Civic Platform adds the operator to the rating formula.
Click one of the Functions from the Operators section for adding the mathematical operation result into the formula.

The Sum, Count, Average,Max, andMin functions display in the Functions category. For description of these functions, see Rating Formula Functions.

Civic Platform displays the following.
Create Expression with the selected function.

Complete the following required fields:

Name	Give the expression a unique name.
Lookup Table Name	Select the table name for the observation associated with the function. The table name you selected affects the options available in the Return column drop-down list.
Return Column	Select a Return Column from this drop‑down list. Return Column is the field in the selected condition assessment that the function evaluates.

Click New in the upper right corner of the window to add a row of criteria to the expression. These criteria determine which values the function includes from the Return Column.

Note:
Adding too many criteria to an expression can cause your system to run slowly or your screen to freeze. To avoid this issue, limit your expression criteria to 30 or fewer.
Choose a field from the Field Namedrop‑down list. This list automatically populates with the fields from the selected condition assessment.
Choose an operator from the Operator drop‑down list. For descriptions of available operator, see Rating Formula Relational Operators.
Choose an operator from the Operator drop‑down list. For descriptions of available operator, see Rating Formula Relational Operators.
Choose a value from the Value drop‑down list. The value you select is the value that the criteria queries. For example, if you chose the Date field name and the = operator, you could enter 5/24/08 in the Value field. The function queries only records whose date field contains 5/24/08 as a value.
Add additional criteria by clicking the New button. Determine the relationship between each criterion by selecting AND or OR from the last Suffix drop‑down list.
Click Save at the bottom of the window to save the expression and add it to the formula.
To view or edit an expression, click its hyperlink name, located in the Expressions section of the Rating Type portlet.
Add IF-ELSE statements in the formula. The classic style supports one-level IF-ELSE statements, and the EMSE style supports complex IF-ELSE statements.

You can define criteria to add as criteria in the IF clause. The steps are the same as the criteria definition steps for expressions except that you define the criteria in the Criteria section. See step d.

Below is a sample classic style formula with an IF-ELSE statement including a criteria and expression. Note that the “if” and “else” must be in lower case.
```
if($$CRITERIA::ta$$) 
```
```
{$$EXPRESSION::test1$$+$$EXPRESSION::test1$$} 
```
```
else if($$CRITERIA::ba$$) 
```
```
{[ASSET::attr1]+10} 
```
```
else {0} 
 
```
(EMSE style only) Add variables and functions in the formula. You can define variables and functions and use them in the formula, same as in normal EMSE scripts. For information on writing EMSE scripts, see the Accela Civic Platform Scripting Guide.

(EMSE style only) Add the function ratingFormula.setReturnRating(returnValue) to set the return value of the formula as the rating value.

Below is a sample EMSE style formula with user-defined variables and functions.

var tempValue1, tempValue2;

if($$CRITERIA::CircleEqual2$$)

   {tempValue1=[CA::LengthNum]}

else{tempValue1=[CA::LengthNum}*5

if($$CRITERIA::MeterLength7$$)

   {tempValue2=[CA::LengthNum]}

else{tempValue2=0}

function addLength(a){return a+tempValue2;}

ratingFormula.setReturnRating(tempValue1+addLength(10))

Before you save the formula, you can validate it to make sure it contains no errors. Click Validate.

Civic Platform returns the validation passed message if the formula meets system criteria.

Civic Platform returns an error message under the following circumstances:
- The formula contains undefined variables.
- The formula contains non-numeric variables.
- The formula contains observation variables that you can only use in defining an expression.
- The formula contains undefined expressions.
- The formula contains undefined criteria. Civic Platform prompts you with correct syntax, if this is a syntax error.

Click Submit.

Civic Platform updates the Rating Types list portlet.

Table 1. Rating Formula Functions
Sum	This function returns the sum of the values of the selected field for the records that match the expression criteria.
Count	This function returns the number of records whose value for the selected field matches the expression criteria.
Average	This function returns the average value of the selected field for the records that match the expression criteria.
Max Min	Together, these functions return the largest or smallest value of the selected field for the records that match the expression criteria. For example, administrators can use a maximum function and a minimum function in the asset rating formula to get the largest or smallest observation scores on a condition assessment.

Table 2. Rating Formula Relational Operators
!=	Not equal to
<	Less than
<=	Less than or equal to
=	Equal to
>	Greater than
>=	Greater than or equal to
IS NOT NULL	Used to query fields that contain any value, regardless of what that value is. When you use this operator, do not use a variable in the third field.
IS NULL	Used to query fields that do not have a value. For example, you might set up a data filter to query for records assigned to a certain department, but not to any individual within the department. When you use this operator, do not use a variable in the third field.
LIKE	The alphabetic character field values that you want to include in the filter or query contain a string (alphabetic characters). For example, if you want to set up a query to list all contacts with the string “Jeff” in their email addresses, choose “Like” as the relational operator and enter “Jeff” as the value.
IN	This operator can substitute multiple criteria. Enter multiple values, and the operator returns records that match any one of the values. When you use the IN operator in an expression, the values you enter must be uppercase. Civic Platform supports only the values A, B, and C, and not a, b, and c, for example.