This documentation supports the 9.1 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

ARSetEscalation

Note

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

Description

Updates the escalation with the indicated name on the specified server. The changes are added to the server immediately and returned to users who request information about escalations.

If you perform a set operation on an overlay and you provide values for an inherited grain, the values are ignored. Only values for extended or overwritten grains of the overlay are set.

Privileges

BMC Remedy AR System administrator.

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARSetEscalation(
   ARControlStruct *control,
   ARNameType name,
   ARNameType newName,
   AREscalationTmStruct *escalationTm,
   ARWorkflowConnectStruct *workflowConnect,
   unsigned int *enable,
   ARQualifierStruct *query,
   ARFilterActionList *actionList,
   ARFilterActionList *elseList,
   char *helpText,
   ARAccessNameType owner,
   char *changeDiary,
   ARPropList *objPropList,
   char *objectModificationLogLabel,
   ARStatusList *status)

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.

If a valid overlay group is specified in the control record, the ARSet* function operates on the object that belongs to that group. If no group is specified, the function operates on the origin object. To specify whether to use an object's real or resolved name in an operation and whether to perform the operation only on objects in a specified overlay group, use the AR_SESS_CONTROL_PROP_DESIGN_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARSetSessionConfiguration).

name

The name of the escalation to update.

newName

The new name for the escalation. The names of all escalations on a given server must be unique. Specify NULL for this parameter if you do not want to change the name of the escalation.

escalationTm

The time specification for evaluating the escalation condition. This parameter can take one of two forms: a time interval that defines how frequently the server checks the escalation condition (in seconds) or a bitmask that defines a particular day (by month or week) and time (hour and minute) for the server to check the condition. Specify NULL for this parameter if you do not want to change the escalation time.

workflowConnect

The list of form names the escalation is linked to. The escalation must be associated with a single form or a list of forms that currently exists on the server. Specify NULL for this parameter if you do not want to specify the form list. If the object is locked, you can append a form name to the list but you cannot remove a form name from the list.

enable

A flag to enable or disable this escalation. A value of 0 disables the escalation, causing its condition checks and associated actions not to be performed. A value of 1 enables the escalation, causing its conditions to be checked at the specified time interval. Specify NULL for this parameter if you do not want to change this flag.

query

A query operation performed when the escalation is executed that determines the set of entries to which the escalation actions (defined by the actionList parameter) are applied. Assign an operation value of 0 (AR_COND_OP_NONE) to match all form entries. Specify NULL for this parameter if you do not want to change the query.

actionList

The set of actions performed for each entry that matches the criteria defined by the query parameter. You can specify from 1 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify NULL for this parameter if you do not want to change the action list.

elseList

The set of actions performed if no entries match the criteria defined by the query parameter. These actions are not performed for all non-matching entries. You can specify from 0 to 25 actions in this list (limited by AR_MAX_ACTIONS). Specify a list with zero items to define no else actions. Specify NULL for this parameter if you do not want to change the else list.

helpText

The help text associated with the escalation. This text can be of any length. Specify NULL for this parameter if you do not want to change the help text.

owner

The owning user for the escalation. Specify NULL for this parameter if you do not want to change the owner.

changeDiary

The additional change diary text to associate with the escalation. This text can be of any length and is appended at the end of any existing text. Existing change diary text cannot be deleted or changed. The server adds the user making the change and a time stamp when it saves the change diary. Specify NULL for this parameter if you do not want to add to the change diary.

objPropList

A list of server object properties. If this parameter is set to NULL, no properties are set. See Server object properties.

objectModificationLogLabel

The version control label that the API function must apply to the object. If the label name does not exist on the server, the function creates it.

Ripple actions

Rename and Delete operations typically change multiple objects in addition to their primary target object. The Rename or Delete function must apply the version control label to all the objects that it affects.

Multiple API calls for a single user action 

Some user actions trigger a sequence of API calls. In that situation, the last API call in the sequence applies the version control label to the object. Thus, clients that create forms (like BMC Remedy Developer Studio does) should provide the label only to the last call. For example, when a form is created, a client might issue these calls:

  • ARCreateSchema
  • ARCreateMultipleFields
  • ARSetVUI
  • ARSetVUI
  • ARSetSchema

In this case, the objectModificationLogLabel value should be passed only to the last call, ARSetSchema, even though the user provides the label during the ARCreateSchema operation.

Operations on label-related forms

Version control labels cannot be applied to these forms:

  • AR System Version Control: Label
  • AR System Version Control: Labeled Object
  • AR System Version Control: Object Modification Log

Return values

status

A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error checking.

See also

ARCreateEscalation, ARDeleteEscalation, ARGetEscalation, ARGetListEscalation. See FreeAR for: FreeARFilterActionList, FreeARPropList, FreeARQualifierStruct, FreeARStatusList.

Was this page helpful? Yes No Submitting... Thank you

Comments