×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

This documentation supports the 21.3 version of Action Request System.

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

AR System 21.3 ... Developing applications Defining workflow to automate processes Specifying workflow actions Using Run Process and $PROCESS$ commands

Process commands

Use a Run Process action or a Set Fields action with $PROCESS$ to execute various tasks in an application workflow. You must understand how each command operates to determine whether it is appropriate to use in your workflow.

This topic lists the various Application, PERFORM-ACTION, and other related workflow commands you can use. The tables include the following information along with the syntax and description for each command.

Column

'Y' or (tick) indicates:

Active Links

Use the command only with active links.

Filter or Escalations

Use the command only with filters and escalations.

Returns a value

The command returns a value. To capture the returned value, you must use the command in a Set Fields action with the $PROCESS$ key word.

Available for PWAThe command can be used in Progressive Web Applications.
Related topics

Using Run Process and $PROCESS$ commands

When to use a Run Process action or a Set Fields action with $PROCESS$

Tip

Press F to view the table in full screen mode. Press Esc to exit full screen mode.

Application commands

The following table describes Application commands, which are always executed on the server. If you use one of these commands in an active link, you must use the @@: processCommand or @ serverName : processCommand or syntax.

Active LinksFilter or EscalationsReturns a valueAvailable for PWACommandDescription and example




Application-Bus-Time-Add "startTime"[ "amount"[ "amountUnits"["holidayScheduleName"["workdayScheduleName"] ] ] ]

Returns a new time that is the requested offset into the future, taking availability and business hours and holidays into account. Offset is a value of 0 or greater than 0. The default is 1 hour. Offset unit values are:

  • 1—Seconds
  • 2—Minutes
  • 3—Hours
  • 4—Days

For more information, see Defining business schedules using Business Time.

Example:

Application-Bus-Time-Add $SERVERTIMESTAMP$ $Lead Time$ 3 $Support Group ID$ $Support Group ID$



Y

Application-Bus-Time-Diff " startTime " " endTime " [" holidayScheduleName "[" workdayScheduleName "] ]

Returns an integer that represents the number of seconds between the start and stop time, taking business hours into account. For more information, see Defining business schedules using Business Time.

For example:

Application-Bus-Time-Diff "$zTmpIntAutoStartTime$" "$zTmpIntAutoEndTime2$" "$z1D HolidayTag$" "$zTmpworkdayTag$"



Y

Application-Bus-Time-Subtract " startTime " [" amount " [" amountUnits " [" holidayScheduleName " [" workdayScheduleName " ] ] ] ]

Returns a new time that is the requested offset into the past, taking business hours into account. Offset is a value of 0 or greater than 0. The default is 1 hour. Offset unit values are:

  • 1—Seconds
  • 2—Minutes
  • 3—Hours
  • 4—Days

For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ Application-Bus-Time-Subtract "$Signature Due Date$" "$tmpDueSoonInterval$" "$tmpDueSoonUnit$" "$zTmpHoliday Schedule$" "$zTmpWorkday Schedule$"



Y

Application-Bus-Time2-Add " startTime " [" amount " [" amountUnits " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... ] ] ]

Performs a business time calculation by starting with the start time and resulting in a new time that adds the requested offset. The command returns a timestamp representing the time calculated. Use this command to recalculate time into the future. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ Application-Bus-Time2-Add "$Signature Due Date$" "$tmpDueSoonInterval$" "$tmpDueSoonUnit$" "$zTmpHoliday Schedule$" "$zTmpWorkday Schedule$"



Y

Application-Bus-Time2-Assoc-Add " startTime " [" amount " [" amountUnits " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... [" EntityID1" " EntityID2" ...] ] ] ]

This command contains EntityID parameters, so you do not need to query the Business Segment-Entity Association form. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ Application-Bus-Time2-Assoc-Add "$Signature Due Date$" "$tmpDueSoonInterval$" "$tmpDueSoonUnit$" "$zTmpHoliday Schedule$" "$zTmpWorkday Schedule$"



Y

Application-Bus-Time2-Assoc-Diff " startTime " " endTime " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... [-e "EntityID1" "EntityID2" ...] ]

This command contains EntityID parameters, so you do not need to query the Business Segment-Entity Association form. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ Application-Bus-Time2-Assoc-Diff "$Signature Start Date$" "$Signature End Date$" "$zTmpHoliday Schedule$" "$zTmpWorkday Schedule$"



Y

Application-Bus-Time2-Assoc-Get-Free-Window " startTimeRange " " endTimeRange " " level " " duration " " earliestStartTime " " latestEndTime " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... [-e " EntityID1" "EntityID2" ... ] ]

This command contains EntityID parameters, so you do not need to query the Business Segment-Entity Association form. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ @@:Application-Bus-Time2-Assoc-Get-Free-Window "$Srv Avail Start Date/Time$" "$Srv End Search Date/Time Range$" "$BTSLevel$" "$DurationInSec$" "$BTSEarliestStartTime$" "$BTSLatestEndTime$"



Y

Application-Bus-Time2-Assoc-Get-Next-Window" startTimeRange " " endTimeRange " " duration " " windowFlag " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... [-e " EntityID1" " EntityID2" ... ] ]

This command contains EntityID parameters, so you do not need to query the Business Segment-Entity Association form. For more information, see Defining business schedules using Business Time.

Example:

Application-Bus-Time2-Assoc-Get-Next-Window "$Srv Avail Start Date/Time$" "$Srv End Search Date/Time Range$" "$DurationInSec$" "$Flag$"



Y

Application-Bus-Time2-Assoc-Subtract " startTime " [" amount " [" amountUnits " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... [-e " EntityID1" "EntityID2" ...] ] ] ]

This command contains EntityID parameters, so you do not need to query the Business Segment-Entity Association form. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ Application-Bus-Time2-Assoc-Subtract "$Signature Due Date$" "$tmpDueSoonInterval$" "$tmpDueSoonUnit$" "$zTmpHoliday Schedule$" "$zTmpWorkday Schedule$"



Y

Application-Bus-Time2-Diff " startTime " " endTime " [" businessTimeSegmentName1 " " businessTimeSegmentName2 " ... ]

Performs a business time calculation by computing the difference between the start time and the end time. The return is an integer representing the difference in seconds. Use this command to compare two different times (start time and end time) to get the actual business time. For more information, see Defining business schedules using Business Time.

Example:

Application-Bus-Time2-Diff "$zTmpIntAutoStartTime$" "$zTmpIntAutoEndTime2$" "$z1D HolidayTag$" "$zTmpworkdayTag$"



Y

Application-Bus-Time2-Get-Free-Window " startTimeRange " " endTimeRange " "level " ] [" duration " ] [" earliestStartTime " ] [" latestEndTime " ] [ " businessTimeSegmentName1 " " businessTimeSegmentName2 " ... ]

Returns the start of the next available or unavailable free time segment at the same level or a higher level that is duration seconds long. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ @@:Application-Bus-Time2-Get-Free-Window "$Srv Avail Start Date/Time$" "$Srv End Search Date/Time Range$" "$BTSLevel$" "$DurationInSec$" "$BTSEarliestStartTime$"



Y

Application-Bus-Time2-Get-Next-Window " startTimeRange " " endTimeRange " [" duration " ] [" windowFlag " ] [" businessTimeSegmentName1 " " businessTimeSegmentName2 "... ]

Returns the start of the next available or unavailable time segment that is duration seconds long. If duration is 0 (the default), the command returns either the start of available time segment or the start of the unavailable time segment. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ @@:Application-Bus-Time2-Get-Next-Window "$z1D_Integer01$" "$z1D_Integer02$" "0" "01" "" "" "$z2TF_BTSegmentID$"



Y

Application-Bus-Time2-Subtract " startTime " [" amount " [" amountUnits " [" businessTimeSegmentName1 "" businessTimeSegmentName2 " ... ] ] ]

Performs a business time calculation by starting with the start time and resulting in a new time that subtracts the requested offset. The command returns a timestamp representing the time calculated. Use this command to recalculate time in the past. For more information, see Defining business schedules using Business Time.

Example:

$PROCESS$ Application-Bus-Time2-Subtract "$Signature Due Date$" "$tmpDueSoonInterval$" "$tmpDueSoonUnit$" "$zTmpHoliday Schedule$" "$zTmpWorkday Schedule$"

Y
YY

Application-command swarm $Incident Number$ $Emailid$
$ChatID$ $TenentId$ $ClientId$ $Swarming Type$ $Secret Key$

Creates a chat room using the incident number and email IDs of the users associated with the incident as stakeholders.

YY

Application-Confirm-Group groupID

Verifies that the current user is a member of the specified group. Returns one of the following integers:

  • 1—The user is a member of the group.
  • 0—The user is not a member of the group, or the specified group ID does not correspond to a valid group.

This command is not context sensitive for a given entry. Validation of group IDs 0, 3, 4, or 7 returns 1.

For example, to find whether the user is a member of Administrator group, enter:

Application-Confirm-Group 1


YY
Application-Confirm-Password password

Validates if the password is the password for the current user. For password, you can use a reference to the field that contains the password, such as field 102 or field 103. This command returns one of the following integers:

  • 1—The password was confirmed.
  • 0—The password is not valid.

If you used AR System version prior to 6.0 to create workflow involving a Password field (ID 102), the workflow might not function in AR System versions 6.0 and later. Version 6.0 included enhanced encryption and tighter security controls. To workaround this issue, use the Application-Confirm-Password $PROCESS$ command. For more information about the Password field, see .Reserved fields in access control v22.1, and .Creating and modifying users v21.3.

Example:

Application-Confirm-Password $Current Password$

Y
Y

Application-Copy-Field-Value targetFieldID sourceFieldID

Copies a field on the current form to another field on the current form. Returns one of the following integers:

  • 1—The assignment failed.
  • 0—The assignment occurred.

To get the return value, use this command in a Set Fields action with $PROCESS$. This command cannot be used in a Run Process action.

For example:

$PROCESS$ Application-Copy-Field-Value TargetFiledID SourceFieldID

YYY

Application-Delete-Entry " formName " entryID

Deletes the specified entry.

Example:

Application-Delete-Entry $SCHEMA$ $1$

Where $SCHEMA$ is the name of the current form.

To delete an entry from a different form, provide the name of the form within quotes:

Application-Delete-Entry "SCHEMA" $1$


 Y

 Application-Event eventNumber eventDetail

Initiates a server event. These valid values for eventNumber cause the AR System server to perform the following actions:

  • 1—Read the configuration file into memory.
  • 2—Read the group information and definitions from database into memory.
  • 3—Re-scan the Add or Remove License form.

For more information about server events, see Capturing server events for workflow or API calls.

Example:

Application-Event 1


 YY
Application-Format-Qual " form " internalQualifier  

Converts an internal representation of a qualifier into a qualification string. See Process command syntax.

Example:

Application-Format-Qual "$Form Name$" $InternalQualification$


 YY
 Application-Format-Qual-Filter " form " internalQualifier

Converts an internal representation of a qualifier from a filter Run If into a qualification string. See Process command syntax .

Example:

Application-Format-Qual-Filter "$Form Name$" $InternalQualification$


 YY
Application-Format-Qual-ID " form " internalQualifier  

Converts an internal representation of a qualifier into a qualification string using ID format. See Process command syntax .

Example:

Application-Format-Qual-ID "$Form Name$" $Qualification Ids$


 YY
 Application-Format-Qual-L " form " " VUILabel " internalQualifier  

For the indicated VUI, converts an internal representation of a qualifier into a qualification string using labels. See Process command syntax .

Example:

Application-Format-Qual-L "$Form Name 2$" "" $Qualification2$


 YY
 Application-Format-Qual-SField " form1 " " form2 " internalQualifier

Converts an internal representation of a qualifier from a Set Fields or Push Fields filter action into a qualification string. See Process command syntax .

Example:

Application-Format-Qual-SField "$Assignee Form Name$"  "$Request Form$" $Qualification Internal Format$


 YY
 Application-Format-Val-SField " form1 " fieldID " form2 " internalAssignment

Converts an internal representation of a Set Fields or Push Fields assignment into an assignment statement. See Process command syntax .

Example:

Application-Format-Val-SField $536870923$ $536870924$ $536870925$ $536870927$

 

 Y

  Application-FTS-Reindex-Form <form name> [ <scanTime> [ <fieldId 1> ] . . . [ <fieldId N> ] ]

Initiates a full text reindex on the specified form.

form name—Indicates the form that you want to reindex. A form name can be a single form or can be an asterisks "*". When you use an asterisks " * " as a form name, you can reindex all the FTS enabled forms.

scanTime—Indicates the date and time from which the server should scan for updates. If the scan time is omitted, the form is completely reindexed. The value specified is only used for regular forms. The server treats join, vendor, and view form requests as on-demand scans. These form types record a last scan time value that is used in on-demand scans and scheduled scans. Zero can be used for the scan time to differentiate between a request for an on-demand scan, and a complete form reindex. Because regular forms do not have scheduled scans, the specified value is used.

The standard format is a character string date, but the server also accepts a numeric timestamp (EPOC time) value.

[fieldId [1..N] Indicates the fields with data changes by including a range of field IDs. If no field IDs are specified, the server will not perform analysis to determine if a reindex is needed before proceeding with the reindex. If the scan time is omitted, no field IDs can be specified. This advanced option is used when the AR System server database has been updated externally, and it is not known if any of the updated columns are associated with full text indexed fields. This option allows the server to determine if any full text indexed fields were affected by the database updates and, if there were none, unnecessary indexing is avoided.

Examples:

Reindexing a single form:

Application-FTS-Reindex-Form "HPD:Help Desk" "9/28/2010 5:06:52 PM" 10000100 10000200

Reindexing all FTS enabled forms:

Application-FTS-Reindex-Form * 1577817000



Y
 Application-Generate-GUID [" GUIDPrefix " ]

Generates a globally unique identifier (GUID). The prefix can be a maximum of two characters, which can contain non-alpha characters (although alpha characters are recommended). If you do not include the GUID prefix, it defaults to ID.

Example:

Application-Generate-GUID


 YY
 Application-Get-Approval-Join " form "

Retrieves the name of the join form between the application and the AP:Detail form. This command is used for the Approval Server.

Example:

Application-Get-Approval-Join" AP-Sample:Lunch Scheduler"

In the result, the form names are separated by spaces as follows:

AP-Sample:Lunch-Detail   AP:Detail


YY

Application-Get-DetSig-Join " form "

Retrieves the name of the join form between the three-way join form (join between the application form and AP:Detail-Signature) and the names of the AP:Detail-Signature form, AP:Detail form, and AP:Signature form. This command is used for the Approval Server.

Example:

Application-Get-DetSig-Join "AP-Sample:Lunch Scheduler"

In the result, the form names are separated by spaces as follows:

AP-Sample:Lunch-Detail-Signature     AP:Detail-Signature     AP:Detail     AP:Signature


YY

Application-Get-DetSig-Join-2 " form "

Retrieves the name of the join form between the three-way join form (join between the application form and AP:Detail-Signature) and the names of the AP:Detail-Signature form, AP:Detail form, and AP:Signature form. This command is used for the Approval Server.

Example:

Application-Get-DetSig-Join-2 "AP-Sample:Lunch Scheduler"

In the result, the form names are separated by new lines as follows:

AP-Sample:Lunch-Detail-Signature   

AP:Detail-Signature   

AP:Detail   

AP:Signature


YY

Application-Get-Form-Alias " form " [" VUILabel " ]

Retrieves the appropriate form alias for the specified form and VUI. If you do not include a VUI, the default VUI is used.

Example:

Application-Get-Form-Alias "$Form Name 2$"


YY

Application-Get-Form-Name " formAlias " [" VUILabel " ]

Retrieves the form name for the specified form alias and VUI. If you do not include a VUI, the default VUI is used.

Example:

Application-Get-Form-Name "$Form Alias$"


YY

Application-Get-License-Count" licenseName "

Retrieves the number of licenses of the specified type. Use the license name that is used in the License Tool.

Example:

Application-Get-License-Count "$Permission Tag Name$ User $License Type$"


YY

Application-Get-Locale-VuiID" form " " VUIType " " localeName "

Retrieves the VUI ID for the locale that you specify. The VUI types are Windows (1) and web absolute positioning (3). Do not use the $VUI-TYPE$ keyword.

Apart from setting the locale, you must also set the Master View for Server Processing property to true.

When this property is set to true then only the AR System server returns this VUI ID, provided the locale and VUI type matches.

Example:

  • To retrieve the View ID of the Standard View for the current form in English locale, use:
    Application-Get-Locale-VuiID $SCHEMA$ 1 "en_US"
  • To retrieve the View ID of the Web (Alternative) View for the current form in English locale, use:
    Application-Get-Locale-VuiID $SCHEMA$ 3 "en_US"


Y

Application-Get-Next-Recurrence-Time " formName " " startTime " "recurrenceDefinitionName"

Returns a timestamp representing the recurrence time. For more information, see Operators.

Example:

Application-Get-Next-Recurrence-Time "$536870949$" "$536870917$" "$536870918$"





Application-Invalidate-User userName

Writes an invalid string for the password value to disable the current user's account. The userName parameter can be hard-coded, the keyword $USER$, or referenced from a field. For syntax information, see Process command syntax.

Example:

Application-Invalidate-User $Login Name$


YY

Application-Map-Ids-To-Names " form " qualificationString

Maps the IDs of the fields or keywords in the string to a name representation.

Example:

Application-Map-Ids-To-Names "TMS:Task" $ElectronicField3$


YY

Application-Map-Ids-To-Names-L " form " " VUILabel " qualificationString

For the indicated VUI, maps the IDs of the fields or keywords in the string to a name representation using labels. If the field label is blank, the database name is used.

Example:

Application-Map-Ids-To-Names-L "$Form Name 2$" "" $Header Ids$


YY

Application-Map-Names-To-Ids " form " qualificationString

Maps the names of the fields or keywords in the string to an internal ID representation.

Example:

Application-Map-Names-To-Ids "$FormName$"  $Lookup Field$


YY

Application-Map-Names-To-Ids-L" form " " VUILabel " QualificationString

For the indicated VUI, maps the labels of the fields or keywords in the string to an internal ID representation. An empty string for the VUI denotes the default VUI for the form.

Example:

Application-Map-Names-To-Ids-L "$Form Name 2$" "" $$17382$$


YY

Application-Parse-Qual" form " qualificationString

Converts a qualification string into an internal representation.

For example, to parse the qualification string into its internal representation, enter:

Application-Parse-Qual "My Form" Integer Field = 99

The qualification string does not need double quotation marks around it because all data after the form name is treated as the qualification string.


YY

Application-Parse-Qual-Filter " form " qualificationString

Converts a Run If filter qualification string into an internal representation. See Process command syntax .

Example:

Application-Parse-Qual-Filter "$Form Name01$" $Selection Criteria$


 YY
Application-Parse-Qual-L " form "" VUILabel " qualificationString  

For the indicated VUI, converts a qualification string with labels into an internal representation. The result of this command is used in the Application-Format-Qual-L command. See Process command syntax .

Example:

Application-Parse-Qual-L "$Form Name 2$" "" $Qualification2$


 YY
Application-Parse-Qual-SField " form1 "" form2 " qualificationString  

Converts a Set Fields or Push Fields filter qualification string into an internal representation. See Process command syntax .

For example:

Application-Parse-Qual-SField "$LinkSourceFormName$"  "BMC.CORE.CONFIG:BMC_FederatedInterfaceLink"  $LinkQualification$


YY

Application-Parse-Qual-SField-L " form1 "" form2 "" VUILabel1 "" VUILabel2 " qualificationString

For the indicated VUI, converts a Set Fields or Push Fields filter qualification string into an internal representation. See Process command syntax .

Example:

Application-Parse-Qual-SField-L"$LinkSourceFormName$"  "BMC.CORE.CONFIG:BMC_FederatedInterfaceLink"  "$VUI$ $LinkQualification$


YY

Application-Parse-Val-SField" form1 " fieldID " form2 " assignmentStatement

Converts a Set Fields or Push Fields filter assignment statement into an internal representation. The result of this command is used in the Application-Format-Val-SField command.See Process command syntax .

Example:

Application-Parse-Val-SField "$zTmpFormName$" $Field8ID$ "$zTmpAssignForm$" $Value8$

When you define service targets, do not use parenthesis ( ) in the title.


YY

Application-Query-Delete-Entry " form1 " qualificationString

Deletes all entries matching the specified qualification. See Process command syntax .

Example:

Application-Query-Delete-Entry "ABC DEF" 'User Name' ="Fred"


Y

Application-Release-Pending

Causes database operations generated by the current workflow to be sent to the database immediately. In a filter, this command changes the usual filter phasing and causes the Run Process action to run in phase 1.

Use this advanced feature with caution. The command allows workflow to see the results of previous workflow by causing the previous workflow's actions to be entered into the database. See Overriding filter processing phasing for a detailed explanation.

Example:
Application-Release-Pending


 Y

Application-Set-Filter-Phasing " value " 

Determines whether form entries are created when the workflow operation to create them occurs or whether they are created in bulk during a later filter phase. When issued, this command affects all subsequent entry create operations for the current API call. Entries already created as a result of the call are not undone. The effect of the command lasts for the duration of the API call or until the command is reissued with a different value. value can be 1 or 0:

  • 1—Entries are created in a later filter phase.
  • 0—Entries are created immediately. This is the default behavior. Use this parameter only if you previously switched on delayed entry creation for the call and now want to switch it off.

If the create phase is delayed, the entries are not immediately added to the database, so their data is unavailable to subsequent workflow actions. This can change the effect of filters that use the data in qualifications or as a source for Set Fields actions.

This command does not affect filters whose names end with !. In such filters, all database operations including creates occur in phase 1. When a filter performs an Application-Release-Pending Run Process command, all delayed create operations are immediately performed. The new entries are held until the end of filter processing or until they are flushed by another Application-Release-Pending Run Process command.

Example:

Application-Set-Filter-Phasing 1





URL-Safe-Encode



YYY

Application-Start-Process [processName] [inputVariableID1]=$value1$,[inputVariableID2]=$value2$,
[inputVariableID3]=$value3$...

Initiates a process in  BMC Helix Innovation Studio  and passes values for each input variable in the process. 

Example:
Application-Start-Process com.bmc.dsm.itsm-applications:setImpacts 536870913=$z1d_SV_
TL_ImpactCI_ReconID$,536870912=$z1D_S
V_AIOPs_NodeCIPDate$,
536870914=id,53687
0915=$z1D_SV_AIOPs_Node
CIODate$,536870916=$z1D_SV_AIOps_GUID$

Approval Server  application commands

The following table lists Approval Server  application commands. 


Column

(tick) indicates:

Active link

Use the command only with active links.

Filter or Escalations

Use the command only with filters and escalations.

Available for PWAThe command can be used in Progressive Web Applications.


Active link

Filter or Escalations

Available for PWA

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.
It command takes the following arguments:

  • -t—detailID is the request ID of the AP:Detail record.
  • -o—ruleName is the name of the Get Next Approver rule that needs these values.
  • -l—valueList is list of values separated by forward slashes (/).

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)(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:

  • -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 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.
  • -o—approverList is the list of approvers for whom signatures are added. 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 approver. 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—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 The page ._ars_itsm_LinkLibrary v21.3 was not found  -- Please check/update the page name used in the MultiExcerpt-Include macro. Assignee group and Vendor assignee groups are separated with the Enter key.

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:

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


(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:

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


(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:

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


(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:

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


(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:

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


(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.
  • -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"


(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:

  • -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.

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:

  • -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.
    Requests in the Error state also qualify as active. 

  • -2—This parameter controls the renaming of the form. If set to 1, the form is renamed. If you provide any other doRename value, the approval server assumes that the form has already been renamed using 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:

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


(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.
  • -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$"


(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.
  • -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$"


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

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:

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


(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.
  • -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$"


(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.
  • -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$"


(tick)

(tick)


Application-Command Approval Update-Config -t settingLabel [-o settingValue ]
This command updates administrative configuration settings for the application. 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.

  • -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.

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 permissions for approval 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"


Remedy Assignment Engine application commands

To support interaction between the AR System server  and Remedy Assignment Engine, use the Application-Command process. You can run this process from filters, escalations, and active links by using the Run Process action.

The Application-Command process allows the specification of commands to be executed by an application. Whenever an Application-Command process is run, a request is created in the Application Pending form that contains details about the command. The Application Dispatcher retrieves commands from this form and passes them to Remedy Assignment Engine for processing. If the Application Dispatcher is not in use, Remedy Assignment Engine retrieves commands directly from the Application Pending form.

Application-Command commands use the Run Process action. As with all Run Process actions, you should use quotes around a parameter when its value contains a space, to make sure that it is evaluated correctly. 

Application-Command processes exist on the AR System server . If you are performing an operation from an active link, you must use the syntax that indicates that the process should be run as a remote process on the server.

For more information, see Defining Run Process actions to run processes, programs, or commands, Using Run Process and $PROCESS$ commands and Keywords.

The following table lists all commands that are defined for Remedy Assignment Engine server. Most of the commands are used automatically by Remedy Assignment Engine and its workflow. Use these commands as the command parameter for Application-Command processes. You must precede each command with Application-Command.

AL
only

Filter
or Esc
only

Command and description

Returns a value

+

+

Application-Command AE-CACHE DoCache[-s formName]  [-e requestID] [-t operation] [-o processInstanceID] [-I processName]

Runs a specified Assignment Engine process. This command forces Remedy Assignment Engine to build its runtime cache. The runtime cache consists of processes, forms, and rules that are currently configured with Remedy Assignment Engine in the ASE:Administration form. When this command is run, Remedy Assignment Engine re-builds its cache by caching data from the ASE:Administration form.

During runtime, Remedy Assignment Engine cache is updated if there are any changes in processes, forms, or rules. You need not run this command manually. However, if started manually, the command builds Remedy Assignment Engine's runtime cache.

This command takes the following arguments:

  • -s—formName is the name of the form on which you are executing the command.
  • -e—requestID of the process or form or rule, the cache of which is being updated. This has nothing to do with 'Assignment' requests. For active links, the request ID is required. For filters, it is optional.
  • -t—Operation carried out on the process (CREATE, DELETE and MERGE).
  • -I—processName is the name of the process to run. It must match the process name in the Processes tab of the Assignment Engine Administration Console.
  • -o—processInstanceID is the unique ID of the process.

Example:
Application-Command AE-CACHE DoCache -t $OPERATION$ -o $Process InstanceId$ -l $Process Name$

For information about the Assignment Engine, see Automatic request assignment .


+

+

Application-Command AE-ASSIGN DoAssign [-t processName] [-e requestID]

This command runs a specified Remedy Assignment Engine process. This command takes the following arguments:

  • -t—processName is the name of the process to run. It must match the process name in the Processes tab of the Assignment Engine Administration Console.

  • -e—requestID is the ID of the request on which the process will run. For active links, the request ID is required. For filters, it is optional.

For example, to run the AE:Sample Help Desk Assignment Process on the request with ID 000000001:

Application-Command AE-ASSIGN DoAssign -t "AE:Sample Help Desk Assignment Process" -e "000000001"

If you want to configure two processes that the same name, to work with Remedy Assignment Engine, you must pass the process instance ID to the -t parameter.


PERFORM-ACTION and other workflow commands

The following table describes PERFORM-ACTION and other workflow commands, which are executed by the workflow engine and can run on the client or the server as appropriate. 

Active LinksFilters or EscalationsReturns a valueAvailable for PWACommandDescription and example
Y


GET-CHANGE-FLAG

Gets the change flag status of the current window. 1 means that changes were made, and 0 means that no changes were made.

Example:

$PROCESS$ GET-CHANGE-FLAG

Y


ENABLE-WAIT-CURSOR-ON-LONG-RUNNING-PROCESS

Enables AR System applications to explicitly enable and disable the wait cursor for a particular execution stack. This run process action only affects the workflow actions that support wait cursor. The wait cursor is automatically disabled at the end of the current execution stack. This run process action needs to be called for each execution stack. For example, clicking a button causes Table A to refresh and the first row to be selected and selecting a row of Table A causes Table B to refresh. If the wait cursor is required for both these refreshes, then it needs to be called twice, once for each execution stack. This is a global setting for every execution stack and not for every form. Possible values are:

  • 1: Enable
  • 0: Disable

For example, to enable the cursor:
ENABLE-WAIT-CURSOR-ON-LONG-RUNNING-PROCESS 1

Y


PERFORM-ACTION-ACTIVE-LINK

Executes all active links associated with the specified Execute On condition (and field ID, as needed). The active links fire as if the Execute On condition indicated occurred. For example, PERFORM-ACTION-ACTIVE-LINK 8 specifies to run all On Modify active links as if a modify operation was performed. The active links fire, but no modify is actually performed. The options for this command are as follows:

  • Button: PERFORM-ACTION-ACTIVE-LINK 1 fieldID
  • Row Double Click or Return: PERFORM-ACTION-ACTIVE-LINK 2 fieldID
  • Submit: PERFORM-ACTION-ACTIVE-LINK 4
  • Modify: PERFORM-ACTION-ACTIVE-LINK 8
  • Display: PERFORM-ACTION-ACTIVE-LINK 16
  • Menu Choice: PERFORM-ACTION-ACTIVE-LINK 128 fieldID
  • Lose Focus: PERFORM-ACTION-ACTIVE-LINK 256 fieldID
  • Set Default: PERFORM-ACTION-ACTIVE-LINK 512
  • Search: PERFORM-ACTION-ACTIVE-LINK 1024
  • After Modify: PERFORM-ACTION-ACTIVE-LINK 2048
  • After Submit: PERFORM-ACTION-ACTIVE-LINK 4096
  • Gain Focus: PERFORM-ACTION-ACTIVE-LINK 8192 fieldID
  • Window Open: PERFORM-ACTION-ACTIVE-LINK 16384
  • Un-Display: PERFORM-ACTION-ACTIVE-LINK 65536
  • Window Close: PERFORM-ACTION-ACTIVE-LINK 32768
  • Copy To New: PERFORM-ACTION-ACTIVE-LINK 131072
  • Window Loaded: PERFORM-ACTION-ACTIVE-LINK 262144
  • Interval:PERFORM-ACTION-ACTIVE-LINK 524288
  • Event: PERFORM-ACTION-ACTIVE-LINK 1048576
  • Table content change: PERFORM-ACTION-ACTIVE-LINK 2097152 fieldID
  • Hover on Label: PERFORM-ACTION-ACTIVE-LINK 4194304 fieldID
  • Hover on Data: PERFORM-ACTION-ACTIVE-LINK 8388608 fieldID
  • Hover on Field: PERFORM-ACTION-ACTIVE-LINK 16777216 fieldID
  • Expand: PERFORM-ACTION-ACTIVE-LINK 33554432 fieldID
  • Collapse: PERFORM-ACTION-ACTIVE-LINK 67108864 fieldID
YYY
PERFORM-ACTION-ADD-ATTACHMENT fieldID [" fileName"]Adds an attachment to an attachment field, and returns a value of 0 (Successful). If the attachment is not added, the command returns one of the following codes:
  • 1: Canceled
  • 2: Failed

For filters and escalations, the field ID must be an attachment field, and the file name is required. For active links:

  • The file name is optional. If omitted, a Browse dialog box is displayed to allow you to select a file name. (If viewed in a web browser, a Browse dialog box is always displayed.)
  • The field ID can be an attachment field or an attachment pool.
    • If the field ID is an attachment field, the attachment is added to the specified field. If the field has a value, the existing value is overwritten.

    • If the field ID is an attachment pool, the attachment is added to the first available field within the pool that has no attachment. If no attachment meets this criteria within the pool, no action is taken.

    If you use this command in a filter with a Run Process action instead of in a Set Fields action, you must use the filter phase override naming convention filterName `!. This causes the action to run in filter phase 1 so that the changes are committed to the database. See Overriding filter processing phasing .

Example:

PERFORM-ACTION-ADD-ATTACHMENT 536870915 "C:\Trace.txt"

 Y


 PERFORM-ACTION-APPLY

If the form is open in Search mode, performs the Search operation (clicks the Search button). In Modify or New mode, performs the Apply or Save operation.

The only difference between the PERFORM-ACTION-APPLY process command and the Commit Changes action is that the Commit Changes action works differently in conjunction with a dialog box. The PERFORM-ACTION-APPLY process command has no effect on a dialog box, it only works with regular forms.

Example:

PERFORM-ACTION-APPLY

Y


PERFORM-ACTION-CHANGE-MODE mode

Changes the mode of the form. This command takes mode as a parameter and then changes the mode. The allowable values for mode are QUERY (new search), CREATE (new request) and SET ALL (modify all). This is exactly what the $OPERATION$ keyword returns currently.

Example:

PERFORM-ACTION-CHANGE-MODE CREATE

Y


PERFORM-ACTION-CLEAR-PROMPTBARClears the prompt bar of all messages. This command is useful to run before custom validation occurs (through PERFORM-ACTION-VALIDATE_NULL-REQUIRED-FIELDS) if the prompt bar will not be cleared automatically.

Example:

PERFORM-ACTION-CLEAR-PROMPTBAR



Y

PERFORM-ACTION-DELETE-ATTACHMENT fieldID

Deletes an attachment from an attachment field, and returns a value of 0 (Successful). If the attachment is not deleted, the command returns one of the following codes:

  • 1: Canceled
  • 2: Failed

If you use this command in a filter with a Run Process action instead of in a Set Fields action, you must use the filter phase override naming convention filterName `!. This causes the action to run in filter phase 1 so that the changes are committed to the database. See Overriding filter processing phasing.

For example, it is used in the Run Process as follows:

PERFORM-ACTION-DELETE-ATTACHMENT 536880912

 Y


PERFORM-ACTION-EXIT-APP

Exits the Windows client or logs out of the web client.

Example:

PERFORM-ACTION-EXIT-APP

 Y


PERFORM-ACTION-GET-ENTRY "entryID"

Retrieves the entry based on the entry ID. This command is applicable only for the Display and Modify modes. For information about the related features, see Process command for modifying data on display forms.

Example:

PERFORM-ACTION-GET-ENTRY $Request ID$

 Y
Y
PERFORM-ACTION-GET-FIELD-LABEL fieldID

Returns a field label. Use this command in a Set Fields action with $PROCESS$ to obtain the return value. For the query builder widget, returns the query builder widget qualification in user readable format ($PROCESS$), which is a string containing what is seen in the query builder widget. The fieldID is the field ID of the view field, which has been initialized as a query widget, and will return null if fieldID is not a query widget or invalid field ID.

For example, it is used in Set Fields action:

  • $PROCESS$ PERFORM-ACTION-GET-FIELD-LABEL 536880912 where 536880912 is the field ID whose label is to be retrieved.
    or
  • $PROCESS$ PERFORM-ACTION-GET-FIELD-LABEL $Character Field$

where $Character Field$ is used to enter fields IDs dynamically.

 Y
Y
PERFORM-ACTION-GET-PREFERENCE fieldID

PERFORM-ACTION-GET-PREFERENCE fieldID

Gets the value of the field you specify from the User Preference form.

For example, to get the value of the User Locale field, enter the following command:

PERFORM-ACTION-GET-PREFERENCE 20121 where 20121 is the field ID of the User Locale field. To find the field ID:

  1. Open the AR System User Preference form in Developer Studio .
  2. Select the field in question, and find the ID property in the Properties tab.
Y


PERFORM-ACTION-GO-HOME

Opens the form configured as your home page.

Example:

PERFORM-ACTION-GO-HOME

 Y


PERFORM-ACTION-SHOW-TOOLBAR [Value]

Shows or hides the toolbar on a form. If the value to set to 1, the form displays the toolbar. Otherwise, the form hides the toolbar. This command is available for all modes, except Dialog and Popup. For information about the related features, see Process command for modifying the toolbar option.

Example:

PERFORM-ACTION-SHOW-TOOLBAR 0

or

PERFORM-ACTION-SHOW-TOOLBAR 1

Y


PERFORM-ACTION-HOME-FIELD-REFRESH

Refreshes the Application List field on the home page form. Typically, you use this command to display a subset of entry points based on the values that are dynamically entered into the reserved character field ID 1576.

Example:

PERFORM-ACTION-HOME-FIELD-REFRESH

YY

PERFORM-ACTION-LIST-APPEND fieldID "value"

Adds the value to the end of the list maintained by a character field.

For example, if character field 1234 contains the value abc;def;ghi;jkl; , the following command modifies the value to abc;def;ghi;jkl;mno.

PERFORM-ACTION-LIST-APPEND 1234 "mno"

YYY

PERFORM-ACTION-MAP-GROUPIDS-TO-NAMES fieldID

Returns a list of group names instead of group IDs. A group list field now always returns a list of group IDs and not group names. 

Example:

$PROCESS$ PERFORM-ACTION-MAP-GROUPIDS-TO-NAMES $536871123$

To use a group list with a LIKE statement, which requires a text string, first use this command to convert the group IDs to group names. For example, to use a statement such as $grouplist$ LIKE "%"'groupname'"%", first add a process command to translate a list of group IDs to a space separated list of group names.

Y


PERFORM-ACTION-MAP-PUT fieldID key "value"

Adds or updates the value in a list or map maintained by a character field.

For example, if character field 1234 contains the value type=4;Name=John, the following command modifies the value to type=4;Name=George.

PERFORM-ACTION-MAP-PUT 1234 Name "George"

Y


PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM navbarItemID

Set focus to the specified navigation bar item.

Example:

PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM 304247449

Y


PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM FieldID state

To expand or collapse items of the navigation bar field. For more information, see Expanding and collapsing items in the navigation bar.

For example, to expand all the items in the navigation bar field, execute the following command by providing the vertical navigation bar field ID.

PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM 536870978 1

Y


PERFORM-ACTION-NEXT

Moves to the next request in the Results pane and displays the details in the Details pane.

Example:

PERFORM-ACTION-NEXT

Y
YY

PERFORM-ACTION-OPEN-ATTACHMENT fieldID

Opens an attachment preview from an attachment field, and returns a value of 0 when successful. If the attachment is not opened, the command returns one of the following codes:

  • 1: Canceled
  • 2: Failed

For example, to use in Run Process or Set Fields action, enter:

$PROCESS$ PERFORM-ACTION-OPEN-ATTACHMENT 536870915

where 536870915 is the attachment field ID.

Users can save the attachment after opening the preview. Viewable file types include JPEG, JPG, PDF, and text. Other files types such as files with extentions .docx, .zip, .exe, and .rar are saved when the process is triggered and preview is not shown.

 Y


PERFORM-ACTION-OPEN-URL [ current | :new | newwithouttoolbar ] " urlString "

Opens the specified URL in a browser. For the Windows client, a browser is opened. The URL is opened in a browser as follows:

  • To open the page in a new browser window, enter  PERFORM-ACTION-OPEN-URL " urlString " or PERFORM-ACTION-OPEN-URL new " urlString "
  • To open the page in a new browser window with the toolbar, menu bar, and location bar hidden, enter PERFORM-ACTION-OPEN-URL newwithouttoolbar "urlString"
  • To open the page in the current browser window, enter PERFORM-ACTION-OPEN-URL current " urlString "

Verify that the URL is complete and well-formed so that the browser handles it correctly. For example, to open a web page, be sure the URL begins with http:// (http://*). The mid tier always requires a complete and well-formed URL.

Example:

PERFORM-ACTION-OPEN-URL $z1D Char01$

or

PERFORM-ACTION-OPEN-URL new $HOMEURL$SMPM/Change/Change_Process_Frames.htm

 Y


 PERFORM-ACTION-PREV

Moves to the previous request in the Results pane and displays the details in the Details pane.

Example:

PERFORM-ACTION-PREV



Y
PERFORM-ACTION-SAVE-ATTACHMENT fieldID [" fileName " ]

PERFORM-ACTION-SAVE-ATTACHMENT fieldID [" fileName " ]

Saves an attachment from an attachment field to a file, and returns a value of 0 (Successful). If the attachment is not saved, the command returns one of the following codes:

  • 1—Canceled
  • 2—Failed

For filters and escalations, the file is saved on the server where filters and escalations are running. The field ID must be an attachment field, and the file name is required.

For active links:

  • The file is saved on the client computer.
  • The field ID can be an attachment field or an attachment pool. If the field ID is an attachment pool, the first available attachment is saved.
  • The file name is optional. If omitted, the web client always displays a dialog box. If the file name is given, the simple file name is displayed in the file name field.

If you use this command in a filter with a Run Process action instead of in a Set Fields action, you must use the filter phase override naming convention filterName `! . This causes the action to run in filter phase 1. See Overriding filter processing phasing .

Example:

$PROCESS$ PERFORM-ACTION-SAVE-ATTACHMENT 536870915 "C:\Trace.txt"

 Y


PERFORM-ACTION-SEND-EVENT " target " " eventType " " eventData " " FdataVisualizationModuleFieldID "

Sends an event to another window. target is the window to which to send the event. Possible values are:

  • @—The "at" sign signifies the parent of the current window.

     In the web client, an Open Window active link action can open a form in the current window. This window does not have a parent window, so a target value of @ is not valid in this case.

  • #—The pound sign character signifies all child windows of the current window.
  • *—The asterisk character signifies all windows managed by the client environment, even the current window.
  • eventType —The name of the event. This is an arbitrary string defined by the application author (for example, ChildClosed). The receiving workflow can access the value of eventType through the EVENTTYPE keyword.
  • eventData —The data for the event.
  • F dataVisualizationModuleFieldID —The target for sending events is the module field in the current form.

For more information, see Process command for highlighting required fields and Process command for highlighting required fields.

Example:

PERFORM-ACTION-SEND-EVENT F536870914 "DisplayItem" $ItemName$, where:

  • 536870914 is the data visualization field ID.
  • DisplayItem is an event type that is recognized by the module.
  • $ItemName$ is a field on the form that contains the name of the item to be displayed in the module field.
Y

YPERFORM-ACTION-SET-AUTOCOMPLETE-KEYSTROKE valueOrFieldID

Sets the value of the autocomplete keystroke. 
For example, to set the autocomplete keystroke to three characters:
PERFORM-ACTION-SET-AUTOCOMPLETE-KEYSTROKE 3

When this runs, the autocomplete list appears after three keystrokes.

You can also specify a field ID from which the command picks a value:

PERFORM-ACTION-SET-AUTOCOMPLETE-KEYSTROKE $536870914$

 Y


 PERFORM-ACTION-SET-PREFERENCE fieldID " value "

Sets the value of the field you specify for the current session only. The preference is not set in the database.

For example, to set the value of the User Locale field to Japanese, enter the following command:

PERFORM-ACTION-SET-PREFERENCE 20121 "ja_JP"

20121 is the field ID of the User Locale field and ja_JP is the value that represents a Japanese locale.

  • To find the field ID:
  1. Open the AR System User Preference form in Developer Studio .
  2. Select the field in question, and find the ID property in the Properties tab.
  • To find the value or format of a user preference field:
  1. Log on to a preference server and specify a value for a user preference. For example, select a Display Locale in the Locale tab.
  2. Open the AR System User Preference form to see what format is used or what value is stored in the corresponding field (for example the User Locale field in the Locale tab).

This is the format or value you specify for the value argument.

Y


PERFORM-ACTION-SET-QUERY-WIDGET fieldid guid AREncodedQual Initializes a view field as a query builder widget. Can be used with $PROCESS$ in the Set Field action.

This command takes the following arguments:

  • fieldid—The field ID of the view field. This value is required.
  • guid—Looks up form/field information. This value is required.
  • AREncodedQual—AR encoded qualification string. Pass NULL if not needed. This value is required. 

Returns one of the following integers:

  • 0: Successful
  • 1: Error

Workflow logging will be added to the run process to help the application developer debug while developing query widget usage in the application.

While this command can be used to initialize a query builder widget, it can also be used to reinitialize the query builder widget to another state. If you want to clear out the constructed query, send the same guid and send NULL for the encoded qualification. No backchannel call will be made to retrieve field information because the query builder widget already knows it has the field information. Alternatively, sending a qualification will reinitialize the current query builder widget with the new qualification. In this case, a backchannel call is still required in this case to interpret the encoded qualification.

Y


PERFORM-ACTION-TABLE-ADD-ROW tableFieldID rowIndex
Inserts an empty table row at the specified position on-screen. ("Row" refers to a row in list view tables, a node in tree view tables, and a cell in cell-based tables). This command does not commit the new row to the database. To add data to the empty row, you must use the appropriate active link. This command takes the following arguments:
  • tableFieldID —The ID of the table field to which to add the row. This value is required.
  • rowIndex(Optional)—The position (row index) at which to insert the row. (Row indexes are based on the version of the table in the client memory data structure.) The specified index determines the actions that occur as follows:
    • 0—Invalid row index. The current selection and highlight are not changed.
    • Greater than 0 and less than 100,000,000—A row is inserted at the specified index, selected, and highlighted. Workflow is then fired on the new row.
    • Greater than 100,000,000—A row is inserted at rowIndex - 100,000,000. For example, if the specified index is 100,000,005, the row is inserted at index 5. The new row is selected but not highlighted. Workflow is then fired on the new row.
    • Less than 0 and greater than -100,000,000—A row is inserted at the specified index multiplied by -1. For example, if the specified index is -500, a row is inserted at index 500. The new row is selected and highlighted. Workflow is then fired on the new row.
    • Less than -100,000,000—A row is inserted at rowIndex + 100,000,000. For example, if the specified index is -100,000,500, a row is inserted at index -500. The new row is selected, but it is not highlighted. Workflow is not fired. This value can come at runtime from a field on the form (for example, use PERFORM-ACTION-TABLE-ADD-ROW $Field1$ $Field2$). If a row already occupies the specified position, this command pushes the existing row and all the rows that follow it down one position. If the specified index is greater than the number of existing rows, the row is inserted at the end of the table. If a row index is not specified, a row is inserted at the end of the table, selected, and highlighted. Workflow is then fired on the new row. See Updating on-screen tables.
      For example, the following command cab be used in Run process in active link:
      PERFORM-ACTION-TABLE-ADD-ROW 536870915 $Character Field2$
      536870915 is the field ID of the tree or table field , and row index can be provided at run time via character field.
Y



PERFORM-ACTION-TABLE-CHANGE-ROW-COL-VISIBILITY tableFieldID [0 | 1] columnFieldID

Hides (1) or shows (0) the contents of a column field for the current row.

Example:

PERFORM-ACTION-TABLE-CHANGE-ROW-COL-VISIBILITY 91530 0 91535

Y


PERFORM-ACTION-TABLE-CLEAR tableFieldID

Clears the contents of the table field. For list view table fields, tree view table fields, and alert list fields, returns the table to its initial state. For results list fields, fires workflow and then resets the mode to Query. This is equivalent to pressing the New Search form action button.

Example:

PERFORM-ACTION-TABLE-CLEAR 536870915

536870915 is the field ID of the tree or table field.

Y


PERFORM-ACTION-TABLE-CLEAR-ROWCHANGED tableFieldID

Clears the ROWCHANGED flag for the current row.

This command was removed from AR System server 7.6.03 and later releases. In those releases, use the PERFORM-ACTION-TABLE-SET-ROWSTATE|process commands#row_state command instead.

Y


PERFORM-ACTION-TABLE-DELETE-ROW tableFieldID rowIndex rowToSelect

On-screen, removes a row from view. In the database, sets the row's state to Deleted. This command does not remove the row from the database. Therefore, table loop guides can still step through the row. ("Row" refers to a row in list view tables, a node in tree view tables, and a cell in cell-based tables.) This command takes the following arguments:

  • tableFieldID —The ID of the table field from which to delete the row. This value is required.
  • rowIndex—The position (row index) of the row to delete. This value is required. (Row indexes are based on the version of the table in the client memory data structure.) This value can come at runtime from a field on the form (for example, use PERFORM-ACTION-TABLE-ADD-ROW $Field1$ $Field2$ ).

    You can use $FIELDID$ to indicate the current row index of a table field. For a table field, $FIELDID$   returns one of the following values:

    • Index of the selected row—Index numbers start at 1. For example, if the fifth row is selected, this keyword returns 5.
    • 0— Indicates that the table is refreshed but no row is selected.
    • NULL— Indicates that the table is unrefreshed.
  • rowToSelect (Optional)—The position of the row to select after the row at rowIndexis deleted. If this value is specified, a row is selected as follows:
    • 0—Invalid row index. The current selection is not changed, but the highlight is removed.
    • NULL—The current selection and highlight are not changed unless the highlighted row is deleted. In that case, the highlight is removed.
    • Greater than 0 and less than 100,000,000—The row at the specified index is selected and highlighted, and workflow is fired.
    • Greater than 100,000,000—The row at rowToSelect - 100,000,000 is selected but not highlighted, and workflow is fired. For example, if the specified index is 100,000,005, row 5 is selected but not highlighted, and workflow is fired.
    • Less than 0 and greater than -100,000,000—The row at the specified index multiplied by -1 is selected and highlighted, and workflow is not fired. For example, if the specified index is -5, the row at index 5 is selected and highlighted.
    • Less than -100,000,000—The row at rowIndex + 100,000,000 is selected but not highlighted, and workflow is not fired. For example, if the specified index is -100,000,500, row -500 is selected but not highlighted, and workflow is not fired. If the selected row is deleted, it remains selected in memory, but it no longer appears on-screen. This command is valid for list view, tree view, and cell-based tables. See Updating on-screen tables.

For example, the command can be used in run process action as follows:

PERFORM-ACTION-TABLE-DELETE-ROW 536870915 $Character Field2$

536870915 is the field ID of the tree or table field and  CharacterField2 is the value of  the row to be deleted.

Y


PERFORM-ACTION-TABLE-DESELECTALL tableFieldID

Deselects all entries in a table field. This command is valid for all types of table fields.

For example, the command can be used in run process action as follows:

PERFORM-ACTION-TABLE-DESELECTALL  536870915



Y

PERFORM-ACTION-TABLE-GET-CHUNKSIZE tableFieldID

Returns one of the following values:

  • 0— Indicates one of the following conditions:
    • The table is not chunked.
    • The table ID is invalid.
    • The table is unrefreshed.
  • Chunk size of the table. If the table is not content clipped, the value is the same as the chunk size defined in Developer Studio .

For a content clipped table, the Min (administrator-defined chunk size; the number of cells which can be displayed in the available space). To determine the actual number of visible cells, use the VisibleRows function. See Cell-based table fields.

Example:

PERFORM-ACTION-TABLE-GET-CHUNKSIZE 536870915

Y
Y

PERFORM-ACTION-TABLE-GET-CURRENT-CHUNK tableFieldID

Returns one of the following values:

  • Index of the currently displayed table chunk—Chunk index numbers start at 1. For example, if the fifth chunk is currently displayed, this command returns 5.
  • NULL— Indicates one of the following conditions:
    • The form does not contain the specified field.
    • The command syntax is incorrect.
    • The table is unrefreshed.
  • 1— Indicates one of the following conditions:
    • The index of the currently displayed chunk is 1.
    • The table has no chunks. For example, it might be a results list table whose chunk size is not defined, a tree view table, or an alert list table.
    • The table is empty.
    • The specified field is not a table. For content clipped tables, the chunk calculation is dynamic as the number of visible cells changes.

Example:

PERFORM-ACTION-TABLE-GET-CURRENT-CHUNK  536870915

Y
Y

PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN fieldID [ returnType ]

Returns the field ID or level of the selected node, which starts at 1. If root is selected, the command returns 0. If nothing is selected, the command returns NULL. This command works only with tree view table fields. The arguments for this command are:

  • Field ID—The field ID of the tree field.
  • Return type—1 returns the selected column's field ID. Anything other than 1 returns the number of the level.

Example:

  • To return the field ID of a tree with an ID of 536870913, enter: PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN 536870913 1
  • To return the level of a tree with an ID of 536870913, enter: PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN 536870913
Y
Y

PERFORM-ACTION-TABLE-IS-LEAF-SELECTED tableFieldID

Returns 1 if selected node is a leaf, and returns 0 if the selected node is not a leaf or if nothing is selected.

Example:

$PROCESS$ PERFORM-ACTION-TABLE-IS-LEAF-SELECTED 303836000

Y


PERFORM-ACTION-TABLE-NEXT-CHUNK tableFieldID

Displays the next chunk of data in a table. If the action is for a results list, use reserved field ID 1020. If content clipping is enabled, this will display the next visible chunk. If the full chunk is not visible, this is not be the same as the next physical chunk.

Example:

PERFORM-ACTION-TABLE-NEXT-CHUNK 536870915

Y


PERFORM-ACTION-TABLE-PREV-CHUNK tableFieldID

Displays the next chunk of data in a table. If the action is for a results list, use reserved field ID 1020. This command is ignored for tree view table fields. If content clipping is enabled, this will display the previous visible chunk. If the full chunk is not visible, this is not the same the previous physical chunk.

Example:

PERFORM-ACTION-TABLE-PREV-CHUNK 536870915

Y


PERFORM-ACTION-TABLE-REFRESH tableFieldID [ startRow ] [ numberToRetrieve ]

Refreshes a table. You can optionally specify a start row and a maximum number of rows to retrieve. If the action is for a results list, use reserved field ID 1020. This command is valid for all types of table fields.

Example:

PERFORM-ACTION-TABLE-REFRESH 301132300 0 50

Y


PERFORM-ACTION-TABLE-REPORT tableFieldID

Runs a report on the selected rows in a table. If no rows are selected, the report is on the entire table. This command is ignored for tree view table fields.

Example:

PERFORM-ACTION-TABLE-REPORT 431390002

Y

YPERFORM-ACTION-TABLE-ROW-SELECTION-MODE selectionMode tableFieldID

Switches a table between selection modes based on the value of selectionMode.
The value of selectionMode can be one of 0, 1, or 2. The following list shows the table selection mode and the corresponding values of selectionMode:

  • 0 — Multiple-selection table
  • 1 — View-only table
  • 2 — Single-selection table where you can select only one of many options.

For example, create a multiple selection table and a button having this process action. The process action on the button has the value of selectionMode as 1. When you display this in a PWA, you can view the table with selectable table items. If you click the button, the run process changes the table to View-only mode.
For an example with more detailed steps, see Creating list tables and setting selection mode by using run processes in Progressive Web Applications.

Y


PERFORM-ACTION-TABLE-SELECT-NODE fieldID rowNumber [ columnNumber ] [ flag ]

Selects the specified node in a tree view table. The arguments for this command are:

  • Field ID—The field ID of the tree field.
  • Row number—The 1-based row position of the node.
  • Column number (optional)—The column (level) of the node. If you enter an invalid column number, a leaf is selected.
  • Flag—1 expands the selected node. Anything other than 1 is ignored.

For example, the following command selects a node whose tree field ID is 536870913, and the node is in row 3 and column 4.
The command also requests that the node be expanded.PERFORM-ACTION-TABLE-SELECT-NODE 536870913 3 4 1

Y


PERFORM-ACTION-TABLE-SELECTALL tableFieldID

Selects all the entries in a table field. This command is valid for all types of table fields. For a tree view table field, the command selects the root label, which represents all data. If there is no root label, the command selects nothing.

Example:

PERFORM-ACTION-TABLE-SELECTALL 536870915

Y


PERFORM-ACTION-TABLE-SET-ROWSTATE tableFieldID rowIndex rowState

Sets the state of the row at the specified position. ("Row" refers to a row in list view tables, a node in tree view tables, and a cell in cell-based tables.) This command takes the following arguments:

  • tableFieldID —The ID of the table field from which to delete the row. This value is required.
  • rowIndex (Optional)—The position of the row to apply the state to. (Row indexes are based on the version of the table in the client memory data structure.) If this value is not specified, one of these actions occurs:
    • If this command is run under a table loop guide, the state is applied to the current row in the guide.
    • Otherwise, the state is applied to all the rows in the table. This value can come at runtime from a field on the form (for example, use PERFORM-ACTION-TABLE-ADD-ROW $Field1$ $Field2$).
  • rowState (Optional)—An integer indicating the state to apply to the specified row:
    • 0 (Loaded or Unchanged)—(Default) The row was just refreshed.
    • 1 (Modified)—A Set Fields action was just performed on the row.
    • 2 (New)—The row was just added. See PERFORM-ACTION-TABLE-ADD-ROW.
    • 3 (Deleted)—The row was just marked as Deleted and removed from view. It is now hidden from users but visible to workflow. See PERFORM-ACTION-TABLE-DELETE-ROW. If this value is not specified, it defaults to 0 (Loaded or Unchanged). If this value is out of the range, such as 4, this command does not change the row's state. This command sets the $ROWCHANGED$ keyword to the rowState value. This command is valid for list view, tree view, and cell-based tables. See Updating on-screen tables.

Example:

PERFORM-ACTION-TABLE-SET-ROWSTATE 91340  $tableSort_SOURCE$ 2

Y


PERFORM-ACTION-VALIDATE-NULL-REQUIRED-FIELDS [display] [fieldIDsSeparatedByBackslashes][isWhitespaceAllowed]

Validates missing values or the $NULL$ value in the data fields. If the Run Process action returns true, it stops the workflow, highlights the field with a colored border (for example, a red border), and displays an error message.

  • The display parameter has two options to determine where to place the message:
    • PROMPT (in the prompt bar)
    • POPUP (in a pop-up box).

  • The fieldIDsSeparatedByBackslashes parameter takes a list of field IDs separated by backslashes to validate specific fields. If this parameter is not specified, the parameter verifies all data fields on the form (but automatically excludes non-data fields, such as table fields, column fields, and panel holders). If a field in a specified parameter list is not a data field or not a required field, the Run Process action ignores those fields.

  • The isWhitespaceAllowed parameter indicates if white spaces are allowed in fields. The default value of this parameter is true. If the value of this parameter is true, the application users can enter blank characters in the required fields. 

If a field listed in the command is a default field and the value was not changed, the field's value is not validated. If that default field is changed and empty, then the field's value is validated.

The validation is performed on the browser (client) before passing the value to the server.

In the following examples, the server validates two fields (8 and 536870913), and the message appears in the prompt bar.

Example:

  • PERFORM-ACTION-VALIDATE-NULL-REQUIRED-FIELDS PROMPT 8\536870913.
  • PERFORM-ACTION-VALIDATE-NULL-REQUIRED-FIELDS PROMPT=7000 8\536870913 false

For more information, see Process command for highlighting required fields.

 Y
Y
SECURITY-FILTER <fieldName> 

This command is used to encode HTML data to prevent erroneous content from executing. This command handles security-related issues before a string input from a user is used in any HTML element and displayed back to the user.

You can use a Set Fields action to call the process and use any string field value as the input parameter, and then get the result back.

For example, to set a view field value as the result:

$PROCESS$ SECURITY-FILTER $field containing malicious data$

Important:

If the fields contain data that matches a vulnerability string, your workflow might stop and generate an error in the logs.

See the following example:

A string containing ${ENV} might cause an error that the workflow logs. In such a scenario, you must create a Set Fields action before the run process as follows:

REPLACE($Short Description$, "${", "$(backslash){")

Similarly, you must create another Set Fields action after the process is completed to replace $(backslash){ with ${, as follows:

REPLACE($Short Description$, "$(backslash){", "${")

The Short Description field in the example refers to the field that contains the vulnerable string. 

Y


SET-CHANGE-FLAG [ 0 | 1 ]Sets the change flag status of the current window to on (1) or off (0).

Example:

SET-CHANGE-FLAG 0

or

SET-CHANGE-FLAG 1

When you do not set a parameter, the change flag status of the current window is set to off.

Y




SET-RO-COLOR redCode , greenCode , blueCode

Sets the background color of read-only fields according to red, green, blue (RGB) color coding.

For example, to set the blue background color:

SET-RO-COLOR 0,0,255

NYY

$PROCESS$ URL-Safe-Encode $CILookup$

This command encodes the URL input based on the UTF 8 standards. When this command is invoked, the AR System server takes care of the special characters in the URL.

For example, when you give the following input:

{"BMC.CORE:BMC_ComputerSystem" : "abc"} , the output is encoded as follows:

%7B%22BMC.CORE%3ABMC_ComputerSystem%22

YNNY PERFORM-ACTION-FETCH-SURVEY-DATA

Use this command to fetch the survey data from a survey questionnaire. Based on the component ID and qualification, this command fetches the three primary data forms (Questions, Options, and Responses) and their details.

Syntax:

PERFORM-ACTION-FETCH-SURVEY-DATA <Survey Component Field ID>

After this run process is complete, the new survey component is loaded on the UI.

YNNY

CHANGE_HOTKEY_MENU fieldID key menuName activelinkName labels autocompleteStroke

OR

CHANGE_HOTKEY_MENU fieldID key menuName $NULL$ $NULL$ 0

Use this command in active links for fields that have Enable Menu Hotkeys set to True.

This command enables you to provide options to users so that they can display different @mention information from different sources. 

For example, you can create a field where users can switch between an @mention that lists usernames and one that lists assets.

To learn about the use of CHANGE_HOTKEY_MENU command, see Configuring the @mention component.

YNNY

SET_MIN_DATE $Scheduled Start Date$ $Scheduled End Date$ 

Use this command to enable application users to select start and end dates when setting schedules in an application. 

For example, when users select a start date of a schedule as September 1, 2023, 1:00 A.M., they are then allowed to select any date as the end date as September 1, 2023, any time after 1:00 A.M. 

YNNY

COMPARE_DATETIME $Date/Time Field$ $Date/Time Field2$

Use this command to compare the values of two Date/Time fields for the start and end of schedules that application users select.

YNNY

PERFORM-ACTION-GET-FIELD-ALTERNATIVE-TEXT fieldID


Use this command to fetch the alternative text of a field. An example of alternative text is the text that is visible on search field before application users type in the search field. 

YNNY

PERFORM-ACTION-TABLE-CLEAR-DELETED fieldID


Use this command to refresh the table view or reset all the deletions while fetching table rows from the database. 

YNNY

GET-DIRTY-FIELDS fieldID


Use this command to get a list of fields that were changed by the application users. 

Was this page helpful? Yes No Submitting... Thank you
Last modified by Anagha Deshpande on Mar 06, 2024
commands process

Comments

  1. Fernando Avendano

    "PERFORM-ACTION-SET-AUTOCOMPLETE-KEYSTROKE" is not documented.

    Sep 20, 2023 06:49
    1. Chaitanya Vikas Ghanta

      Hello Fernando,
      I have added the explanation for this command PERFORM-ACTION-SET-AUTOCOMPLETE-KEYSTROKE. Please check and let me know if this helps.

      Regards,
      Chaitanya

      Jan 12, 2024 04:30

Log in or register to comment.

Process command syntax
Process command for modifying data on display forms
© Copyright 1991-2024 BMC Software, Inc. © Copyright 1991-2024 BladeLogic, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.