How to handle documents
A document can be handled in a process for the following cases:
start an invocation with a file variable - an invocation is started from a website for example.
receive internal event with file - a process instance will either start a new process instance or trigger a specific instance.
receive external event with file - an event containing a file, received from the operator will either start a process instance or trigger a specific instance.
send external event containing files - an external event containing a file will be sent to the operator webhook.
human task with file - a human task can be used to upload a document.
handle a file within a module action
use a file as an input in the module action,
retrieve a file as an output in the module action,
transfer a file variable to an other node inside the same process,
persiste an use a file inside another process
You'll find below how to configure your process for the different cases.
The document are handled as a process variables which type is io.marjory.filestore.File.
The file structure is the following one:
To get the File content use the following
GET/Files/{File.id}
Case 1 - Start an invocation
For this case, the information received to start an invocation contains a document. To be able to handle it, the document should be defined as a process variable.
When received, the File content will be stored using a File store API, the process variable will be automatically updated as defined below after upload:
File.content set to null.
File.id; File.name; File.size; File.link - updated with the returned data from the file server.
Case 2 - Receive internal event with file
An internal event is sent from a process to another one, it can either start a new instance or trigger an existing instance. The file here will already been uploaded and the variables will have the following content:
Start instance
The event to be received will have the follow
1{ 2 "env": "string", 3 "processVariables": { 4 "ref": 123, 5 "kbis": { 6 "id": "operator1/012ca03b-4f4a-4e33-b770-4005505ad8ac", 7 "name": "kbi.json", 8 "size": "1232342", 9 "content": null 10 } 11 }, 12 "workflowId": "string", 13 "workflowVersionId": "string" 14}
Trigger instance
send signal with the new file representation
Case 3 - Receive external event with file
Start instance
Let’s assume that we receive the following webhook event1{ 2 "reference": "1", 3 "fileData": "sdfsd45fsdfgsdfgsghjkhjd4456567gsdfgsdfgsdfgsdfgsçdfgdfhgjgdfgsdfg" 4}
Using Marjory Runtime API, Start an invocation with the following variables
1{ 2 "env": "string", 3 "processVariables": { 4 "termsContract": { 5 "id": "", 6 "name": "", 7 "size": "", 8 "content": "sdfsd45fsdfgsdfgsghjkhjd4456567gsdfgsdfgsdfgsdfgsçdfgdfhgjgdfgsdfg" 9 } 10 }, 11 "workflowId": "string", 12 "workflowVersionId": "string" 13}
Trigger instance
In Runtime Event Processor,
Detect variable type (example: termsContract variable)
check if variable type (get info from Workflow repo) is File.content is not empty, save kbis.content using File store API
set id, name, size, lastModified, link (S3 url)
set file.content = null after upload
send signal to runtime V1 or V2
id
name
size
lastModified
link
This duplicate the same code as in Marjory Runtime. We should create an endpoint inside Marjory Runtime or Instance container to send a signal
Case 4 - Send external event containing files
1st possibility: is it possible de send an URL (example kbis.getLink() ) instead of file content in this case?
2nd possibility: create a special module action that will download file content from File store and then send it to the Operator.
3rd possibility: use a script task that will get the file content from file, convert it to base64 and then use the usual throw event to send the event to operator.
The 3rd option is not recommended by product team!
A process variable will be set with the file content. (SignalRequest)
Case 5 - Human task with file
In Workflow Editor,
Display variables of type File as an upload file component
In Marjory Runtime,
check if kbis type if File
check if variable type (get info from Workflow repo) is File & content is empty, save kbis.content using File store API
set id, name, size, lastModified, link (S3 url)
set kbis.content = null after upload
when saving or completing the task, send File with the following structure
id
name
size
lastModified
link
Case 6 - Module module action file input / output
All module actions that manipulate files should handle the new File type
All file content manipulation should be encapsulated inside the module action.
The generated or received file content should be stored using File Store API.
The file content should not be returned .
Only the following attributes should be returned in the response
id
name
size
lastModified
link
Last updated