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] [NOWAIT]: AREA = area_1, PROJECT = project_1, 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};
  } }

Note: You should always provide the parameters and values for the AREA and PROJECT fields with the ADD command. It is indeterminate as to which Business Area and Project into which the issue will be added without these.

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 NOWAIT keyword provides the facility to execute the ADD action as a background task, not waiting for the result of the action before returning control back to the user. This may be used if you have many ADD actions to perform, and you do not want the user to wait for these to complete before they may carry on working in the user interface. This keyword should be used with caution, as there are no indications to the user if there is a failure from the action. Any failures are reported in the application server log file. Also, note that if you place the action within a REFRESH directive, as opposed to within a PREUPDATE or POSTUPDATE directive, then the values within the issue as they stand at that moment will be added to the new issue, as opposed to the final values when the user has submitted the issue for insertion or updating. The ADD_UPDATE task must be running for this option to work successfully.

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.

The ADD action is not supported in these directives: load, clone, mail

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.

The ADD_ROW action is not supported in these directives: load, clone, mail

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.

If you do not specify a parameter and value for the AREA and PROJECT fields, then the issue is copied to the AREA and PROJECT of the current issue. You should not specify the PROJECT field without also specifying a value for the AREA field.

The optional NOWAIT keyword provides the facility to execute the COPY action as a background task, not waiting for the result of the action before returning control back to the user. This may be used if you have many COPY actions to perform, and you do not want the user to wait for these to complete before they may carry on working in the user interface. This keyword should be used with caution, as there are no indications to the user if there is a failure from the action. Any failures are reported in the application server log file. Also, note that if you place the action within a REFRESH directive, as opposed to within a PREUPDATE or POSTUPDATE directive, then the values within the issue as they stand at that moment will be copied to the new issue, as opposed to the final values when the user has submitted the issue for insertion or updating. The ADD_UPDATE task must be running for this option to work successfully.

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.

The COPY action is not supported in these directives: load, clone, mail

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}

The above example 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. The action is most frequently used within the preupdate directive. It is not used, and it is invalid to use this action within the mail directive. It is most typically used within the preupdate or postupdate directive.

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 Enterprise 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 key condition that triggers the reauthorization requires a little explanation. In the above example, the condition is:

    if (STATUS.{changed to: 'Approved'} && APPROVED_BY.{is null})

    The reauthorization is special, in that the user is not able to exit from the action, until they either successfully enter their password, or cancel the complete action. The first part of the trigger expression (STATUS.{changed to: 'Approved'}) is the change upon which you want to trigger the reuthorization. Once the user enters their password, ExtraView validates this, and then executes the expression again. This is where the APPROVED_BY.{is null} part of the expression comes into play. A successful reauthorization will have set the APPROVED_BY field to a value, usually the value of the current user. Therefore, the reauthorization is not reentered, as the evaluation of APPROVED_BY.{is null} now returns a false value

  • 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

The REAUTHORIZE action is only supported in these directives: onchange, preupdate

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] ... ... [, ATTACHMENT[.{selected}]]}

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:

<== link custCSRInfo ==> 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. 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. The optional NOWAIT keyword provides the facility to execute the UPDATE action as a background task, not waiting for the result of the action before returning control back to the user. This may be used if you have many UPDATE actions to perform, and you do not want the user to wait for these to complete before they may carry on working in the user interface. This keyword should be used with caution, as there are no indications to the user if there is a failure from the action. Any failures are reported in the application server log file. Also, note that if you place the action within a REFRESH directive, as opposed to within a PREUPDATE or POSTUPDATE directive, then the values within the issue as they stand at that moment will be update to the issue, as opposed to the final values when the user has submitted the issue for insertion or updating. The ADD_UPDATE task must be running for this option to work successfully.

The UPDATE action is not supported in these directives: load, clone, mail