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
The system now uses the SAPUI5 default setting `![@UI.PartOfPreview]: true`, such that the table will always shown when navigating to that respective Object page.
225
229
230
+
231
+
## Modelling Samples
232
+
233
+
This chapter describes more modelling cases for further reference, from simple to complex, including but not limited to the followings.
234
+
235
+
### Specify Object ID
236
+
237
+
Use cases for Object ID annotation
238
+
239
+
#### Use Case 1: Annotate single field/multiple fields of associated table(s) as the Object ID
240
+
241
+
Modelling in `db/schema.cds`
242
+
243
+
```cds
244
+
entity Incidents : cuid, managed {
245
+
...
246
+
customer : Association to Customers;
247
+
title : String @title: 'Title';
248
+
urgency : Association to Urgency default 'M';
249
+
status : Association to Status default 'N';
250
+
...
251
+
}
252
+
253
+
```
254
+
255
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
256
+
257
+
```cds
258
+
annotate ProcessorService.Incidents with @changelog: [customer.name, urgency.code, status.criticality] {
259
+
title @changelog;
260
+
}
261
+
262
+
```
263
+
264
+
265
+
266
+
#### Use Case 2: Annotate single field/multiple fields of project customized types as the Object ID
267
+
268
+
Modelling in `db/schema.cds`
269
+
270
+
```cds
271
+
entity Incidents : cuid, managed {
272
+
...
273
+
customer : Association to Customers;
274
+
title : String @title: 'Title';
275
+
...
276
+
}
277
+
278
+
entity Customers : cuid, managed {
279
+
...
280
+
email : EMailAddress; // customized type
281
+
phone : PhoneNumber; // customized type
282
+
...
283
+
}
284
+
285
+
```
286
+
287
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
288
+
289
+
```cds
290
+
annotate ProcessorService.Incidents with @changelog: [customer.email, customer.phone] {
291
+
title @changelog;
292
+
}
293
+
294
+
```
295
+
296
+
297
+
298
+
#### Use Case 3: Annotate chained associated entities from the current entity as the Object ID
299
+
300
+
Modelling in `db/schema.cds`
301
+
302
+
```cds
303
+
entity Incidents : cuid, managed {
304
+
...
305
+
customer : Association to Customers;
306
+
...
307
+
}
308
+
309
+
entity Customers : cuid, managed {
310
+
...
311
+
addresses : Association to Addresses;
312
+
...
313
+
}
314
+
315
+
```
316
+
317
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
318
+
319
+
```cds
320
+
annotate ProcessorService.Incidents with @changelog: [customer.addresses.city, customer.addresses.postCode] {
> Change-tracking supports annotating chained associated entities from the current entity as object ID of current entity in case the entity in consumer applications is a pure relation table. However, the usage of chained associated entities is not recommended due to performance cost.
329
+
330
+
### Tracing Changes
331
+
332
+
Use cases for tracing changes
333
+
334
+
#### Use Case 1: Trace the changes of child nodes from the current entity and display the meaningful data from child nodes (composition relation)
335
+
336
+
Modelling in `db/schema.cds`
337
+
338
+
```cds
339
+
entity Incidents : managed, cuid {
340
+
...
341
+
title : String @title: 'Title';
342
+
conversation : Composition of many Conversation;
343
+
...
344
+
}
345
+
346
+
aspect Conversation: managed, cuid {
347
+
...
348
+
message : String;
349
+
}
350
+
351
+
```
352
+
353
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
354
+
355
+
```cds
356
+
annotate ProcessorService.Incidents with @changelog: [title] {
#### Use Case 2: Trace the changes of associated entities from the current entity and display the meaningful data from associated entities (association relation)
365
+
366
+
Modelling in `db/schema.cds`
367
+
368
+
```cds
369
+
entity Incidents : cuid, managed {
370
+
...
371
+
customer : Association to Customers;
372
+
title : String @title: 'Title';
373
+
...
374
+
}
375
+
376
+
entity Customers : cuid, managed {
377
+
...
378
+
email : EMailAddress;
379
+
...
380
+
}
381
+
382
+
```
383
+
384
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
385
+
386
+
```cds
387
+
annotate ProcessorService.Incidents with @changelog: [title] {
#### Use Case 3: Trace the changes of fields defined by project customized types and display the meaningful data
396
+
397
+
Modelling in `db/schema.cds`
398
+
399
+
```cds
400
+
type StatusType : Association to Status;
401
+
402
+
entity Incidents : cuid, managed {
403
+
...
404
+
title : String @title: 'Title';
405
+
status : StatusType default 'N';
406
+
...
407
+
}
408
+
409
+
```
410
+
411
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
412
+
413
+
```cds
414
+
annotate ProcessorService.Incidents with @changelog: [title] {
415
+
status @changelog: [status.code];
416
+
}
417
+
418
+
```
419
+
420
+
421
+
422
+
#### Use Case 4: Trace the changes of chained associated entities from the current entity and display the meaningful data from associated entities (association relation)
423
+
424
+
Modelling in `db/schema.cds`
425
+
426
+
```cds
427
+
entity Incidents : cuid, managed {
428
+
...
429
+
title : String @title: 'Title';
430
+
customer : Association to Customers;
431
+
...
432
+
}
433
+
434
+
entity Customers : cuid, managed {
435
+
...
436
+
addresses : Association to Addresses;
437
+
...
438
+
}
439
+
440
+
```
441
+
442
+
Add the following `@changelog` annotations in `srv/change-tracking.cds`
443
+
444
+
```cds
445
+
annotate ProcessorService.Incidents with @changelog: [title] {
> Change-tracking supports analyzing chained associated entities from the current entity in case the entity in consumer applications is a pure relation table. However, the usage of chained associated entities is not recommended due to performance cost.
454
+
455
+
#### Use Case 5: Trace the changes of union entity and display the meaningful data
456
+
457
+
`Payable.cds`:
458
+
459
+
```cds
460
+
entity Payables : cuid {
461
+
displayId : String;
462
+
@changelog
463
+
name : String;
464
+
cryptoAmount : Decimal;
465
+
fiatAmount : Decimal;
466
+
};
467
+
468
+
```
469
+
470
+
`Payment.cds`:
471
+
472
+
```cds
473
+
entity Payments : cuid {
474
+
displayId : String; //readable ID
475
+
@changelog
476
+
name : String;
477
+
};
478
+
479
+
```
480
+
481
+
Union entity in `BusinessTransaction.cds`:
482
+
483
+
```cds
484
+
entity BusinessTransactions as(
485
+
select from payments.Payments{
486
+
key ID,
487
+
displayId,
488
+
name,
489
+
changes : Association to many ChangeView
490
+
on changes.objectID = ID AND changes.entity = 'payments.Payments'
491
+
}
492
+
)
493
+
union all
494
+
(
495
+
select from payables.Payables {
496
+
key ID,
497
+
displayId,
498
+
name,
499
+
changes : Association to many ChangeView
500
+
on changes.objectID = ID AND changes.entity = 'payables.Payables'
501
+
}
502
+
);
503
+
504
+
```
505
+
506
+
507
+
508
+
### Don'ts
509
+
510
+
Don'ts
511
+
512
+
#### Use Case 1: Don't trace changes for field(s) with `Association to many`
513
+
514
+
```cds
515
+
entity Customers : cuid, managed {
516
+
...
517
+
incidents : Association to many Incidents on incidents.customer = $self;
518
+
}
519
+
520
+
```
521
+
522
+
The reason is that: the relationship: `Association to many` is only for modelling purpose and there is no concrete field in database table. In the above sample, there is no column for incidents in the table Customers, but there is a navigation property of incidents in Customers OData entity metadata.
523
+
524
+
#### Use Case 2: Don't trace changes for field(s) with *Unmanaged Association*
525
+
526
+
```cds
527
+
entity AggregatedBusinessTransactionData @(cds.autoexpose) : cuid {
528
+
FootprintInventory: Association to one FootprintInventories
529
+
on FootprintInventory.month = month
530
+
and FootprintInventory.year = year
531
+
and FootprintInventory.FootprintInventoryScope.ID = FootprintInventoryScope.ID;
532
+
...
533
+
}
534
+
535
+
```
536
+
537
+
The reason is that: When deploying to relational databases, Associations are mapped to foreign keys. Yet, when mapped to non-relational databases they're just references. More details could be found in [Prefer Managed Associations](https://cap.cloud.sap/docs/guides/domain-models#managed-associations). In the above sample, there is no column for FootprintInventory in the table AggregatedBusinessTransactionData, but there is a navigation property FootprintInventoryof in OData entity metadata.
538
+
539
+
#### Use Case 3: Don't trace changes for CUD on DB entity
The reason is that: Application level services are by design the only place where business logic is enforced. This by extension means, that it also is the only point where e.g. change-tracking would be enabled. The underlying method used to do change tracking is `req.diff` which is responsible to read the necessary before-image from the database, and this method is not available on DB level.
552
+
553
+
226
554
## Contributing
227
555
228
556
This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/change-tracking/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
0 commit comments