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

To view an earlier version, select the version from the Product version menu.

BMC Remedy Approval Server application commands

AL only

Filter or Esc only

Command and description

Returns a value

(tick)

(tick)

Application-Command Approval Add-PGNA-Values [-t detailID] [-o ruleName] [-l valueList]
This command provides the variable values for the Parameterized Get Next Approver rule type.
This command takes the following arguments:

  • -tdetailID is the request ID of the AP:Detail record.
  • -oruleName is the name of the Get Next Approver rule that needs these values.
  • -lvalueList is list of values separated by forward slashes (/).

    Note:

    When this command is executed with missing parameter values or invalid parameter values,

    • no error message is logged in the approval debug log
    • no variable values are provided to the Parameterized Get Next Approver rule type

In the following example, the variables enclosed in quotes are provided to the approval server for use when the next Parameterized Get NextApprover rule runs.
Application-Command Approval Add-PGNA-Values -t "00000000000012" -o "Sample Param GNA Rule" -l "4/Frank Williams"

Warning:

Do not use a slash (/ ) character within a valueList parameter, because it is a separator. For example, if you use the following command, then Williams is ignored, and the result might not be as expected.

(tick)(tick)

Application-Command Approval Add-Sig [-s formName] [-e requestID] [-t processName] -o {approverList } [-1 {0 | 1 }] [-2 {0 | 1| 2 | 999}] [-l assigneeGroup\nVendorAssigneeGroups]
This command links to an existing approval details record, and creates one if none exists. It then adds one or more signature lines for each value of the -o parameter.
This command takes the following arguments:

  • -sformName is the name of the form on which you are executing the command.
  • -erequestID identifies the request being processed.
  • -tprocessNameis the name of an existing approval process. 
    • If supplied, the specified approval process is activated.
    • If not supplied, the system searches for a process against the specified form.
    • If only one process is specified, that process is used.
    • If several processes are specified, an error is reported, and no approval process starts.
    • If the same process is attached to more than one approval request form, the approval server cannot determine which form to use, and an error is returned.
  • -oapproverList is the list approvers for whom to add signatures. If omitted, this command performs no action. Multiple approvers are separated by semicolons.
  • -1— Indicates whether the new signature line is identified as independent or not independent.
    • 1 — Signature line is not independent
    • 0 or any other value — Signature line is independent
  • -2— Indicates the action to take on multiple approvers. 0 means one of, 1 means all must sign, 2 means allow only one approver, and 999 means to pull the value from the AP:Process Definition form. Indicates the action to take on multiple approvers.
    • 0 — Creates one signature line for a list of potential approvers. The first approver to act on the request determines the response. The request is withdrawn from the other approvers.
    • 1 — Creates a separate signature line for each approver. For the request to proceed, all approvers must act on their signature lines.
    • 2 — Default; creates a signature line for one approvers. Multiple responses generate an error, and the approval process stops.
    • 999 — Uses the value specified for If multiple approvers in the AP:Process Definition form.
  • -l — This parameter allows you to pass a value for Assignee Group Permissions (field ID 112), for use with the multi-tenancy feature. For more information about multi-tenancy, see the information provided in  Foundation objects . Assignee group and Vendor assignee groups are seperated with the Enter key.
    Note:

    You can provide the assignee group permissions for this parameter in the following format:

    [ -l "$Assignee Permission Group$
    $Vendor Field Permissions$;$2nd Vendor$" ]

    •  $Assignee Permission Group$ - The field with ID 112.  
    • $Vendor Field Permissions$;$2nd Vendor$ - List of all the vendor fields on the application form separated by semi-colon (;).  

    The Assignee Permission Group and Vendor Field Permissions are separated by backslash (\).
    If this command is executed for a request that is in the Process Done phase, it restarts the approval process for that request.

 In the following example, the command creates a new signature of the approver or approvers specified in the Name field for the process mentioned in the Process Name field.
Application-Command Approval Add-Sig -t "$Process Name$" -s "$Form Name$" -e "$Application Request ID$" -o "$Name$" -1 "$Independent$"  -2  "$If Multiple$"

 

(tick)

(tick)

Application-Command Approval Det-Approved [-s formName] [-e requestID] [-t processName]
This command marks the AP:Detail record Approved. Any outstanding signature lines or More Information records are marked Closed. The Process Done phase notifies the associated request of the approval. This command corresponds to an approval by global override.
This command takes the following arguments:

  • -sformName is the name of the form on which you are executing the command.
  • -erequestID identifies the request being processed.
  • -tprocessNameis the name of a process associated with the request.
    • If supplied, only the associated detail record is updated.
    • If not supplied, all detail records from all processes associated with the request are updated.
    • If the same process is attached to more than one form, all the detail records associated with this process, regardless of the application, are marked Approved.


      In the following example, the command marks the AP:Detail record as Approved for the request ID specified in the Request ID field.
      Application-Command Approval Det-Approved -t "$Process Instance Id$" -s "$Application$" -e "$Request ID$"

(tick)

(tick)

Application-Command Approval Det-Cancelled [-s formName] [-e requestID] [-t processName]
This command stops an approval process that is in progress, and marks the AP:Detail record Cancelled. Any outstanding signature lines or More Information records are marked Cancelled. The Process Done phase notifies the associated request of the cancellation.
This command takes the following arguments:

  • -sformName is the name of the form on which you are executing the command.
  • -erequestID identifies the request being processed.
  • -tprocessNameis the name of a process associated with the request.
    • If supplied, only the associated detail record is updated.
    • If not supplied, all detail records from all processes associated with the request are updated.
    • If the same process is attached to more than one form, all the detail records associated with this process, regardless of the application, are marked Cancelled.


      In the following example, the command marks the AP:Detail record as Cancelled for the request specified in the Request ID field.
      Application-Command Approval Det-Cancelled -t "$Process Instance Id$" -s "$Application$" -e "$Request ID$"

(tick)

(tick)

Application-Command Approval Det-Error [-s formName] [-e requestID] [-t processName]
This command marks the approval detail item Error. Any outstanding signature lines or More Information records are marked Closed. The Process Done phase notifies the associated request of the error. This command is intended only to be used internally by the approval server.
This command takes the following arguments:

  • -sformName is the name of the form on which you are executing the command.
  • -erequestID identifies the request being processed.
  • -tprocessNameis the name of a process associated with the request.
    • If supplied, only the associated detail record is updated.
    • If not supplied, all detail records from all processes associated with the request are updated.

      In the following example, the command marks the AP:Detail record as Cancelled for the request specified in the Request ID field.
      Application-Command Approval Det-Error -t "$Process Instance Id$" -s "$Application$" -e "$Request ID$"

(tick)

(tick)

Application-Command Approval Det-Rejected [-s formName] [-e requestID] [-t processName]
This command marks the approval detail item Rejected. Any outstanding signature lines or More Information records are marked Closed. The Process Done phase notifies the associated request of the rejection. This command corresponds to a rejection by global override.
This command takes the following arguments:

  • -sformName is the name of the form on which you are executing the command.
  • -erequestID identifies the request being processed.
  • -tprocessNameis the name of a process associated with the request.
    • If supplied, only the associated detail record is updated.
    • If not supplied, all detail records from all processes associated with the request are updated.
    • If the same process is attached to more than one form, all the detail records associated with this process, regardless of the application, are marked Rejected. 


      In the following example, the command marks the AP:Detail record as Rejected for the request specified in the Request ID field.
      Application-Command Approval Det-Rejected -t "$Process Instance Id$" -s "$Application$" -e "$Request ID$"

(tick)

(tick)

Application-Command Approval Generate-Multi-Process-Preview [-s formName] [-e requestID] -l phase:processList; [-o{0|1}]
This command creates a preview related data for a particular request in AP:Preview Data form. This data related to the request is used during generation of Real-Time preview. For more information, see Using the multi-process preview.
This command takes the following arguments:

  • -sformName is the name of the form on which you are executing the command.
  • -erequestID identifies the request being processed.
  • -l — The names of processes to include. If omitted, this command performs no action. Multiple process names are separated by semicolons. Optionally, you can include extra information as a prefix to a process name separated by a colon (: ). It could be anything related to the process that you want to highlight. For example, in the case of BMC Change Management applications, you can include phase information.
  • -o — Indicates whether a single process (0 ) or multi-process (1 ) preview should be generated. If omitted, its value defaults to 1.


    In the following example, the command creates a preview related data for the request specified in the Request ID field.
    Application-Command Approval Generate-Multi-Process-Preview -e "$Request ID$" -s "$SCHEMA$" -l "PHASE1:Management Cost Authorization; PHASE2:Major Account Level Approval" -o "1"

(tick)

(tick)

Application-Command Approval Generate-Preview [-o "Generate-Preview"] -e "requestID" -s "formName" [-t "processName"]
Creates a preview request for a single process based on the future signature lines found in the AP:PreviewInfo form for the associated application request. This is used with preview On Start and On Change options.
This command takes the following arguments:

  • -o — If specified, the value of this parameter must be Generate-Preview.
  • -erequestID identifies the request being processed.
  • -sformName must be the application form name.
  • -tprocessName is the name of a process associated with the request.


    In the following example, the command creates a preview related data for a single process — Management Cost Authorization associated to the request mentioned in the Request ID field.
    Application-Command Generate-Preview -o "Generate-Preview" -e "$RequestID$" -s "$SCHEMA$" -t "Management Cost Authorization"

(tick)

(tick)

Application-Command Approval MoreInfo-Return [-s formName] [-e requestID]
This command takes data from the specified More Information request and copies the response back to the associated signature request. The More Information request must be marked Completed.
This command takes the following arguments:

  • -s — If supplied, formName it must be the More Information form.
  • -e — If supplied, requestID must be the ID of the More Information record.

    In the following example, the command copies the response from the AP:More Information form to the AP:Signature form for the request specified in the More Information ID field.
    Application-Command Approval MoreInfo-Return -e "$More Information ID$"

(tick)

(tick)

Application-Command Approval New-Details -t processName [-s formName] [-e requestID] [-1 priority ] [-2 processDueDate ] [-l assigneeGroup\nVendorAssigneeGroups] 

This command starts an approval server process for the specified request. This command creates an approval details record. It then searches for Auto Approval and Self Approval rules; if either exists and passes, the command marks the record Approved and continues with the Process Done phase to update the associated request. If no Auto Approval or Self Approval rules pass, the first set of approvers is found and signature lines are created for them as defined by the rules of the process.
If this command is started after Add-Sig, and a detail record already exists for the application request, an error occurs and the process terminates. To fix this issue, pull the NotAddSig field (field ID 14523) from AP:Detail onto the two-way join between your application form and AP:Detail, and save the join form.
This command takes the following arguments:

  • -tprocessName is the name of a process associated with the request. The specified approval process is activated.
    • If several processes are specified, an error is reported, and no approval process starts.
    • If the same process is attached to more than one application form, the approval server cannot determine which form to use, and returns an error.
  • -1 — If supplied, it sets the priority to Urgent (1), Normal (2), or Low (3). Any other priority is ignored, and the default -Normal (2)- is applied.
  • -2 — If supplied, this integer value is translated into the Process Due Date and further used to calculate the action date for the signature; the Process Due interval defined on AP:Process Definition is ignored in this case. 

  • -l — If supplied, this value is passed to field 112 (Assignee Group Permissions), which is used to support the multi-tenancy feature.
    Note:
    You can provide the assignee group permissions for this parameter in the following format:

    [ -l "$Assignee Permission Group$
    $Vendor Field Permissions$;$2nd Vendor$" ]

    •  $Assignee Permission Group$ - The field with ID 112.  
    • $Vendor Field Permissions$;$2nd Vendor$ - List of all the vendor fields on the application form separated by semi-colon (;).  

    The Assignee Permission Group and Vendor Field Permissions are separated by colon (:). 

     

The following example initiates the approval server process named Management Cost Authorization for creating a new approval.

Application-Command Approval New-Details -t "Management Cost Authorization" -e "$Request ID$" -l "$Assignee Groups$
$Vendor Assignee Groups$" 

(tick)

(tick)

Application-Command Approval Rename-Form -t oldFormName -o newFormName [-1 activeOnly][-2 doRename]
This command changes the name of a form. All references in the definition forms are updated.
This command takes the following arguments:

  • -toldFormName is the name of the form that you want to rename.
  • -onewFormName is the new name that you want to assign to the form.
  • -1 — This parameter controls which AP:Detail records are updated. If set to 1, only active entries are updated. Providing any other activeOnlyvalue causes all entries to be updated.
    Note:
    Requests in the Error state also qualify as active. 

  • -2 — This parameter controls the renaming of the form. If set to 1, the form itself is renamed. If you provide any other doRename value, the approval server assumes that the form has already been renamed using BMC Remedy Developer Studio, and you are simply updating the cross-references.
    The following example renames the form mentioned in the From Old Name field to the new name specified in the To New Name field.
    Application-Command Approval Rename-Form -t "$From Old Name$" -o "$To New Name$" -1 "$Update$" -2 "1"

(tick)

(tick)

Application-Command Approval Rename-Process -t oldProcessName -o newProcessName [-1 activeOnly] [-2 doRename]
This command changes the name of a process. All references in the related definition forms are updated. The name of a process can be as long as 80 bytes. This equates to 80 characters in English and most European languages, but only 40 characters in double-byte languages.
This command takes the following arguments:

  • -toldFormName is the name of the form that you want to rename.
  • -onewFormName is the new name that you want to assign to the form.
  • -1 — This parameter controls which AP:Detail records are updated. If set to 1, only active entries are updated. Providing any other activeOnlyvalue causes all entries to be updated.
    Note:
    Requests in the Error state also qualify as active.

  • -2 — This parameter controls the renaming of the process. If set to 1, the process itself is renamed. If you provide any other doRename value, the approval server assumes that the form has already been renamed using the AP:Process Definition form, and you are simply updating the cross-references. 

    In the following example, the command renames the process mentioned in the From Old Name field to the new name specified in the To New Name field.
    Application-Command Approval Rename-Process -t "$From Old Name$" -o "$To New Name$" -1 "$Update$" -2 "1"

(tick)

(tick)

Application-Command Approval Sig-Approved [-s formName] -e requestID [-t processName]
This command performs approval processing on a signature line that has been marked Approved. The rule process continues to the next approvers.
This command takes the following arguments:

  • -s — If supplied, formName must be the AP:Signature form.
  • -erequestID is the ID of the signature entry.
  • -t — If supplied, processName must match the process name specified in the AP:Signature form. 
    In the following example, the command marks the signature record mentioned in the Signature ID field as Approved.
    Application-Command Approval Sig-Approved -e "$Signature ID$" 

(tick)

(tick)

Application-Command Approval Sig-Cancelled [-s formName] -e requestID [-t processName] [-1 {0|1}]
This command performs cancellation processing on a signature line that has been marked Cancelled. The request can be in any active state (Pending, Hold, More Information, Error) for this operation to be performed. The signature line is cancelled and the process performs the appropriate actions, depending on whether other signature lines are active.
This command takes the following arguments:

  • -s — If supplied, formName must match the value in the AP:Signature form.
  • -erequestID is the ID of the signature entry.
  • -t — If supplied, processName must match the process name specified in the AP:Signature form.
  • -1— Indicates whether the related signature lines should be cancelled.
    • The default value is 0, in which case the related signature lines are not cancelled.
    • If you supply 1, the related signature lines are also cancelled. For example, signatures are created for two people, Allen and Bob, in an ad hoc manner, with the All Must Sign option. When Sig-Cancelled is used to cancel Allen's signature with the -1 parameter values:
    • 0 — only Allen's signature is marked Cancelled, and not the related signature lines.
    • 1 — both Allen's and Bob's signatures are marked as Cancelled


      In the following example, the command marks the signature record mentioned in the Signature ID field as Cancelled.
      Application-Command Approval Sig-Cancelled -e "$Signature ID$"

(tick)

(tick)

Application-Command Approval Sig-Notify [-s formName] -e requestID [-1 numNotifications]
This command causes a notification message to be sent, indicating that the specified AP:Signature record has exceeded its defined time limit without being resolved. The notification message is sent to the corresponding form-AP:Detail-Signature join.
This command takes the following arguments:

  • -s — If supplied, formName must match the value in the AP:Signature form.
  • -erequestID is the ID of an AP:Signature form request.
  • -1 — If supplied, numNotificationsindicates the notification value.
    • 0 — Default value; indicates that this is the initial notification.
    • Any other value — indicates that this is a repeat notification. This parameter triggers the delivery of the notification or repeat notification message. 
      In the following example, the command sends a notification to the approver or approvers to respond to the request specified in Signature ID field.
      Application-Command Approval Sig-Notify -s "" -e "$Signature ID$"

(tick)

(tick)

Application-Command Approval Sig-Notify-Change -s formName -e requestID [-t processName)]
This command causes a notification message to be sent, indicating that the specified entry has been changed. The approval server sends a notification about the change in the signature status to all users who have previously acted upon a signature line for a specific entry.
The notification message is sent to the corresponding AP:Detail-Signature join form after the detail record is rejected or approved by using the Det-Rejected or Det-Approved command.
The -s and -e parameters are required to identify the entry that has been changed.
This command takes the following arguments:

  • -s — If supplied, formName must match the value in the AP:Signature form.
  • -erequestID is the ID of an AP:Signature form request.
  • -tprocessNameis the name of a process associated with the request.
    • If specified, the notification is sent to the appropriate process.
    • If not specified, the notification is sent to all the processes associated with the entry.
      Note:
      When this command is executed with invalid parameter values, the following error message is logged in the approval debug log:
      Notify on Change command found no approval detail items to operate on.
      The error message does not provide any details about the invalid parameter values.

      In the following example, the command sends the notification about the change in the signature status to all users who have previously acted upon the signature specified in Signature ID field.
      Application-Command Approval Sig-Notify -s "" -e "$Signature ID$"

(tick)

(tick)

Application-Command Approval Sig-Notify-State -s formName -e requestID [-t processName][-1 numNotifications] [-2  {0|3|4|6| otherState}] [-3 {0|1 }]
This command causes a notification message to be sent, indicating that the specified AP:Signature record has exceeded its defined time limit for a given state without being resolved. The notification message is sent to the corresponding
AP:Detail-Signature join form.
This command gets fired when a user acts on a request through Approval Central. An administrator can fire this command manually, and the notification is sent if the signature state has been changed to Hold, More Information, or Error.
A notification can only be sent if the administrator has created AP:Notification records for the following states:

  • Hold
  • More Information
  • Error
  • Still Pending
  • Still Pending (Repeat)
  • Still Hold, Still Hold (Repeat)
  • Still More Information
  • Still More
  • Information (Repeat)
  •  Still Error
  • Still Error (Repeat)
    This command takes the following arguments:
  • -sformName must be the AP:Signature form.
  • -erequestID identifies the request being processed.
  • -t — If supplied, processNamemust match the process name specified in the AP:Signature form.
    • If supplied, the approval server uses it to execute this application command.
    • If not supplied, the approval server determines the process name using the formName and requestID.
  • -1 — If supplied, numNotificationsindicates the notification value.
    • 0 — Default value; indicates that this is the initial notification.
    • Any other value — indicates that this is a repeat notification.
      This parameter triggers the delivery of the notification or repeat notification message
  • -2— This parameter specifies the numeric value of the state the notification is for.
    • It can be set to 0 (Pending), 3 (Hold), 4 (More Information), or 6 (Error).
    • otherState will default to 0 (Pending).
  • -3— Provides more information about the notification.
    • 0 (Default) — indicates that the notification is for an escalation.
    • 1 — indicates that the notification is simply a direct notification. Any other value assumes the default.


      In the following example, the command notifies all approvers about the status of the signature specified in the Signature ID field.
      Application-Command Approval Sig-Notify-State -s "" -e "$Signature ID$"

(tick)

(tick)

Application-Command Approval Sig-Reassign [-s formName] -e requestID [-t processName] { -o shortApproverList | -l longApproverList }
This command reassigns the signature line to another approver list by using either the -o (for an approver list less than 255 characters) or -l option. The signature line must be in an active state (Pending, Hold, More Information, Error) for this operation to be performed.
This command takes the following arguments:

  • -s — If supplied, formName must be the AP:Signature form.
  • -erequestID is the ID of the signature entry.
  • -t — If supplied, processName must match the process specified by the detail record that is associated with the signature line.
  • -oshortApproverList contains the names of the approvers to whom the request is to be reassigned, when the length of the approver names does not exceed 255 characters.
  • -llongApproverList contains the names of the approvers to whom the request is to be reassigned, when the length of the approver names is longer than 255 characters. The approval server does not impose an upper limit on the length of this string. However, it is limited by the BLOB column of the database in use. 


    In the following example, the command reassigns the current signature (specified in the Signature ID field) to the approver or approvers specified in the ReassignTo field.
    Application-Command Approval "Sig-Reassign" -e "$Signature ID$" -o "$ReassignTo$"

(tick)

(tick)

Application-Command Approval Sig-Rejected [-s formName ] -e requestID [-t processName ]
This command is issued when a signature line is changed to Rejected. It marks the associated detail line as Rejected.
This command takes the following arguments:

  • -s — If supplied, formName must be the AP:Signature form.
  • -erequestID is the ID of the signature entry.
  • -t — If supplied, processName must match the process specified by the detail record that is associated with the signature line.


    In the following example, the command marks the signature record mentioned in the Signature ID field as Rejected.
    Application-Command Approval Sig-Rejected -e "$Signature ID$"

(tick)

(tick)

Application-Command Approval Update-Config -t settingLabel [-o settingValue]
This command updates administrative configuration settings for the application.
Note:

The command is executed internally when you change the configurations in the AP:Server-Settings form to update the ar.cfg file.


This command takes the following arguments.

  • -tsettingLabel identifies the specific setting being updated. This label is defined in arstruct.h and is placed in the ar.cfg (or ar.conf ) file.
  • -o— You can use this parameter as follows:
    • Omit it to reset settingLabel to its default value.
    • Mention a settingValue in the format appropriate for the ar.cfg (or ar.conf ) file to change the value of the settingLabel.
      Examples of configuration settings:
    • For the approval notification setting, not specifying this parameter resets all options to their default values. Otherwise, only the option that is defined in the settingValue parameter is reset.
    • For the Debug mode setting, other debug options can be defined, and if they are, this setting takes effect. However, if only 0 or 65536(the setting for approval debugging) is set, then only that flag is changed, and other settings remain as they are in the file.
      Note:
      The approval server immediately applies the changes in settings that are not start-up-only.

      For example, the following command disables the debug mode of approval server in ar.cfg file.
      Application-Command Approval Update-Config -t "Debug-mode:" -o "0"

(tick)(tick)

Application-Command Approval Update-Permissions [ –t “processName” ]  [-o  "$For$"]  [-l assigneeGroup<EnterKey>VendorAssigneeGroups]

This command updates the permisions for approcal data, such as AP:Signature, AP:Detail. The 112 field on the AP:Signature form updates with all the active approver’s login IDs.

This command takes the following arguments:

  • -t — If supplied, processName for the records which needs permission changes. Otherwise server automatically puts current form name in –s parameter. Which means all the active signature’s permissions will be updated.
  • -o — "update-detail" OR “update-questioncomment” based on which record’s permissions to be modified.
  • -l — This parameter allows you to pass a value for Assignee Group Permissions (field ID 112), for use with the multi-tenancy feature. 

For example, the following command updates the permissions(112) on AP:Question-Comment Info form from the associated Signature record. 

Application-Command Approval Update-Permissions -t "$zTempProcess Name$" -o "update-questioncomment"


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

Comments