IRPCObjectOperations.AddObjectWithFiles

View as Markdown

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

Creates a new object, optionally with its files, and optionally checks it in.

Remarks

This is the general way to create an object. One call creates the object checked out, attaches the files, runs the creation event handlers and, if check_in is true, checks the object in. All of it happens in one transaction: if any step fails, no object is created (the object ID that was reserved for it is not reused).

Required properties. Send at least:

A missing required property fails with "The mandatory property value "<name>" is missing." Get the class and its required properties with GetObjectClassesAndGroups. The server fills the automatic properties (Created, Created by, Last modified, ...) itself.

Set acl. The server stores the ACL you send as the object's permissions. If acl is unset, the object gets an empty ACL: after check-in only users with a vault-level right to see all objects can see it, and not even its creator. To give the object ordinary permissions, send the acl_for_objects of a named ACL from GetNamedACLs (call it with include_builtin: true), for example ID -1, "Full control for all internal users". For a named ACL that does not depend on the current user, a link alone is enough: acl { custom_component { has_named_acl: true named_acl_id: -1 } }. A link alone to the built-in "Only for me" (-20) leaves the object without permissions; send its full acl_for_objects, which names the user.

Single-file documents. With Single file (22) true, the object must end up with exactly one file: true without a file source fails with "Cannot set document to single-file mode." At check-in, the file of a single-file document takes the object's title as its file title; the title given in the file source is not kept.

File sources (files.type and the matching files.data member):

• OBJ_FILE_SOURCE_TYPE_FILE_CONTENT with file_content: the file bytes inline in the request. The simplest way to create a document with one file. Only for a single-file document of object type 0 (Document); otherwise the call fails with invalid argument. At most 10 MiB; title is required.
• OBJ_FILE_SOURCE_TYPE_UPLOADED_FILE with uploaded_file, or OBJ_FILE_SOURCE_TYPE_UPLOADED_FILES with uploaded_files: content uploaded first. Give either upload_id (from UploadTempFile followed by UploadTempFileCommit) or file_ref (from FileUploadWhole or FileUploadEnd, on servers that report ServerVaultCapabilities.file_upload_stateless_supported; stateless uploads are switched off by default in M-Files Server 26.11). An upload session that was not committed fails ("The process cannot access the file because it is being used by another process."), and an upload is consumed by the object it is attached to: a second object cannot use the same upload_id.
• OBJ_FILE_SOURCE_TYPE_BLANK_TEMPLATE (blank_template.name) or OBJ_FILE_SOURCE_TYPE_USER_DEFINED_TEMPLATE (user_defined_template.obj_id, a template object, see GetTemplates): the file is copied from a template.
• OBJ_FILE_SOURCE_TYPE_EMPTY_FILES with empty_files: files with a title and extension but no content yet. Only together with draft: true.
• files unset or OBJ_FILE_SOURCE_TYPE_UNDEFINED: no files. Set Single file (22) to false.

The response. is_visible_to_user tells whether the creator could see the new object before it was checked in. When the checked-in object is not visible to the caller (for example because acl was unset), created_object carries only the object ID and version number, with no properties, files or title. Read the object again with GetObjectInfoAndProperties when you need its full state.

Workflow. The class's default workflow is not applied by the server when the class does not force a workflow: send Workflow (38) and Workflow State (39) yourself. A state of another workflow wins: the server sets Workflow (38) to the state's workflow. Sending only a state also sets the workflow; sending only a workflow leaves the state empty.

Permissions. The user needs the vault-level right to create objects and a license that allows modifications.

Request: AddObjectWithFilesRequest

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: AddObjectWithFilesResponse

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.

Related methods

• IRPCPropertyDefs.GetObjectClassesAndGroups -- Gets all classes and class groups that the user is allowed to see.
• IRPCNamedACLs.GetNamedACLs -- Gets the named ACLs of the given types that the calling user is allowed to see.
• UploadTempFile -- Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
• UploadTempFileCommit -- Completes an upload made with UploadTempFile.
• IRPCFileTransferStreaming.FileUploadWhole -- Uploads a whole file by streaming its content.
• IRPCFileTransfer.FileUploadEnd -- Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or AddObjectWithFiles for that.
• GetTemplates -- Gets the templates of an object type, optionally only those of one class or matching keywords.
• GetObjectInfoAndProperties -- Gets the version information and the property values of one object, either its latest version or a specific version.
• AddObject -- Creates a new object without files.
• AddObjectWithFilesWithPropertyMetadata -- Creates a new object with files, storing metadata about each property value (who or what set it, why, and with what confidence).