File attachments

It is possible to attach a file to a data record in the monitor. This gives users the option of viewing or downloading the file.

File source

The BPC Monitor supports the retrieval of files directly from OpenSearch, as a reference to the file storage service and as a reference via an HTTP proxy backend connection (for example from INUBIT).

Files in OpenSearch

You can save files in BPC OpenSearch. In this case, a file is attached directly in the monitor data set.

The files should be encoded as a Base64 string and stored in the data set under dataIndex. The data set must contain the following information so that the file can be restored with the correct name and format:

  • Name of the file

  • MIME type

The names of the columns containing this information must be made in the settings of the column containing the file data (see Configuration: File column).

The data record containing the file can be added via a BPC log service or via an index request to OpenSearch. The following example shows a data record with a file attachment:

   {
      "PROCESSID": "2",
      "TEXT": "This is second test object",
      "FILEID": "foodmenu.xml",
      "filename": "foodmenu.xml",
      "contentType": "application/xml",
      "DATA": "PGJyZWFrZmFzdF9tZW51Pgo8Zm9vZD4KPG5hbWU+QmVsZ2lhbiBXYWZmbGVzPC9uYW1lPgo8cHJpY2U+JDUuOTU8L3ByaWNlPgo8ZGVzY3JpcHRpb24+VHdvIG9mIG91ciBmYW1vdXMgQmVsZ2lhbiBXYWZmbGVzIHdpdGggcGxlbnR5IG9mIHJlYWwgbWFwbGUgc3lydXA8L2Rlc2NyaXB0aW9uPgo8Y2Fsb3JpZXM+NjUwPC9jYWxvcmllcz4KPC9mb29kPgo8Zm9vZD4KPG5hbWU+U3RyYXdiZXJyeSBCZWxnaWFuIFdhZmZsZXM8L25hbWU+CjxwcmljZT4kNy45NTwvcHJpY2U+CjxkZXNjcmlwdGlvbj5MaWdodCBCZWxnaWFuIHdhZmZsZXMgY292ZXJlZCB3aXRoIHN0cmF3YmVycmllcyBhbmQgd2hpcHBlZCBjcmVhbTwvZGVzY3JpcHRpb24+CjxjYWxvcmllcz45MDA8L2NhbG9yaWVzPgo8L2Zvb2Q+Cjxmb29kPgo8bmFtZT5CZXJyeS1CZXJyeSBCZWxnaWFuIFdhZmZsZXM8L25hbWU+CjxwcmljZT4kOC45NTwvcHJpY2U+CjxkZXNjcmlwdGlvbj5MaWdodCBCZWxnaWFuIHdhZmZsZXMgY292ZXJlZCB3aXRoIGFuIGFzc29ydG1lbnQgb2YgZnJlc2ggYmVycmllcyBhbmQgd2hpcHBlZCBjcmVhbTwvZGVzY3JpcHRpb24+CjxjYWxvcmllcz45MDA8L2NhbG9yaWVzPgo8L2Zvb2Q+Cjxmb29kPgo8bmFtZT5GcmVuY2ggVG9hc3Q8L25hbWU+CjxwcmljZT4kNC41MDwvcHJpY2U+CjxkZXNjcmlwdGlvbj5UaGljayBzbGljZXMgbWFkZSBmcm9tIG91ciBob21lbWFkZSBzb3VyZG91Z2ggYnJlYWQ8L2Rlc2NyaXB0aW9uPgo8Y2Fsb3JpZXM+NjAwPC9jYWxvcmllcz4KPC9mb29kPgo8Zm9vZD4KPG5hbWU+SG9tZXN0eWxlIEJyZWFrZmFzdDwvbmFtZT4KPHByaWNlPiQ2Ljk1PC9wcmljZT4KPGRlc2NyaXB0aW9uPlR3byBlZ2dzLCBiYWNvbiBvciBzYXVzYWdlLCB0b2FzdCwgYW5kIG91ciBldmVyLXBvcHVsYXIgaGFzaCBicm93bnM8L2Rlc2NyaXB0aW9uPgo8Y2Fsb3JpZXM+OTUwPC9jYWxvcmllcz4KPC9mb29kPgo8L2JyZWFrZmFzdF9tZW51Pg=="
   }

File reference of the File Storage Service

Files can be managed by the File Storage Service and referenced in a monitor.

These references have the following format:

bpc://backend-connection/FILE_STORAGE_BACKEND_CONNECTION_ID/FILE_STORAGE_ITEM_ID

File reference with HTTP proxy

Files can be stored in a separate system (e.g. INUBIT) and accessed via a configured HTTP proxy connection. How files are stored there depends on the setting in INUBIT.

The files should be provided via a REST endpoint so that they can be downloaded from the BPC (see also Configuration of downloading files in the monitor).

Configuration of downloading files in the monitor

After a file or a reference to the file has been saved in the monitor data set, the following settings are required to enable the file to be downloaded.

Configuration: File column

Create a setting object fileConfig in the column configuration (column_config or column_historyConfig for parent or child indices) in the settings of the column that contains the file contents or references.

This setting must configure the fields columnFileName and columnContentType, which define the name of the file name or content type column. Optionally, the dataSource field can be used to specify that files always come from a specific source (OpenSearch, (INUBIT) HTTP proxy). The options OpenSearch, FileStorage, BackendConnection, and auto are offered. In the case of auto (default), an attempt is made to determine the source based on the content of the file column.

Example
{
    ...
    "dataIndex": "DATA",
    "xtype": "attachmentcolumn",
    "text": "REFFILE",
    ...
    "fileConfig": {
        "columnFileName": "filename",
        "columnContentType": "contentType",
        "dataSource": "auto"
    }
}

The example configures that file contents or references are located in the OpenSearch field DATA. The corresponding file name is located in the column filename, the corresponding content type in the column contentType.

If the column attachmentcolumn is xtype, a download button is displayed in this column. However, this is not necessary for downloading attachments of files in child indices via the popup or inline view; the fileConfig entry is sufficient here.

If "dataSource": "auto" is set, the file is delivered if it is a file in the file storage. Otherwise, an attempt is made to interpret the content of the file column as a Base64-encoded string. If decoding fails, the value is sent as the URL Parameters directory in the query to the configured HTTP proxy.

Configuration: Download from INUBIT

If the file is to be downloaded from INUBIT, the following settings are required:

  • Function_InubitBackendConnection (inubit_proxyId):
    INUBIT Backend Connection.

  • Function_InubitBaseURL (inubit_baseUrl):
    Fixed component in all URLs to INUBIT.

  • Function_FileDownloadEndpoint (inubit_referenceEndpoint):
    The INUBIT endpoint under which files can be downloaded should be set.

  • Monitor_ProcessID (column_id):
    The query contains information about the process ID as URL Parameters, therefore the corresponding column should be set.

  • Monitor_HistoryID (column_historyId):
    If the download refers to the child process, the ID of the child process should be included in the query for the INUBIT as a URL parameter. The corresponding column must therefore be set.

After everything has been configured, the URL has the following structure:

{Protokoll}://{Domain}/{inubit_baseUrl}/{inubit_referenceEndpoint}?directory={Inhalt der Datei-Spalte}&processid={processId}&childid={childId}

Specific use case

This example shows how a Base64-encoded file can be written to OpenSearch via the log service and then downloaded from the monitor child grid.

Creating a log service instance

The log service instance is configured using the following parameters:

  • Instance ID: myTestLogger

  • OpenSearch index: myTestIndex

  • OpenSearch history index: myTestChildIndex

Writing data to OpenSearch via the log service API

The data to be saved contains a Base64-encoded file. This should be stored in a separate file.

In this example, a file named logservice.json is created with the following content:

{
    "entries": [
        {
            "parent": {
                "processid": 3,
                "name": "hello world",
                "lastupdate": "2017-05-17T15:28:23.181Z"
            },
            "children": [
                {
                    "parentid": 3,
                    "childid": 1,
                    "langertext": "Dieser Text",
                    "lastupdate": "2017-05-17T15:28:23.181Z",
                    "datei": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACAQMAAABIeJ9nAAAABlBMVEUAAAD///+l2Z/dAAAADElEQVQIHWNwYGgAAAFEAMGoX3f9AAAAAElFTkSuQmCC",
                    "filename": "food.png",
                    "contentType": "application/png"
                }
            ]
        }
    ]
}

Important attributes:

  • datei - contains the Base64-encoded file.

  • contentType - specifies the MIME type of the file.

  • filename - The name under which the file is to be saved.

Send data to the Logservice API via cURL

In the next step, the data is sent to the Logservice API using the cURL command.

Prerequisites:

  • The file logservice.json is located in the current directory.

  • A valid API key is available. (see here)

  • A BackendConnection of the type HTTP Proxy has been set up. (see here)

curl -H "X-ApiKey: 1f697af5-c147-3d94-c529-e06f3f15bb87" \
     -H "Content-Type: application/json" \
     -XPOST 'http://localhost:8181/cxf/bpc-logservice/log/myTestLogger' \
     -d @logservice.json

Creating a monitor instance

The monitor instance requires the following configuration:

  • OpenSearch Index (data_index ): myTestIndex

  • OpenSearch history index (data_history_index): myTestChildIndex

  • Column ID (column_id): processid

  • History ID (column_historyId): parentid

  • Additional history ID (column_historySubId): childid

  • Backend Connection (inubit_proxyId): Selection of the backend connection created

  • Inline detail view (detailView_inline ): true

In addition, the column containing files or file references must be configured accordingly (see Configuration: File column):

{
    ...
    "dataIndex": "datei",
    "text": "Datei",
    ...
    "fileConfig": {
        "columnFileName": "filename",
        "columnContentType": "contentType",
        "dataSource": "auto"
    }
}

Download file

To download the uploaded file, proceed as follows:

  1. Navigate to the monitor instance.

  2. Open the detailed view of the first and only data row.

  3. The download button is located in the first column of the detailed view.

file attachment

After clicking on the download button, the file should be downloaded.

Configuration for the file preview for file storage (CORS & CSP)

The files managed by the File Storage Service are stored at configured cloud storage providers. In the backend connection, you can configure whether a download should take place directly from this cloud provider or be routed via the BPC.

When viewing files directly in the monitor, Content Security Policy (CSP) and Cross-Origin Resource Sharing (CORS) of the bucket/container must also be configured if a download takes place directly from the cloud provider.

Setting the CSP header

In this case, the content security policy in the file BPC-INSTALLATION/karaf/etc/jetty.xml should be adjusted so that the corresponding bucket/container is permitted:

<Item>
    <New id="header-csp" class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule">
        <Set name="pattern">/*</Set>
        <Set name="name">Content-Security-Policy</Set>
        <Set name="value">script-src 'self' 'unsafe-eval'; connect-src 'self' https://test-bucket.s3.eu-central-1.amazonaws.com; img-src 'self' https://test-bucket.s3.eu-central-1.amazonaws.com data: blob:; style-src 'self' 'unsafe-inline'; font-src 'self'; frame-ancestors 'self'; form-action 'self'; worker-src 'self' blob: ;</Set>
    </New>
</Item>

In this example, access and image representations for the S3 bucket test-bucket are permitted in the region eu-central-1.

Setting the CORS header

To ensure that the resources loaded by the cloud provider can also be used in the BPC, the CORS header in the bucket/container must be adapted so that the URL of the BPC is released for GET and HEAD requests.

The following example shows the release for a BPC that can be reached at https://bpc.example.com:

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "HEAD"
        ],
        "AllowedOrigins": [
            "https://bpc.example.com"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen