Function Recipes

Overview

This page lists a collection of function recipes you can use throughout the Appian application. Similar to a cookbook, it shows the individual ingredients that go into creating an expression using Appian functions, the order in which to combine them, and tips on when to use them or modify for preference.

The expressions listed below are not the only way to accomplish each desired outcome. This page is intended to teach you methods for creating expressions using Appian functions that are practical and efficient, as well as provide working expressions you can implement as is. Just as with cooking recipes, you may want to alter the values in each recipe to accommodate your specific requirements.

The function recipes are categorized by the type of output. Each recipe is titled with the question in mind, "What do you want to do?"

NOTE: For function recipes that require a rule as an Ingredient, create the rule as listed before implementing the function recipe.

Date/Time Results

Retrieve Next Anniversary Date

Use Case

You want to retrieve next year's anniversary date based on a start date, such as an employee's hire date of 02/05/2011.

Ingredients

Inputs

  • start (date)

Expression

if(
  and(month(ri!start) <= month(today()),day(ri!start) <= day(today())),
  date(1 + year(today()), month(ri!start), day(ri!start)),
  date(year(today()), month(ri!start), day(ri!start))
)

Start a Timer One Minute After a Process Starts

Use Case

You want to set a timer to start exactly one minute after a process starts, as compared to automatically.

Ingredients

Expression

Configure this in the "Delay until the date and time specified by this expression" on the Setup tab for the Timer Event.

pp!start_time + minute(1)

NOTE: To change the time difference from 1 minute to more, modify the value in the minute() function as desired.

Add Ten Minutes to a DateTime Value

Use Case

You want to add ten minutes to a datetime value saved as pv!datetime.

Ingredients

Expression

pv!datetime + intervalds(0,10,0)

NOTE: To change interval added to the datetime value, modify the values in intervalds() as desired.

Determine if a Date-Time Value Falls Within Working Hours

Use Case

Users are able to enter any date-time value, but you want to perform an extra validation after users submit the form to determine if a date-time value (saved as ri!dt) falls between your company's working hours of 6:00 AM and 5:00 PM.

The idea is to work with one consistent time scale, which is done here by the use of timestamps rather than both hours and minutes. This function constructs new timestamps for the boundaries matching the input.

Ingredients

Inputs

  • dt (DateTime)

Expression

or(
  ri!dt > gmt(
    datetime(
      year(ri!dt),
      month(ri!dt),
      day(ri!dt),
      17,
      0,
      0
    )
  ),
  ri!dt < gmt(
    datetime(
      year(ri!dt),
      month(ri!dt),
      day(ri!dt),
      6,
      0,
      0
    )
  )
)

NOTE: To change the working hours, modify the values within the datetime() function as desired

Display the Number of Days Before a Specific Date

Use Case

You want to tell users how many business days are left before a deal closes, if the deal has already closed, or if the deal is closing today.

Ingredients

Inputs

  • closeDate (Date)

Expression

if(
  networkdays(today(), ri!closeDate)<=0,
  "This deal has closed.",
  if(
    networkdays(today(), ri!closeDate)=1,
    "This deal will close at the end of today.",
    "This deal will close in" & networkdays(today(), ri!closeDate) & "business days."
  )
)

NOTE: To change the text that displays, modify the text as desired. To base the number of days on a system calendar, replace any instance of networkdays(today(), ri!closeDate) with calworkdays(today(), ri!closeDate, "companyCalendar") where companyCalendar is the name of your system calendar. To include all days (including weekends), replace any instance of networkdays(today(), ri!closeDate) with tointeger(ri!closeDate - today()).

See also: calworkdays() and tointeger()

Convert an XML String into a Value of Type Datetime

Use Case

You have a localized XML string representing a date and time and need to convert it to a value of type Datetime in the GMT timezone.

Ingredients

Inputs

  • dateText (Text)

Expression

=with(
  local!fullArray: split(ri!dateText, "T"),
  local!dateArray: split(local!fullArray[1], "-"),
  local!timeArray: split(left(local!fullArray[2], 12), ":"),
  local!smsArray: split(local!timeArray[3], "."),
  local!timeZone: "GMT" & right(local!fullArray[2], 6),
  local!rawDate: datetime(
    local!dateArray[1], 
    local!dateArray[2], 
    local!dateArray[3], 
    local!timeArray[1], 
    local!timeArray[2],
    local!smsArray[1],
    local!smsArray[2]
  ),
  gmt(
    local!rawDate,
    local!timeZone
 )
)

yields 9/25/2013 1:50 AM GMT+00:00 where ri!dateText = 2013-09-24T19:50:24.192-06:00

Number Results

Return the Number of Active Employees in Your Application

Use Case

You want to quickly display how many employee records exist in your application.

Ingredients

Expression

  • myQueryRule(topaginginfo(1,0)).totalCount

NOTE: When using a batchsize of 0 and attempting to only retrieve a total count based on a query, the function detailed above is better to use than count(myQueryRule()). If you used count(myQueryRule()), the system would run the main query; whereas using .totalcount, the system only executes a count query against the database.

Return the Total Number of Revisions Made to a Document

Use Case

You want to show the number of times a document has had a new version saved.

Ingredients

Input

  • doc (Document)

Expression

  • document(ri!doc,"totalNumberOfVersions")-1)

Return a Random Integer in a Range

Use Case

You want to return a random integer between two integers, inclusive.

Ingredients

Inputs

  • min (Number (Integer))
  • max (Number (Integer))

Expression

ri!min + tointeger(rand() * (ri!max - ri!min))

Text Results

Truncate Text After 50 Characters

Use Case

You want to truncate the remaining part of a text value once it surpasses 50 characters by replacing the excess text with an ellipsis (…).

Ingredients

Inputs

  • text (Text)

Expression

if(
  len(ri!text) > 50,
  left(ri!text, 50) & "...",
  ri!text
)

NOTE: To change the amount of characters allowed before truncating, modify the numeric value as desired.

Display the Full Name of a User

Use Case

You want to display the full name of a user despite knowing only the username. Additionally, the field that is storing user information may not always contain a value.

Ingredients

Inputs

  • user (User)

Expression

if(
  isnull(ri!user),
  "",
  user(ri!user, "firstName") & " " & user(ri!user, "lastName")
)

NOTE: To change the user information that is populated, modify the second parameter in the user() function as desired.

Create a Title from any Text Value

Use Case

You want to convert a text value to display as a title, which will capitalize the first word, and all words not found in a "no capitalize" list.

Ingredients

Inputs

  • title (Text)

Expression

with(
  /* Breaks up the title into an array of words and removes whitespaces. */
  local!titleArray: split(trim(ri!title), " "),
  /* A list of words that will be ignored. Adjust this list to change what does not get capitalized. */
  local!noCaps: {"a","an","the","at","by","in","of","up","as","and","but","or","for","nor","etc.","etc","on","at","to","from", "that"},
  /* If the word is in local!noCaps but not the first word, don't capitalize. Otherwise capitalize the word. */
  concat(
    a!forEach(
      items: local!titleArray,
      expression: if(
        and(not(fv!isFirst), contains(local!noCaps, fv!item)),
        fv!item,
        proper(fv!item)
      ) & if(fv!isLast, "", " ")
    )
  )
)

NOTE: To produce initial caps for your own text, modify the text value as desired.

Array Results

Remove all Values in an Array

Use Case

You want to remove all values in an array so it is considered empty.

Ingredients

Inputs

  • array (Any Array)

Expression

ldrop(ri!array, count(ri!array))

NOTE: Instead of the word array, enter the name or array reference as needed.

Repeat Each Item in an Array Based on the Values of a Different Array

Use Case

You want to repeat each item in an array (for example, local!textList) a certain number of times as defined by the values in a different array (for example, local!frequencyList).

  • Where local!textList = {"a", "b", "c"} and local!frequencyList = {2, 3, 1}, the output would be {"a", "a", "b", "b", "b", "c"}.

Ingredients

Inputs

  • textList (Array)
  • frequencyList (Array)

Expression

load(
  local!textList: {"a","b","c"},
  local!frequencyList:{2,3,1},
  a!forEach(
    items:local!textList,
    expression: repeat(
      local!frequencyList[fv!index],
      fv!item
    )
  )
)

NOTE: To change which variables to use, modify the textList value to the array variable that should determine the text to repeat and modify the frequencyList value to the array variable that should determine how many times each text value in the aforementioned array should be repeated.

Extract a List from an EntityData Array of the Data Written to a Single Entity

Use Case

You want to extract the list of data written to an entity (for example, Opportunity) based on the output generated by using the Write to Multiple Data Store Entities Smart Service to write to three entities: Opportunity, Contact, and Line Item.

See also: Write to Multiple Data Store Entities Smart Service

The explanation of the configuration is longer than the solution. If you configure the Write to Multiple Data Store Entities Smart Service to update data for three entities (Opportunity, Contact, and Line Item), each entity may show up more than once in the EntityData input array. Consequently, the output of the smart service ("Stored Values") would contain a dynamic number of elements for each EntityData.

To get the list of all Opportunities that were updated by the smart service, you need to append every Data field where the entity is equal to Opportunity.

Ingredients

Expression

Within the expression editor of a new custom output:

a!forEach(
  items: merge(ac!StoredValues, cons!OPPORTUNITY_ENTITY),
  expression: if(
    fv!item[1].entity = fv!item[2],
    fv!item.Data,
    {}
  )
)

NOTE: To change the entity by which to pull the list of data from, modify the OPPORTUNITY_ENTITY value as desired.

Sort an Array

Use Case

You want to sort an array of values.

Ingredients

Inputs

  • array (Any Array)

Expression

todatasubset(
  a!forEach(
    ri!array,
    {
       value: fv!item
    }
  ),
  a!pagingInfo(
    startIndex: 1,
    batchSize: -1,
    sort: a!sortInfo(
      field:"value",
      ascending: true
    )
  )
).data.value

Boolean Results

Determine if Items in an Array are Contained Within Another Array

Use Case

You want to see if any of the items in an array are contained within another array.

Ingredients

Expression

or(
  a!forEach(
    items:ri!originalArray,
    expression: contains(ri!compareArray, fv!item)
  )
)

Matching Results

Return a CDT from an Array that Contains a Field Value Matching Another Value

Use Case

You have an array of department CDTs, each containing a field called Id, and you want to retrieve the CDT with an id value matching the value of a process variable.

Ingredients

  • displayvalue()
  • rule input: ri!departmentid (Integer)
  • rule input: ri!departments (CDT Array)
  • Custom Data Type:

          department (Text)
              |- id (Integer)
              |- address (Text)
    

Expression

displayvalue(ri!departmentId, ri!departments.id, ri!departments, "none")

NOTE: To change the value that displays if the ri!departmentId doesn't match any ri!department.id values, modify the "none" text value as desired.

FEEDBACK