What is the correct way to set metadata types for a document with respect to the metadata type relations of a document type using the REST API?

[ads.dms]

Consider the following example using the REST API (the Mayan EDMS frontend is not used to modify anything in the following example):

1. Add one document type "Default" using POST /document_types/ (should exist already after default installation).
2. Add two metadata types "Required Relation" (name: "mdt_required"), “Optional Relation” (name: "mdt_optional") and "Unused Relation" (name: "mdt_unused") using POST /metadata_types/.
3. Add the relations between the document type and the metadata types using POST /document_types/1/metadata_types/
   • "mdt_required" is set to the relation “Required”.
   • "mdt_optional" is set to the relation “Optional”.
   • "mdt_unused" is set to the relation “Required”.

4. Create a document with "document_type_id": 1 and upload a document file using POST /documents/upload/.

One could state that the uploaded document is in an invalid state now, because the following metadata type constraints of the document type are violated:

• "mdt_required" is not assigned (and therefore has no value).
• "mdt_unused" is not assigned (and therefore has no value).

The same could be stated for "mdt_optional" if an optional relation translates to “This metadata type must be assigned to a document of this document type but its value can be empty.” (which is not the case, as far as I understand).

Let us ignore this uncertainty for a moment and proceed to assign and set the metadata type values for the created document.

5. Assign the metadata type "mdt_required" (a value must be set for it since it is set as “Required”) for the document using POST /documents/1/metadata/
6. Assign the metadata type "mdt_optional" (ommit a value for it, this is possible since it is set as “Optional”) for the document using POST /documents/1/metadata/

Note that the metadata type "mdt_unused" is still not assigned to the document. This is (as mentioned before) a constraint violation of the document type to metadata type relations.

My assumption based this minimal example are:

1. The “Required” relation of a document type technically translates to “The document does not need to have this metadata type assigned. If it has this metadata type assigned its value cannot be empty.”

2. The “Optional” relation of a document type technically translates to “The document does not need to have this metadata type assigned. If it has this metadata type assigned its value can be empty.”

3. It is the responsibility of the developer to add all metadata types that are associated using the relation “Required” with the document type the created document belongs to if using the REST API.

   Not doing this does not lead to an error, but introduces an inconsistent state. Compare the document type relation definitions vs. the actual metadata type values of the document.

   In other words: It is possible to create documents using the REST API that do not respect the document type relations defined.

4. It does not matter whether the metadata types that are associated using the relation “Optional” with the document type the created document belongs to are added using the REST API or not. Both seems to be consistent regarding other operations, e.g. “Delete Metadata from a Document”.

   I assume the metadata types that are defined as “Optional” should be added as well to the document, even if they do not have a value. This ensures consistency with the document type definition.

Are these assumptions correct? Until now I did not fulfill points 3 and 4, i.e. I did not assign each and every metadata type with the document type of the created document. Until now I omitted the metadata values that do not have a value (which seems incorrect due to the points made in this topic).

Note that this does not seem to be a problem if using the default web frontend, due to the fact that the UI ensures that the user fills in all metadata values.

I think some guidance regarding the proper/intended usage of both metadata type relations would be helpful. Note that I could not find anything in the documentation or knowledge base on this detail level.

[roberto.rosario]

Summary

Agreed. This feature is being discussed for removal.

The same behavior can be now coded using validation and/or the workflow engine but with greater flexibility.

Background

Document metadata has been a core feature of Mayan since the initial release. At the time there was not workflow engine or REST API and features were modified to work in the more generic method possible.

This is the reason for the metadata type to document type relationships system. It allowed to most common types of usage for metadata with the least amount of code.

However once the REST API and workflow engine were added we’ve been slowly removing smart features from apps and leveraging the workflow engine as the sole source of automation.

The rate at which we convert features to the workflow engine is slow on purpose to allow for a deprecation period and backward compatibility while the same major version.

You are correct, a user flow via the REST API is different from a user flow via the UI. However the type of user and purpose is also different. There are many things that can be made to work the same and we’ve done so as great effort (like the source API actions system), but since these are two different interfaces there will be things impossible to unify.

After 14 years we’ve learned more about the many use cases for Mayan EDMS and in each version take steps to address them by either adding, removing, merging functionality. As usage converge in real life so too do features in Mayan.

For version 5.0 we are discussing removing among other things:

• Metadata type to document type relationship. This can be handled by the workflow engine an isolate a document that does not comply with metadata policy. The policy can be as simple as required data or as complex as validation across the values of multiple metadata. The policy and action will be up to the administrator to configure.
• Mayor changes to the ACL system.
• Remove the workflow progress field.
• Remove the cabinets app. This was added after repeated requests to support new users wanted a file manager like features. This will be removed because it does not follow Mayan EDMS philosophies. The Cabinets app has too much unique code that is not used anywhere else in the project.
• Remove the SANE scanner source. Attempting to control devices from a web app has been very difficult as there is no direct control.