insert() Function


insert( array, value, index )

Inserts a value into the given array and returns the resulting array.


Keyword Type Description


Any Type Array

The array to modify.


Any Type or Any Type Array

The value or values to insert.


Integer or Integer Array

The index or array of indices at which the value should be inserted.


Any Type Array

Usage considerations

Index values

When the index value is greater than the array length or is less than 1, the value is appended to the right side of the array.

Data types of array items

The array to be modified can contain items of one or more types. When all array items are of a single type, the value must be the same type as the current items. The updated array will be a list of that type. For example, insert({10, 20}, 30, 2) returns 10, 30, 20, a List of Number (Integer).

Any values that are not the same type will not be added. For example, insert({10, 20, 30, 40}, "fifty", 2) returns 10, null, 20, 30, 40 because the text value ("fifty") cannot be added to an array of numbers.

An array with values of more than one type returns a List of Variant. For example, insert({10, "twenty"}, 30, 3) returns 10, "twenty", 30, , a List of Variant with a Number (Integer), Text, and Number (Integer).

You can append values of any type to these mixed-type arrays. For example, insert({10, "twenty"}, 30.15, 3) returns 10, "twenty", 30.15, a List of Variant with a Number (Integer), Text, and Number (Decimal).

Match the length of the value and index parameters

When using a list as the index parameter, the value must be a scalar value or a list of matching length.

If the index list is longer, a null is inserted at each index where there is not a corresponding value element.

For example, insert({10,20,30}, {100,2}, {1,2,3,4}) returns {100, 10, 2, 20, null, 30, null} because the value list has a length of 2. Once the values from the list are inserted, nulls are inserted at any remaining indexes.


Insert a value as the first array item

insert({10, 20, 30, 40}, 100, 1)

Returns {100, 10, 20, 30, 40}.

Insert a value as the last array item

insert({10, 20, 30, 40}, 100, 5)

Returns {10, 20, 30, 40, 100} because the index is greater than the length of the array.

Insert multiple values at the start of the array

insert({10, 20, 30, 40}, {100, 200}, 1)

Returns {100, 200, 10, 20, 30, 40}.

Insert a value at multiple array indexes

insert({10, 20, 30, 40}, 100, {1, 2})

Returns {100, 10, 100, 20, 30, 40}.

Insert a value from a list at a specific index

When using a list for the index parameter, Appian uses the existing index positions of the array to insert new values.

insert({10, 20, 30, 40}, {100, 200}, {1, 2})

Returns {100, 10, 200, 20, 30, 40}. The first change inserts 100 at index 1 and 200 at index 2 (after 10).

Feature compatibility

The table below lists this function's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile Compatible
Sync-Time Custom Record Fields Compatible

Can be used to create a custom record field that only evaluates at sync time.

Real-Time Custom Record Fields Incompatible

Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.

Process Reports Compatible
Process Events Compatible
Open in Github Built: Fri, May 26, 2023 (08:44:55 PM)

On This Page