Downloading digital documents at an external link

1. Abstract

The platform allows you to download digital documents from a remote address in an external system and save them to the registry for further use in business processes. For example, this may be required for viewing acts, images, or other digital documents, etc.

Currently, the system allows receiving digital documents via an external link with the NO_AUTH authentication type when a request is made to public APIs (for details, see Setting up integration with an external system).

For receiving digital files from a remote address, the JUEL function save_digital_document_from_url() was developed. It can be used to simplify the modeling of processes in scripts (for more details, see Using in a business process).

The Digital Document Service (digital-document-service) is responsible for processing digital documents in the Platform.

remote-file-transfer
Figure 1. Receiving digital content from a remote address and further processing inside the register

2. Setting up integration with an external system

In order for a request for receiving external resources to go beyond the Platform cluster, it is necessary to create Service Entry at the registry level — a traffic exit point outside the system.

A Service Entry is created automatically when the registry administrator configures the integration in the Control Plane administrative panel. After applying the changes to the registry configuration and passing the Jenkins-pipeline MASTER-Build-<registry-name>, the connection to the external system will be configured.
For details about settings in the Control Plane console, see the Configuring integrations with external systems in Control Plane page.

  1. Log in to the Control Plane console as a registry administrator.

  2. Go to the Registries section and open the required registry.

  3. Find the Settings for interaction with other systems section and click + ADD EXTERNAL SYSTEM.

  4. In the new window, configure the integration with the external system for further interaction according to the registry regulations.

    Configure the interaction using the NO_AUTH authentication method. Other authentication methods are not available for this scenario.

    cp ext sys 3

3. Using in a business process

3.1. General information and restrictions

After configuring interaction with an external system in Control Plane, you can model scenarios of receiving digital documents at a remote address and their further use in business processes.

To receive digital files at a remote address, use the JUEL function save_digital_document_from_url (). It can be used when developing Groovy scripts in business processes.

The function can accept 2 input parameters:

  • URL of a digital document

  • File name

    It is possible to receive only one document per request to an external source.

    Both parameters are String, so a modeler can pass virtually any argument to the function:

Example 1. Function template
save_digital_document_from_url(String remoteFileUrl, String targetFileName)

The algorithm of the function is as follows:

  1. The save_digital_document_from_url () function makes a request to an open resource at the specified link and receives a digital document (for example, an image in .jpeg format).

  2. Then it passes the file to the Digital Document Service (digital-document-service).

  3. The service saves the file in encrypted form to the Object storage of intermediate BP data (lowcode-file-storage), and it receives in response the id and checksum metadata of the document transferred to the business process.

After that, id and checksum can be used in a business process to save and retrieve later the document from the CEPH object data storage.

For a full list of parameters that can be used in a business process, see the table below.

Table 1. Structure of the response body
Json Path Type Description

$.id

UUID

Unique identifier of a digital document, generated using a pseudo-random number generator.

$.name

Text

Original file name

$.type

Text

File content type (application/pdf, image/png, image/jpeg, etc.)

$.checksum

Text

Automatically generated hash superimposed on the content of the file using the SHA256 algorithm.

$.size

Numerical

File size
Response example
{
  "id": "{UUID}",
  "name": "{fileName}",
  "type": "{contentType}",
  "checksum": "{sha256}",
  "size": 0
}
Maximum file size

The maximum file size (max-remote-file-size) that the Digital Document Service can handle is 100 MB. If digitalDocuments.maxFileSize is not explicitly specified, a value of 100 MB is assumed as the system limit.

Supported file formats

When using the save_digital_document_from_url() function, the system automatically validates the files loaded by users through UI forms of the portals. Validation includes checking files for compliance with certain restrictions, in particular with respect to permissible file types:

  • "application/pdf": "pdf"

  • "image/png": "png"

  • "image/jpeg": "jpg", "jpeg"

  • "text/csv": csv

  • "application/octet-stream": "asics"

  • "application/pkcs7-signature": "p7s"

Use the ready-made diagram of the business process to learn the details:

Copy the contents of the .bpmn file and paste it in the Code tab in the Process Models section of the Regulations administrator portal.

3.2. Business process modeling

3.2.1. Script for receiving a digital document from an external link

  1. Create a Script Task.

  2. In the Name field, enter the name of the task. For example, Receiving a file from another system.

  3. In the Script field, open Script Editor and write a Groovy script for data processing.

    dig doc remote url 1

  4. Use the save_digital_document_from_url () function to retrieve a digital document from an external system.

    • Pass both the link function and the file name as input parameters. This can be done, for example, by defining the url and fileName parameters as variables, assigning them appropriate values, and using them in the function.

      dig doc remote url 2

    • Or you can immediately create an object and assign to it the function as a value with the corresponding input parameters.

      dig doc remote url 3

      After processing of the received data in the Digital document service, the id and checksum metadata of the document stored in the temporary storage of intermediate data are returned to the business process.

      After saving the digital document to the temporary repository, the developer must define the logic for saving the document in the permanent CEPH repository, because the file will be deleted from the temporary repository after the BP is finished.

    The result of the script execution must be saved to the documentMetadata variable that will be used later in another script to create an object that stores the metadata of the received document in the permanent CEPH storage.
    dig doc remote url 4

3.2.2. User task for outputting a file from the database to the UI form

After saving the object with the metadata of the digital document to the main database, we find the record by its ID and transfer the object as a variable to the UI form of the User portal.

  1. Create a User Task.

  2. Enter the task name. For example, View the file from the database in the form.

  3. Apply the delegate template from the list of available templates — User form.

  4. In the Form key field, enter the service name of the form to which you want to transfer data. For example file-saved-from-ext-system-view.

  5. In the Assignee field, enter the process initiator token — ${initiator}.

  6. In the Form data pre-population field, enter the data of the object containing a digital document (in our example, that is an image), which will be displayed in the form. For example, ${response.value.responseBody}.

    dig doc remote url 5

3.3. Modeling of UI forms

The digital document received from an external link can be displayed in the UI form of the business process and downloaded to the local machine for further use.

Use the ready-made form to learn the details:

Copy the contents of the .json file and paste it in the Code tab in the UI-forms section of the Regulations administrator portal.

  1. Create a UI form for a business process.

  2. In Builder, configure the Text Field component to display the filename.

  3. Next, configure the File component for receiving the data (a digital document) from the CEPH repository.

    dig doc remote url 6

    Go to the API tab, and in the Property Name field, enter the keyword to search for a record in the object repository. For example image.

    The parameter is not hardcoded. You can use any keys provided by your business process logic.

    dig doc remote url 7

    The result returned to the UI form may look like this:

    Example 2. Digital document received from CEPH using the image keyword

    dig doc remote url 8

3.4. Usage in the Officer portal

Let’s consider an example of how a user UI form looks like with a displayed digital document received from an object repository.

  1. Enter the Officer portal.

  2. Run the modeled business process.

    dig doc remote url 9

  3. Download the received file to your local machine for future use.

    dig doc remote url 10

4. Related pages

5. Additional videos