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 [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};
} }
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: [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.
Occasionally you might want to add a number of blank repeating rows to an issue. However, it is not valid to add completely blank rows to a repeating row. You can, however, use an unused field that is not even on the layout in question. For example, to add three blank rows to a layout named MY_RR_LAYOUT, you could use this, utilizing the ALT_ID field which is not used on repeating rows and using a text field on the layout:
{ADD ROW: TO MY_RR_LAYOUT MY_TXT_FIELD = ALT_ID};
{ADD ROW: TO MY_RR_LAYOUT MY_TXT_FIELD = ALT_ID};
{ADD ROW: TO MY_RR_LAYOUT MY_TXT_FIELD = ALT_ID};
The ADD_ROW action is not supported in these directives: load, clone, mail
{CLEAR}
This causes the field to be cleared. As an example, to clear the contents of the field named PRIORITY:
PRIORITY.{clear}
{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}
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: 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: Message}
This writes the Message to the system log.
{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: user_field_name 'message to display'}
user_field_name user_field_name within the rules that are part of the reauthorization code. The value is set automatically by the action and unpredictable behavior will result if you assign it any value. You can use the rules to set any other field values, such as the timestamp of the event. Of course, you can assign a value user_field_name by rules that are not triggered with the REAUTHORIZE REAUTHORIZE command 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;
}
# 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
Electronic signature display
The REAUTHORIZE action is only supported in these directives: onchange, preupdate
{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 [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