Skip to content
This repository has been archived by the owner on May 12, 2021. It is now read-only.

Document Microservice

Jump to bottom
mitozv edited this page Apr 26, 2018 · 9 revisions

Description

The Document Microservice provide an API that bridges applications developed in the OpenShift environment to the NRS Document Management System (DMS). The NRS Document Management System API specification can be viewed at NRS API Store.

The Document Microservice is deployed in the OpenShift environment and is only available to be accessed locally by applications hosted in the same OpenShift Environment.

Architecture Overview

How To Reuse

An Openshift template has been created so it will be reusable for other openshift applications that need to use the Document Management System. The following are required to be setup prior to using the template in order for the document services to function properly.

Pre-requisites

1. WebADE Setup

WebADE is used by DMS API to secure access to the API endpoints, folders and files using OAuth2. Refer to WebADE Documentation for more details.

WebADE account set-up can be done either using a SQL script or a JSON configuration. The new method is through JSON configuration. The JSON configuration needs to be built in the ISSS Jenkins build server. An example configuration is available in the DMOD project in Bitbucket of the NRS repository server.

Service Accounts - document service uses two accounts:

  • <APPLICATION_ACRONYM>_CLIENT - This account is assigned with refresh_token, client_credentials and authorization_code OAuth grants. This is the service account that is used by document-service to read documents and folders in DMS on behalf of the public users.

  • <APPLICATION_ACRONYM>_UI - This is assigned an implicit OAuth grant. This service account is used when redirecting users into the WebADE login screen. IDIR users need to be assigned an <APPLICATION_ACRONYM>_USER profile in order to have read and write access to the folders for the application.

Actions:

  • UPDATE_FILES - action to update folders and files inside the application directory. This will be used in setting up application folders in WCC.
  • READ_FILES - action to read folders and files inside the application directory.

2. Setup Folder Access in WCC

The application folder which follows the folder directory structure of /<APPLICATION_ROOT_DIRECTORY>/<APPLICATION_ACRONYM> needs to be assigned to the <APPLICATION_ACRONYM>.READ_FILES and <APPLICATION_ACRONYM>.UPDATE_FILES actions. This process should be requested by creating an RFD subtask in the NRS JIRA ticket system.

Environment Variables

The Document Microservice Template requires runtime variables to be configured inorder to function properly and to customise for the application that uses it.

  • APPLICATION_ACRONYM - the application acronym (e.g DMOD). This is used to identify the service accounts and folder structure for the applications.
  • APPLICATION_ROOT_DIRECTORY - the root directory (e.g NRS). Given NRS for the root directory and DMOD for the application acronym. The folder structure in DMS will be /NRS/DMOD. All the folders and files created for the application will be under this directory.
  • DMS_DEFAULT_DOCUMENT_VISIBILITY - this is the visibility settings that will be set for the folders and files created for the application. E.g (InternalOnly - when set to InternalOnly, the document is not available publicly until it is set to ExternallyVisible)
  • DMS_DEFAULT_OCIO_CLASSIFICATION - the default OCIO classification of the document when files and folders are initially created
  • ISSS_SERVER - the server url of the ISSS server
  • DMS_SERVICE_URI_PATH - the path of the DMS service relative to the ISSS_SERVER
  • OAUTH_ACCESS_TOKEN_URI_PATH - the path of the OAuth access token relative to the ISSS_SERVER
  • OAUTH_AUTHORIZATION_URI_PATH - the path of the OAuth Authorization URI relative to the ISSS_SERVER
  • SERVICE_CLIENT_ID - the service client id that is used for the public users. The account must be in the format <APPLICATION_ACRONYM>_CLIENT.
  • SERVICE_CLIENT_SECRET - the secret or password for the service client id

Document Microservice Endpoints

GET /api/documents

  • Description: This endpoint returns the contents, files, folders of the ROOT directory of the Application. This wraps the /folders/{folderID/browse operation of the NRS Document Management system.
  • Parameter: NONE
  • Response: JSON format - details of the content is documented in API Console - Browse Folder Endpoints

GET /api/documents/folders/{id}

  • Description: This endpoint returns the contents, files, folders of the specified folder id. This is similar to the GET /api/documents endpoint except that this will return the content of the specific folder input.
  • Parameter: id - id of the folder
  • Response: JSON format - details of the content is documented in Browse Folder Endpoints

POST /api/documents/folders

  • Description: This endpoint creates a new folder in the ROOT application directory. This wraps the /folders/{folderID} operation of the NRS Document Management system.
  • Parameter: JSON format containing the following: 
    {
    "name":"<input new folder name>"
}
  • Response: JSON format - metadata information of the folder. Documented in API Console - Post Folder Endpoint

POST /api/documents/folders/{id}

  • Description: This endpoint creates a new child folder of the specified folder id. This is similar to POST /api/documents/folders. This wraps the /folders/{folderID} operation of the NRS Document Management system.
  • Parameter: JSON format containing the following: 
    {
    "name":"<input new folder name>"
}
  • Response: JSON format - metadata information of the folder. Documented in API Console - Post Folder Endpoint

GET /api/documents/files/{id}

  • Description: This endpoint returns the metadata information of the file specified by the input id. This wraps the /files/{fileID} operation of the NRS Document Management system.
  • Parameter: id - id of the file.
  • Response: JSON format - details of the content is documented in API Console - Get File Endpoints

POST /api/documents/files/{id}

  • Description: This endpoint updates the metadata information of the file specified by the input id. Currently, it only supports file updates of the expiryDate and generalVisibility of a document. If a document is to be published, the generalVisibility need to be set or if the document is to be expired, the expiryDate has to be specified.
  • Parameter: JSON format containing the following: 
    {
   "expiryDate":"<input date string in the format yyyy/MM/dd HH:mm:ss>",
   "generalVisibility":"<set to "ExternallyVisible" to have the documents visible to everyone>"
}
  • Response:

POST /api/documents/folders/{id}/files/content

  • Description: This endpoint uploads a new file into the specified folder.
  • Parameter: file - Multipart Form Data of the file.
  • Response: JSON format - details of the file metadata are documented in API Console - Post File

PUT /api/documents/files/{id}/content

  • Description: This endpoint update the content of the file specified by the file id.
  • Parameter: file - Multipart Form Data of the file.
  • Response: JSON format - output is the same as the POST /api/documents/folders/{id}/files/content

Use Cases for the ExampleMeanApp application

Displaying files and folders

  • To display files and folders stored in the ROOT application directory, the operation GET /api/documents should be invoked.
  • If the generalVisibility of the folder and file is not "ExternallyVisible", the files and folders will only be displayed for users that belong to the DMOD_USER group.

Displaying content of the folders

  • To display the content of the folder, the operation GET /api/documents/folders/{id} where id is the folder id should be invoked.

Publishing files

  • To make the file visible for the rest of the users, the operation PUT /api/documents/files/{id} with parameter generalVisibility set to ExternallyVisible should be invoked.
Clone this wiki locally