You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+74-67Lines changed: 74 additions & 67 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,80 +33,83 @@ The `@cap-js/attachments` package is a [CDS plugin](https://cap.cloud.sap/docs/n
33
33
34
34
For a quick local development setup with in-memory storage:
35
35
36
-
- The plugin is self-configuring as described in [Package Setup](#package-setup). To enable attachments, simply add the plugin package to your project:
37
-
```sh
38
-
npm add @cap-js/attachments
39
-
```
40
-
41
-
<details>
42
-
43
-
The attachments plugin needs to be referenced in the package.json of the consuming CAP NodeJS application:
44
-
45
-
```cds
46
-
"devDependencies": {
47
-
"@cap-js/attachments": "<latest-version>",
48
-
//...
49
-
}
50
-
```
51
-
52
-
In addition, different profiles can be found in `package.json` as well, such as:
36
+
- The plugin is self-configuring as described, see the following details section. To enable attachments, simply add the plugin package to your project:
37
+
```sh
38
+
npm add @cap-js/attachments
39
+
```
40
+
41
+
<details>
42
+
The attachments plugin needs to be referenced in the package.json of the consuming CAP NodeJS application:
43
+
44
+
```cds
45
+
"devDependencies": {
46
+
"@cap-js/attachments": "<latest-version>",
47
+
// (...)
48
+
}
49
+
```
53
50
54
-
```json
55
-
"cds": {
56
-
"requires": {
57
-
//...
58
-
"[hybrid]": {
59
-
"attachments": {
60
-
"kind": "s3"
61
-
//...
51
+
In addition, different profiles can be found in `package.json` as well, such as:
52
+
53
+
```json
54
+
"cds": {
55
+
"requires": {
56
+
// (...)
57
+
"[hybrid]": {
58
+
"attachments": {
59
+
"kind": "s3"
60
+
// (...)
61
+
}
62
+
}
62
63
}
63
64
}
64
-
}
65
-
}
66
-
```
67
-
</details>
65
+
```
66
+
</details>
68
67
69
68
- To use Attachments, extend a CDS model by adding an element that refers to the pre-defined Attachments type (see [Changes in the CDS Models](#changes-in-the-cds-models) for more details):
70
-
```cds
71
-
using { Attachments } from '@cap-js/attachments';
72
69
73
-
entity Incidents {
74
-
// ...
75
-
attachments: Composition of many Attachments;
76
-
}
77
-
```
70
+
```cds
71
+
using { Attachments } from '@cap-js/attachments';
72
+
73
+
entity Incidents {
74
+
// (...)
75
+
attachments: Composition of many Attachments;
76
+
}
77
+
```
78
78
79
79
In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base application to provide a demonstration how to use this plugin. A miniature version of this app can be found within the [tests](./tests/incidents-app) directory for local testing.
80
80
81
81
For productive use, a valid object store binding is required, see [Object Stores](#object-stores) and [Storage Targets](#storage-targets).
82
82
83
-
84
83
### Local Walk-Through
85
-
With the steps above, we have successfully set up asset handling for our reference application. To test the application locally, use the following steps. For local testing, the attachments contents are stored in a local database.
84
+
85
+
With the steps above, we have successfully set up asset handling for our reference application. To test the application locally, use the following steps.
86
+
87
+
> [!NOTE]
88
+
> For local testing, the attachment objects are stored in a [local database](https://cap.cloud.sap/docs/guides/databases-sqlite).
86
89
87
90
1.**Start the server**:
88
91
89
-
-*Default* scenario (In memory database):
90
-
```sh
91
-
cds watch
92
-
```
92
+
-*Default* scenario (In memory database):
93
+
```sh
94
+
cds watch
95
+
```
93
96
94
97
2.**Navigate to the object page** of the incident `Solar panel broken`:
95
-
96
-
Go to object page for incident **Solar panel broken**
98
+
Go to object page for incident **Solar panel broken**
97
99
98
100
3. The `Attachments` type has generated an out-of-the-box Attachments table (see 1) at the bottom of the Object page:
4.**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 that file in the dedicated resource (database, S3 bucket, etc.). We demonstrate this by uploading the PDF file from [_tests/integration/content/sample.pdf_](./tests/integration/content/sample.pdf):
102
-
<imgwidth="1300"alt="Upload an attachment"style="border-radius:0.5rem;"src="etc/upload.gif">
104
+
<imgwidth="1300"alt="Upload an attachment"style="border-radius:0.5rem;"src="etc/upload.gif">
103
105
104
106
5.**Delete a file** by going into Edit mode, selecting the file, and pressing the **Delete** button above the Attachments table. Clicking the **Save** button will then delete that file from the resource (database, S3 bucket, etc.).
105
-
<imgwidth="1300"alt="Delete an attachment"style="border-radius:0.5rem;"src="etc/delete.gif">
107
+
<imgwidth="1300"alt="Delete an attachment"style="border-radius:0.5rem;"src="etc/delete.gif">
106
108
107
109
### Changes in the CDS Models
108
110
109
111
To use the aspect `Attachments` on an existing entity, the corresponding entity needs to either include attachments as an element in the model definition or be extended in a CDS file in the `srv` module. In the quick start, the former was done, adding an element to the model definition:
112
+
110
113
```cds
111
114
using { Attachments } from '@cap-js/attachments';
112
115
@@ -116,7 +119,8 @@ entity Incidents {
116
119
}
117
120
```
118
121
119
-
The entity Incidents can also be extended in the `srv` module, as seen in the following example:
122
+
The entity Incidents can also be extended in the `srv` module, as seen in the following example:
123
+
120
124
```cds
121
125
using { Attachments } from '@cap-js/attachments';
122
126
@@ -142,23 +146,23 @@ When testing locally, the plugin operates without a dedicated storage target, st
142
146
Meanwhile, with a dedicated storage target the attachment is not stored in the underlying database; instead, it is saved on the specified storage target and only a reference to the file including metadata is kept in the database, as defined in the CDS model.
143
147
144
148
For productive use, you need a valid object store binding. Currently, only the AWS S3 object store is supported.
145
-
For using an AWS S3 Object Store in BTP, you must already have an SAP Object Store service instance on an AWS landscape created. To bind it locally, follow this setup:
149
+
For using an AWS S3 Object Store in BTP, you must already have an SAP Object Store service instance on an AWS landscape created. To bind it in a hybrid setup, follow this setup:
146
150
147
151
1. Log in to Cloud Foundry:
148
152
149
-
```sh
150
-
cf login -a <CF-API> -o <ORG-NAME> -s <SPACE-NAME> --sso
151
-
```
153
+
```sh
154
+
cf login -a <CF-API> -o <ORG-NAME> -s <SPACE-NAME> --sso
155
+
```
152
156
153
157
2. To bind to the service, generate a new file _.cdsrc-private.json in the project directory by running:
Where `LocalObjectStoreName` can be any name given by the user here and `RemoteObjectStoreName` is the name of your object store instance in SAP BTP.
163
+
Where `HybridObjectStoreName` can be any name given by the user here and `RemoteObjectStoreName` is the name of your object store instance in SAP BTP.
160
164
161
-
3. To run the application locally, run the command:
165
+
3. To run the application in hybrid mode, run the command:
162
166
163
167
```bash
164
168
cds watch --profile hybrid
@@ -171,11 +175,13 @@ See [Object Stores](#object-stores) for further information on SAP Object Store.
171
175
The BTP malware scanning service is used in the `AttachmentService` to scan attachments for vulnerabilities.
172
176
173
177
For using [SAP Malware Scanning Service](https://discovery-center.cloud.sap/serviceCatalog/malware-scanning-service), you must already have a service instance which you can access. To bind it, run the following command:
By default, malware scanning is enabled for all profiles if a storage provider has been specified. You can configure malware scanning by setting:
184
+
179
185
```json
180
186
{
181
187
"cds": {
@@ -213,8 +219,8 @@ entity Incidents {
213
219
attachments: Composition of many Attachments;
214
220
}
215
221
```
216
-
In this example, the `@UI.Hidden` is set to `true`, which means the plugin will be hidden by default. You can also use dynamic expressions which are then added to the facet.
217
222
223
+
In this example, the `@UI.Hidden` is set to `true`, which means the plugin will be hidden by default. You can also use dynamic expressions which are then added to the facet.
218
224
219
225
```cds
220
226
entity Incidents {
@@ -267,13 +273,13 @@ To configure a shared object store instance, modify both the package.json files
267
273
268
274
```json
269
275
"cds": {
270
-
"requires": {
271
-
"attachments": {
272
-
"objectStore": {
273
-
"kind": "shared"
274
-
}
275
-
}
276
+
"requires": {
277
+
"attachments": {
278
+
"objectStore": {
279
+
"kind": "shared"
280
+
}
276
281
}
282
+
}
277
283
}
278
284
```
279
285
To ensure tenant identification when using a shared object store instance, the plugin prefixes attachment URLs with the tenant ID. Be sure the shared object store instance is bound to the `mtx` application module before deployment.
@@ -359,6 +365,7 @@ In addition to the field names, header information (`@UI.HeaderInfo`) are also a
359
365
## Monitoring & Logging
360
366
361
367
To configure logging for the attachments plugin, add the following configuration to the `package.json` of the consuming application:
0 commit comments