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.
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.
Unlike the Set Value function, the Set Field Values function is only available within field pipelines.
What Are Multi-Value Fields?
First, let's cover what multi-value fields are and why you may need to use them.
Multi-value fields contain multiple instances of an object type. In programming terms, multi-value fields can be best represented as an array in JavaScript or a list in Python - although it should be noted that Syncari multi-value fields are their own distinct data structure.
You can identify multi-value fields by navigating to Schema Studio and selecting the entity of your choice. Clicking on each field will reveal its datatype and whether or not it is a multi-value field.
In this example above, the 'Invoice Order Line Items' field is a multi-value field containing a series of child objects.
Child is a unique datatype inherited from NetSuite that is often used in invoicing pipelines, as line items are child objects of the invoice, itself. In practice, you may also see the datatype as object or string, indicating this field contains multiple objects or multiple strings, respectively.
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}
]