FunctionCopy link to clipboard
a!update( data, index, value )
Inserts new values or replaces existing values at the specified index or field name and returns the resulting updated data.
See also:
- insert(): Use this function if you want to insert new values into a list without replacing existing values.
- append(): Use this function if you want to append values to the end of a list.
- Inserting a Value into an Index of an Array: If you plan to use this function on a node output and simply want to insert one or more values into an array, check out the Is Stored at Index operator discussed in this help topic which provides this specific functionality.
ParametersCopy link to clipboard
| Keyword | Type | Description |
|---|---|---|
|
|
Any Type |
A list, map, dictionary, CDT, or record containing data to be updated. |
|
|
Any Type |
|
|
|
Any Type |
The new value to add or replace an existing value. |
ReturnsCopy link to clipboard
Any Type
Usage considerationsCopy link to clipboard
Using the data parameterCopy link to clipboard
-
The data parameter must be a collection such as a list, map, dictionary, CDT, or record. Scalars like text, integers, and dates cannot be updated.
-
If the data parameter is passed a typed list, such as List of Text or List of Integer, the value parameter must be of the same type. Otherwise,
a!update()will attempt to cast the value parameter to the appropriate type for the list. If the cast is not possible, an error will occur. For example, when updating a List of Text with an Integer, the Integer will be cast to Text in the updated list.
Limitations and alternativesCopy link to clipboard
- Do not use maps, dictionaries, CDTs, or records which contain fields that differ only in casing.
ExamplesCopy link to clipboard
ListsCopy link to clipboard
Updating a list at an indexCopy link to clipboard
1
2
3
4
5
a!update(
data: { 1, 2, 3 },
index: 1,
value: 5
)
Copy
Returns { 5, 2, 3 }.
Updating a list at an index with a different typeCopy link to clipboard
1
2
3
4
5
a!update(
data: { "ab", "cd" },
index: 2,
value: 3
)
Copy
Returns { "ab", "3" }. The Integer 3 was cast to a Text "3" since the data parameter was a List of Text.
Updating at a null indexCopy link to clipboard
1
2
3
4
5
a!update(
data: { "ab", "cd" },
index: null,
value: "ef"
)
Copy
Returns { "ab", "cd" }. A null index will result in no update to the data.
Appending an item to a listCopy link to clipboard
1
2
3
4
5
a!update(
data: { 1, 2, 3 },
index: 4,
value: 4
)
Copy
Returns { 1, 2, 3, 4 }.
Appending an item to a list at an index larger than the length of the listCopy link to clipboard
1
2
3
4
5
a!update(
data: { 1, 2, 3} ,
index: 6,
value: 11
)
Copy
Returns { 1, 2, 3, null, null, 11 }. If the index is greater than the length of the list, null values are added in between the end of the original list and the new value.
Updating and appending multiple items at the same time in a listCopy link to clipboard
1
2
3
4
5
a!update(
data: { 1, 2, 3 },
index: { 1, 4 },
value: { 11, 14 }
)
Copy
Returns { 11, 2, 3, 14 }.
Updating and appending multiple items with the same value in a listCopy link to clipboard
1
2
3
4
5
a!update(
data: { 1, 2, 3 },
index: { 1, 4 },
value: 11
)
Copy
Returns { 11, 2, 3, 11 }.
Updating and appending multiple items at the same time to an empty listCopy link to clipboard
1
2
3
4
5
a!update(
data: {},
index: { 2, 4 },
value: {11, 13}
)
Copy
Returns { null, 11, null, 13 }. Since the data parameter was an empty list, updating non-consecutive indices results in null values being added in the remaining indices.
MapsCopy link to clipboard
Updating a map with a field nameCopy link to clipboard
1
2
3
4
5
a!update(
data: a!map(a: 1, b: 2),
index: "a",
value: 5
)
Copy
Returns a!map(a: 5, b: 2).
Updating multiple values across a list of mapsCopy link to clipboard
1
2
3
4
5
a!update(
data: { a!map(x: 10, y: 20), a!map(x: 1, y: 2) },
index: "x",
value: { -10, -1 }
)
Copy
Returns { a!map(x: -10, y: 20), a!map(x: -1, y:2) }.
Updating multiple values in a single mapCopy link to clipboard
1
2
3
4
5
a!update(
data: a!map(a: 1, b: 2),
index: {"a", "b"},
value: { 5, 6 }
)
Copy
Returns a!map(a: 5, b: 6).
Updating the same value multiple times in a single mapCopy link to clipboard
1
2
3
4
5
a!update(
data: a!map(a: 1, b: 2),
index: {"a", "a"},
value: { 5, 6 }
)
Copy
Returns a!map(a: 6, b: 2).
Inserting a key into a mapCopy link to clipboard
1
2
3
4
5
a!update(
data: a!map(a: 1, b: 2),
index: "c",
value: 3
)
Copy
Returns a!map(a: 1, b: 2, c: 3).
Inserting a key into an empty mapCopy link to clipboard
1
2
3
4
5
a!update(
data: a!map(),
index: "a",
value: 1
)
Copy
Returns a!map(a: 1).
Inserting multiple keys into an empty mapCopy link to clipboard
1
2
3
4
5
a!update(
data: a!map(),
index: {"a", "b"},
value: { 5, 6 }
)
Copy
Returns a!map(a: 5, b: 6). Since the data parameter was an empty map, the specified fields will be added to the map.
DictionariesCopy link to clipboard
In general, the same rules that apply to maps will apply to dictionaries.
Updating a dictionary with a field nameCopy link to clipboard
1
2
3
4
5
a!update(
data: { a: 1, b: 2 },
index: "a",
value: 5
)
Copy
Returns { a: 5, b: 2 }.
RecordsCopy link to clipboard
In order to test record examples, you will need to create a record type with the same field names. Use record field references instead of strings shown in the examples below.
Updating a record with a field nameCopy link to clipboard
In this example, there is a record type called "Customer" with 3 fields on it: id, name, and age.
1
2
3
4
5
a!update(
data: recordType!Customer(id: 4, name: "Jane", age: 42),
index: recordType!Customer.fields.age,
value: 43
)
Copy
Returns recordType!Customer(id: 4, name: "Jane", age: 43).
Updating multiple values across a list of recordsCopy link to clipboard
In this example, there is a record type called "Customer" with 3 fields on it: id, name, and age.
1
2
3
4
5
a!update(
data: { recordType!Customer(id: 4, name: "Jane", age: 42), recordType!Customer(id: 7, name: "John", age: 35)},
index: recordType!Customer.fields.age,
value: {43, 36}
)
Copy
Returns { recordType!Customer(id: 4, name: "Jane", age: 43), recordType!Customer(id: 7, name: "John", age: 36)}.
Updating multiple values in a single recordCopy link to clipboard
In this example, there is a record type called "Customer" with 3 fields on it: id, name, and age.
1
2
3
4
5
a!update(
data: recordType!Customer(id: 4, name: "Jane", age: 42),
index: {recordType!Customer.fields.name, recordType!Customer.fields.age},
value: {"Jane Doe", 43}
)
Copy
Returns recordType!Customer(id: 4, name: "Jane Doe", age: 43).
Updating a related record with a field nameCopy link to clipboard
In this example, the record type "Customer" has a 1:1 relationship with the record type "Address".
1
2
3
4
5
6
7
a!update(
data: recordType!Customer(
Address: recordType!Address(zip: 12345)
),
index: recordType!Customer.relationships.Address.fields.zip,
value: 23456
)
Copy
Returns recordType!Customer(Address: recordType!Address(zip: 23456)).
Updating a null related record with a field nameCopy link to clipboard
In this example, the record type "Customer" has a 1:1 relationship with the record type "Address".
1
2
3
4
5
a!update(
data: recordType!Customer(Address: null),
index: recordType!Customer.relationships.Address,
value: recordType!Address(zip: 12345)
)
Copy
Returns recordType!Customer(Address: recordType!Address(zip: 12345)).
CDTsCopy link to clipboard
In order to test the CDT examples, you will need to create a CDT with the same field names.
Updating a CDT with a field nameCopy link to clipboard
In this example, there is a CDT called "Customer" with 3 fields on it: id, name, and age.
1
2
3
4
5
a!update(
data: type!Customer(id: 3, name: "John", age: 30),
index: "age",
value: 31
)
Copy
Returns type!Customer(id: 3, name: "John", age: 31).
Updating a nested CDT with a field nameCopy link to clipboard
In this example, the top level CDT called "mainCDT" has a nested CDT inside of it called "nestedCDT" which has one field called "field1".
1
2
3
4
5
6
7
8
9
10
11
a!update(
data: type!mainCDT(
nestedCDT: type!nestedCDT(field1: "abc")
),
index: "nestedCDT",
value: a!update(
data: type!nestedCDT(field1: "abc"),
index: "field1",
value: "New Value"
)
)
Copy
Returns type!CDT(nestedCDT: type!nestedCDT(field1: "New Value")). Multiple, nested a!update functions are required to update this value since the field to be updated cannot be referenced in the top level index parameter.
Feature compatibilityCopy link to clipboard
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 | Incompatible | Cannot be used to configure a process report. |
| Process Events | Incompatible | Cannot be used to configure a process event node, such as a start event or timer event. |
| Process Autoscaling | Compatible |