Matrix sublists respect the replaceAll attribute for updates, as other Keyed Sublists do, but in some cases, updates to matrix sublists require additional handling.
Matrix sublists require additional handling for replaceAll because body-level fields populate values into them. For example, setting the pricing schedule for an item dictates values in the pricing matrix. In the UI, when a pricing schedule is selected, the pricing schedule logic is run first, and values specified in the pricing matrix sublist are taken into account to arrive at what the update should do. However, the UI does not have the notion of replaceAll because the user interacting with the form can delete values they do not want to keep in individual fields.
SOAP web services requests cannot delete individual field values in a sublist. The only way to get rid of old values is to set replaceAll to TRUE and send all values in the update request. Some body fields can override values in a matrix sublist, but a SOAP web services request can then change some or all of these sublist values, depending on the replaceAll setting.
Review the following cases to get an understanding of how the slaving of values from body fields into a matrix sublist interacts with the replaceAll setting on updates:
- No sublist values from body fields and replaceAll=TRUE
- The SOAP web services request does not include any body field values that drive values in the sublist, so the update is handled like those in other keyed sublists where replaceAll is set to TRUE.
- The existing sublist is replaced with the sublist submitted in the SOAP web services request. The newly submitted sublist should include all values.
- No sublist values from body fields and replaceAll = FALSE
- The SOAP web services request does not include any body field values that drive values in the sublist, so the update is handled like those in other keyed sublists where replaceAll is set to FALSE.
- Lines in the existing sublist are selectively updated with lines in the sublist submitted in the SOAP web services request. The newly submitted sublist need only include values to be added and updated.
- Sublist values from body fields and replaceAll=TRUE
- The SOAP web services request sets body field value(s) that drive values in the sublist, so specialized handling is required.
- First, all sublist values are removed. Next, sublist values driven by body field values are set. Then, the sublist is updated with all lines specified in the newly submitted sublist. The newly submitted sublist lines thus override the values driven by body fields.
Important When sublist values from a SOAP web services request override values driven by body fields, errors may occur. If you do not want these overrides, you must set replaceAll to FALSE. For example, if you are setting a quantity pricing schedule, you should set ReplaceAll to FALSE.
- Sublist values from bodyfields and replaceAll=FALSE
- The SOAP web services request sets body field value(s) that drive values in the sublist, so specialized handling is required.
- First, sublist values driven by body field values are set. Then, the sublist is updated with any updated or added lines from the newly submitted sublist.