BMC Remedy Approval Server application commands

+

+

+

+

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:

• -s — formName is the name of the form on which you are executing the command.
• -e — requestID identifies the request being processed.
• -t — processNameis 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$"

+

+

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:

• -s — formName is the name of the form on which you are executing the command.
• -e — requestID identifies the request being processed.
• -t — processNameis 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$"

+

+

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:

• -s — formName is the name of the form on which you are executing the command.
• -e — requestID identifies the request being processed.
• -t — processNameis 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$"

+

+

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:

• -s — formName is the name of the form on which you are executing the command.
• -e — requestID identifies the request being processed.
• -t — processNameis 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$"

+

+

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:

• -s — formName is the name of the form on which you are executing the command.
• -e — requestID 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"

+

+

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.
• -e — requestID identifies the request being processed.
• -s — formName must be the application form name.
• -t — processName 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"

+

+

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$"

+

+

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

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:

• -t — processName 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.

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$" 

+

+

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:

• -t — oldFormName is the name of the form that you want to rename.
• -o — newFormName 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"

+

+

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:

• -t — oldFormName is the name of the form that you want to rename.
• -o — newFormName 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"

+

+

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.
• -e — requestID 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$" 

+

+

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.
• -e — requestID 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$"

+

+

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.
• -e — requestID 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$"

+

+

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.
• -e — requestID is the ID of an AP:Signature form request.
• -t — processNameis 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$"

+

+

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:
• -s — formName must be the AP:Signature form.
• -e — requestID 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$"

+

+

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.
• -e — requestID 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.
• -o — shortApproverList 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.
• -l — longApproverList 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$"

+

+

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.
• -e — requestID 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$"

+

+

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

This command takes the following arguments.

• -t — settingLabel 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"

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"