The Set Field Values function is similar to its sibling, the Set Value function, but differs in one key way: while Set Value is used to overwrite a single-value field, Set Field Values allows you to edit multi-value fields.
Unlike the Set Value function, the Set Field Values function is only available within field pipelines.
NOTE
We recommend you read through our doc on the Set Value function before reading through this article. This way you can get a better understanding of temporary variables and overwriting field values before moving onto more advanced concepts.
What Are Multi-Value Attributes?
First, let's cover what multi-value attributes are and why you may need to use them.
Multi-value attributes contain multiple instances of an object type. In programming terms, multi-value attributes can be best represented as an array in JavaScript or a list in Python - although it should be noted that Syncari multi-value attributes are their own distinct data structure.
You can identify multi-value attributes by navigating to Schema Studio and selecting the entity of your choice. Click an attribute to open its configuration, if Allow Multiple Values is enabled, the attribute is a multi-value field.
Multi-value fields are iterable, meaning that if you add a multi-value field as a source for a function, then the function will automatically iterate through and be invoked on each item in the multi-value field. For example, if a multi-value field of integers is a source for an Increment function that increments by 2, then each integer in the multi-value field will be incremented by 2.
In the next section we'll take a look at an example of how you can use the Set Field Values function to add multiple items to a multi-value field at once.
The Set Field Values Function in Practice
Multi-value fields are useful in any situation where a field needs to contain a list of values. One of the more common examples of this is when including line items in a quote-to-cash or invoicing pipeline.
In the above screenshot, we are editing the contents of the Invoice Order Line Items field - a multi-value field - using a single invocation of the Set Field Values function.
For this specific field, we need to add 4 objects, an amount, item (item ID), location, and department.
each of these key-value pairs will be stored as objects within this multi-value field. Again, you can think of this as a list of objects - although the multi-value field is a unique Syncari datatype - expressed below:
[
{'Amount': 35},
{'item': 154799},
{'location': 26},
{'department': 25}
]