Extend the Document Store of Analytical Cell Comments by Developer Extensibility

[Scott_Li_]

This blog explains how to extend the Document Store by developer extensibility in Embedded Steampunk of S4 Public Cloud. The following contents are covered:

• Introduction of cell commenting feature and Document Store. 
• Prerequisites of Document Store developer extensibility.
• Extend Document Store by developer extensibility.

1. Introduction of Cell Commenting Feature and Document Store 

In some Review Booklet and Multidimensional Analysis  (MDA) Apps, users might see a “comment” button in the side panel and then users can add comments on a data cell of the grid through the comments side panel. This feature is called Cell Commenting, as shown in the following figure: 

To enable the Cell Commenting feature the analytical cube and query must be enabled with Document Store which stores the context of the cell, including the fixed filters in the filter bar, the dynamic filters and the selected dimensions on row and column.

Document Store consists of two artifacts:

• Document Store Table: a database table to store the cell context.
• Document Store CDS View: a special category of CDS view which selects from the Document Store Table and has annotation @analytics.dataCategory: #DOCSTORE.

The fields in the Document Store are pure technical fields related to the dimensions of the cube. A dimension in cube can have maximum 6 related fields as following: 

Naming Rule	Meaning	Data Type
TRA_*	Transient Characteristic	The same data type as the dimension
SVA_*	Single Character Variable	Char(1)
SVH_*	Single Variable for Hierarchy	Char(1)
HIO_*	Hierarchy Object	Char(30)
HNM_*	Hierarchy Name	Char(30)
HNO_*	Hierarchy Node Object	Char(23)

*: could be the same field name in cube, for example TRA_COMPANYCODE, or a number. The maximum length of the field name in the Document Store is 18, so when the length of cube field name plus the prefix(TRA_, SVA_, ...) exceeds the maximum, a number should be used instead, for example TRA_00001, TRA_00002. Just make sure the field name is unique in the table.

The enablement of Document Store for analytical cube and query include:

• The Document Store is created for the analical cube view.
• The analytical cube view is associated to the Document Store CDS view and the association is exposed.
• The analytical query view contain the Document Store association exposed in cube view. 

For SAP delivered Review Booklets or Multidimensional Analysis applications, if the commenting feature is enabled the above steps have already been done. 

2. Prerequisites of Document Store Developer Extensibility 

When a document store enabled cube is extended with a new dimension field by developer extensibility or key user extensibility, the document store will not be extended automatically. In this situation, this new extended field cannot support Cell Commenting. It means if the new dimension is used in the report layout(added in the row or column) or the filter, an error will be raised when you try to create a comment on the cell. Nevertheless, if the new dimension is not used in the report layout or filter, the cell commenting is not impacted, and you can still add comments for the data cells. 

Please be known that if you extend the cube and query with a measure type field, extension is not needed on the Document Store. Only new added dimension fields need the extension in Document Store accordingly. 

There are some prerequisites to extend the Document Store by developer extensibility: 

• The Document Table and Document CDS View must be C0 released for ‘Use in Cloud Development’.
• The Document Table should have some extensibility annotations which start with ‘@AbapCatalog.enhancement’. 
• The Document CDS View should also have the extensibility annotations which start with ‘@AbapCatalog.extensibility’. 

If the prerequisites are not met, please ask SAP to enable the C0 release. 

3. Extend the Document Store by Developoer Extensibility

When you have extended the cube with a dimension field, either by developer extensibility or key user extensibility, and want to extend the document store, please follow the steps below. 

3.1 Find Dimention Type

• Open "Relation Explorer" in ABAP Developer Tool (in the cube right click and select 'Show In→ Relation Explorer) 

• Check the details on the new-added dimension on the right side, please pay attention to the text in the “[ ]”, it means which kind of dimension it is.  

Ralation Explorer

[Hier] means the dimension has a foreign key association and the association target has hierarchy assocation.

For every new extended dimension field, two types of fields need to be added in the Document CDS View. They are denoted by: 

                  @analytics.document.type: #TRA  

                  @analytics.document.type: #SVA

If the extended dimension has [Hier], four additional fields need to be added in the Document Store CDS View. They are denoted by:

                  @analytics.document.type: #SVH 

                  @analytics.document.type: #HIO  

                  @analytics.document.type: #HNM 

                  @analytics.document.type: #HNO  

As said above, the TRA field should have the same data type as the field in the cube. For key user extensibility case, you can find the data type of new extended dimension in the following way: open the cube view in ADT, and put the cursor on the name of the cube, then press F2 you will see the information of the cube, as the following figure shows:

3.2 Extend the Document Store Table

 Assume a new dimension field PostingLevel_2 has been extended in the cube view. It has a foreign key association I_CnsldtnPostingLevel which has a hierarchy association _PostgLevelHierNode, then 6 fields need to be extended in the document store table and document store CDS view respectively. 

To extend the Document Table, in the ADT of your Embedded Steampunk development system, right click the package, select New -> Other ABAP Repository Object->Structure. Give the name and description, then you can create the structure (which is actually a structure extension). Assume the Document Store table name is ‘test_doc_store_tab’, then a new structure extension would be created with the name  ‘test_doc_store_ext” as the following code: 

extend type test_doc_store_tab with test_doc_store_ext { 
  tra_00062_dcu        : fc_plevl; 
  sva_00062_dcu        : abap.char(1); 
  svh_00062_dcu        : abap.char(1); 
  hnm_00062_dcu        : abap.char(30); 
  hno_00062_dcu        : abap.char(32); 
  hio_00062_dcu        : abap.char(30); 
} 

You can also use template ‘appendStructure’ to create the skeleton of the code. 

A correct suffix should be added for the fields according to the definition of annotation @AbapCatalog.enhancement.fieldSuffix  in the Document Store Table. Here ‘dcu’ is used as an example. You should also add prefix before the name for customer development as normal. 

As the length of field name “PostingLevel_2” is more than 13, a unique number should be used instead, normally we are using the existing max number plus 1 to get the number. If the field name is short than 13, please use the field name directly, for example sva_glaccount. 

For field TRA_* the data type should be the same as the field in the cube, so here TRA_00062 uses fc_plevl. 

3.3 Extend the Document Store CDS View

Similarly, 6 fields should be added in the Document CDS View. In ADT, right click the package, select New-> Other ABAP Repository Object ->Data Definition. Write the code as following: 

extend view entity I_CDS_TST_SO_HEADER_CUBEDST with { 
  @analytics.document:{ type: #TRA , reference: 'PostingLevel_2' } 
  Persistence.tra_0062_dcu as tra_0062_dcu, 

  @analytics.document:{ type: #SVA , reference: 'PostingLevel_2' } 
  Persistence.sva_0062_dcu as sva_0062_dcu, 

  @analytics.document:{ type: #SVH , reference: 'PostingLevel_2' } 
  Persistence.svh_0062_dcu as svh_0062_dcu, 

  @analytics.document:{ type: #HNM , reference: 'PostingLevel_2' } 
  Persistence.hnm_0062_dcu as hnm_0062_dcu, 

  @analytics.document:{ type: #HNO , reference: 'PostingLevel_2' } 
  Persistence.hno_0062_dcu as hno_0062_dcu, 

  @analytics.document:{ type: #HIO , reference: 'PostingLevel_2 ' } 
  Persistence.hio_0062_dcu as hio_0062_dcu, 
} 

You can also use the template ‘extendViewEntity’ to create the skeleton of the code.  

A correct suffix should be added for the fields according to the definition of annotation @ @AbapCatalog.extensibility.elementSuffix  in the Document Store CDS View. Here ‘dcu’ is used as an example. You should also add prefix before the name for customer development as normal. 

Here ‘Persistence’ is the data source of the Document Store CDS View, that is the Document Store Table. Refer to the following example of a Document Store CDS View: 

                       

In the above example, 6 fields are added. For the simple case without hierarchy association, only two fields(TRA_* and SVA_*) are needed.

After the above stpes you will finish the developer extension of Document Store. You can verify the extesion by checking the information of the Document CDS View (press F2 on the view name). Now the users are able to add comments for the new extended dimension.

Further Links and Resources

	SAP S/4HANA Cloud Public Edition	SAP S/4HANA/SAP S/4HANA Cloud Private Edition
Review Booklets	link to help.sap.com	link to help.sap.com
Multidimensional Analysis	link to help.sap.com	link to help.sap.com
Cell Commenting	link to help.sap.com	link to help.sap.com