Send and receive attachments via Web Service
During the modeling of your processes, you may find it necessary to exchange attached files with an external system, either to store them, share them, or process them in other applications. The use cases are varied and highly useful in the context of process automation; therefore, Flokzu offers three ways to move attachments using Service Tasks in the workflow.
Sending attachments to other Flokzu instances using Flokzu Services.
Sending the attached file (binary) to an external system via REST.
Sending a URL via REST that allows downloading a file from an external system asynchronously.
Because all three features are configured at modeling time, it is only possible to move files that are stored in Attachment Type Fields.
With this mechanism, you can create a copy of the file in another different instance of your organization, whether from the same process or a different one.
👉 Cloning or copying instances: When you want to clone a complete instance or create a new one with information that already exists in the system.
👉 Modeling sub-processes: At times, it will be useful to model your processes as smaller or isolated parts of a larger procedure within your organization, that is, as a sub-process. In that case, the information loaded in an initial process A should continue in another process B.
To perform any of these actions, you must add a Service Task in the workflow, with an integration of Flokzu Services.
Let's see an example:
Suppose a process where a certain product must be evaluated, and if approved, a request is initiated for its acquisition. Internally in the organization, this is modeled with two different processes: Product Evaluation and Purchase Request.
The evaluation process form will have an attachment-type field Description (PDF) where the user is asked to include the product information, and the workflow will have a Evaluate Product task where the responsible person decides whether or not to make the purchase.
To learn how to create an instance with Flokzu Services, you can read this post.
The integration with Flokzu Services Create Purchase Request is configured to create the new process, and it is also desired that the PDF is copied to the Product Catalog (PDF) field of the Purchase Request process.
With this configuration, Flokzu will initiate a new purchase request and create a copy of the PDF file in the indicated field. This way, the administration area responsible for executing the purchase will have all the relevant information available in their own process.
Similarly, you can use Flokzu Services to copy the attachment to an existing instance or to obtain the file from another previously created instance.
This functionality supports the copying of attachments uploaded by the user to Flokzu, as well as files stored in Google Drive or Microsoft OneDrive.
Flokzu allows integration with applications capable of receiving an attached file to store or process it. For this, we will use REST Service Tasks that can invoke Web Services and send one or more attached files as input parameters.
To use this feature, you must add a REST Service Task and customize the call by selecting the option form-data.
To learn how to invoke a web service with a customized body, you can read this post.
Form-data refers to a way of communicating between web services, where data is sent as key/value pairs representing the fields of a form and their values. While it is useful for sending any type of data the external application requires (text, numbers, boolean values), it is also the only mechanism that supports "multipart/form-data" encoding, necessary to send files. If the call is not customized, or the raw or x-www-form-urlencoded option is used, it will still be possible to select attachment-type fields as parameters, but the file will not be sent in those cases.
Attachments uploaded with Google Drive or OneDrive are not stored by Flokzu and therefore cannot be sent using this mechanism. See the section Send Download URL for an Attachment.
Flokzu allows sending any number of files as long as the total size of the web service call does not exceed 10 Megabytes.
Some web services are designed to receive a link that they then use to download the file asynchronously. This mechanism is more efficient as it decouples the response times and minimizes the data traffic between the web services executed from your process workflow. Additionally, it has no file size limitations.
To obtain a download URL, you must add a REST Service Task and configure an attachment-type field in a parameter without using the form-data option
Instead of obtaining the file, your service will receive in the indicated parameter the metadata including a download URL:
Then your service must be responsible for invoking the URL and executing it to download the file.
The download URL can also be obtained by consuming the GET Process Instance from the OpenAPI. The response will include within the fields parameter the file metadata with the download URL.
The Flokzu download link is generated each time the external service is invoked or requested from OpenAPI and expires a few minutes after being created.
This means that even for the same file, you will get a different URL with each request, and your service must properly manage the download time.
If a service needs to download a file beyond the validity time, it must make a new request and obtain a new download link.
In the case of attachments stored in Google Drive or Microsoft OneDrive, the download link is provided by these services, does not expire, and access control is managed by them, which means the download may require additional authentication.
If the web service you are invoking returns a file in its response, you can attach it in the Attachments Tab of your instance or in a form field.
In the Output Data tab of the Service Task, you must select the Binary option and then choose from the list the place where the attachment will be saved.
Keep in mind that if the selected field already contains a file, it will be overwritten.
Sending attachments to other Flokzu instances using Flokzu Services.
Sending the attached file (binary) to an external system via REST.
Sending a URL via REST that allows downloading a file from an external system asynchronously.
Because all three features are configured at modeling time, it is only possible to move files that are stored in Attachment Type Fields.
Sending attachments between Flokzu instances
With this mechanism, you can create a copy of the file in another different instance of your organization, whether from the same process or a different one.
When is this feature useful?
👉 Cloning or copying instances: When you want to clone a complete instance or create a new one with information that already exists in the system.
👉 Modeling sub-processes: At times, it will be useful to model your processes as smaller or isolated parts of a larger procedure within your organization, that is, as a sub-process. In that case, the information loaded in an initial process A should continue in another process B.
How does it work?
To perform any of these actions, you must add a Service Task in the workflow, with an integration of Flokzu Services.
Let's see an example:
Suppose a process where a certain product must be evaluated, and if approved, a request is initiated for its acquisition. Internally in the organization, this is modeled with two different processes: Product Evaluation and Purchase Request.
The evaluation process form will have an attachment-type field Description (PDF) where the user is asked to include the product information, and the workflow will have a Evaluate Product task where the responsible person decides whether or not to make the purchase.
To learn how to create an instance with Flokzu Services, you can read this post.
The integration with Flokzu Services Create Purchase Request is configured to create the new process, and it is also desired that the PDF is copied to the Product Catalog (PDF) field of the Purchase Request process.
With this configuration, Flokzu will initiate a new purchase request and create a copy of the PDF file in the indicated field. This way, the administration area responsible for executing the purchase will have all the relevant information available in their own process.
Similarly, you can use Flokzu Services to copy the attachment to an existing instance or to obtain the file from another previously created instance.
This functionality supports the copying of attachments uploaded by the user to Flokzu, as well as files stored in Google Drive or Microsoft OneDrive.
Sending attachments via Web Service
Flokzu allows integration with applications capable of receiving an attached file to store or process it. For this, we will use REST Service Tasks that can invoke Web Services and send one or more attached files as input parameters.
How does it work?
To use this feature, you must add a REST Service Task and customize the call by selecting the option form-data.
To learn how to invoke a web service with a customized body, you can read this post.
Form-data refers to a way of communicating between web services, where data is sent as key/value pairs representing the fields of a form and their values. While it is useful for sending any type of data the external application requires (text, numbers, boolean values), it is also the only mechanism that supports "multipart/form-data" encoding, necessary to send files. If the call is not customized, or the raw or x-www-form-urlencoded option is used, it will still be possible to select attachment-type fields as parameters, but the file will not be sent in those cases.
Attachments uploaded with Google Drive or OneDrive are not stored by Flokzu and therefore cannot be sent using this mechanism. See the section Send Download URL for an Attachment.
Flokzu allows sending any number of files as long as the total size of the web service call does not exceed 10 Megabytes.
Sending Download URL for an Attachment
Some web services are designed to receive a link that they then use to download the file asynchronously. This mechanism is more efficient as it decouples the response times and minimizes the data traffic between the web services executed from your process workflow. Additionally, it has no file size limitations.
How does it work?
To obtain a download URL, you must add a REST Service Task and configure an attachment-type field in a parameter without using the form-data option
Instead of obtaining the file, your service will receive in the indicated parameter the metadata including a download URL:
{
"file": {
"attachmentId": "dc35696a412b4505bff824aa2f152642",
"creationTime": "2024-04-02T20:26:27.77941695Z",
"lastEditedUtc": "",
"mimeType": 31,
"name": "TAB-6-1.pdf",
"size": 2398,
"superType": 0,
"url": "https://flokzu-storage-production...."
},
"sender": [{
"sender_email": "myemail@email.com",
"sender_name": "John Doe"
}
]
}Then your service must be responsible for invoking the URL and executing it to download the file.
OpenAPI
The download URL can also be obtained by consuming the GET Process Instance from the OpenAPI. The response will include within the fields parameter the file metadata with the download URL.
URL Validity
The Flokzu download link is generated each time the external service is invoked or requested from OpenAPI and expires a few minutes after being created.
This means that even for the same file, you will get a different URL with each request, and your service must properly manage the download time.
If a service needs to download a file beyond the validity time, it must make a new request and obtain a new download link.
In the case of attachments stored in Google Drive or Microsoft OneDrive, the download link is provided by these services, does not expire, and access control is managed by them, which means the download may require additional authentication.
Receiving files via Web Service
If the web service you are invoking returns a file in its response, you can attach it in the Attachments Tab of your instance or in a form field.
In the Output Data tab of the Service Task, you must select the Binary option and then choose from the list the place where the attachment will be saved.
Keep in mind that if the selected field already contains a file, it will be overwritten.
Updated on: 14/06/2024
Thank you!