Defining a calculation

A calculation definition contains basic information, applicability, and operations.

About this task

The main parts of a calculation are the operations and the expressions. Operations determine what the calculation does:
  • At a minimum, one Set Field operation is mandatory.
  • A calculation can optionally have multiple Input Field operations and multiple Variable operations.
  • The operations are processed in the order listed. The operations can be reordered.
  • Place the Set Field operations last in the list.
  • An expression must be valid and free of syntax errors to save an operation.
Tip: If you are having trouble getting the syntax correct for an expression, provide a dummy expression like 1+2 so that you can save the operation and not lose your work if the session times out.

Procedure

  1. Click Open Administration menu Administration menu > Solution Configuration > Calculations.
  2. Click New Calculation.
  3. Enter an internal Name for the calculation.

    Allowed characters are A-Z, a-z, 0-9, underscore, hyphen, and spaces. Special characters are not allowed.

  4. Enter a Description.
    Note: For complicated calculations, provide a short statement that describes each operation. This ensures that anyone who follows you can understand and debug the calculation.
  5. Leave Enabled selected. It can be changed later.
  6. Select an Object Type. It cannot be changed later.
  7. Select Manual or Automatic in Calculation Type.
    • Manual calculations are started only by a run a calculation action in a workflow.
    • Automatic calculations are started in all other ways except by a run a calculation action in a workflow.
  8. Click Create.
    The window expands. The word Draft and the version number, 1, are displayed next to the calculation name. You can begin defining the calculation.
  9. In Applicability you define the conditions for the calculation. Expand Applicability and click New Condition. The Applicability panel opens.
    • Leave Applicability empty if the calculation runs for all objects of the object type.
    • Add conditions to restrict the calculation to specific objects of the object type.
    • For each condition, you build a comparison statement with two fields and an operator.
    • If you define multiple conditions, all conditions must be met for the calculation to start.

      To override this rule, define Advanced Logic to combine the conditions in a specific way.

    Note: Do not use the System Comment field (System Fields:Comment) in calculations. This system field is a special field that is used with File (SOXDocument) and Signature objects.
    1. In Compare, you define the first field in the comparison statement. You can choose:
      • A field in the current object

        Select an Object Field.

      • A field in a related object
        • Select Direct Child, Direct Parent, Ancestor, or Descendant in Relationship Type.
        • Select an object type in Related Object Type.
        • Select a field in Related Object Field.
        • Select a path in Relationship Paths (displays only if Relationship Type is Ancestor or Descendant).
        • Add Filter By conditions.
        • Set Primary Parent Only (displays only if Relationship Type is Direct Parent or Ancestor).
      • A field in a Preference object

        Select a Preference Object Field. You can add Filter By conditions.

      • End User

        An End User condition checks whether the signed on end user is a specified user and whether the user is in a specified user group. The second field in the comparison statement is a specified value, an expression, or an actor field on an object.

    2. In Using, choose an Operator. The list of operators depends on the field type of the field that you chose in Compare.
    3. In To, you define the second field in the comparison statement. You can choose:
      • A specified value

        The value that you can provide depends on the field type of the field you chose in Compare. The comparison is case-sensitive, so ensure that you specify the correct case for the value.

      • An expression

        Enter an expression that uses a single field or variable from the list in Using variables, functions, and fields. All the variables and fields listed there can be used in an expression. The field or variable must be in the specified format. It can be part of a longer string. For example, you can specify a file name like Evidence_[$Parent:SOXRisk/System Fields:Name$].pdf if you want to validate that the parent object has a specific PDF attachment.

      • A field in the current object

        Select an Object Field.

      • A field in a related object
        • Select Direct Child, Direct Parent, Ancestor, or Descendant in Relationship Type.
        • Select an object type in Related Object Type.
        • Select a field in Related Object Field.
        • Select a path in Relationship Paths (displays only if Relationship Type is Ancestor or Descendant).
        • Add Filter By conditions.
        • Set Primary Parent Only (displays only if Relationship Type is Direct Parent or Ancestor).
      • A field in a Preference object

        Select a Preference Object Field. You can add Filter By conditions.

    4. If you chose a date field in Compare, you can define an offset in Adjust Date By.
      • A specified value and enter Number of Days.
      • A field in the current object
      • A field in a related object
        • Select Direct Child, Direct Parent, Ancestor, or Descendant in Relationship Type.
        • Select an object type in Related Object Type.
        • Select a field in Related Object Field.
        • Select a path in Relationship Paths (displays only if Relationship Type is Ancestor or Descendant).
        • Add Filter By conditions.
        • Set Primary Parent Only (displays only if Relationship Type is Direct Parent or Ancestor).
      • A field in the Preference object

        You can add Filter By conditions.

    5. Click Done.
      The condition is numbered and saved. Conditions are numbered consecutively in the order that they are defined.
    6. Optional: Add more conditions.
    7. Optional: Set Advanced Logic to true to override the default rule that all conditions must be met. Write a statement in Logic. Use the condition numbers together with the operators and, or, not, and parentheses.
      The order of operations is: (), NOT, AND, OR.
      For example:
      • 1 or 2 or 3
      • 1 and (2 or 3)
      • 1 not (2 or 3)
  10. In Operations you define what the calculation does. Expand Operations and click New Operation. The Operation panel opens.
  11. Define Input Field operations for the calculation.
    1. Click New Operation.
    2. In Type, select Input Field.
    3. Enter an internal Name for the operation.

      Allowed characters are A-Z, a-z, 0-9, underscore, hyphen, and spaces. Special characters are not allowed. The name must not start with a number or a space.

    4. Click Add Field.
      The panel expands and three options are displayed:
      • A field in the current object
      • A field in a related object
      • A field in a Preference object
    5. If you select A field in the current object, select an Object Field and click Done.
    6. If you select A field in a related object, complete the following fields:
      • Select Direct Child, Direct Parent, Ancestor, or Descendant in Relationship Type.
      • Select an object type in Related Object Type.
      • Select a path in Relationship Paths (displays only if Relationship Type is Ancestor or Descendant).
      • Select a field in Related Object Field.
      • Choose a Field to sort on.
      • Select Ascending or Descending in Sort Direction.

        An example of how you can use sorting is to list months in different orders. For example, to analyze trends, you might want to sort KRI values by January, February, and March. Then, later by March, February, and January.

      • Set Primary Parent Only (displays only if Relationship Type is Direct Parent or Ancestor) (optional).
      • Add Filter By conditions (optional). If you add multiple conditions, set Advanced Logic as needed.
      • Click Done.
    7. If you select A field in a Preference object, complete the following fields:
      • Select a field in Preference Object Field.
      • Add Filter By conditions (optional). If you add multiple conditions, set Advanced Logic as needed.
      • Click Done.
    8. Define more Input Field operations, as needed by the calculation.
  12. Define Variable operations for the calculation.
    1. Click New Operation.
    2. In Type, select Variable.
    3. Enter an internal Name for the operation.

      Allowed characters are A-Z, a-z, 0-9, underscore, hyphen, and spaces. Special characters are not allowed. The name must not start with a number or a space.

    4. All input fields, variables, and set fields that precede this operation are listed in Involved Fields.
    5. Enter an Expression. For more information, see Expressions in GRC Calculations.
    6. Click Done.
    7. Define more Variable operations, as needed by the calculation.
  13. Define Set Field operations for the calculation.
    1. Click New Operation.
    2. In Type, select Set Field.
    3. Enter an internal Name for the operation.

      Allowed characters are A-Z, a-z, 0-9, underscore, hyphen, and spaces. Special characters are not allowed. The name must not start with a number or a space.

    4. Select a field in Output Field.
    5. All input fields, variables, and set fields that precede this operation are listed in Involved Fields.
    6. Enter an Expression. For more information, see Expressions in GRC Calculations.
    7. Click Done.
    8. Define more Set Field operations, as needed by the calculation.
  14. Review the operations.
    1. To reorder the operations, click Reorder icon.
      Use drag and drop to set the processing order. Click Done.
    2. To remove an operation, click it and select Remove.
  15. When you are ready to test the calculation, click Publish.
    The 1 version of the calculation becomes the first published version.
  16. Run the calculation to test it.

    For information about correcting calculations that have errors, see Testing and debugging a calculation.

  17. If you need to make changes to the calculation, open it again. Since you are now opening a published calculation, the word Published appears, the version number is displayed next to the calculation name and the Publish button is grayed out. When you make a change to the calculation, Published changes to Draft, the version number is incremented by 1, and the Publish button becomes active.

What to do next

Each time you change the calculation, you need to publish it and re-test it.