References from documents to data objects

Document assignments are based on references to a data object by combining two properties of the document object:

When a document is successfully assigned, values are automatically assigned to both properties.

►NOTE◄

• Due to the data structure each document object can only be assigned to a single data object. To attach the same file content to multiple objects, multiple documents with redundant content must be created.

• During Barcode detection, copies of a document are created automatically if the same document (section) contains more than one relevant barcode.

• Assigning the same document to multiple data objects interactively requires repeated uploads.

Referencing a data object

The process of referencing is triggered, whenever a document is saved. During Barcode detection, the referencing is implicitly triggered each time a document is created.

The property Reference type (referenceType) of the document must specify a Document reference type at this point. This contains the definition of a search, which must return exactly one data object in order for the document to be referenced successfully

►IMPORTANT◄ A search will only resolve data objects with read access for the current session. A document can only be assigned to data objects as 'readable' at the time of the referencing. A document with a reference to a data object without read access will appear in an overview for 'Documents'. However, any attempt to select the document from the list is denied with an error message.

►NOTE◄ The search definition of a Document reference type features a parameter Max results that can be set to a value of 1 to prevent multiple results being returned. If multiple data objects match the search criteria, the search returns only the first result, according to applicable Sort criteria, if any. It is absolutely essential to uncheck the option Calculate total number? in this context, otherwise a search result with a total count larger than 1 will qualify as 'ambiguous' despite the Max results limit of 1 and therefore the document will not be assigned.

The value of the property Reference (reference) is provided for the context of the search via the text variable 'reference'. Typically, it serves as a key criterion for referencing, possibly determined automatically by Barcode detection.

►NOTE◄ A Document reference type may define referencing logic that does not involve the Reference string, e.g. if all uploaded documents of a certain type should be directly assigned to the current company account (see Company of session). However, without any characters in the Reference property, the search will not be executed and a Reference status of 'Not referenced' is set. Therefore, at at least a dummy value for Reference must be set, even in these special cases.

The indication of an object class by the Referenced entity (referencedEntity) property is only relevant if the selected Document reference type is designed to be applicable to various object classes and does not specify an entity itself. In this case, an entity type must be defined by the document, otherwise the search is not executed and a Reference status of 'Not referenced' is set for the document.

Results of referencing

Referencing changes the following properties of the document:

If referencing returns exactly one single data object, the Reference state 'Referenced' is set and the event Document assigned is triggered. Unless event handler execution (if any) for this event raises an Abort or error causing a roll-back, the document is finally assigned to the data object afterwards.

If any of the other Reference states ('Not referenced' or 'Unresolved') is set during results from referencing, the document is saved as well. Consequently, these documents are featured in the overview for 'Documents', for root-cause analysis and/or correction.

►NOTE◄

• Referencing is not only triggered when a document is created, but also each time a document is saved (Update) using the parameters provided at that time.

• On one hand, this enables interactive corrections regarding the reference or the selection of Document reference type to achieve successful assignments.

• On the other hand, a valid assignment may become invalid by such manipulations. For example, if a value for Reference is changed from a valid to an invalid key, saving the document will change the Reference state to 'Unresolved', even if the Referenced Entity id property still refers to the successfully resolved data object. The current document is no longer listed as an assigned document for this data object. The original assignment can only be restored if a Reference is corrected and resolved by saving the document again.

• The behaviour is somewhat different if, after a successful or failed assignment, the value for the reference is deleted, which makes the referencing parameters incomplete. Where the reference state 'Not referenced' would be set for a new document, the status of an existing document remains unchanged. A valid reference remains valid, an 'unresolved' reference stays 'unresolved'.