Videos

Using allow_partial and required_parameter flags

 

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: Add, Set, and 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 allow_partial and required_parameter flags in these messages.

The elements of Add, Set, and 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.

Required parameters

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?

The 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 Add, Set, or Delete message.

If 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 allow_partial, 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
True/False  No No  Response  oper_success No
True/False  No Yes Response  oper_success  Yes
True/False  Yes No No Response  oper_success No
True/False  Yes No Yes Response  oper_success Yes
True  Yes Yes  Response  oper-failure  Yes
False  Yes  Yes  - Error  N/A  Yes