Changing and Deleting Objects Through the MCP¶
The MCP changes an object the same way the console does: the model reads the whole object, changes it, and sends it back whole with the revision token it read. This page covers saving, overwriting and deleting.
Saving an object¶
save_object saves one whole object: a zone, a channel, a published mapping or function, a DICOM, web service or database connection, a system variable, an HTML form, a certificate or a private key. Users and roles have their own tools, and packages and System Configuration cannot be changed through the MCP.
To change an object, the model reads it with get_object, changes the JSON, and sends back the type, the object and the revision token it read as revision. To create one, it leaves out the object's id and names the zone in zoneId. Only an administrator creates a zone, a channel is created with create_channel, and a certificate or private key is created by importing it with import_certificates.
QIE then:
- Checks the user may change it: edit rights in the object's zone, or an administrator for a zone. An object in a zone the user cannot view is answered as if it did not exist.
- Checks the token, as a delete does: a stale token is refused naming who changed the object and when, and a token QIE did not issue is refused, recorded and alerted.
- Applies what was sent onto the stored object, described below.
- For a channel or HTML form in a locked package that lets some of its fields change, refuses a change to any other part, naming each one, because the console's save would keep those parts as stored and still report success. An HTML form in such a package can change only whether it is enabled. Message content and the fields QIE manages are not compared, and a password reads only as set or not set, so replacing a password is not caught here.
- Checks every object the save now points to, such as a channel's database connection: it must be one the user can see, in the same zone or in Global Settings.
- Checks the type's rules on the object as it was sent, so a value the console would rewrite is refused rather than changed.
- For a channel, copies the source and format settings through the same views the channel editor saves from, which clears settings the chosen source kind does not use, and does the same for each destination the save changed. QIE then numbers the nodes by the editor's rule and runs the channel editor's checks.
- Checks the values that must match stored objects, as the console's pickers allow only those: a private key that has a key, a Table variable for a data map, a system variable or channel cache named in a web service row, a Queue ID a channel queue source uses, a published function's parameters, and a table column that a zone the user cannot view still uses. Only a value the save sets is checked; one the object already held is left as it is.
- Refuses the save with every rule steps 6 to 8 found broken, each named by its rule id.
describe_typelists all of these rules. - Saves through the console's own save, taking the same steps it takes on every save. An object in a locked package that lets none of its fields change is refused with the console's message.
The result carries the new revision token. A channel that is running an older version reports restartRequired with a note: it keeps running the old version until restart_channel. Saving a published function or published mapping returns usedBy, the channels that use it as find_usages lists them, and restartRequired with a note naming the running ones, which keep the version they loaded until they are restarted. The model tells the person and restarts them only when asked. A mapping node names its published mapping by id, and a channel save never changes the published mapping: sending isModified true, the console's Edit published mapping, is refused, so a published mapping changes only through its own save. The audit record of a save holds the object's name, the revision token sent and the revision number of the saved configuration.
How what is sent is applied¶
| Sent | Result |
|---|---|
| A field left out | Keeps its stored value |
| A list | Replaces the stored list. An element carrying the id of a stored element keeps the fields it leaves out; an element without an id is added |
A secret sent back as {"$secret": "set"} or {"$secret": "unset"} |
Keeps the stored value; text sets a new value and null clears it. The bare text $secret is refused, so it cannot become the password by mistake |
A connection URL or custom parameters still reading $secret |
The stored credential is put back in its place |
| A channel script sent back as its placeholder | Keeps the stored script; text replaces it |
A reference sent as {"id": ...} |
Points at that object; its name is ignored |
| A new mapping function or condition | Its $kind says which kind it is |
Some fields can only be sent back as they were read. A save that changes one is refused, naming the field and the tool that changes it:
| Field | Changed with |
|---|---|
Fields describe_type marks serverManaged |
QIE sets them |
| The zone an object is in | The console |
| A zone's user and role permissions | set_user_zone_permissions and save_role |
| A channel's samples | push_sample and delete_sample |
| A channel's nodes, their links and which nodes take the source's message | add_node, remove_node, link_nodes and unlink_nodes |
| Channel cache values, sample bodies and script variable values | The content tools |
| A stored private key's password, unless the user is an administrator | The console, which asks for the current password |
Node numbers sent are ignored, because QIE numbers the nodes itself.
Overwriting a newer version¶
When someone changes an object after the model read it, save_object refuses the model's save as stale, so neither change is lost without anyone deciding. When the person wants the model's version to win, the model can send the same object with overwrite_object.
overwrite_object takes the same arguments as save_object and needs the revision token the model read, which may be stale. A token QIE did not issue for the object is refused, recorded and alerted. QIE applies what was sent onto the object as it is stored now, so a field the model left out keeps the newer version's value, and makes every check a save makes. It then asks the person to confirm, as described in MCP Tool Results and Errors, naming the object as it is stored now. If the object changes again before the person answers, nothing is saved. An overwrite cannot create an object.
Checking without saving¶
validate_object takes the same arguments and makes the same checks without saving. It checks the revision token only when one is sent. It returns valid and a list of violations, each with the rule, where it applies (a field, a node number or the channel) and the message. A field that cannot be changed, or an unknown field, is refused as save_object refuses it.
Deleting an object¶
delete_object deletes one object: a zone, a channel, a published mapping or function, a DICOM, web service or database connection, a system variable, an HTML form, a certificate or a private key. Users and roles have their own tools, and packages cannot be deleted through the MCP.
The model sends the object's type and id and the revision token get_object returned. QIE then:
- Checks the user may delete it: edit rights in the object's zone, or an administrator for a zone, because deleting a zone deletes its connections, variables, forms and other shared objects. An object in a zone the user cannot view is answered as if it did not exist. A zone that still holds channels or packages is refused, as the console refuses it, and so is the Global zone; QIE checks this again after the person confirms.
- Checks the token. An object changed since the model read it is refused as stale, naming who changed it and when; a token QIE did not issue for the object is refused, recorded and alerted.
- Asks the person to confirm, as described in MCP Tool Results and Errors.
- Deletes it through the console's own delete.
An object that other objects still use, such as a database connection a channel uses, is refused with QIE's list of what uses it, as the console warns. Sending deleteEvenIfInUse true deletes it anyway, after a new confirmation.
Sending the same delete again within 10 minutes returns the first result instead of asking again.