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:

      "File": {
        "id": "",
        "name": "",
        "size": "",
        "link": "",
        "content": "sdfsdfsdfgsdfgsdfgsdfgsdfgsdfgsdfgsdfgsdfg"
              }
  • 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:

"File": {
    "id": "operator1/012ca03b-4f4a-4e33-b770-4005505ad8ac",
    "name": "file.json",
    "size": "324",
    "content": "null"
          }

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