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

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

Functions

The following table describes functions that you can use to specify field values in the following workflow actions:

  • Open Window
  • Push Fields
  • Service
  • Set Fields

All functions listed in the following table work with active links, filters, and escalations, with the following exceptions:

  • The HOVER, LISTGET, LISTSIZE, MAPGET, TEMPLATE, and VISIBLEROWS functions work only in active links.
  • The ENCRYPT, DECRYPT, and STRIPHTML functions work only in filters and escalations.

Functions

FunctionArgumentsReturnDescription
DROPPEDROWINDEX(field ID)intFor a row on which a drop event occurs on a list view, tree view, or cell-based table field,returns the 1-based row index of the row for the most recent drop operation.
DROPPEDCOLUMNINDEX(field ID)intFor a column on a drop event occurs on a list view, tree view, or cell-based table field, returns the 1-based column index of the column for the most recent drop operation.
COLAVG(column)any (matches column)

For a given column on a list view, tree view, or results list table field, returns the average of all non-NULL row values as a real type. Exceptions:

  • For char columns, converts the column values to numeric and averages the numeric values.
  • If the column type is currency, the average of the currency value is calculated, and the currency type is ignored.
  • If the column type is enum (radio button or selection), the average of the enum ID is calculated.
  • COLAVG ignores date/time, date, and time columns; and returns a NULL value.
 COLCOUNT(column) or (table) intFor a list view, tree view, or results list table field, returns the total number of rows. For a column field, returns the total number of non-NULL rows in a given column.
 COLMAX(column)any (matches column)For a given column on a list view, tree view, or results list table field, returns the maximum value of the row values.
 COLMIN(column)any (matches column)For a given column on a list view, tree view, or results list table field, returns the minimum value of the row values.
 COLSUM(column)any (matches column)

For a given column on a list view, tree view, or results list table field, returns the sum of all values as a real type. Exceptions:

  • For char columns, converts the column values to numeric and sums up the numeric values.
  • If the column type is currency, the sum of the currency value is calculated, and the currency type is ignored.
  • If the column type is enum (radio button or selection), the sum of the enum ID is calculated.
  • COLSUM ignores date/time, date, and time columns; and returns a NULL value.
 CURRCONVERT(currency, type, timestamp) For a given currency, converts currency to a different type according to new date, and recalculates the functional currency values. Use syntax such as: CURRCONVERT($currencyField$, $currencyField2$.TYPE$, $TIMESTAMP$) Use other values for the type and timestamp, such as a character field and a date field. For example:CURRCONVERT($currencyField$, $characterField$, $dateField$) For information about data conversion rules for currency fields, see Workflow considerations for currency fields.
CURRSETDATE(currency, timestamp) 

For a given currency, sets a new date of currency and recalculates the functional currency values. Use syntax such as:

CURRSETDATE($<currencyField>$, $TIMESTAMP$)

Use other values for the timestamp, such as a date field or integer. For example:

CURRSETDATE($<currencyField>$, 1026779689)

For information about data conversion rules for currency fields, see Workflow considerations for currency fields.

CURRSETTYPE(currency, type) 

For a given currency, sets new type of currency and recalculates the functional currency values. Use syntax such as:

CURRSETDATE($<currencyField>$, $<currencyField2>$.TYPE$)

Use other values for the type, such as a character field. For example:

CURRSETTYPE($<currencyField>$, $<characterField>$)

For information about data conversion rules for currency fields, see Workflow considerations for currency fields.

CURRSETVALUE(currency, value) 

For a given currency, sets new value of currency and recalculates the functional currency values. Use syntax such as:

CURRSETVALUE($<currencyField>$, $<currencyField2>$.VALUE$)

Use another field to set the currency value, such as a decimal field. For example:

CURRSETVALUE($<currencyField$, $decimalField>$)

For information about data conversion rules for currency fields, see Workflow considerations for currency fields.

DATE(timestamp)charFor a given date, returns the date portion of the time stamp.
DATEADD(datepart, number, date)date

Adds a specified number of days, weeks, months, or years to the date and returns the new date. Specify datepart using one of the following quoted values:

  • Year --"year ", "yy ", or "yyyy "
  • Month --"month ", "mm ", or "m "
  • Day --"day ", "dd ", or "md "
  • Week --"week ", "wk ", or "ww "

The date parameter is the date value to add to. For example, to add 10 weeks to the 05/20/02 date, enter:

DATEADD("ww", 10, "05/20/08")
 DATEDIFF(datepart, startdate, enddate)int

Depending on the value of datepart (day or week), returns the number of days or weeks between the start date and the end date. Specify datepart using one of the following quoted values:

  • Day --"day ", "dd ", or "md "
  • Week --"week ", "wk ", or "ww "

For example, to find the number of days between date1 and date2, enter:

DATEDIFF("dd", $date1$, $date2$)
DATENAME(datepart, date)char

Depending on the value of datepart (month or weekday), returns the name of the month or the name of the day of the week corresponding to date. Specify datepart using one of the following quoted values:

  • Month --"month ", "mm ", or "m "
  • Weekday --"weekday " or "wd "

For example, to find the weekday for December 31, 2007, enter:DATENAME("wd", "12/31/07")

DATENUM(datepart, date)int

Depending on the value of datepart (year, month, week, day, or weekday), returns the numeric value of the year (4 digits), month (1 to 12), week (1 to 52), day (1 to 31), or weekday (1=Sunday, 2=Monday, and so on). Specify datepart using one of the following quoted values:

  • Year --"year ", "yy ", or "yyyy "
  • Month --"month ", "mm ", or "m "
  • Day --"day ", "dd ", or "md "
  • Week --"week ", "wk ", or "ww "
  • Weekday --"weekday " or "wd "

For example, DATENUM("mm", "12/31/07") returns 12.

DAY(timestamp)intReturns the day of the time stamp (1 to 31).
DECRYPT(ciphertext, key) 

Used in Set Fields filter and escalation actions only. Returns the unencrypted text value of the encrypted text (cyphertext), using the encryption key (key). The return value is smaller than the size of the encrypted string. When decrypting, you must use the same key that you used when encrypting. For example, to decrypt the string in Field1 using the key my_key, enter:

DECRYPT($Field1$, "my_key")

To decrypt a string using a key in KeyField, enter:

DECRYPT("<stringToDecrypt>", $KeyField$)

Note: Use this function with character fields only. See information about the Encrypted String field in Reserved fields.

ENCRYPT(plaintext, k




ey)
 

Used in Set Fields filter and escalation actions only. Returns the encrypted value of a text string (plaintext), using the encryption key (key). The return value is larger than the size of the unencrypted string. For example, to encrypt the string in Field1 using the key my_key, enter:

ENCRYPT($Field1$, "my_key")

To encrypt a string using a key in KeyField, enter:

ENCRYPT("<wordToEncrypt>", $KeyField$)

Note: Use this function with character fields only. See information about the Encrypted String field in Reserved fields.

For more information about the algorithm used for encryption, see Workflow-Encryption-Algorithm.

HOUR(timestamp)intReturns the hour of the time stamp (0 to 23).
HOVER(column)char

For a column in a list view, tree view, a results list table field, or a cell-based table, the string value of the column in the row being hovered over is returned. For a table itself, the row number of the hovered over row is returned. For a given attachment pool, a string value containing the file name (if any) of the hovered attachment is returned. For example, to get the HOVER value for a table column with ID 536880913, enter:

HOVER(536880913)

Note: When the field being referenced for the HOVER function is not being hovered over, an empty string is returned.

This function should be used in conjunction with an On Hover active link execution option.

LEFT(int, char)char

Use this function when the value of the Length Units property of a field is bytes.
Used for single-byte characters.
Returns the left-most characters of the first parameter (char) up to the number of characters indicated by the second parameter (int).

LEFTC(string, int)stringUse this function when the value of the Length Units property of a field is characters.
Returns the left-most characters of the first parameter up to the number of characters indicated by the second parameter.
LENGTH(char)int

Use this function when the value of the Length Units property of a field is bytes.
Used for single-byte characters.
Returns the number of characters in the string.

LENGTHC(string)int

Use this function when the value of the Length Units property of a field is characters.
Returns number of characters in a string.

LISTGET(fieldid, index)stringReturns the value from the list that is maintained by a character field, at the indicated position. If the range of the index is not between 1 and LISTSIZE(), this function returns NULL. For example, if character field 1234 contains the value abc;def;ghi;jkl, calling LISTGET(1234,2) returns the value def.
LISTSIZE(fieldid)intReturns the number of entries in a list or map that is maintained by a character field. If the value is NULL, the function returns 0. For example, if character field 1234 contains the value abc;def;ghi;jkl, calling LISTSIZE(1234) returns the value 4.
LOWER(char)char

Returns all characters in the string (char) as lowercase characters.

Note: No conversion is performed to double-byte characters.

LPADC(string, number, padCharacter)char

Use this function when the Length Units property of a field is characters.
Returns the value that results from padding the first parameter (char) to the left with the value of the third parameter (char), so that the resulting value is the length (in characters) of the second parameter (int) or the length of the original string, whichever is longer.

For example, if you want the results of a Set Fields operation to be a 15-character value with the prefix LEAD, followed by zeros, and ending in the contents of the integer field Call #, enter:

LPADC($Call #$,15,"LEAD00000000000").

If the Call # field contains the number 947, the result of the Set Fields action is LEAD00000000947.

LTRIM(char)charReturns the value of (char) after deleting any blank space and tabs to the left.
MAPGET(fieldid, key)int, string

Returns a value from a map that is present within a character field. If the key does not have a value, this function returns NULL. For example, if character field 1234 contains the value type=4;Name=""John Smith"";operation=""="";status=Open, calling MAPGET(1234,"Name") returns the value John Smith.

Note: You can use double-quotes to escape the value containing space or delimiters.

MAX(any,any[,any]..)any (matches input)

Returns the maximum value of the set specified. The data type of all values must match for the result to be meaningful. For example, to check the current time and the escalation time, and return the greater (latest) value of the two, enter:

MAX ($Escalate Date$, $TIMESTAMP$).

MAX returns $NULL$ only if all arguments in the function evaluate to $NULL$.

MIN(any,any[,any]..)any (matches input)

Returns the minimum value of the specified set. The data type of all values must match for the result to be meaningful. For example, to check the current time and the escalation time, and return the lower (earliest) value of the two, enter:

MIN ($Escalate Date$, $TIMESTAMP$).

If any argument evaluates to $NULL$, the argument is not considered in the evaluation of the function. For example, if MyField is empty (has a value of $NULL$ ), but the field HasValue has a value of 10, then MIN($MyField$, $HasValue$) returns 10.MIN returns $NULL$ only if all arguments in the function evaluate to $NULL$.

MINUTE(timestamp)intReturns the minute of the time stamp (0 to 59).
MONTH(timestamp)intReturns the month of the time stamp (1 to 12).
REPLACE(char,char,char)char

Returns the value that results from replacing any occurrences of the second parameter (char) found in the first parameter (char) with the contents of the third parameter (char). For example, to replace the name Bob with the name Robert, enter:

REPLACE ($Submitter$, "Bob", "Robert").

To replace all occurrences of the double-quote character (") within a character string with another character, for example, replacing any instance of a double quote with the name Robert, enter:

REPLACE ($Submitter$, """", "Robert").

As a result, anywhere a double quote is found in the Submitter field, the double quote is replaced with the name Robert.

RIGHTC(string, number)char

Use this function when the Length Units property of a field is characters.

Returns the right-most characters of the first parameter (char) up to the number of characters indicated by the second parameter (int).

For example, to set the value of a field to the last four characters of an account code, enter:

RIGHTC($Account#$,4).
ROUND(real), (decimal), or (currency)int or currencyReturns the rounded value of a real number or a complex data type. For a decimal value, for example, 5.1 to 5.4 are rounded to 5, and 5.5 to 5.9 are rounded to 6. For a currency value, for example, 5.01 USD through 5.49 USD are rounded to 5.00 USD, and 5.50 USD through 5.99 USD are rounded to 6.00 USD.
RPADC(string, number, padCharacter)char

Use this function when the value of the Length Units property of a field is characters.
Returns the value that results from padding the first parameter (char) on the right with the value of the third parameter (char), so that the resulting value is the length (in characters) of the second parameter (int) or the length of the original string, whichever is longer.

For example, to add blank spaces after a submitter's name to make the entry 20 characters long, enter:

RPADC($Submitter$,20," ")
RTRIM(char)charReturns the value of (char) after deleting any blank space and tabs to the right.
SECOND(timestamp)intReturns the seconds from the time stamp (0 to 59).
SELECTEDROWCOUNT(tableid)intFor tree view tables, it returns the number of leaf nodes represented by the selected node. If a node does not contain a leaf node, this function returns 1. For list view tables, it returns the number of selected rows. For cell-based tables, it returns the number of selected cells.
STRIPHTML(fieldID)charRemoves all formatting and image information from the contents of a rich-text-formatted field. The function returns a plain text string. See Adding rich-text-formatting capabilities to a character field.
STRSTR(char, char)int

Use this function when the value of the Length Units property of a field is bytes.
Returns the position (in characters) of the second parameter (char) if it is found in the first parameter (char). If the second string is not found, this function returns a -1. This function is zero-indexed.

STRSTRC(string, findchar)int

Use this function when the value of the Length Units property of a field is characters.
Returns the position of the second parameter, if found in the first parameter. This function is zero-indexed.
For example, STRSTRC("test","s") returns the value '2'.

SUBSTR

(char, int, int)char

Use this function when the value of the Length Units property of a field is bytes.
Returns the substring of characters in the first parameter (char) starting at the position (in characters ) indicated by the second parameter (int) and continuing to the position indicated by the third parameter (int). The string is zero-indexed (that is, numbering of characters begins at 0).

If the third parameter is not included, the function returns characters to the end of the string. If the third parameter is less than the second parameter, the function returns a NULL value.

SUBSTRC(string, int, int)stringUse this function when the value of the Length Units property of a field is characters.
Returns the substring of characters in the first parameter starting at the position indicated by the second parameter  and continues to the position indicated by the third parameter. If the third parameter is not included, the function returns characters to the end of the string. If the third parameter is less than the second parameter, the function returns a NULL value. The string is zero-indexed.
TEMPLATE(char,char,char,...)charReturns a string from the specified template formatted with values substituted for template parameters. The first parameter is the template name. The template parameters and their values follow in pairs. For example:TEMPLATE("Simple Template", "First Name", $Short Description$, "Last Name", $Submitter$, "City", "Sunnyvale")
TIME(timestamp)charReturns the time portion of the time stamp.
TRUNC(real), (decimal), or (currency)int or currencyReturns the truncated value of a real number or a complex data type. For a decimal value, for example, 5.1 through 5.9 are truncated to 5. For a currency value, for example, 5.01 USD through 5.99 USD are truncated to 5.00 USD.
UPPER(char)char

Returns all characters in the string (char) as uppercase characters.

Note:

  • No conversion is performed to double-byte characters.
  • This function does not support the Capital Sharp S (ß) character in an active link.
VISIBLEROWS(int)intReturns the number of rows currently visible. The value does not include any deleted rows in the visible range. If no records are displayed or the table is not chunked, the function returns a value of 0. If the table ID is invalid, the function returns a NULL value.
WEEKDAY(timestamp)intReturns the weekday of the time stamp (1 to 7, where 1=Sunday and 7=Saturday).
YEAR(timestamp)intReturns the year portion of the time stamp.



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

Comments

  1. Jason Miller

    It looks like   AR_FUNCTION_ DROPPEDROWINDEX   and   AR_FUNCTION_ DROPPEDCOLUMNINDEX are incorrectly documented. They are actually   DROPPEDROWINDEX   and   DROPPEDCOLUMNINDEX  .

     

    Also  SELECTEDROWCOUNT only has a 1 for the description. That is not very helpful.

    Jan 25, 2017 06:26
    1. Prachi Kalyani

      Hello Jason,

      I have updated the topic.

      Thanks,

      Prachi

      Jan 27, 2017 02:19
      1. Jason Miller

        Wonderful! Thanks!

        Do you think it the 8.0, 8.1 and 9.0 pages should be updated as well since those are still supported versions?

        https://docs.bmc.com/docs/display/public/ars8000/Functions

        https://docs.bmc.com/docs/display/public/ars81/Functions

        https://docs.bmc.com/docs/display/public/ars9000/Functions

        Jan 27, 2017 10:30
        1. Prachi Kalyani

          We have updated the topics for all the versions.

          Thanks,

          Prachi

          Jan 28, 2017 07:53
  2. Jason Miller

    Is there a reason many of the string functions are missing?

    Example: LEFTC, LPADC, RIGHTC, RPADC, SUBSTRC, STRSTRC

    The are also missing form the 8.0, 8.1 and 9.0 docs. Misi refers to some of these functions in his comments here: https://docs.bmc.com/docs/display/public/ars81/Functions

    I assume the functions were listed at that time or he would have pointed this oversight at that time instead of just discussing deprecated functions. It is bothersome that that people depend on these docs trusting they are complete.

    Aug 25, 2017 11:43
    1. Anagha Deshpande

      Hello Jason,

      We are working on this. Will update the topic soon.

      Regards,

      Anagha 

      Aug 28, 2017 03:26
      1. Onkar Telkikar

        Hello Jason,

        Apologies for the late reply.

        We have updated the documentation for 18.08, 18.05, 9.1, and 9.0 versions. However, at present, we haven't updated the documentation for 8.1 and 8.0 versions, because AR System 8.1 and 8.0 versions are currently in End of Version Support.

        Regards,

        Onkar  

        Sep 26, 2018 07:37
        1. Jason Miller

          Thank you for making updates!

          I do not agree with the approach of only updating the documentation for supported versions because there will be customers using 8.x for many years to come (for example I know there are still organization on 5.x out there). While I appreciate BMC has resource constraints, only correcting documentation of supported versions will continue to frustrate customer with what is already considered by many as sub-standard and incomplete documentation.

          Sep 26, 2018 11:24
  3. Suresh B

    I have table with a STATUS column values YES/NO. Is there any function to count number of YESs? COLCOUNT(STATUS) counts rows. Something like COLCOUNT(STATUS="YES")

    Feb 12, 2018 11:23
  4. Chris Jones

    STRSTRC (string)

    should be

    STRSTRC (string, find)

    Mar 13, 2018 05:37
    1. Kamalakannan Srinivasan

      Hi Chris,

      Thank you for your comment. Will discuss with the technical team and then update the topic.

      Regards,
      Kamal

      Mar 14, 2018 03:57
      1. Onkar Telkikar

        Hello Chris,

        Apologies for the late reply. I have updated the documentation.

        Thanks,

        Onkar

        Sep 26, 2018 04:27
  5. Phillip Brockhaus

    Another problem with STRSTRC and STRSTR - STRSTRC says that it returns a string and STRSTR says that it returns an int. I believe they both return int.

    Nov 05, 2019 09:02
    1. Himanshu Raul

      Hi Phillip,

      Thank you for your feedback on the documentation. We have updated the topic.

      Regards,

      Himanshu

      Jan 02, 2020 12:57