Using Inline Functions

This content applies to legacy design tools (such as K2 Studio, K2 for Visual Studio, or the Silverlight-based K2 workflow design tool). If you have upgraded from K2 blackpearl 4.7 to K2 Five, these tools may still be available in your environment. These legacy tools may not be available in new installations of K2 Five. These legacy tools may also not be available, supported, or behave as described, in future updates or versions of K2. Please see the legacy component support policy for more information about support for these components.

Inline functions are available from the Context Browser, and allow the process creator to perform simple and advanced operations as well as integrate data from Word, Excel, and other SharePoint Lists and Libraries.

An expression can be a short expression that refers to a field object or a long expression that supports decision functions or formatting based on fields or other items.

The Expression Wizard is opened from either selecting the Expression function from the Context Browser > Function Browser or by clicking on the button on a Function Wizard screen. The Expression Wizard enables a user to build expressions that perform operations and return values.

The expression builder includes a set of operators and functions for use in the Build Expression wizard. An expression can use a single function, but typically an expression combines functions with operators and uses multiple functions.

List data types cannot be used in the expression builder. Examples of list data types are binary data fields, XML repeating sections, SmartObject lists and functions returning arrays or binary (array of bytes).table>

An operator is added to the Build Expression canvas by clicking on the specific operator button, or by typing it in directly. Parenthesis can also be added to the Build Expression canvas by clicking on the ellipses button.

To distinguish between Text and Numeric values, quotes (single or double) are used for Text.
For example:
When using & for joining text strings, “abc” & “def” will give a result of “abcdef”
When using + for adding numeric values, 1.0 + 2.0 will give a result of 3.0

The supported operators are categorized as follows:

Category Operators Description
Mathematical =, <, >, +, -, *, /, ^ , <=, >=

equal, less than, greater than, plus, minus, multiply, divide, power of, less than or equal to, greater than or equal to
Text & Concatenates strings (including static values such as "<space>") together
Logical =, <>, And, Or, Xor equal, not equal, and, or, xor
Date and Time =, <, >, <=, >= equal, less than, greater than, less than or equal to, greater than or equal to

BODMAS

The expression builder adheres to BODMAS (Brackets, Over, Divide, Multiply, Add, Subtract) rules.

Expressions are evaluated in the following order:

  • Brackets
  • Boolean (and, or, xor
  • Comparison (<, >, <=, >=, <>, =)
  • Multiply, Divide, Mod, Power (*, /, mod, pow)
  • Addition, Subtraction, Concatenation (+, -, &)
  • Not (not)
  • Negate (-)
  • Special (when, format)
  • Literals (true, false, “hello”, 5, 5.0)
Example:

The expression 1 + 2 * 3 will result in multiplying 2 and 3 first, before adding 1 to the result. Furthermore Boolean and comparison operations happen before any mathematical ones. For instance the expression 2 > 5 + 1 will fail the validation check because the Boolean operation greater than is evaluated before the addition, which will result in trying to add a false value and 1.

Types of operators

  • Unary: These operators must be used in front of something (e.g. the ‘-‘ in -5).
  • Inset: These operators must be used in the middle of two things (e.g. the ‘+’ in 1 + 1).
  • Supplementary: These operators must be used around two things.
  • Term: This refers to a part of an expression (could be like a word or phrase in a sentence).
Operator Description Example
& Use to join two or more strings or fields. Input Value: FirstName & " " & LastName
Result: "John Doe"
+ Use to add numbers or decimals. Input Value: 1 + 1.1
Result: 2.1
- Use to subtract numbers or decimals. Input Value: 1.1 – 1
Result: 0.1
* Use to multiply numbers or decimals. Input Value: 1 * 1.1
Result: 1.1
/ Use to divide numbers or decimals. This will always result in a decimal.

Input Value: 1 / 1.1.

Result: 0.909
mod Use to return the remainder after a division.

Input Value: 16 mod 5

Result: 1
pow Use to apply an exponent (power of) to preceding number. Input Value: 2 pow 3
Result: 8
= Use to determine if two numbers or fields are equal. Returns Boolean. Input Value: Price = 500
Result: True
<> Use to determine if two numbers are not equal. Returns Boolean. Input Value: Price <> 400
Result: True
> Use to determine if number on left is greater than number on right. Returns Boolean. Input Value: 2>1
Result: True
< Use to determine if number on left is less than number on right. Returns Boolean. Input Value: 1<2
Result: True
>= Use to determine if number on left is greater than or equal to number on right. Returns Boolean. Input Value: 1>=1
Result: True
<= Use to determine if number on left is less than or equal to number on right. Returns Boolean. Input Value: 1<=1
Result: True
And Performed on two Boolean values. Returns True if both values are True, and False if either value is False. Input Value: True
Input Value: False
Result: False
Or Performed on two Boolean values. Returns True if either value is True, False if both values are False. Input Value: True
Input Value: False
Result: True
Xor Performed on two Boolean values. Returns True if one and only one value is True. Input Value: True
Input Value: True
Result: False
Not Negates (Boolean) a value. Input Value:not (1=1)
Result: False
(…) Surrounds selected items with parentheses. Use for order of operations. Input Value:(5 + 5) * (4 + 6)
Result: 100
- (unary) Negates (numeric) a value. Input Value:-(5 + 5)
Result: -10

Brackets (Parenthesis or Supplementary)

Brackets behave exactly like they do in mathematics. They force a certain part of the expression to be evaluated before another one is evaluated. You can also use brackets for Boolean and comparison terms. For example:

(true and true) or (false and true)
= true or (false and true)
= true or false
= true

or

(5 > 6) or (6 > 5)
= false or (6 > 5)
= false or true
= true

Not (Unary)

Not simply changes true to false; and false to true.

not true or false
= false or false
= false

Boolean (Inset)

Boolean operators simply combine two true/false values in certain ways. These ONLY work on true/false (Boolean) values. They are and, or and xor. The following tables give the outcomes.

And (both must be true):

Value 1 Value 2 Outcome
True False False
True True True
False False False
False True False

Or (either value can be true):

Value 1 Value 2 Outcome
True False True
True True True
False False False
False True True

Xor (Exclusive or, either can be true, but not both):

Value 1 Value 2 Outcome
True False True
True True False
False False False
False True True

Comparison (Inset)

The comparison operators determine the size relation between two values. They can be used on numbers, text, dates and time spans.

Multiply (Inset)

The multiply operators are * (multiply), / (divide), mod (modulus) and pow (power). These operators only work on number values. Divide will always result in a decimal. Multiply, modulus and power will result in the most precise type:

  • If any of the two operands are decimal then the result is decimal.
  • If both operands are integer then the result is integer.

Addition (Inset)

There are the two mathematical addition operators (+ and -); as well as the string addition (concatenation) operator &. These can also be used on dates and time spans. Please note that the following expression will not result in a concatenation in the expression builder (unlike the K2 text box):

Hello [FieldPart]

It is required to use the string addition operator to concatenate strings.

Negate (Unary)

The negate operator simply turns a number value into it’s negative. For instance:

-(1 + 1)
= -2

Operator Description Example
when Used to execute one of two sub-expressions based on a condition.

Input Value: when 1=1 then "yes" otherwise "no"
Result: "yes"
format Used to format a non-textual value into a textual value. Input Value: 1 format "0.0"
Result: 1.0

When (Complex)

This operation allows you to select which piece of the expression you would like to execute based on a Boolean (true/false) value. For instance:

when 5 > 10 then "Yes" otherwise "No"

= when false then "Yes" otherwise "No"

= "No"

More generally, when condition then true part otherwise false part

There are two restrictions:

  • The term between when and then must be Boolean (true/false) once it has evaluated.
  • The terms between then and otherwise, and the term after otherwise have to be the same type. The following is not a valid expression: when true then "Yes" otherwise 1

The expression engine will not evaluate the true part or false part if it does not need to. This means if you have a SmartObject Create in the true part and the condition is false then the SmartObject Create will not be called.

Format (Inset)

The format operator allows you to format a number, date, etc. according to a certain format string. For instance: [DateField] format "yyyy mm dd". It The standard .Net formatting format is used, and the following online references explain the available formatting styles in more detail:

Dates:

  • http://msdn.microsoft.com/en-us/library/az4se3k1.aspx
  • http://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx
Numbers:
  • http://msdn.microsoft.com/en-us/library/dwhawy9k.aspx
  • http://msdn.microsoft.com/en-us/library/0c899ak8.asp

Literal Description Example
text Used to create a text value. Start with either " or ' and end the literal with the same character.

Input Value: "Hello ""Customer"""
Result: Hello "Customer"
integer Used to create an integral value. Input Value: 1
Result: 1
decimal Used to create a real (decimal) value. Input Value: 1.0
Result: 1.0
boolean Used to create a Boolean value, “yes” or “true”; and “no” or “false”. Input Value: yes
Result: true
date time Used to create a date time value. It must be one of the following:
[year month day]
[year month day hour:minute]
[year month day hour:minute:second]		 Input Value: [2001 01 01]
Result: First January 2001
Input Value: [1001*2 01 01]
Result: First January 2002
time span Used to create a time span. It must be one of the following:
[hours:minutes:seconds]
[days:hours:minutes:seconds]
[days:hours:minutes:seconds:milliseconds]		 Input Value: [15:0:0]
Result: 15 hours
Input Value: [8*2:0:0:0]
Result: 16 days

Number Literals

Numbers can either be integers or decimals; for example, 5 and 5.1. Remember even 5.0 is a decimal. Exception: When working with mathematical or comparison operators it is valid (unlike functions) to use text. For instance the following is perfectly valid:

"5" + 1

However, if the operator is not mathematical two strings will be left as strings:

"A" > "5"

However if one is a number both will be numbers:

"1" > 2

Finally, these string values are NOT validated – they will only fail at runtime. Validation in this case has been relaxed to make it simpler to use Field Parts that do not have the correct type.

String Literals

Strings are pieces of text. They can start with either a double quote " or a single quote '; they must start and end with the same type of quote. They can contain new lines. To add a quote in the middle of a string, double it up. For instance:

"Dear Customer,

We would like to thank you for the purchase of ""Product"".

Regards

Management"

Or:

'Dear Customer,

We would like to thank you for the purchase of ''Product''.

Management'

Adding a Field Part in the middle of the string can be done in the following way: "Dear " + [Customer] + ","

Boolean Literals

Valid values for Boolean literals are true and false, as well as yes and no.

Date Literals

Dates can be specified in an expression using the following syntax:

[yyyy mm dd]

Or

[yyyy mm dd hh:mm]

Or

[yyyy mm dd hh:mm:ss]

Date and time span literals can also contain operators or Field Parts in their terms, as long as they evaluate to positive integer values. For example the following expression is valid:

[(1002 * 2) 01 01]

Subtraction:

Two dates can also be subtracted, whether Field Part or date literal. This will result in a time span.

Timespan Literals

You can also specify time differences in an expression. Please note that a TimeSpan cannot be the result of an expression because K2 does not support it outside of the expression builder – it must be used to form a date.

[hh:mm:ss]

Or

[dd:hh:mm:ss]

Or

[dd:hh:mm:ss:ms]

Timespan behave the same as date literals – you can use operators inside of terms. The following expression will result in a valid Timespan:

[1+1:00:00]
Please note that both the date and Timespan literals have no concept of localization.

Addition:

You can add two time spans (results in a Timespan). You can also add a Timespan to a DateTime which results in a DateTime. Example:

[2010 01 01] + [01:00:00:00]

= [2010 01 02]

Subtraction:

You can subtract two TimeSpans (results in a TimeSpan). This will give you the difference between them. Example:

[03:00:00:00]- [02:00:00:00]

= [01:00:00:00]

As previously stated, this cannot be the final result of an expression and must be used as part of a bigger expression that involves dates.

Negation:

This will make the TimeSpan negative (results in a TimeSpan).

 

Inline Functions are powerful tools that allows the process designer to use complex functions in various locations within K2. These functions can be configured and then saved in two different ways, either by saving the function configuration for use later, or by saving the result of the function in a process data field.

These options can be found on any of the Inline Functions by expanding the Function Name. Click on the arrow next to the Function Name to display the advanced features.

Feature Description How to use it
Save result to data field Saves the result of the Inline Function to a specified data field Check the box next to Save result to data field
Save function configuration Saves the configuration of the Inline Function Check the box next to Save function configuration
The generated Function Name will be XML encoded to ensure it can be saved in the K2 for SharePoint process definition (XML)

Save Result to Data Field

The Save result to data field option can be found on any of the Inline Functions by clicking on the arrow next to the Function Name. This will display the advanced features. When clicking on Finish, the data field is created and results will be saved to this data field. To Edit/Delete the data field, right-click the data field and select the required action.

To view or edit the Data Field portion, click on the saved Inline Function to open the data field portion.

Double click the Value to view the configured Inline Function, i.e. how the value is calculated.

The configured Inline Function is displayed. This configuration represents the method used to calculate the Value of the data field.

You need to have the same type+name process/activity data field or you will receive a compile error when trying to deploy the process.
The name supplied in the Function Name textbox will be used as the generated Data Field name.

Save Function Configuration

The Save function configuration option can be found on any of the Inline Functions by clicking on the arrow next to the Function Name. This will display the advanced features.

When clicking on Finish, the configuration of the specific function is saved and can be found under the Saved Functions node in the Function Browser. To Delete the function, right-click the function and select Delete.

When using process specific data or context within the function, reusing the saved function in a the new process could break the functions as that process would not have the process specific data.
The name supplied in the Function Name textbox will be used as the generated Function name in the Saved Functions folder.

Note that the success of a conversion depends on the data itself and not only on the input type. For example, converting a Long data type to a Short will work as long as the data itself is convertible, i.e. a number of 16 bits or less. Converting a Decimal to Boolean will only work if the decimal number is 1.0 or 0.0.

Boolean can be converted from a number, where 1 equals True and 0 equals False.

Function Accepted input types
To Binary String (Base-64)
To Boolean String, Byte, Short, Integer, Long, Double, Decimal, Boolean
To Bytes String
To DateTime String
To Decimal String, Byte, Short, Integer, Long, Double, Decimal, Boolean
To Double String, Byte, Short, Integer, Long, Double, Decimal, Boolean
To Integer String, Byte, Short, Integer, Long, Double, Decimal, Boolean
To Long String, Byte, Short, Integer, Long, Double, Decimal, Boolean
To Short String, Byte, Short, Integer, Long, Double, Decimal, Boolean
To String String, Byte, List of Byte, Short, Integer, Long, Double, Decimal, Boolean
To K2 FQN User String, String[]
To SharePoint Claims User String, String[]

An item is selected and then added to the canvas or K2 field part by clicking the Add button or by using drag-and-drop.

Functions Description Example
To Base-64 String Converts an array of bytes to a base-64 encoded string Input Value: { 69, 120, 97, 109, 112, 108, 101 }
Result: "RXhhbXBsZQ=="
To Binary Converts a base-64 encoded string to an array of bytes. Input Value: "RXhhbXBsZQ=="
Result: { 69, 120, 97, 109, 112, 108, 101 }
To Boolean Converts a value to a Boolean data type. Input Value: "True"
Result: True
To Bytes Converts a string to an array of bytes using the default character encoding. Input Value: "Example"
Result: { 69, 120, 97, 109, 112, 108, 101 }
To Date Time Converts a value to a DateTime data type. InputValue: "2009/02/02 05:05:05 AM"
Result: 2009/02/02 05:05:05 AM
To Decimal Converts a value to a Decimal Data type. Input Value: "1"
Result: 1.0
To Double Converts a value to a Double data type. Input Value: "1"
Result: 1.0
To Integer Converts a value to an Integer data type. Input Value: "1.0"
Result: 1
To Long Converts a value to a Long data type. Input Value: "1.0"
Result: 1
To Short Converts a value to a Short data type. Input Value: "1.0"
Result: 1
To String Converts a value to a String data type. Example 1:
Input Value: 12345
Result: "12345"
Example 2:
Input Value: { 69, 120, 97, 109, 112, 108, 101 }
Result: "Example"
To K2 FQN User Converts an encoded SharePoint claims user or group to K2 FQN user or group.

Example 1:
Input Value: c:0-.f|ldaproleprovider|legal
Result: K2LDAP:legal

Example 2:
Input Value: c:0-.f|ldaproleprovider|legal;i:0#.f|ldapmembershipprovider|holly

Result: K2LDAP:joe;K2LDAP:holly
To SharePoint Claims User Converts a K2 FQN user or group to an encoded SharePoint claims user or group. Example 1:
Input Value: c:0-.f|ldaproleprovider|legal
Result: K2LDAP:legal
Example 2:
Input Value: c:0-.f|ldaproleprovider|legal;i:0#.f|ldapmembershipprovider|holly
Result: K2LDAP:joe;K2LDAP:holly

The Function Wizard content varies according to the selected function.

Data functions generates and returns a random GUID or updates a Data Field.

Functions Description Example
Generate GUID

Generates and returns a random GUID in String format

 0f8fad5b-d9cb-469f-a165-70867728950e
Update Data Field

Updates a Data Field with the specified value.

Data Field - The Data Field which will be updated.

Value - The value with which to update the Data Field.

Data Field - Salary

Value - 104200

Result - 104200

Date and Time functions perform operations on date and time input values and returns a string, numeric, or date and time value.

An item is selected and then added to the canvas or K2 field part by clicking the Add button or by using drag-and-drop.

Functions Description Example
Add Days Adds a specified number of days to a date. Date and Time: 01/01/2009 00:00:00 AM
Days: 1
Result: 01/02/2009 00:00:00 AM
Add Hours Adds a specified number of hours to a date and time. Date and Time: 01/01/2009 00:00:00 AM
Hours: 1
Result: 01/01/2009 01:00:00 AM
Add Minutes Adds a specified number of minutes to a date and time. Date and Time: 01/01/2009 00:00:00 AM
Minutes: 1
Result: 01/01/2009 00:01:00 AM
Add Seconds Adds a specified number of seconds to a date and time. Date and Time: 01/01/2009 00:00:00 AM
Seconds: 1
Result: 01/01/2009 00:00:01 AM
Day Gets the day of a given date. Date: 01/01/2009 00:00:00 AM
Result: 1
Day Difference Determines the number of days between two dates, and hours are decimal fractions.

Example 1:
First Date: 01/01/2009 00:00:00 AM
Second Date: 01/02/2009 00:00:00 AM
Result: 1.0

Example 2:
First Date: 01/01/2009 00:00:00 AM
Second Date: 01/01/2009 12:00:00 PM
Result: 0.5
End of Month - Integer Gets the last day of a month. Year: 2009
Month: 1
Result: 01/31/2009 11:59:59 PM
End of Month - DateTime Gets the last day of a month. Date and Time: 01/01/2009 00:00:00 AM
Result: 01/31/2009 11:59:59 PM
End of Quarter - Integer Gets the last day of a quarter.

Year: 2009
Quarter: 1

Result: 03/31/2009 11:59:59 PM
End of Quarter - DateTime Gets the last day of a quarter. Date and Time: 01/01/2009 00:00:00 AM
Result: 03/31/2009 11:59:59 PM
End of Week - Integer Gets the last day of a week. Year: 2009
Week: 1
Result: 01/06/2009 11:59:59 PM
End of Week - DateTime Gets the last day of a week. Date and Time: 01/01/2009 00:00:00 AM
Result: 01/06/2009 11:59:59 PM
End of Year - DateTime Gets the last day of a year. Date and Time: 01/01/2009 00:00:00 AM
Result: 12/31/2009 11:59:59 PM
End of Year - Integer Gets the last day of a year. Year: 2009
Result: 12/31/2009 11:59:59 PM
Format Date and Time Formats a date and time to a text representation using a specified date and time format. DateTime: 01/01/2009 00:00:00 AM
Format: "dddd, dd MMMM yyyy"
Result: "Thursday, 1 January 2009"
Maximum Gets the maximum date and time from a list of values. Values: {01/01/2009 00:00:00 AM, 01/02/2009 00:00:00 AM }

Result: 01/02/2009 00:00:00 AM
Minimum Gets the minimum date and time from a list of values. Values: {01/01/2009 00:00:00 AM, 01/02/2009 00:00:00 AM }

Result: 01/01/2009 00:00:00 AM
Month Gets the month of a given date as a number. Date: 01/01/2009 00:00:00 AM
Result: 1
Now Gets the current date and time. Result: 05/20/2009 03:34:27 PM
Quarter Gets the quarter number a specified date is in. Date and Time: 01/01/2009 00:00:00 AM
Result: 1
Start of Month - DateTime Gets the first day of a month. Date and Time: 01/01/2009 00:00:00 AM
Result: 01/01/2009 00:00:00 AM
Start of Month - Integer Gets the first day of a month. Year: 2009
Month: 1
Result: 01/01/2009 00:00:00 AM
Start of Quarter - DateTime Gets the first day of a quarter. Date and Time: 01/01/2009 00:00:00 AM
Result: 01/01/2009 00:00:00 AM
Start of Quarter - Integer Gets the first day of a quarter. Year: 2009
Quarter: 1
Result: 01/01/2009 00:00:00 AM
Start of Week - Integer Gets the first day of a week. Year: 2009
Week: 1
Result: 12/28/2008 00:00:00 AM
Start of Week - DateTime Gets the first day of a week. Date and Time: 01/01/2009 00:00:00 AM
Result: 12/28/2008 00:00:00 AM
Start of Year - Integer Gets the first day of a year. Date and Time: 01/01/2009 00:00:00 AM
Result: 01/01/2009 00:00:00 AM
Start of Year - DateTime Gets the first day of a year. Year: 2009
Result: 01/01/2009 00:00:00 AM
Subtract Days Subtracts a specified amount of days from a date. Date and Time: 01/01/2009 00:00:00 AM
Days: 1
Result: 12/31/2008 00:00:00 AM
Subtract Hours Subtracts a specified amount of hours from a date and time. Date and Time: 01/01/2009 00:00:00 AM
Hours: 1
Result: 12/31/2008 00:23:00 AM
Subtract Minutes Subtracts a specified amount of minutes from a date and time. Date and Time: 01/01/2009 00:00:00 AM
Minutes: 1
Result: 12/31/2008 00:59:00 AM
Subtract Seconds Subtracts a specified number of seconds from a date and time. Date and Time: 01/01/2009 00:00:00 AM
Seconds: 1
Result: 12/31/2008 00:00:59 AM
Today Gets the current day. Result: 05/20/2009 00:00:00 AM
Tomorrow Return tomorrow's date. Result: 05/21/2009 00:00:00 AM
Week Number Gets the week number of the year of a specified date. Date: 01/01/2009 00:00:00 AM
Result: 6
Weekday Gets the name of the day of the week from a specified date. Date: 01/01/2009 00:00:00 AM
Result: "Thursday"
Year Gets the year of a date. Date: 01/01/2009 00:00:00 AM
Result: 2009
Yesterday Returns yesterday's date. Result: 05/19/2009 00:00:00 AM

The following table lists the date and time abbreviations recognized by the Format Date and Time function.

Date and Time Abbreviations Example
Year y, yy, yyyy 9, 09, 2009
Month M, MM, MMM, MMMM 2, 02, Feb, February
Day d, ddd, dddd 21, Sat, Saturday
Hour h, hh, H, HH 4, 04, 16, 16
Minute m, mm 1, 01
Second s, ss 1, 01
Millisecond ffff 9999
A.M. or P.M. t, tt P, PM
Timezone z, zz, zzz -6, -06, -06:00

The following table lists the standard date and time specifiers recognized by the Format Date and Time function.

Specifier Pattern value (for en-US culture)
t h:mm tt
d M/d/yyyy
T h:mm:ss tt
D dddd, MMMM dd, yyyy
f dddd, MMMM dd, yyyy h:mm tt
F dddd, MMMM dd, yyyy h:mm:ss tt
g M/d/yyyy h:mm tt
G M/d/yyyy h:mm:ss tt
m, M MMMM dd
y, Y MMMM, yyyy
r, R ddd, dd MMM yyyy HH':'mm':'ss 'GMT' (*)
s yyyy'-'MM'-'dd'T'HH':'mm':'ss (*)
u yyyy'-'MM'-'dd HH':'mm':'ss'Z' (*)
(*) = culture independent

The Function Wizard content varies according to the selected function.

SharePoint 2013 supports integration with the following versions of Microsoft Office:

  • Office 2013
  • Microsoft Office 2010 with Service Pack 2
  • Microsoft Office 2007 with Service Pack 2 and KB 2553248

The following Excel features are available within the Function Browser:

Functions Description Example

Get Cell With Input (location String, inputCell String, inputValue String, outputCell String)

Returns the cell value as a string, after setting the input and performing a recalculation if applicable.

Cell A1 Value : "1"
Input Range: "A2"
Input Value: "20"
Output Cell: "A3"
Calc of Cell A3: "A1 + A2"
Result: "21"

Get Cell (location String, outputCell String)

Returns the cell value from an Excel Workbook as a string. Output Cell Value: "100test"
Result: "100test"
Get Range With Input

Returns the cell or range value as a string, after setting the input and performing a recalculation if applicable. Can be a cell or a range. This function only works with String[] arrays.

If required to set or return a single cell using the GetRange/GetRangeWithInput functions, the single value can be wrapped in a Split function to get it into the String[] array which is required by the function. Additionally, if there is a delimited list of strings to be passed in, the Split function can be used to get the delimited list into an array.

Input Value Parameter - Supports GetList method of a SmartObject or a function that returns a list of strings

Important: the dimensions of the Input Range and Input Value parameters must be the same in order to ensure data integrity. See the section below titled Considerations when working with Excel.

Cell:
Cell A1 Value : "1"
Input Range: "A2"
Input Value: "20"
Output Cell: "A3"
Calc of Cell A3: "A1 + A2"
Result: "21"

Range:
Input Range: "A1:A5"
Input Value: "Split(10;20;30;40;50,;)"
Output Range: "A6"
Cell A1 Value: "1"
Cell A2 Value: "2"
Cell A3 Value: "3"
Cell A4 Value: "4"
Cell A5 Value: "5"
Calc of Cell A6: "Sum of A1 to A5"
Range Result: "150"

Get Range

Returns the cell value or range value from an Excel Workbook as a string. Can be a cell or a range. This function only works with String[] arrays.

If required to set or return a single cell using the GetRange/GetRangeWithInput functions, the single value can be wrapped in a Split function to get it into the String[] array which is required by the function. Additionally, if there is a delimited list of strings to be passed in, the Split function can be used to get the delimited list into an array.

Important: the dimensions of the Input Range and Input Value parameters must be the same in order to ensure data integrity. See the section below titled Considerations when working with Excel.

Cell:
Output Cell Value: "4"
Cell Result: "4"

Range:
Output Range: "A1:A4"
Cell A1 Value: "1"
Cell A2 Value: "2"
Cell A3 Value: "3"
Cell A4 Value: "4"
Range Result: "1234"

Considerations when working with Excel

Raw Data: The default value for Raw Data is 'False'. If false, the formatted value is returned. For example, if using currency with a $symbol and two decimals, a value of '$15.00' is returned. If True, the actual value of the cell will be returned, in this case '15'.

Dimensional Support: To interpret the data which is returned by the Get Cell and Get Range inline functions, it is important to understand what the output range function is capable of. The Excel Inline functions currently support the following:

  • Returns from individual Excel cells.
  • Array returns from one or more Excel columns, as long as the return does not consist of more than one row.

The following returns are not currently supported:

  • Array returns from Excel rows.
  • Two-dimensional array returns, for example ‘blocks’ of Excel data which consist of more than one column.

The following rules apply for both the Get Cell and Get Range inline functions. In the diagrams below, green cells represent output ranges that will be returned for the given request. Red cells represent output ranges that cannot be returned by the inline function.

To specify an output range from an individual cell, the Output Range string in the Configure Function window must be entered in a format of Column x Row:

In the example above, the returned output range is from cell A1 only.

To specify an output range from a column, the Output Range string in the Configure Function window must be entered in a format of [First cell : last cell], separated by a colon, for example, A1:A10:

In this example, the returned output range is A1:A10.

Output ranges from spreadsheet rows cannot be used. For example, if an output range of A1:E1 is requested, only the value for cell A1 will be returned, as seen below:

Two-dimensional output ranges from spreadsheets cannot be used. For example, if an output range of A1:E10 is requested, the Excel Inline function will not return the expected range of columns and rows. Only the relevant values for the first column in the range (i.e. A1:A10) will be returned, as seen below:

 

The Files inline functions allow the retrieval of file information, including content, from various sources.

A function is selected and then added to the canvas or K2 field part by clicking the Add button or by using drag-and-drop. After adding the function, the Wizard for the specific function will open.

Category Functions Description
Files Get File From Content The Get File From Content wizard enables a user to get a file from data fields, expressions, base64-encoded data and other items containing the file’s content, and allows you to specify a filename.
Get File From Location The Get File From Location wizard enables a user to get a file from a file location which must be accessible at runtime, and allows you to specify a filename.
Get File From SharePoint Item Reference The Get File From SharePoint Item Reference wizard enables the user to get a file from a SharePoint Item Reference containing one or more documents.
Get File From SharePoint The Get File From SharePoint wizard enables the user to get a file from a SharePoint document library.
Get File From InfoPath Attachments The Get File From InfoPath Attachments wizard enables the user to get all documents contained in an InfoPath attachment field node.
Get File From Process Attachments The Get File From Process Attachments wizard enables the user to get workflow attachments from the associated Process Instance. These are available from Process Instances of workflows that have Attachments enabled .
The return type for all FILE inline functions is STRING, because of the fact that the functions resolve to an XML structure containing the file name and the file contents.

InfoPath functions will get an InfoPath attachment's content or filename from an array of bytes.

Functions Description Example
Get Attachment Content Gets an attachment's file content from an array of bytes. Attachment: The attachment as Binary
Result: The file content of the attachment as Binary
Get Attachment Name Gets an InfoPath attachment's filename from an array of bytes. Attachment: The attachment as Binary
Result: "c:\document.docx"
Set Attachment Creates an InfoPath attachment and returns it as a base-64 string. Filename: "c:\document.docx"
Content: The file content as Binary.
Result: A base-64 string containing the attachment.

The Function Wizard content varies according to the selected function.

List functions perform calculations on lists based on input values and returns a number.

Functions Description Example
Count

Counts the number of items in a list of values.

Values - Input

Integer - Return type

 Input Values: { 1, 2, 3 }
Result: 3
First Item

Gets the first value in a list.

Values - Input

Expected When Empty - Object type. This is returned when the input value is invalid

Object - Return Value

Values: {1, 2, 3}

Expected When Empty: 0

Result: 1
Index Item

Gets the last value in a list.

Values - Object of array type. e.g. output from a Split() function call can be passed into this parameter. When using an XML node, make sure to use the lowest node in the tree.

Index - Number of long type. This specifies the 1-based index of the item in the array you wish to retrieve.

Expected When Empty - Object type. This is returned when the input value is invalid or when the index specified is out of bounds.

Object - Return value (Object) is the selected object in the array if there are no errors.

Example 1:

Values: { "a", "b", "c" }

Index: 1

Expected When Empty: "empty"

Result: "a"

Example 2:

Values: { "a", "b", "c" }

Index: 4

Expected When Empty: "empty"

Result: "empty"
Last Item

Gets the last value in a list.

Values - Input

Expected When Empty - Object type. This is returned when the input value is invalid

Object - Return Value

Values: {1, 2, 3}

Expected When Empty: 0

Result: 3

The Function Wizard content varies according to the selected function.

Logical functions performs a logical operation or comparison on objects and expressions and returns a Boolean value.

Functions Description Example
And Performs an And operation on two Boolean values, returning true if both values are true, false if any value is false. Input Value: True
Input Value: False
Result: False
False Gets the Boolean value of false. Result: False
If Returns one of two values (Boolean condition, True, False) based on a Boolean condition. Nested expressions are allowed up to 7. Condition: True
True Value: "Test string 1"
False Value: "Test string 2"
Result: "Test string 1"
No Gets the Boolean value of false. Result: False
Not

The Not function changes false to true and true to false. Returns a true value if the condition evaluates to false and a false value if the condition evaluates to true.

 Condition: True
Result: False
Or Performs an Or operation on two Boolean values, returning true if one of the values is true, false if both values are false. Value: True
Value: False
Result: True
True Gets the Boolean value of true. Result: True
Xor Performs an Exclusive Or operation on two Boolean values, returning true if one and only one of the values is true. Value: True
Value: True
Result: False
Yes Gets the Boolean value of true. Result: True

The True value and False value inputs need to return values of the same type. For example, dragging a SmartBox SmartObject Delete method into a True Value will be allowed by the If’s Input wizard, but it will not work at runtime because the Delete method does not return a value.

The Function Wizard content varies according to the selected function.

Mathematical functions perform calculations, usually based on input values and returns a number.

Functions Description Example
Absolute - Decimal Gets the absolute (positive) value of a number. Input Value: -1.1
Result: 1.1
Absolute - Long Gets the absolute value of a number. Input Value: -2
Result: 2
Average - List of Decimal Calculates the average of a collection of values. Input Values: { 1.1, 2.2, 3.3 }
Result: 2.2
Average - List of Long Calculates the average of a collection of values. Input Values: { 1, 2, 3 }
Result: 2
Format Number - Decimal String Formats a number to a text representation using a specified numeric format specified. Number: 0.111
Format: "C"
Result: "$ 0.11"
Maximum - List of Decimal Gets the maximum value of a list of values. Values: { 1.1, 2.2, 3.3 }
Expected When Empty: 0
Result: 3.3
Maximum - List of Long Gets the maximum value of a list of values. Values: { 1, 2, 3 }
Expected When Empty: 0
Result: 3
Minimum - List of Decimal Gets the minimum value of a set of values. Values: { 1.1, 2.2, 3.3 }
Expected When Empty: 0
Result: 1.1
Minimum - List of Long Gets the minimum value of a set of values. Values: { 1, 2, 3 }
Expected When Empty: 0
Result: 1
Power - Decimal Gets one value raised to the power of another. Base: 1.1
Power: 1.1
Result: 1.11053424105458
Power - Long Gets one value raised to the power of another. Base: 2
Power: 2
Result: 4
Random - Decimal Gets a random number less than or equal to a specified maximum value. Maximum: 1.2
Result: 0.5810660167974728
Random - Long Gets a random number less than or equal to a specified maximum value. Maximum: 2
Result: 1
Random Between - Decimal Gets a random number between two specified values. Minimum: 0.0
Maximum: 1.2
Result: 0.5810660167974728
Random Between - Long Gets a random number between two specified values. Minimum: 0
Maximum: 2
Result: 1
Root - Decimal Gets the positive nth root of a positive number. Number: 32.0
Nth Root: 5.0
Result: 2.0
Root - Long Gets the positive nth root of a positive number. Number: 100
Nth Root: 2
Result: 10
Round - Decimal Rounds a number up or down to a value with a specified precision. Value: 1.111
Digits: 1
Result: 1.1
Round Down - Decimal Rounds a value down. Value: 1.15
Digits: 1
Result: 1.1
Round Up - Decimal Rounds a value up. Value: 1.15
Digits: 1
Result: 1.2
Square - Long Gets the square of a number. Number: 2
Result: 4
Square - Decimal Gets the square of a number. Number: 1.1
Result: 1.21
Square Root - Decimal Gets the square root of a number. Number: 1.1
Result: 1.04880884817015
Square Root - Long Gets the square root of a number. Number: 100
Result: 10
Sum - List of Decimal Gets the sum of a set of values. Values: { 1.1, 2.2, 3.3 }
Result: 6.6
Sum - List of Long Gets the sum of a set of values. Values: { 1, 2, 3 }
Result: 6

The Function Wizard content varies according to the selected function.

Regular Expressions provide a powerful, flexible, and efficient method for processing text. A regular expression is a pattern that the regular expression engine attempts to match in input text.

Functions Description Example
Match Multiple

To match multiple values from the input string value using a regular expression pattern. e.g. Finding all claim codes in a text form that has “CLM” in front followed by a fixed 5 digit number.

Input – Input text to search on. This is a String type.

Regex Pattern – Regular Expression pattern to use for the search.

Case Sensitive – Option to indicate whether the search should be case sensitive or not.

Return value (String[]) - is the array of string values that matched the pattern. If there is no match, it returns “No match found”.

Example 1:
Input: "example"
Pattern: "[a-z]*"
Case Sensitive: "true"
Result: { "example" }

Example 2:
Input: "Example"
Pattern: "[a-z]*"
Case Sensitive: "true"
Result: { "xample" }

Example 3:
Input: "example"
Pattern: "[a-z]*"
Case Sensitive: false
Result: { "example" }

Example 4:
Input: "Example"
Pattern: "[a-z]*"
Result: { "Example" }
Match Single

To match a single value string from the input string value using a regular expression pattern. e.g. Finding a user’s name specified in a text form.

Input – Input text to search on. This is a String type.

Regex Pattern – Regular Expression pattern to use for the search.

Case Sensitive – Option to indicate whether the search should be case sensitive or not.

Expected When Empty – String type. This is returned when there is no match found or the matched value is empty.

Return value (String) - is the matched string if there is a match.

Example 1:
Input: "Example"
Pattern: "[a-z]*"
Case Sensitive: true
Expected When Empty: "empty"
Result: "empty"

Example 2:
Input: "An example"
Pattern: "\\b\\w+es\\b"
Case Sensitive: true
Expected When Empty: "empty"
Result: "empty"

Example 3:
Input: "example;"
Pattern: "[a-z]*"
Case Sensitive: true
Expected When Empty: "empty"
Result: "example"

Example 4:
Input: "Example"
Pattern: "[a-z]*"
Case Sensitive: false
Expected When Empty: "empty"
Result:"Example"

Example 5:
Input: "example"
Pattern: "[a-z]*"
Expected When Empty: "empty"
Result: "example"
Match

For doing a regular expression pattern match of a value. e.g. to check if the input value is a valid E-mail address.

Input – Input text to search on. This is a String type.

Regex Pattern – Regular Expression pattern to use for the search.

Case Sensitive – Option to indicate whether the search should be case sensitive or not.

Return value (Boolean) - is true if a match was found, otherwise false.

Example 1:
Input: "Examples"
Pattern: "\\b\\w+es\\b"
Case Sensitive: true
Result: true

Example 2:
Input: "Example"
Pattern: "\\b\\w+es\\b"
Case Sensitive: true
Result: false

Example 3:
Input: ""
Pattern: "[a-z]*"
Case Sensitive: true
Result: true

Note that * will always return a match

Example 4:
Input: ""
Pattern: "[a-z]"
Case Sensitive: true
Result: false

Example 5:
Input: "Examples"
Pattern: "\\b\\w+es\\b"
Case Sensitive: false
Result: true

Matches words ending in 'es'

Example 6:
Input: "Example"
Pattern: "\\b\\w+es\\b"
Case Sensitive: false
Result: false

Matches words ending in 'es'

Gets the connection values for SharePoint Member and User Emails, and SharePoint Groups and Users.

Function Description Example
Get Emails for SharePoint Members in Groups Provides the SiteURL, User Id, and K2 Label connection string for all Members in a SharePoint Group

Input Values:

  • SiteUrl:

    This is the SharePoint site URL where the function is meant to be executed

    Example:

    http://portal.denallix.com

  • Group Ids:

    This value is the IDs of Groups as they are stored in SharePoint.

     

    This value is not readily in SharePoint. To obtain this value., execute a REST query, Https://<sharepointUrl>/ api/web/siteGroups. A XML result will be returned with the Id values.

    Note: Ensure that the Feed reading view is turned off in IE in order to execute the REST query. To disable Feed reading follow this path:

    Internet Options>Content>Feeds and Web Slices settings, Turn off Feed reading view.

  • K2 Label:

    Any value can be added here.

    Example:

    K2
Get Emails for SharePoint Users Provides the SiteURL, User Id, and K2 Label connection string for a SharePoint User

Input values:

  • SiteUrl:

    This is the SharePoint site URL where the function is meant to be executed

    Example:

    http://portal.denallix.com

  • User Ids:

    This value is the IDs of Users as they are stored in SharePoint.

    This value is not readily in SharePoint. To obtain this value., execute a REST query, Https://<sharepointUrl>/ api/web/siteusers. A XML result will be returned with the Id values.

    Note: Ensure that the Feed reading view is turned off in IE in order to execute the REST query. To disable Feed reading follow this path:

    Internet Options>Content>Feeds and Web Slices settings, Turn off Feed reading view.

  • K2 Label:

    Any value can be added here.

    Example:

    K2
Get SharePoint Groups Provides the SiteURL, Group Id, and Host Server Connection String for a SharePoint Group

Input Values:

  • SiteUrl:

    This is the SharePoint site URL where the function is meant to be executed

    Example:

    http://portal.denallix.com

  • Group Ids:

    This value is the IDs of Groups as they are stored in SharePoint.

    This value is not readily in SharePoint. To obtain this value., execute a REST query, Https://<sharepointUrl>/ api/web/siteGroups. A XML result will be returned with the Id values.

    Note: Ensure that the Feed reading view is turned off in IE in order to execute the REST query. To disable Feed reading follow this path:

    Internet Options>Content>Feeds and Web Slices settings, Turn off Feed reading view.

  • Host Server Connection String (Deprecated):

    The Host Server Connection string is auto populated.

  • K2 Label:

    Any value can be added here.

    Example:

    K2
Get SharePoint Users Provides the SiteURL, Group Id, and Host Server Connection String for a SharePoint User

Input Values:

  • SiteUrl:

    This is the SharePoint site URL where the function is meant to be executed

    Example:

    http://portal.denallix.com

  • User Ids:

    This value is the IDs of Users as they are stored in SharePoint.

    This value is not readily in SharePoint. To obtain this value., execute a REST query, Https://<sharepointUrl>/ api/web/siteusers. A XML result will be returned with the Id values.

    Note: Ensure that the Feed reading view is turned off in IE in order to execute the REST query. To disable Feed reading follow this path:

    Internet Options>Content>Feeds and Web Slices settings, Turn off Feed reading view.

  • Host Server Connection String (Deprecated):

    The Host Server Connection string is auto populated.

  • K2 Label:

    Any value can be added here.

    Example:

    K2

Text functions perform operations such as concatenations or insertions on text. Text-based operations are 1-based, meaning that the index of the first character in a string is 1.

Functions Description Example
Contains Returns a true value if a substring is found within another string. Sequence: "12345"
Text: "234"
Result: True
Empty String Returns an empty string. Result: "Blank"
Find Returns the index if the specified string is found within another string. Returns 0 if no match can be found. Substring: "12345"
Text: "234"
Result: 2
Hyperlink Creates a hyperlink with a display name and URL. Display Name: "K2"
URL: "http://www.k2.com"
Result: "<a href= http://www.k2.com > K2</a>"
Insert Inserts a substring into a string at a specified position. Text: "Example"
Substring: "00000"
Position: 2
Result: "E00000xample"
Join Concatenates a list of text values or fields, delimiting each with a separator. Values: { "1", "2", "3" }
Separator: ";"
Result: "1;2;3"
Left Returns a subset of characters from the left side of a string. Text: "Test"
Length: 1
Result: "T"
Length Returns the length of a string. Text: "Test"
Result: 4
Mid Returns a subset of characters from a string, starting at a specified index and continuing to the end of the string. Text: "Example"
Start: 3
Result: "xample"
Mid - Length Returns characters from a string, starting at an index and continuing a specified length. Text: "Example"
Start: 2
Length: 5
Result: "xampl"
Pad Left Pads a string with a padding character on the left side up to a specified length. Source String: "Example"
Pad Character: "#"
Overall Length: 9
Result: "## Example "
Pad Right Pads a string with a padding character on the right side up to a specified length. Source String: "Example"
Pad Character: "#"
Overall Length: 9
Result: " Example #"
Proper Converts a string to proper case. Text: "the quick brown fox jumps over the lazy dog"
Result: "The Quick Brown Fox Jumps Over The Lazy Dog"
Replace Replaces a substring within a string with a new substring. Text: "Ex000le"
Find: "000"
Replace: " amp "
Result: "Example"
Right Returns characters from the right side of a string. Text: "Example"
Length: 3
Result: "ple"
Split Splits text into substrings delimited by a specified separator value. Text: "a;b;c"
Separator: ";"
Result: { "a", "b", "c" }
To Lower Converts a string to lower case. Text: "Example"
Result: " example "
To Upper Converts a string to upper case. Text: "Example"
Result: " EXAMPLE "
Trim Removes leading and trailing spaces and line breaks from a string. Text: " Example "
Result: "Example"
URL Encode Encodes a URL string. URL: "http://local.com/test url.asmx"
Result: "http%3a%2f%2flocal.com%2ftest+url.asmx"
URL Decode Decodes a URL string. URL: "http%3a%2f%2flocal.com%2ftest+url.asmx"
Result: "http://local.com/test url.asmx"

The Function Wizard content varies according to the selected function.

SharePoint 2013 supports integration with the following versions of Microsoft Office:

  • Office 2013
  • Microsoft Office 2010 with Service Pack 2
  • Microsoft Office 2007 with Service Pack 2 and KB 2553248

The Word feature contains an action called Get Word Content which gets the content data of a Content Control in a Word document residing anywhere on a network or in a SharePoint location.

Content Controls are individual controls that you can add and customize for use in templates, forms, and documents. For example, many online forms are designed with a drop-down list control that provides a restricted set of choices for the user of the form. Content Controls can provide instructional text for users, and you can set controls to disappear when users type in their own text. You can reuse and distribute your customized Content Controls, as well as create your own building blocks to include in a Content Control.

Prerequisite

The following is a prerequisite in order to use the Word Inline Function:

View the Content Controls in a document

You can find the Content Controls for your document on the Developer tab.

Click the Microsoft Office Button and then click Word Options.

Click Popular. Check the Show Developer tab in the Ribbon check box, and then click OK.

If Content Controls are not available, you may have opened a document created in an earlier version of Microsoft Office Word. To use Content Controls, you must convert the document to the Word 2007 file format by clicking the Microsoft Office Button , clicking Convert, and then clicking OK. Content Controls require Microsoft Office Word 2007 or a later version

These are the Content Controls available in Microsoft Office Word.

  • Rich Text
  • Text
  • Combo
  • Drop-Down list
  • Date Picker
  • Building Block Gallery

Alternatively use the Quick Parts link to add Content Controls. Quick Parts can be found under the Insert tab in Word, see below.

Providing the Content Control tag with a name

In order for the K2 Get Word Content action to function properly, the tag of the Content Control need to be unique. If more than one tag is used with the same name, only the content of the first tag will be returned. Ensure that each Content Control tag is unique.

To provide the Content Control tag with a name, select the control in Design Mode, and click on Properties. Specify the tag name and click OK.

Using the Get Word Content Control Inline Function

It is important to note that the K2 Service Account requires Farm Administration rights and Word Services rights. If Run As is utilized instead of the K2 Service Account, then the specified Run As user will require these rights.

The Get Word Content Control can be found by expanding the Word node in the Function Browser of the process designer.

The parameter for Content Control Name should be the tag set in the Word document. Only one Content Control name can be set at a time, as the parameter does not allow for multiple items to be retrieved at once.

Feature Description How to use it
Location The network or SharePoint location where the Word document resides. Use a Data/XML field to populate the field or alternatively type in the location in the box provided.
Content Control Name Name of the Content Control tag in the Word document. Use a Data/XML field to populate the field or alternatively type in the Content Control tag name.