Actions

Actions are rule statements that may be executed within directives. Not all actions may be included within all directives. For example, it is not valid to perform a REAUTHORIZATION rule within a load directive. This action is only valid within an ONCHANGE or PREUPDATE directive.

Note that the square brackets in the actions on this page refer to optional syntax.

ADD

{ADD [as role]: field_1 = value_1 [, field_2 = value_2] ... ... [, ATTACHMENT[.{selected}]]}

This will add a new item to the ExtraView database, based upon a set of name value pairs, where the fields are the data dictionary names of the fields, and the values are valid for the display type of the field. This action only works within the postupdate directive, as it is essential to perform the underlying update before you initiate actions that are dependent. As an example, the following will add a new record when a button named ADD_SERIAL_BUTTON is pressed:

if (ADD_SERIAL_BTN.{changed} && UNIT_SERIAL.{not null}) {
  { ADD: AREA='Calibration',
    PROJECT='Unit',
    UNIT_SERIAL,
    COMPONENT,
    SITE,
    FACILITY};
  }
}

If the field that provides the values for the ADD operation is of type Log Area (e.g. the COMMENTS field), then only the last entry from the source issue is added to the new issue.

The as role optional syntax allows the action to be implemented by altering the user’s current role to the role, purely for the action. The role is the title of the role, not its name. This is useful when you need to add a record to a different Business Area or Project where the current user may not have sufficient permissions.

The optional ATTACHMENT keyword allows all or selected attachments to be copied from the current issue to the new issue being created. If the ATTACHMENT keyword is further qualified with {selected}, then only attachments that the user has individually selected with the Select? checkbox will be copied. The Select? checkbox is enabled on the user interface with the security permission keys named PR_ADD_PROBLEM.ATTACH_SELECT and PR_RESOLUTION.ATTACH_SELECT.

ADD ROW

{ADD ROW: [TO layout_type_name] field_1 = value_1 [, field_2 = value_2] [,field3 = sourceField] ] }

This will add a new row to a repeating record, where the square braces indicate optional elements and the parameter lists are the standard, as in the ADD or UPDATE actions. All the destination fields must be defined in the data dictionary as repeating row fields. The values may not be repeating row fields, as there is no certainty which of many repeating rows the value will refer to.

If the optional TO: layout_type_name is included, then the repeating row with that name is targeted for the addition of the new row. The fields being set must be in the layout that is loaded from the specified layout type, area, project and role of the user that is executing the rule operation.

CLEAR

{CLEAR}

This causes the field to be cleared. As an example, to clear the contents of the field named PRIORITY:

PRIORITY.{clear}

COPY

{COPY [as role]: field_1 = value_1 [, field_2 = value_2] ... ... [, ATTACHMENT[.{selected}]]}

This action is similar to the ADD action, except it may be used entirely without the field/value list. Thus {COPY} by itself will create a new issue, with all the values from the original issue. Specifying a name and value allows that value to be used for that specific field name. This action only works within the postupdate directive, as it is essential to perform the underlying update before you initiate actions that are dependent.

The optional ATTACHMENT keyword allows all or selected attachments to be copied from the current issue to the new issue being created. If the ATTACHMENT keyword is further qualified with {selected}, then only attachments that the user has individually selected with the Select? checkbox will be copied. The Select? checkbox is enabled on the user interface with the security permission key named PR_ADD_PROBLEM.ATTACH_SELECT and PR_RESOLUTION.ATTACH_SELECT.

DEFAULT

{DEFAULT}

This sets the field to its default value. As an example, to set the contents of the field named PRIORITY to its default value:

PRIORITY.{default}

ERROR

{ERROR: Message}

This is only valid in preupdate rules. It will prevent the update from going forward and return an alert to the user with the text Message. Note that several messages may be accumulated and returned in the alert to the user as all the rules are executed without updating the database. Contrast this with the {STOP: Message} action where execution is stopped immediately.

You may use the standard escape characters in the error message. The most common requirement is to use n as a linefeed within your message.

LOG

{LOG: Message}

This writes the Message to the system log.

MAIL

{MAIL: ‘template_name’, user}

This action uses an ad hoc email template named template_name and uses it to format the notification that is sent to the user named user.

Both HTML and text-based email templates may be sent with this action. This is controlled by the format of the template itself, and a simple naming convention for the template. The processing for this action requires either the template_name or the template_title to follow the MAIL: action. If this name or title has a suffix of .txt, then any email generated to a user whose personal email format is full, brief or very brief text will be generated in text. All other mails will be generated as HTML. This implies that if you want email templates where some users will receive HTML mail and others will receive text, you should create two templates. For example, you might have one template named Customer_Response_Template with the HTML and another named Customer_Response_Template.txt with the text.

When creating text-based email templates, make sure that you use the WYSIWYG (what-you-see-is-what-you-get) mode of the email template utility and be sure that the template does not contain any HTML tags.

In the email rule action, use the HTML template name or title, but without the .txt suffix.

If a text template does not exist, all users will receive the HTML template as a result of the action. If a text template exists, users with text email format preferences will receive the text email template. If an HTML template does not exist and a text template does exist, then all users will receive the text template.

REAUTHORIZE

{REAUTHORIZE: user_field_name ‘message to display’}

  • This special action implements electronic signatures and is only available with the ExtraView GC version
  • This action is only valid within the refresh and preupdate directive sections of the business rules
  • The administrator may set up the reauthentication of the current user at the time the issue is updated. If the re-authentication is successful, the issue is updated and the name of the current user is placed in the field user_field_name. The reauthentication or electronic signature mechanism demands that the user must enter their password before the transaction is allowed to continue. The application will continue to request the user’s password until it is entered correctly. The user may cancel out of the signature request, but will not be able to update the record
  • The field user_field_name must be placed on the add or edit screen of an issue. The field also requires read and write access for the user roles that will perform the re-authentication. If you want to hide the field from the user's view, set a layout cell attribute of the type of FIELD STYLE and a value of display:none
  • With most electronic signatures, you will want to record a timestamp of the event. You can set up a field with a display type of day or date and place it on the form in the same way as the user_field_name. It should also be given a similar layout cell attribute
  • As an example, create the following business rule in the preupdate directive section of the rules:

    if (STATUS.{changed to: 'Approved'} && APPROVED_BY.{is null}) {
      {REAUTHORIZE: APPROVED_BY 'By clicking the Submit button you are approving the update of this issue. This is an electronic signature which is recorded in the database. <span style=color:#CC0000>Any appropriate text may be placed here as a warning.</span>'};
    }
    # if we get here, we have assented to the reauthorization, so set the trigger fields:
    if (STATUS.{changed to: 'Approved'} && APPROVED_BY.{is not null}) {
      APPROVAL_DATE = SYSDAY;
      APPROVED_BY = USER;
    }
    # clear approval if reopened:
    if (STATUS.{changed from: 'Approved'} && STATUS != 'Closed') {
      APPROVAL_DATE = "";
      APPROVED_BY = {null};
    }
    if (STATUS.{changed from: 'Closed'} && STATUS != 'Approved') {
      APPROVAL_DATE = "";
      APPROVED_BY = {null};
    }

    Assign the APPROVAL_DATE to SYSDAY if the field is of type day as opposed to date. This will set the APPROVAL_DATE to the current date and time when the APPROVED_BY field is set, and set it to a null value if the APPROVED_BY field is set to null

  • The message to display in the REAUTHORIZE syntax allows the display of any text on the popup window where the electronic signature is provided. Many organizations have a message approved by their legal departments that is used here. Notice that the message to display may contain HTML, allowing you to format the message. A typical electronic signature popup window will look like the following:


    Electronic signature display

  • The administrator may set up any number of electronic signature requests, each with a different logical expression that triggers the requirement for the user to enter their signature
  • If you implement the REAUTHORIZE rule within a repeating row, then the user field that contains the electronic signature must be a popup user field and the user must complete the electronic signatures in order, starting with the first repeating row

STOP

{STOP: Message}

This will interrupt the processing of preupdate rules and returns to the user without executing further rules. This action works differently from the ERROR action in that the ERROR action continues execution and may accumulate more than one message.

You may use the standard escape characters in the error message. The most common requirement is to use n as a linefeed within your message.

UPDATE

{UPDATE [as role]: linkName field_1 = value_1 [, field_2 = value_2] ... ... }

This will update one or more records, based upon the definition of the link specification. If the link points to more than one record, all affected records will be updated. This action only works within the postupdate directive, as it is essential to perform the underlying update before you initiate actions that are dependent. As an example, the following will update all customer contact records, if the contact is changed:

AREA='CSR Calls', CUST_LIST
if (AREA = 'Customers' && CUST_CONTACT_PHONE.{changed}) {
  {UPDATE: custCSRInfo CUST_CONTACT, CUST_CONTACT_PHONE}
}

If the field that provides the values for the UPDATE operation is of type Log Area (e.g. the COMMENTS field), then only the last entry from the source issue is added to the new issue.

The as role optional syntax allows the action to be implemented by altering the user’s current role to the role, purely for the action. The role is the title of the role, not its name. This is useful when you need to update a record in a different Business Area or Project where the current user may not have sufficient permissions.