Flexible create, update, and delete with allow_partial
There are three USP messages that are used to change the state of an Agent’s service elements:
Delete. Since these messages can be used for a number of different use cases, they contain mechanisms to ensure that the Controller is able to configure service elements through the Agent in a way that guarantees the state it is trying to achieve. These mechanisms include the
required_parameter flags in these messages.
The elements of
Delete messages operate directly on an Object or Object Instance Path. This sets the scope of each part of the message in a context that proceeds from specific to general. As the processing of the message succeeds or fails in each context, the success or failure is passed up through processing to determine whether an update to a particular object fails, or if the message itself fails and throws an error.
Whether or not a given object succeeds in being created or updated is partly determined by the
required_parameter flag. This flag is set on parameters that the Controller wants updated or configured upon the object’s creation. If a required parameter fails to be configured for any reason, the operation on that particular object will also fail.
Error, or Response?
allow_partial flag determines whether or not a message should fail if any of the individual objects that were requested to be created, updated, or deleted fail to do so. If set to false, the Controller wishes the Agent to apply no changes if any of the changes it requested fail. In these cases, the Agent returns an error in response to the
allow_partial flag is set to true, the Controller wishes the Agent to make any changes it can, even if some of them fail. This rarely results in an Error response from the Agent, favoring instead a Response message that contains detailed information about which operations succeeded or failed.
The behavior of
allow_partial and required parameters is outlined in detail in the messages section of the USP spec, with a helpful table that explains the different permutations of
required_parameters, and the response behavior of the Agent:
|allow_partial||Required Parameters||Required Parameter Failed||Other Parameter Failed||Response/Error||Oper_status of Object||Contains param_error|