IRPCObjectOperations.SetProperties

View as Markdown

Vault API / core write session or assertion returns metadata structure version

Adds, replaces or removes property values of an object.

Remarks

Checked-in objects. With allow_modifying_checked_in_object: true, the server checks the object out, applies the change and checks it in, creating exactly one new version. Without it, a checked-in object fails with "The object is not checked out." Every such call creates a new version, even when the values do not change.

Checked-out objects. If the caller has the object checked out, obj_ver must name the checked-out version; the change goes to that version and no new version is created. Naming the checked-in version of an object checked out to the caller fails ("... not the current checked-out version."), and an object checked out to someone else fails with "The object is checked out to another user."

Targeting a version. obj_ver must name a version by number: the OBJ_VER_VERSION_TYPE_LATEST marker fails with "The parameter is incorrect." For a checked-in object, the server always changes the latest version, whatever number you send (even a number that does not exist yet), unless fail_if_newer_version_exists is true: then a number other than the latest checked-in version fails with "There is a newer version of this object on the server." Use it for optimistic concurrency: read the version, then write with fail_if_newer_version_exists.

Adding, replacing and removing.

• Values in properties are added or replace the existing value of the same property definition. All other properties stay as they are.
• To empty a property, send it with is_null_value: true (and its type).
• remove removes property values from the object. Properties that the object's class lists cannot be removed, not even optional ones: the call fails with "The property "<name>" cannot be removed from the object." Set them empty instead.
• remove_unspecified_properties: true makes properties the full set: every property not in it and not listed by the class is removed. Class-listed properties stay (with their values or empty), as do the properties the server maintains. The full set must still include the Class (100) property, otherwise the call fails with "Class was not specified."; an empty full set fails with invalid argument. Rarely what you want.

Single-file documents. Changing the title of a single-file document with allow_modifying_checked_in_object also renames its file.

Workflow. Change the workflow state by setting Workflow State (39), a lookup into value list 8, or by setting State transition (99), a lookup into value list 17 with a transition ID from GetWorkflowStatesAndTransitions. A state change that the workflow does not allow fails with "Access denied. The state transition "<from> -> <to>" is not allowed." If you change Workflow (38), set the state as well: the server does not clear or replace a state of the previous workflow. A transition that requires an electronic signature needs signature: the session ID of a second LogIn of the same user, made less than 15 seconds earlier; the server logs that session out. See GetStateTransitionSignatureSettings.

Permissions. The caller needs edit access to the object; the server makes an exception that lets an assignee mark an assignment complete. allow_missing_required_properties requires the vault-level right to change the metadata structure and takes effect only if the vault allows objects with empty required fields.

Use SetPropertiesMultiple to change several objects in one transaction.

Request: SetPropertiesRequest

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

Response: SetPropertiesResponse

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

Related methods

• GetWorkflowStatesAndTransitions -- Gets the states and transitions of the given workflow.
• IRPCLogin.LogIn -- Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
• GetStateTransitionSignatureSettings -- Gets the signature settings for a state transition.
• SetPropertiesMultiple -- If the object is currently checked in, a new checked-in version is created. If the object is currently checked out, the changes are applied to the checked-out version.
• SetPropertiesWithMetadata -- Adds, replaces or removes property values of an object, also storing metadata about each value.
• SetPropertiesWithMetadataAttributedTo -- Sets property values with metadata and records the change as made by a built-in agent user.