SDMS System

This module works only for Ontimize Boot version 3.11.0 or above. Actual release version: Ontimize Boot

Introduction

The Storage Document Management System (SDMS) is a system that allows you to manage documents related to an entity in your project. Ontimize Boot provides a DMS that allows to store files in external services according to the engine set in its configuration.

Previous concepts

  • Workspace: Represents the base folder where the documents for an entity will be stored.

Prerequisites

You can follow this tutorial using your own application, although for this example we will use an application created using the archetype that can be found on this page and with a REST service.

There are 2 options to follow this tutorial, clone the repository with the initial state and follow the tutorial step by step, or download the final example and see which files are new and which have been updated.

Initial project

/$ git clone https://github.com/ontimize/ontimize-examples 
/ontimize-examples$ cd ontimize-examples
/ontimize-examples$ git checkout boot-sdms-initial

Final example

/$ git clone https://github.com/ontimize/ontimize-examples 
/ontimize-examples$ cd ontimize-examples
/ontimize-examples$ git checkout boot-sdms

To simplify the code being written, three dots (…) may appear in some parts of the code. This indicates that there may be previous code before and after those dots.

Steps

Server

Add SDMS dependencies

/pom.xml

...
<dependencies>
  ...
  <dependency>
    <groupId>com.ontimize.jee.sdms</groupId>
    <artifactId>ontimize-jee-sdms-common</artifactId>
  </dependency>
  ...
</dependencies>
...

ws/pom.xml

...
<dependencies>
  ...
    <dependency>
        <groupId>com.ontimize.jee.sdms</groupId>
        <artifactId>ontimize-jee-sdms-rest</artifactId>
    </dependency>
  ...
</dependencies>
...

model/pom.xml

...
<dependencies>
...
  <dependency>
    <groupId>com.ontimize.jee.sdms</groupId>
    <artifactId>ontimize-jee-sdms-server</artifactId>
  </dependency>

  <dependency>
    <groupId>com.ontimize.jee.sdms</groupId>
    <artifactId>ontimize-jee-sdms-event</artifactId>
  </dependency>
...
</dependencies>
...

boot/pom.xml

...
<dependencies>
...
  <dependency>
    <groupId>com.ontimize.boot</groupId>
    <artifactId>ontimize-boot-starter-sdms</artifactId>
  </dependency>
...
</dependencies>
...

Modify application.yml

The application.yml file will be modified the engine to be used by the SDMS, for this example we will set up the S3 engine. Information on the configuration of the SDMS system in the application.yml file can be found at this link.

Currently only the S3 engine using the Amazon AWS S3 service API is available.

application.yml

ontimize:
  sdms:
    engine: s3
    s3:
      access-key: ${S3_ACCESS_KEY}
      secret-key: ${S3_SECRET_KEY}
      bucket: ${S3_BUCKET}
      region: ${S3_REGION}

Modify the entity service to add the methods of the SDMS service

All methods available by the SDMS service will be added to the service interface of our entity. Our method names are constructed with the name of the entity followed by the SDMS method name.
The SDMS methods available are:

  • SdmsFindById: It allows us to retrieve the information of an SDMS element by its ID (Base64 encrypted id).
  • SdmsFind: It allows us to retrieve the information of several elements of the SDMS from a filter.
  • SdmsDownloadById: It allows us to download an SDMS document by its ID (Base64 encrypted id)
  • SdmsDownload: It allows us to download several SDMS documents from a filter.
  • SdmsUpload: It allows us to upload a document to the SDMS.
  • SdmsCreate: It allows us to create an SDMS element in the system.
  • SdmsUpdate: It allows us to update an SDMS element in the system.
  • SdmsCopy: It allows us to copy an SDMS element in the system to another space in the SDMS.
  • SdmsMove: It allows us to move an SDMS element in the system to another space in the SDMS.
  • SdmsDeleteById: It allows us to delete an SDMS element in the system by its ID (Base64 encrypted id).
  • SdmsDelete: It allows us to delete several SDMS elements in the system from a filter.

ICandidateService.java

...
import com.ontimize.jee.sdms.common.dto.OSdmsRestDataDto;
import org.springframework.web.multipart.MultipartFile;
import java.io.Serializable;
...

public interface ICandidateService {

...

EntityResult candidateSdmsFindById( Serializable id, OSdmsRestDataDto data );
EntityResult candidateSdmsFind( OSdmsRestDataDto data );
EntityResult candidateSdmsDownloadById( Serializable id, OSdmsRestDataDto data );
EntityResult candidateSdmsDownload( OSdmsRestDataDto data );
EntityResult candidateSdmsUpload(OSdmsRestDataDto data, MultipartFile file );
EntityResult candidateSdmsCreate( OSdmsRestDataDto data );
EntityResult candidateSdmsUpdate( OSdmsRestDataDto data );
EntityResult candidateSdmsCopy( OSdmsRestDataDto data );
EntityResult candidateSdmsMove( OSdmsRestDataDto data );
EntityResult candidateSdmsDeleteById( Serializable id, OSdmsRestDataDto data );
EntityResult candidateSdmsDelete( OSdmsRestDataDto data );

...
}

Now in the implementation of the service we implement the methods with the help of the IOSdmsService component of the SDMS system and by calling the corresponding method.
We will also establish the workspace where the entity will store and manage the files. We will do this via the OSdmsWorkspace annotation which admits 2 parameters:

  • name: Sets the name of the workspace. If this parameter is not set, the value will be default.
  • value: Sets the path to the workspace, and can be set to variable between braces.

The annotation can be set at class level by enabling the workspace for all SDMS methods, and/or at method level by setting its scope to the annotated method. It can also be set as many workspaces as required.

CandidateService.java

...

import com.ontimize.jee.sdms.common.dto.OSdmsRestDataDto;
import com.ontimize.jee.sdms.common.workspace.annotation.OSdmsWorkspace;
import com.ontimize.jee.sdms.server.service.IOSdmsService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.multipart.MultipartFile;

...

@OSdmsWorkspace( "candidate/doc/{id}" )
@OSdmsWorkspace( name = "all", value = "candidate/doc" )
...
public class CandidateService implements ICandidateService {

  ...

  @Autowired
  private IOSdmsService oSdmsService;

  ...

  @Override
  public EntityResult candidateSdmsFind( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.find( data );
  }

@OSdmsWorkspace( name = "images", value = "candidate/img/{id}" )
  @Override
  public EntityResult candidateSdmsDownloadById( final Serializable id, final OSdmsRestDataDto data ) {
  	return this.oSdmsService.downloadById( id, data );
  }

  @Override
  public EntityResult candidateSdmsDownload( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.download( data );
  }

  @Override
  public EntityResult candidateSdmsUpload(final OSdmsRestDataDto data, final MultipartFile file ) {
  	return this.oSdmsService.upload( data, file );
  }

  @Override
  public EntityResult candidateSdmsCreate( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.create( data );
  }

  @Override
  public EntityResult candidateSdmsUpdate( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.update( data );
  }

  @Override
  public EntityResult candidateSdmsCopy( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.copy( data );
  }

  @Override
  public EntityResult candidateSdmsMove( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.move( data );
  }

  @Override
  public EntityResult candidateSdmsDeleteById( final Serializable id, final OSdmsRestDataDto data ) {
  	return this.oSdmsService.deleteById( id, data );
  }

  @Override
  public EntityResult candidateSdmsDelete( final OSdmsRestDataDto data ) {
  	return this.oSdmsService.delete( data );
  }

  ...

}

Modify the entity Rest controller

We modify the Rest controller of our entity so that instead of inheriting from the ORestController class, it inherits from the OSdmsRestController class. This class adds all the endpoints of the ORestController class and the SDMS endpoints, linking them with the corresponding SDMS methods that we have established in the service of our entity.

ICandidateService.java

...

import com.imatia.platform.hr.api.core.service.ICandidateService;
import com.ontimize.jee.sdms.rest.controller.OSdmsRestController;

...

public class CandidateRestController extends OSdmsRestController<ICandidateService> {

...
}

Endpoints

The endpoints set by the OSdmsRestController are the following:

If the workspace is not sent in an http request, the SDMS will set the default workspace as the active workspace. But if the default workspace has variables, you will need to pass it the workspace with the variable values to access the workspace.

Find by ID

This endpoint maps the request to the SdmsFindById method of the SDMS service.

The id of the requested document is passed in Base64 encrypted in the url and the data parameter is added with the workspace information in JSON format.

The data value must be encoded with percent-encoding to be read correctly.

GET: /candidates/candidate/sdms/find/id/Y2FuZGlkYXRlLzEvZmlsZS0wOC50eHQ=
Content-Type: multipart/form-data
Content-Disposition: form-data; name="data"; {"filter": { "workspace": "default", "data": {"id": 1}}}

Find

This endpoint maps the request to the SdmsFind method of the SDMS service.

The id of the requested document is passed in Base64 encrypted in the url and the data parameter is added with the workspace information in JSON format.

POST: /candidates/candidate/sdms/find/id
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}, "id": ["Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ=", "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="]}}

Download by ID

This endpoint maps the request to the SdmsDownloadById method of the SDMS service.

The id of the requested document is passed in Base64 encrypted in the url and the data parameter is added with the workspace information in JSON format.

The data value must be encoded with percent-encoding to be read correctly.

GET: /candidates/candidate/sdms/download/id/Y2FuZGlkYXRlLzEvZmlsZS0wOC50eHQ=
Content-Type: multipart/form-data
Content-Disposition: form-data; name="data"; {"filter": { "workspace": "default", "data": {"id": 1}}}

Download

This endpoint maps the request to the SdmsDownload method of the SDMS service.

The id of the requested document is passed in Base64 encrypted in the url and the data parameter is added with the workspace information in JSON format.

POST: /candidates/candidate/sdms/download/id
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}, "id": ["Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ=", "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="]}}

Upload

This endpoint maps the request to the SdmsUpload method of the SDMS service.

The data parameter is added with the workspace information in JSON format.

The data value must be encoded with percent-encoding to be read correctly.

POST: /candidates/candidate/sdms/upload
Content-Type: multipart/form-data
Content-Disposition: form-data; name="file"; filename="/C:/cv.pdf"
Content-Disposition: form-data; name="data"; {"filter": { "workspace": "default", "data": {"id": 1}}, "data": {"id": "Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ"}}

Create

This endpoint maps the request to the SdmsCreate method of the SDMS service.

POST: /candidates/candidate/sdms/create
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}}, "data": {"id": "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="}}

Update

This endpoint maps the request to the SdmsUpdate method of the SDMS service.

PUT: /candidates/candidate/sdms/update
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}, "id": "Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ="}, "data": {"id": "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="}}

Copy

This endpoint maps the request to the SdmsCopy method of the SDMS service.

PUT: /candidates/candidate/sdms/copy
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}, "id": "Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ="}, "data": {"id": "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="}}

Move

This endpoint maps the request to the SdmsMove method of the SDMS service.

PUT: /candidates/candidate/sdms/move
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}, "id": "Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ="}, "data": {"id": "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="}}

Delete by ID

This endpoint maps the request to the SdmsDeleteById method of the SDMS service.

The id of the requested document is passed in Base64 encrypted in the url and the data parameter is added with the workspace information in JSON format.

The data value must be encoded with percent-encoding to be read correctly.

DELETE: /candidates/candidate/sdms/delete/id/Y2FuZGlkYXRlLzEvZmlsZS0wOC50eHQ=
Content-Type: multipart/form-data
Content-Disposition: form-data; name="data"; {"filter": { "workspace": "default", "data": {"id": 1}}}

Delete

This endpoint maps the request to the SdmsDelete method of the SDMS service.

The id of the requested document is passed in Base64 encrypted in the url and the data parameter is added with the workspace information in JSON format.

DELETE: /candidates/candidate/sdms/delete/id
Content-Type: application/json
Body: {"filter": { "workspace": "default", "data": {"id": 1}, "id": ["Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ=", "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="]}}

Request Parameters

The data parameter of the SDMS system always goes to the “filter” and “data” sections.

The “filter” section contains the parameters related to the selection of elements of the SDMS. Here you will always find the information related to the workspace you want to use.

In the “data” section are the parameters related to the information to be sent to the SDMS.

The rest of the parameters that can be sent in each of the sections will depend on the engine used.

Possible parameters in the S3 engine

  • Filter

    • workspace: The name of the workspace to use.
      example: "workspace": "default"

    • data: The variables values of the workspace.
      example: "data": "{"id": "ID-1"}" | "data": "{"id": 1}" | "data": "{"id": [1, 2, 3]}"

    • id: The S3 key of the document encoded in Base64 (several can be in an array).
      example: "id": "Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ=" | "id": ["Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ=", "Y2FuZGlkYXRlLzEvZmlsZS0wMi50eHQ="]

    • key: The S3 key of the document (several can be in an array).
      example: "key": "candidate/1/file-01.txt" | "key": ["candidate/1/file-01.txt", "candidate/1/file-02.txt"]

    • prefix: The S3 prefix of the document (several can be in an array).
      example: "prefix": "candidate/1/folder-1" | "prefix": ["candidate/1/folder-1", "candidate/1/folder-2"]

    • fileName: The S3 name of the document (several can be in an array).
      example: "fileName": "file-01.txt" | "fileName": ["file-01.txt", "file-02.txt"]

    • maxKeys: The maximum number of S3 documents to return.
      example: "maxKeys": 10

    • delimiter: The delimiter to use in the S3 documents search.
      example: "delimiter": "/"

    • marker: The marker to use in the S3 documents search.
      example: "marker": "candidate/1/file-01.txt"

  • Data

    • id: The S3 key of the document encoded in Base64.
      example: "id": "Y2FuZGlkYXRlLzEvZmlsZS0wMS50eHQ="

    • key: The S3 key of the document.
      example: "key": "candidate/1/file-01.txt"

    • prefix: The S3 prefix of the document.
      example: "prefix": "/folder-1"

    • fileName: The S3 name of the document.
      example: "fileName": "file-01.txt"

    • currentPrefix: The current S3 prefix of the document.
      example: "currentPrefix": "candidate/1/folder-1"