Attached document
Value resolver – Abstract
Purpose: Returns the contents of all Documents assigned to an entity in the input value and belonging to the optionally specified Document type.
The Attached document value resolver expects an entity as input value and returns an array listing the 'Contents' from the documentContent field of all Documents that meet all of the following criteria:
Read access exists for the document in the applicable context.
The 'Referenced object' (referencedEntity) field of the document refers to the type of entity in the input value.
The 'Referenced object ID' (referencedEntityId) field of the document refers to the ID (id) of the entity in the input value.
The 'Reference status' (referenceStatus) field of the document refers to the 'Referenced' (REFERENCED) status.
►NOTE◄ Each time a document is saved, the processes described in Assigning documents are started again to assign the document. If the assignment fails for a document that has already been successfully assigned, e.g. because another Document reference type is now selected that does not return an entity as a match, then the reference status after saving the document is 'Unresolved' (UNRESOLVED). This means that the document is not considered 'attached' from the point of view of the entity for which criteria 2 and 3 would still be fulfilled.
Special case:
If there is no entity as input value, the value resolver returns 'No value' ($null).
If the input value is an entity, but no Documents are found that meet the above criteria, an empty array is returned.
If the input value is an entity and exactly one document meets the above criteria, its content is returned as the only entry in an array.
►NOTE◄ The value resolver is not used to access Documents as entities, but only returns their content. Access to the data of the document entities for 'Attached documents', on the other hand, would be provided, for example, by a Search (Event action) for the 'Document' (en.lobster.scm.doc.Document) entity type, which must map the above criteria (2, 3 and 4) with reference to the input value.
►CAUTION◄ The return value is an array and NOT a list ...
The fact that the return value is an array and not a real 'List' (List) may occasionally cause restrictions or require precautions. The following list does not claim to be complete:
An array does not pass a Check type for the 'List' (List) type. The combination of the 'Is collection of" option in connection with the 'Content' type in the Check type does not solve this problem.
Access to existing entries in the array via the List item value resolver is possible (in contrast to previous versions of Lobster Data Platform / Orchestration).
However, no entries can be added to the array.
With the Input object (type safe) value resolver, the array can be formally converted into a list which then also withstands type checking.
However, no entries can be added to this list either.
Configuration
The input value is expected to be an entity of any type, since Documents can only be assigned to entities, i.e. 'Attached' to them.
|
The optional of type parameter can be used to limit the selection of Documents to exactly one specific Document type by static single selection. Without a selection for the of type parameter, the value resolver returns the contents of all assigned documents (criteria see above) regardless of their Document type. The selection is supported by a search function which, as shown in the image, takes into account not only the localization but also the internal name for the Document type. If Dynamic enum filters are applicable to the Document type in the context of the configuration, they restrict the selection. However, Dynamic enum filters do not change the runtime behaviour of a configuration. |
|
Example
Simple use case: 'Resume' file(s) attached to the user
An association criterion (see Association criteria) is considered passed if the input value in the data context is a Users for whose account at least one 'Attached' document of the Document type 'Curriculum Vitae' (CV) is found.
Configuration:
|
The association criteria combines two rules in an AND Junction:
|
|
Runtime example: Value of the variable docCV if exactly one attached PDF document with the Document type 'Curriculum Vitae' (CV) was found for the user.:
<value xsi:type="array"> <item mediaType="application/pdf" name="cv-2801.pdf" xsi:type="core:Content"> <body>JVBERi0xLjUNCiW1tbW1DQoxID[...]</body> </item> </value>The return value is an array object with an item of the 'Content' (Content) type.
The 'Content' object represented by the item element contains the base64 file content in the body element as well as the 'Media type' (mediaType) and 'Name' (name) as XML attributes.
More complex use case: Compile file attachments for a shipment
A Custom action event event triggers a notification by e-mail in the context of a workflow for a business object of the 'shipment' (Shipments) type.
The following files should be attached to generated E-mails:
The contents of all assigned Documents for the program in question.
A PDF file deposited on the Lobster Data Platform / Orchestration server containing the current terms and conditions.
The body of the mail should list the names of the attached documents. Therefore, all attachments are collected in an attachments list variable before the E-Mail event action is executed.
Configuration:
|
The screenshot on the right shows an excerpt from an event handler that controls the assignment to the attachments list variable via Set value event action: On the right side of the assignment, the list of all relevant attachments is compiled by a value resolution chain:
|
|
