File Storage API

File storage endpoints provide functionality to store files and binary data through configured file storage backend connections.

Method Endpoint

GET

/cxf/bpc-core/file-storage/file/{fileId}

Description

Retrieves metadata of a file in the file storage.

Path Parameter

fileId

The File ID

Returns

Returns the metadata of the requested file in JSON format.

HTTP Status Code

  • 200 : OK

  • 400 : File ID parameter is missing.

  • 403 : The user has no read permission for the file.

  • 404 : The requested file does not exist.

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

GET

/cxf/bpc-core/file-storage/files

Description

Retrieves a list of file metadata in the file storage.

Query Parameter

backendConnectionId

The file storage backend connection ID (optional)

bucket

The object stores bucket name (optional)

start

first record to be read (optional, default = 0). Default is 0.

limit

number of records to read (optional, default = 1000, max. 10.000). Default is 1000.

sort

sort instruction (ExtJS-JSON) (optional)

Returns

Returns a JSON array containing metadata for files stored in the object store bucket.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

GET

/cxf/bpc-core/file-storage/download/{fileId}

Description

Downloads the requested file from the file storage.

This is done by redirecting to a presigned download URL or streaming the cloud file content (depending on the option 'fileStorageDownloadThroughBpc').

Path Parameter

fileId

The File ID

Query Parameter

inline

If true, the content-disposition header is set to 'inline', otherwise 'attachment'. Default is false.

Returns

The requested file as a download.

HTTP Status Code

  • 307 : Redirect to download

  • 400 : File ID parameter is missing.

  • 403 : The user has no read permission to request a download.

  • 404 : The requested file does not exist.

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

GET

/cxf/bpc-core/file-storage/download-url/{fileId}

Description

Get a download URL for the requested file from the file storage.

The return body is a presigned download URL to the file or the url of the download endpoint (depending on the option 'fileStorageDownloadThroughBpc').

Path Parameter

fileId

The File ID

Query Parameter

inline

If true, the content-disposition header is set to 'inline', otherwise 'attachment'. Default is false.

Returns

A temporary valid download url for the requested file.

HTTP Status Code

  • 200 : Download URL

  • 400 : File ID parameter is missing.

  • 403 : The user has no read permission to request a download.

  • 404 : The requested file does not exist.

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

POST

/cxf/bpc-core/file-storage/upload

Description

Create a file in the file storage.

The file and necessary metadata are passed via multipart form data. Required are the following form fields:

  • file: the uploaded file

  • backendConnectionId: the ID of the configured file storage backend connection

  • readRestriction: the read restriction

  • writeRestriction: the write restriction

The parameter bucket specifies the name of the bucket to upload to. If omitted, the default bucket defined in the file storage connection is used.

Additionally, a form field creatorServiceId can be specified, referring to the service instance that triggers the upload.

The read and write restrictions use the following format:

{
    "user": "hans_schmidt",
    "organisations": [ "DEFAULT" ],
    "roles": [ "expert", "advanced", "beginner" ],
    "rights": [ "loadModule_monitor" ]
}

The evaluation is done as follows:

  • User Specific: If the user field is present, all other fields are ignored. Only this exact user satisfies the restriction.

  • Role/Right/Org Constraints: If the user field is omitted, the user must satisfy all specified (non-empty) arrays (AND logic between fields):

    • Organisations: User must belong to at least one listed organisation (OR logic).

    • Roles: User must have at least one listed role (OR logic).

    • Rights: User must have at least one listed right (OR logic).

Note, the uploader needs to fulfill both read and write restrictions.

Consumes

  • multipart/form-data

Returns

The created file metadata, including a success flag.

HTTP Status Code

  • 200 : File has been stored

  • 400 : Missing form data content

  • 400 : The user does not fulfill the passed read or write restrictions.

Content-Type

  • application/json

Required Access Rights

The logged in user, API Key or access token must have either the following role or right.

  • Role : FILE_STORAGE_ADMIN

  • Right : FILE_STORAGE_UPLOAD

POST

/cxf/bpc-core/file-storage/existing-file

Description

Add a file in the file storage by passing a reference to a file in the cloud storage.

The file key and necessary metadata are passed in the request body as JSON. The following fields are required:

  • backendConnectionId: the ID of the configured file storage backend connection

  • bucket: the name of the bucket/container where the file is stored - if omitted, the default bucket is used

  • fileKey: the file key

  • readRestriction: the read restriction

  • writeRestriction: the write restriction

The following fields are optional and if not present, the information is taken from the file metadata at the cloud storage provider.

  • filename: the file name

  • contentType: the files content type

Additionally, a field creatorServiceId can be specified, referring to the service instance that triggers the upload.

The read and write restrictions use the following format:

{
    "user": "hans_schmidt",
    "organisations": [ "DEFAULT" ],
    "roles": [ "expert", "advanced", "beginner" ],
    "rights": [ "loadModule_monitor" ]
}

The evaluation is done as follows:

  • User Specific: If the user field is present, all other fields are ignored. Only this exact user satisfies the restriction.

  • Role/Right/Org Constraints: If the user field is omitted, the user must satisfy all specified (non-empty) arrays (AND logic between fields):

    • Organisations: User must belong to at least one listed organisation (OR logic).

    • Roles: User must have at least one listed role (OR logic).

    • Rights: User must have at least one listed right (OR logic).

Note, the uploader needs to fulfill both read and write restrictions.

Consumes

  • application/json

Query Parameter

check-file

If false, the file information is not retrieved from the cloud provider. Useful, if the file will be uploaded at a latter time.

  1. Default is true.

Returns

The created file metadata, including a success flag.

HTTP Status Code

  • 200 : File has been stored

  • 400 : Missing information needed to store file

  • 400 : The user does not fulfill the passed read or write restrictions.

  • 404 : The referenced file does not exist.

Content-Type

  • application/json

Required Access Rights

The logged in user, API Key or access token must have either the following role or right.

  • Role : FILE_STORAGE_ADMIN

  • Right : FILE_STORAGE_UPLOAD

PUT

/cxf/bpc-core/file-storage/upload/{fileId}

Description

Replaces an existing file in the file storage.

The file is passed via multipart form data.

Consumes

  • multipart/form-data

Path Parameter

fileId

The File ID

Returns

The updated file metadata.

HTTP Status Code

  • 200 : File has been updated

  • 400 : Missing file ID parameter or file upload.

  • 403 : The user does not fulfill the write restrictions.

  • 404 : The requested file does not exist.

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

PUT

/cxf/bpc-core/file-storage/file/{fileId}

Description

Updates the metadata of a file in the file storage.

Updates can be applied to 'File Name', 'Read Restrictions' and 'Write Restrictions'. Fields in the PUT-DTO that are left out will not be updated.

Consumes

  • application/json

Path Parameter

fileId

The File ID

Returns

HTTP Status Code

  • 200 : Returns the updated file store item

  • 400 : File ID parameter is missing.

  • 403 : The user has no write permission to perform deletion.

  • 404 : The requested file does not exist.

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

DELETE

/cxf/bpc-core/file-storage/file/{fileId}

Description

Deletes a file in the file storage.

Path Parameter

fileId

The File ID

Query Parameter

skipCloudDelete

If true, only the metadata of the file will be removed, not the file itself from the cloud storage. Default is false.

Returns

HTTP Status Code

  • 204 : Deletion was successful.

  • 400 : File ID parameter is missing.

  • 403 : The user has no write permission to perform deletion.

  • 404 : The requested file does not exist.

Content-Type

  • application/json

Required Access Rights

A logged in user, API Key or access token is required.

POST

/cxf/bpc-core/file-storage/index

Description

Triggers an indexing process from cloud storage to the OpenSearch index.

Missing metadata entries in the File-Storage OpenSearch index will be created for files in the cloud storage. Only files that are not already present in the index will be indexed.

The backend connection ID is required. If a bucket is specified, only that bucket will be synchronized. Otherwise, all buckets of the backend connection will be synchronized.

Consumes

  • application/json

Returns

HTTP Status Code

  • 200 : Indexing process has been completed.

  • 400 : Missing/invalid parameters.

  • 403 : The user has no permission to perform indexing.

Content-Type

  • application/json

Required Access Rights

The logged in user, API Key or access token must have either the following role or right.

  • Role : FILE_STORAGE_ADMIN

  • Right : FILE_STORAGE_INDEXING
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen