From 03a1a72d2ac996f80874610aabbee92f33004849 Mon Sep 17 00:00:00 2001 From: Rishi Kunnath <82925475+rishikunnath2747@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:54:17 +0530 Subject: [PATCH 1/9] Update readme --- README.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e0e6388..4395952 100644 --- a/README.md +++ b/README.md @@ -24,15 +24,23 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei ## Setup -In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base application, to add `Attachments` type to the CDS model. +In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base application, to add `Attachments` type to the CDS model. -> **Note:** This plugin is yet to be released. After the release, to enable SDM, simply add this self-configuring plugin package to your project using the following command: -> -> ```sh -> npm add @cap-js/sdm -> ``` +### Using the released version -Prior to release follow below steps to enable sdm plugin +1. Clone the incidents-app repository: + +```sh + git clone https://github.com/cap-js/incidents-app.git +``` + +2. Navigate to incidents-app root folder and execute the following command: + +```sh + npm add @cap-js/sdm +``` + +### Using the development version 1. Clone the incidents-app repository: @@ -60,7 +68,7 @@ Prior to release follow below steps to enable sdm plugin npm install ``` -## Use sdm +## Use @cap-js/sdm plugin **To use sdm plugin in incidents-app, create an element with an `Attachments` type.** Following the [best practice of separation of concerns](https://cap.cloud.sap/docs/guides/domain-modeling#separation-of-concerns), create a separate file _db/attachments.cds_ and paste the below content in it: From ca3900dd771c1a03944c46c1d6157b5f99170bd7 Mon Sep 17 00:00:00 2001 From: Rishi Kunnath <82925475+rishikunnath2747@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:57:17 +0530 Subject: [PATCH 2/9] Update changelog --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d8ceee0..42bcfe1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). The format is based on [Keep a Changelog](http://keepachangelog.com/). +## Version 1.0.1 + +### Fixed + +Updated the documentation + ## Version 1.0.0 ### Added From a9147904926f9ec448ec16312c59bf7519f065b6 Mon Sep 17 00:00:00 2001 From: Rishi Kunnath <82925475+rishikunnath2747@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:59:08 +0530 Subject: [PATCH 3/9] Update version --- README.md | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4395952..d08e3a8 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ In this guide, we use the [Incidents Management reference sample app](https://gi ```sh npm pack - This will generate a file with name cap-js-sdm-1.0.0.tgz + This will generate a file with name cap-js-sdm-x.y.z.tgz ``` 4. Copy the path of .tgz file generated in step 3 and in terminal navigate to incidents-app root folder and execute: diff --git a/package.json b/package.json index 8c5356e..d9de0e3 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@cap-js/sdm", "description": "CAP plugin for effortless integration of CAP applications with SAP Document Management Service.", - "version": "1.0.0", + "version": "1.0.1", "repository": "cap-js/sdm", "author": "SAP SE (https://www.sap.com)", "homepage": "https://cap.cloud.sap/", From 73f26bd91ac3651b3f4a6c5d823fffcf864933f7 Mon Sep 17 00:00:00 2001 From: Rishi Kunnath <82925475+rishikunnath2747@users.noreply.github.com> Date: Wed, 26 Jun 2024 20:29:52 +0530 Subject: [PATCH 4/9] adding testing.md --- README.md | 2 +- TESTING.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 TESTING.md diff --git a/README.md b/README.md index d08e3a8..103bbf3 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei ### Table of Contents - [Setup](#setup) -- [Use `sdm`](#use-sdm) +- [Use @cap-js/sdm plugin](#use-cap-jssdm-plugin) - [Testing the application locally](#testing-the-application-locally) - [Running the unit tests](#running-the-unit-tests) - [Support, Feedback, Contributing](#support-feedback-contributing) diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 0000000..cb3cf51 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,185 @@ +# Local testing of @cap-js/sdm plugin + +XSUAA is required to enforce authentication for any CAP Application. To test the plugin locally, follow the given steps + +## Configuring XSUAA + +1. Log in to the required space on the cloud foundry using cf cli as below: + +```sh + cf l -a +``` + +2. Go to the CAP project location and configure your app for XSUAA-based authentication: + +```sh + cds add xsuaa --for hybrid +``` + +This command creates the XSUAA configuration file xs-security.json and adds the service and required dependencies to the package.json file + +3. Make sure xsappname is configured and tenant-mode is set to dedicated in xs-security.json file: + +```sh + { + "xsappname": "bookshop-hybrid", + "tenant-mode": "dedicated", + ... + } +``` + +4. Configure the redirect URI by adding the following OAuth configuration to the xs-security.json file: + +```sh + "oauth2-configuration": { + "redirect-uris": [ + "http://localhost:5000/" + ] + } +``` + +5. Create an XSUAA service instance with this configuration: + +```sh + cf create-service xsuaa application bookshop-uaa -c xs-security.json +``` + +6. Create a service key: + +```sh + cf create-service-key bookshop-uaa bookshop-uaa-key +``` + +7. Bind to the new service key: + +```sh + cds bind -2 bookshop-uaa +``` + +8. Add an auth section containing the binding and the kind xsuaa to the .cdsrc-private.json file. + +```sh + { + "requires": { + "[hybrid]": { + "auth": { + "kind": "xsuaa", + "binding": { ... } + } + } + } + } +``` + +9. Verify if the .cds file under srv folder has + +```sh + @requires: 'authenticated-user' +``` + +10. Go to the BTP subaccount and add the required users under the Role collections. + + + + +## Running Approuter​ + +The approuter component implements the necessary authentication flow with XSUAA to let the user log in interactively. The resulting JWT token is sent to the application where it's used to enforce authorization and check the user's roles. + +1. Add approuter to the app folder of the project: + +```sh + cds add approuter +``` + +If package.json is not found create a file named package.json and add the below: + +```sh + { + "name": "approuter", + "description": "Node.js application router for CAP", + "dependencies": { + "@sap/approuter": "^14" + }, + "scripts": { + "start": "node node_modules/@sap/approuter/approuter.js" + }, + "engines": { + "node": "^12.0.0 || ^14" + } + } +``` + +2. Create a file named xs-app.json and add the below: + +```sh + { + "authenticationMethod": "route", + "logout": { + "logoutEndpoint": "/do/logout" + }, + "routes": [{ + "source": "^/(.*)$", + "target": "$1", + "authenticationType": "xsuaa", + "destination": "srv_api", + "csrfProtection": false + }] + } +``` + +3. Create default-env.json and add the following: + +```sh + { + "destinations": [ + { + "name": "srv_api", + "url": "http://localhost:4004", + "forwardAuthToken": true, + "strictSSL": false + } + ] + } +``` + +4. Create default-services.json. Fetch the xsuaa content from the VCAP_SERVICES of the CAP Application and paste the content to file default-services.json: + +```sh + { "uaa": { + + } + } +``` + +Copy this file to the root directory of our project because in the service, the JWT token needs to be validated. Here rename uaa to xsuaa: + +```sh + { "xsuaa": { + + } + } +``` + +5. Install npm packages for approuter: + +```sh + npm install --prefix app/approuter +``` + +6. In the project folder run: + +```sh + cds bind --exec -- npm start --prefix app/approuter +``` + +7. Make sure that the CAP application is running as well with the hybrid profile in another terminal: + +```sh + cds watch --profile hybrid +``` + +8. Open http://localhost:5000 in the browser which redirects to the port 4004 and the application can be accessed locally. + + + From 4fb3c62c7dea97f838943c56b8f3da7e1291ca87 Mon Sep 17 00:00:00 2001 From: Rashmi Date: Thu, 27 Jun 2024 15:45:57 +0530 Subject: [PATCH 5/9] Update TESTING.md --- TESTING.md | 83 ++++++++++++++++-------------------------------------- 1 file changed, 25 insertions(+), 58 deletions(-) diff --git a/TESTING.md b/TESTING.md index cb3cf51..332768d 100644 --- a/TESTING.md +++ b/TESTING.md @@ -1,5 +1,6 @@ # Local testing of @cap-js/sdm plugin + XSUAA is required to enforce authentication for any CAP Application. To test the plugin locally, follow the given steps ## Configuring XSUAA @@ -13,7 +14,7 @@ XSUAA is required to enforce authentication for any CAP Application. To test the 2. Go to the CAP project location and configure your app for XSUAA-based authentication: ```sh - cds add xsuaa --for hybrid + cds add xsuaa ``` This command creates the XSUAA configuration file xs-security.json and adds the service and required dependencies to the package.json file @@ -28,56 +29,26 @@ This command creates the XSUAA configuration file xs-security.json and adds the } ``` -4. Configure the redirect URI by adding the following OAuth configuration to the xs-security.json file: -```sh - "oauth2-configuration": { - "redirect-uris": [ - "http://localhost:5000/" - ] - } -``` - -5. Create an XSUAA service instance with this configuration: +4. Create an XSUAA service instance with this configuration: ```sh cf create-service xsuaa application bookshop-uaa -c xs-security.json ``` -6. Create a service key: +5. Create a service key: ```sh cf create-service-key bookshop-uaa bookshop-uaa-key ``` -7. Bind to the new service key: - -```sh - cds bind -2 bookshop-uaa -``` - -8. Add an auth section containing the binding and the kind xsuaa to the .cdsrc-private.json file. - -```sh - { - "requires": { - "[hybrid]": { - "auth": { - "kind": "xsuaa", - "binding": { ... } - } - } - } - } -``` - -9. Verify if the .cds file under srv folder has +6. Bind to the new service key: ```sh - @requires: 'authenticated-user' + cds bind --to bookshop-uaa:bookshop-uaa-key ``` -10. Go to the BTP subaccount and add the required users under the Role collections. +7. Go to the BTP subaccount and add the required users under the Role collections to allow user authentication and authorization. @@ -132,47 +103,43 @@ If package.json is not found create a file named package.json and add the below: ```sh { - "destinations": [ - { - "name": "srv_api", + "PORT": 5000, + "destinations": [ + { + "name": "srv_api", "url": "http://localhost:4004", "forwardAuthToken": true, "strictSSL": false + } + ], + "VCAP_SERVICES": { + "xsuaa": [ + { + "tags": [ + "xsuaa" + ], + "credentials": { SERVICE KEY VALUE } } ] } +} ``` -4. Create default-services.json. Fetch the xsuaa content from the VCAP_SERVICES of the CAP Application and paste the content to file default-services.json: - -```sh - { "uaa": { - - } - } -``` -Copy this file to the root directory of our project because in the service, the JWT token needs to be validated. Here rename uaa to xsuaa: - -```sh - { "xsuaa": { - - } - } -``` - -5. Install npm packages for approuter: +4. Install npm packages for approuter: ```sh npm install --prefix app/approuter ``` -6. In the project folder run: +5. In the project folder run: ```sh cds bind --exec -- npm start --prefix app/approuter ``` + + 7. Make sure that the CAP application is running as well with the hybrid profile in another terminal: ```sh From fd474959cefb20ccbd859c3b7103332c8813653b Mon Sep 17 00:00:00 2001 From: Rashmi Date: Thu, 27 Jun 2024 15:55:45 +0530 Subject: [PATCH 6/9] Update TESTING.md --- TESTING.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/TESTING.md b/TESTING.md index 332768d..8f2bf60 100644 --- a/TESTING.md +++ b/TESTING.md @@ -132,11 +132,23 @@ If package.json is not found create a file named package.json and add the below: npm install --prefix app/approuter ``` -5. In the project folder run: +## Configuring @cap-js/sdm plugin + +1. Bind to the SDM service + ```sh + cds bind sdm -2 : --kind sdm + ``` + +2. In the project folder run in one terminal window: ```sh cds bind --exec -- npm start --prefix app/approuter ``` +3. Run in another terminal window: + +```sh + cds watch --profile hybrid +``` From f2c4978b3726f4c0795323c3fa3edddbba314ad5 Mon Sep 17 00:00:00 2001 From: Rashmi Date: Thu, 27 Jun 2024 15:57:26 +0530 Subject: [PATCH 7/9] Update TESTING.md --- TESTING.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/TESTING.md b/TESTING.md index 8f2bf60..62dc4d0 100644 --- a/TESTING.md +++ b/TESTING.md @@ -132,13 +132,13 @@ If package.json is not found create a file named package.json and add the below: npm install --prefix app/approuter ``` -## Configuring @cap-js/sdm plugin +## Configuring @cap-js/sdm plugin and running the application 1. Bind to the SDM service ```sh cds bind sdm -2 : --kind sdm ``` - +This generates a new file .cdsrc-private.json in the project folder. 2. In the project folder run in one terminal window: ```sh @@ -150,15 +150,7 @@ If package.json is not found create a file named package.json and add the below: cds watch --profile hybrid ``` - - -7. Make sure that the CAP application is running as well with the hybrid profile in another terminal: - -```sh - cds watch --profile hybrid -``` - -8. Open http://localhost:5000 in the browser which redirects to the port 4004 and the application can be accessed locally. +4. Open http://localhost:5000 in the browser which redirects to the port 4004 and the application can be accessed locally. From 9a7200c9d0bb706f45929c415d1985fa62293ef5 Mon Sep 17 00:00:00 2001 From: "Yashmeet ." Date: Thu, 27 Jun 2024 16:46:09 +0530 Subject: [PATCH 8/9] Update ReadMe --- README.md | 53 +++++++++-------- example/mta.yaml | 144 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 27 deletions(-) create mode 100644 example/mta.yaml diff --git a/README.md b/README.md index 103bbf3..f10e277 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei ### Table of Contents +- [Prerequisite](#prerequisite) - [Setup](#setup) - [Use @cap-js/sdm plugin](#use-cap-jssdm-plugin) - [Testing the application locally](#testing-the-application-locally) @@ -22,11 +23,18 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei - [Code of Conduct](#code-of-conduct) - [Licensing](#licensing) +## Prerequisite +Install cds-dk globally by executing below command +```sh + npm i @sap/cds-dk -g + ``` + ## Setup -In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base application, to add `Attachments` type to the CDS model. +In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base application, to integrate SDM CAP plugin. ### Using the released version +If you want to use the released version of SDM CAP plugin follow the below steps: 1. Clone the incidents-app repository: @@ -41,6 +49,7 @@ In this guide, we use the [Incidents Management reference sample app](https://gi ``` ### Using the development version +If you want to use the version under development follow the below steps: 1. Clone the incidents-app repository: @@ -79,7 +88,7 @@ using { Attachments } from '@cap-js/sdm'; extend my.Incidents with { attachments: Composition of many Attachments } ``` -**Create a SAP Document Management Service instance and key. Using credentials from key [onboard a repository](https://help.sap.com/docs/document-management-service/sap-document-management-service/onboarding-repository) and configure the onboarded repositoryId under cds.requires in package.json** +**Create a SAP Document Management Integration Option [Service instance and key](https://help.sap.com/docs/document-management-service/sap-document-management-service/creating-service-instance-and-service-key). For Service instance use the name "sdm-di-instance". Using credentials from key [onboard a repository](https://help.sap.com/docs/document-management-service/sap-document-management-service/onboarding-repository) and configure the onboarded repositoryId under cds.requires in package.json** ``` "sdm": { @@ -89,38 +98,28 @@ extend my.Incidents with { attachments: Composition of many Attachments } } ``` -## Testing the application locally - -For using SAP Document Management Service to store attachments, use the instance-name and service-key values of SAP Document Management Service Integration Option in the below setup. +## Deploying the application -1. Install cds-dk globally +1. Log in to Cloud Foundry space: ```sh - npm i @sap/cds-dk -g + cf login -a -o -s ``` -2. Log in to Cloud Foundry space: +2. Add mta to CAP project use [_example/mta.yaml_](./example/mta.yaml) +3. Build the project by running following command from root folder of incidents-app. ```sh - cf login -a -o -s + mbt build ``` + Above step will generate .mtar file inside mta_archives folder. -3. To bind to the service continue with the steps below. - - In the project directory, you can generate a new file \_.cdsrc-private.json by running: - +4. Deploy the application ```sh - cds bind sdm -2 : --kind sdm + cf deploy mta_archives/*.mtar ``` -4. **Start the server**: - -- _Default_ scenario (In memory database): - ```sh - cds watch --profile hybrid - ``` - -5. **Navigate to the object page** of the incident `Solar panel broken`: +4. **Navigate to the object page** of the incident `Solar panel broken`: ```sh * Open http://localhost:4004 in a browser. @@ -131,19 +130,19 @@ For using SAP Document Management Service to store attachments, use the instance Or, directly navigate to [Object page for incident **Solar panel broken.**]() -6. The `Attachments` type has generated an out-of-the-box Attachments table (see 1) at the bottom of the Object page: +5. The `Attachments` type has generated an out-of-the-box Attachments table (see 1) at the bottom of the Object page: Attachments Table -7. **Upload a file** by going into Edit mode and either using the **Upload** button on the Attachments table or by drag/drop. Then click the **Save** button to have that file stored in SAP Document Management Integration Option. We demonstrate this by uploading the PDF file from [_xmpl/db/content/Solar Panel Report.pdf_](./xmpl/db/content/Solar%20Panel%20Report.pdf): +6. **Upload a file** by going into Edit mode and either using the **Upload** button on the Attachments table or by drag/drop. Then click the **Save** button to have that file stored in SAP Document Management Integration Option. We demonstrate this by uploading the PDF file from [_xmpl/db/content/Solar Panel Report.pdf_](./xmpl/db/content/Solar%20Panel%20Report.pdf): Upload an attachment -8. **Open a file** by clicking on the attachment. We demonstrate this by opening the previously uploaded PDF file: `Solar Panel Report.pdf` +7. **Open a file** by clicking on the attachment. We demonstrate this by opening the previously uploaded PDF file: `Solar Panel Report.pdf` Delete an attachment -9. **Rename a file** by going into Edit mode and setting a new name for the file in the rename box. Then click the **Save** button to have that file renamed in SAP Document Management Integration Option. We demonstrate this by renaming the previously uploaded PDF file: `Solar Panel Report.pdf` +8. **Rename a file** by going into Edit mode and setting a new name for the file in the rename box. Then click the **Save** button to have that file renamed in SAP Document Management Integration Option. We demonstrate this by renaming the previously uploaded PDF file: `Solar Panel Report.pdf` Delete an attachment -10. **Delete a file** by going into Edit mode and selecting the file(s) and by using the **Delete** button on the Attachments table. Then click the **Save** button to have that file deleted from the resource (SAP Document Management Integration Option). We demonstrate this by deleting the previously uploaded PDF file: `Solar Panel Report_2024.pdf` +9. **Delete a file** by going into Edit mode and selecting the file(s) and by using the **Delete** button on the Attachments table. Then click the **Save** button to have that file deleted from the resource (SAP Document Management Integration Option). We demonstrate this by deleting the previously uploaded PDF file: `Solar Panel Report_2024.pdf` Delete an attachment ## Running the unit tests diff --git a/example/mta.yaml b/example/mta.yaml new file mode 100644 index 0000000..9a0d877 --- /dev/null +++ b/example/mta.yaml @@ -0,0 +1,144 @@ +_schema-version: "3.1" +ID: sdmincidents +description: Extend Upload Set to Fiori Elements and utilize Document Management Service +version: 1.0.0 +modules: + - name: incidents-srv + type: nodejs + path: gen/srv + requires: + - name: sdi-hana + - name: sdm-incidents-auth + - name: sdm-di-destination + - name: sdm-di-instance + provides: + - name: srv-api + properties: + srv-url: ${default-url} + parameters: + buildpack: nodejs_buildpack + build-parameters: + builder: npm + - name: incidents-db-deployer + type: hdb + path: gen/db + requires: + - name: sdi-hana + parameters: + buildpack: nodejs_buildpack + - name: incidents-destination-content + type: com.sap.application.content + requires: + - name: srv-api + - name: sdm-incidents-auth + parameters: + service-key: + name: incidents-auth-key + - name: incidents-repo-host + parameters: + service-key: + name: incidents-repo-host-key + - name: sdm-di-destination + parameters: + content-target: true + parameters: + content: + instance: + destinations: + - Name: incidents-repo-host + ServiceInstanceName: incidents-html5-srv + ServiceKeyName: incidents-repo-host-key + sap.cloud.service: approuter + - Authentication: OAuth2UserTokenExchange + Name: sdm-incidents-auth + ServiceInstanceName: sdm-incidents-auth + ServiceKeyName: incidents-auth-key + sap.cloud.service: approuter + - Authentication: OAuth2UserTokenExchange + Name: incidents-srv + TokenServiceInstanceName: sdm-incidents-auth + TokenServiceKeyName: incidents-auth-key + URL: ~{srv-api/srv-url} + sap.cloud.service: approuter + existing_destinations_policy: update + build-parameters: + no-source: true + - name: incidents-app-content + type: com.sap.application.content + path: . + requires: + - name: incidents-repo-host + parameters: + content-target: true + build-parameters: + build-result: resources + requires: + - artifacts: + - incidents.zip + name: sdmincidents + target-path: resources/ + - name: sdmincidents + type: html5 + path: app/incidents + build-parameters: + build-result: dist + builder: custom + commands: + - npm install + - npm run build:cf + supported-platforms: [] +resources: + - name: sdi-hana + type: com.sap.xs.hdi-container + parameters: + service: hana + service-plan: hdi-shared + - name: sdm-incidents-auth + type: org.cloudfoundry.managed-service + parameters: + config: + tenant-mode: dedicated + xsappname: sdmincidents + path: ./xs-security.json + service: xsuaa + service-keys: + - name: incidents-auth-key + service-plan: application + - name: sdm-di-destination + type: org.cloudfoundry.managed-service + parameters: + config: + HTML5Runtime_enabled: true + init_data: + instance: + destinations: + - Authentication: NoAuthentication + Name: ui5 + ProxyType: Internet + Type: HTTP + URL: https://ui5.sap.com + existing_destinations_policy: update + version: 1.0.0 + service: destination + service-keys: + - name: incidents-destination-key + service-plan: lite + - name: incidents-repo-host + type: org.cloudfoundry.managed-service + parameters: + service: html5-apps-repo + service-name: incidents-html5-srv + service-plan: app-host + - name: sdm-di-instance + type: org.cloudfoundry.managed-service + parameters: + service: sdm + service-plan: standard +parameters: + deploy_mode: html5-repo + enable-parallel-deployments: true +build-parameters: + before-all: + - builder: custom + commands: + - npx cds build --production From 8a284533ccd7f1ffe88d1c5aacc1109995d32f3f Mon Sep 17 00:00:00 2001 From: "Yashmeet ." Date: Thu, 27 Jun 2024 19:27:02 +0530 Subject: [PATCH 9/9] Update ReadMe --- README.md | 60 ++++++++++-------- TESTING.md | 156 ----------------------------------------------- example/mta.yaml | 144 ------------------------------------------- 3 files changed, 33 insertions(+), 327 deletions(-) delete mode 100644 TESTING.md delete mode 100644 example/mta.yaml diff --git a/README.md b/README.md index f10e277..db50204 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei ### Table of Contents -- [Prerequisite](#prerequisite) +- [Pre-Requisites](#pre-requisites) - [Setup](#setup) - [Use @cap-js/sdm plugin](#use-cap-jssdm-plugin) - [Testing the application locally](#testing-the-application-locally) @@ -23,11 +23,12 @@ This plugin can be consumed by the CAP application deployed on BTP to store thei - [Code of Conduct](#code-of-conduct) - [Licensing](#licensing) -## Prerequisite -Install cds-dk globally by executing below command -```sh - npm i @sap/cds-dk -g - ``` +## Pre-Requisites +* Node.JS 16 or higher +* CAP Development Kit (`npm install -g @sap/cds-dk`) +* SAP Build WorkZone should be subscribed to view the HTML5Applications. +* [MTAR builder](https://www.npmjs.com/package/mbt) (`npm install -g mbt`) +* [Cloud Foundary CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html), Install cf-cli and run command `cf install-plugin multiapps`. ## Setup @@ -42,7 +43,13 @@ If you want to use the released version of SDM CAP plugin follow the below steps git clone https://github.com/cap-js/incidents-app.git ``` -2. Navigate to incidents-app root folder and execute the following command: +2. Navigate to incidents-app root folder and checkout to the branch **incidents-app-deploy**: + +```sh + git checkout incidents-app-deploy +``` + +3. Install SDM CAP plugin by executing the following command: ```sh npm add @cap-js/sdm @@ -51,27 +58,33 @@ If you want to use the released version of SDM CAP plugin follow the below steps ### Using the development version If you want to use the version under development follow the below steps: -1. Clone the incidents-app repository: +1. Clone the sdm repository: ```sh - git clone https://github.com/cap-js/incidents-app.git + git clone https://github.com/cap-js/sdm.git ``` -2. Clone the sdm repository: +2. Open terminal, navigate to sdm root folder and generate tarball: ```sh - git clone https://github.com/cap-js/sdm.git + npm pack + + This will generate a file with name cap-js-sdm-x.y.z.tgz ``` -3. Open terminal, navigate to sdm root folder and generate tarball: +3. Clone the incidents-app repository: ```sh - npm pack + git clone https://github.com/cap-js/incidents-app.git +``` - This will generate a file with name cap-js-sdm-x.y.z.tgz +4. Navigate to incidents-app root folder and checkout to the branch **incidents-app-deploy**: + +```sh + git checkout incidents-app-deploy ``` -4. Copy the path of .tgz file generated in step 3 and in terminal navigate to incidents-app root folder and execute: +5. Copy the path of .tgz file generated in step 2 and in terminal navigate to incidents-app root folder and execute: ```sh npm install @@ -106,29 +119,22 @@ extend my.Incidents with { attachments: Composition of many Attachments } cf login -a -o -s ``` -2. Add mta to CAP project use [_example/mta.yaml_](./example/mta.yaml) - -3. Build the project by running following command from root folder of incidents-app. +2. Build the project by running following command from root folder of incidents-app. ```sh mbt build ``` Above step will generate .mtar file inside mta_archives folder. -4. Deploy the application +3. Deploy the application ```sh cf deploy mta_archives/*.mtar ``` -4. **Navigate to the object page** of the incident `Solar panel broken`: - +4. Launch the application ```sh - * Open http://localhost:4004 in a browser. - * If prompted for sign-in, enter alice in username field and click on Sign In button. - * Click on /incidents/webapp under Web Applications. + * Navigate to Html5Applications menu in BTP subaccount and open the application (nsincidents v1.0.0) in a browser. * Click on incident with title Solar panel broken. - ``` - - Or, directly navigate to [Object page for incident **Solar panel broken.**]() + ``` 5. The `Attachments` type has generated an out-of-the-box Attachments table (see 1) at the bottom of the Object page: Attachments Table diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index 62dc4d0..0000000 --- a/TESTING.md +++ /dev/null @@ -1,156 +0,0 @@ -# Local testing of @cap-js/sdm plugin - - -XSUAA is required to enforce authentication for any CAP Application. To test the plugin locally, follow the given steps - -## Configuring XSUAA - -1. Log in to the required space on the cloud foundry using cf cli as below: - -```sh - cf l -a -``` - -2. Go to the CAP project location and configure your app for XSUAA-based authentication: - -```sh - cds add xsuaa -``` - -This command creates the XSUAA configuration file xs-security.json and adds the service and required dependencies to the package.json file - -3. Make sure xsappname is configured and tenant-mode is set to dedicated in xs-security.json file: - -```sh - { - "xsappname": "bookshop-hybrid", - "tenant-mode": "dedicated", - ... - } -``` - - -4. Create an XSUAA service instance with this configuration: - -```sh - cf create-service xsuaa application bookshop-uaa -c xs-security.json -``` - -5. Create a service key: - -```sh - cf create-service-key bookshop-uaa bookshop-uaa-key -``` - -6. Bind to the new service key: - -```sh - cds bind --to bookshop-uaa:bookshop-uaa-key -``` - -7. Go to the BTP subaccount and add the required users under the Role collections to allow user authentication and authorization. - - - - -## Running Approuter​ - -The approuter component implements the necessary authentication flow with XSUAA to let the user log in interactively. The resulting JWT token is sent to the application where it's used to enforce authorization and check the user's roles. - -1. Add approuter to the app folder of the project: - -```sh - cds add approuter -``` - -If package.json is not found create a file named package.json and add the below: - -```sh - { - "name": "approuter", - "description": "Node.js application router for CAP", - "dependencies": { - "@sap/approuter": "^14" - }, - "scripts": { - "start": "node node_modules/@sap/approuter/approuter.js" - }, - "engines": { - "node": "^12.0.0 || ^14" - } - } -``` - -2. Create a file named xs-app.json and add the below: - -```sh - { - "authenticationMethod": "route", - "logout": { - "logoutEndpoint": "/do/logout" - }, - "routes": [{ - "source": "^/(.*)$", - "target": "$1", - "authenticationType": "xsuaa", - "destination": "srv_api", - "csrfProtection": false - }] - } -``` - -3. Create default-env.json and add the following: - -```sh - { - "PORT": 5000, - "destinations": [ - { - "name": "srv_api", - "url": "http://localhost:4004", - "forwardAuthToken": true, - "strictSSL": false - } - ], - "VCAP_SERVICES": { - "xsuaa": [ - { - "tags": [ - "xsuaa" - ], - "credentials": { SERVICE KEY VALUE } - } - ] - } -} -``` - - -4. Install npm packages for approuter: - -```sh - npm install --prefix app/approuter -``` - -## Configuring @cap-js/sdm plugin and running the application - -1. Bind to the SDM service - ```sh - cds bind sdm -2 : --kind sdm - ``` -This generates a new file .cdsrc-private.json in the project folder. -2. In the project folder run in one terminal window: - -```sh - cds bind --exec -- npm start --prefix app/approuter -``` -3. Run in another terminal window: - -```sh - cds watch --profile hybrid -``` - -4. Open http://localhost:5000 in the browser which redirects to the port 4004 and the application can be accessed locally. - - - diff --git a/example/mta.yaml b/example/mta.yaml deleted file mode 100644 index 9a0d877..0000000 --- a/example/mta.yaml +++ /dev/null @@ -1,144 +0,0 @@ -_schema-version: "3.1" -ID: sdmincidents -description: Extend Upload Set to Fiori Elements and utilize Document Management Service -version: 1.0.0 -modules: - - name: incidents-srv - type: nodejs - path: gen/srv - requires: - - name: sdi-hana - - name: sdm-incidents-auth - - name: sdm-di-destination - - name: sdm-di-instance - provides: - - name: srv-api - properties: - srv-url: ${default-url} - parameters: - buildpack: nodejs_buildpack - build-parameters: - builder: npm - - name: incidents-db-deployer - type: hdb - path: gen/db - requires: - - name: sdi-hana - parameters: - buildpack: nodejs_buildpack - - name: incidents-destination-content - type: com.sap.application.content - requires: - - name: srv-api - - name: sdm-incidents-auth - parameters: - service-key: - name: incidents-auth-key - - name: incidents-repo-host - parameters: - service-key: - name: incidents-repo-host-key - - name: sdm-di-destination - parameters: - content-target: true - parameters: - content: - instance: - destinations: - - Name: incidents-repo-host - ServiceInstanceName: incidents-html5-srv - ServiceKeyName: incidents-repo-host-key - sap.cloud.service: approuter - - Authentication: OAuth2UserTokenExchange - Name: sdm-incidents-auth - ServiceInstanceName: sdm-incidents-auth - ServiceKeyName: incidents-auth-key - sap.cloud.service: approuter - - Authentication: OAuth2UserTokenExchange - Name: incidents-srv - TokenServiceInstanceName: sdm-incidents-auth - TokenServiceKeyName: incidents-auth-key - URL: ~{srv-api/srv-url} - sap.cloud.service: approuter - existing_destinations_policy: update - build-parameters: - no-source: true - - name: incidents-app-content - type: com.sap.application.content - path: . - requires: - - name: incidents-repo-host - parameters: - content-target: true - build-parameters: - build-result: resources - requires: - - artifacts: - - incidents.zip - name: sdmincidents - target-path: resources/ - - name: sdmincidents - type: html5 - path: app/incidents - build-parameters: - build-result: dist - builder: custom - commands: - - npm install - - npm run build:cf - supported-platforms: [] -resources: - - name: sdi-hana - type: com.sap.xs.hdi-container - parameters: - service: hana - service-plan: hdi-shared - - name: sdm-incidents-auth - type: org.cloudfoundry.managed-service - parameters: - config: - tenant-mode: dedicated - xsappname: sdmincidents - path: ./xs-security.json - service: xsuaa - service-keys: - - name: incidents-auth-key - service-plan: application - - name: sdm-di-destination - type: org.cloudfoundry.managed-service - parameters: - config: - HTML5Runtime_enabled: true - init_data: - instance: - destinations: - - Authentication: NoAuthentication - Name: ui5 - ProxyType: Internet - Type: HTTP - URL: https://ui5.sap.com - existing_destinations_policy: update - version: 1.0.0 - service: destination - service-keys: - - name: incidents-destination-key - service-plan: lite - - name: incidents-repo-host - type: org.cloudfoundry.managed-service - parameters: - service: html5-apps-repo - service-name: incidents-html5-srv - service-plan: app-host - - name: sdm-di-instance - type: org.cloudfoundry.managed-service - parameters: - service: sdm - service-plan: standard -parameters: - deploy_mode: html5-repo - enable-parallel-deployments: true -build-parameters: - before-all: - - builder: custom - commands: - - npx cds build --production