18.5    Commenting Documents

In addition to discussions seen before, since SAP BusinessObjects BI 4.2, Web Intelligence includes the ability to add comments to documents. Compared to the discussions whose granularity is the document, comments allow you to drill into the comment and directly comment the document content.

This ability requires your administrator to set up an external database, where the comments are stored. By default, this comment database is the audit database, but your administrator can change it in the CMC.

When you open a document, Web Intelligence checks in the database if comments exist for this document. If this is the case, these comments are retrieved so you can see them when the document is displayed in Web Intelligence.

There are two types of comments:

• Document comment, which is integrated in the document itself.
  You need to be in Design mode to add a document comment, since you are modifying the document structure. This comment is added in the document through a new cell type containing the text comment. As for any cell (see Chapter 5, Section 5.4), you can modify its properties—size, position, background color, font, and so on—to define how the comment must look in the document.
  When you print the document, the cell and the comment it contains are printed as well.
• Block or cell comment, which is created on top of an existing cell or block and associated with it.
  This comment does not modify the document and you can add these comments in Reading or Design mode. It is not displayed in the document but an icon shows that the cell or block has been commented. When you hover your mouse on this icon, a pop-up message with the comment appears, as seen in Figure 18.11.

Figure 18.11    Comment Added on a Cell and Displayed When Hovering the Mouse

These comments are contextual, meaning they are associated with the data in the commented cell or block. When you refresh the document, if the data is no longer in the data set, the comment is not available. If the data is back after a new refresh, then the comment becomes available again.

As the comments rely on a service provided by the BI platform, they are not available in Web Intelligence standalone or offline modes:

• In these modes, it is not possible to add a new comment.
• If a document has already been commented, its comments are not displayed in offline mode.

When you save a document under a different name, this creates a copy of the document. Its comment are not saved in this copy by default. In the Save Document dialog box, if you select the Save document with comments option, these comments are duplicated in the comments database for this new document and are hence also available for it.

18.5.1    Adding Comments

To comment a document, you must have first saved the document in the BI Platform repository, since the comments are identified through the ID of the document in the comment database. Then, the steps to follow depend on the comment type to add, as well as whether you are creating a new comment or answering an existing one, as described in the next sections.

Document Comment

To add a comment in the document, follow these steps:

1. In Design mode, in the Report Elements toolbar, select the Comment • Insert Comment Cell button or the Cell • Pre-Defined • Comment command.
2. Click the report at the desired location to position your comment. (You can exit this insert mode by pressing the (Escape) key.)
   You can also add the cell for the comment by right-clicking in the report and, in the contextual menu, selecting the Insert • Comment command.
3. If it was not yet open, the Comments side panel opens.
4. Type your text into the Comment on the selected item text field.
5. Click OK to validate it. Your text is displayed in the comment cell, as shown in Figure 18.12.
6. Save your document to keep this document’s change.

Figure 18.12    Comment Inserted in a Document

Cell or Block Comment

To add a comment on a cell or a block, follow these steps:

1. In Reading or Design mode, right-click the cell or the block to comment.
2. In the contextual menu, select the Comment command.
3. If it was not yet open, the Comments side panel opens.
4. Type your text into the Comment on the selected item text field.
5. Click OK to validate it.
6. The comment is then saved in the comment database. An icon ( or ) is displayed on the top-right of the cell or the block to highlight it. Hovering the mouse over this cell or block opens a window to show this comment, as seen in Figure 18.11.

There is no need to save the document since the comment is saved in the comment database and the document itself is not modified.

Replying to Comment

A document, block, or cell comment can be seen as a discussion where several users can exchange. This is done by replying after the last posted message; the last reply is added to the end of the discussion. To reply to a comment, follow these steps:

1. In Reading or Design mode, go to the Comments side panel.
2. In your report, select a document comment or a commented cell or block. In the Comments side panel, the comment is displayed, and under it, is a new text field, Add a comment.
3. In this text field, type another message to answer the previous comment. This new text is added to the comment thread, as seen in Figure 18.13.
4. In Web Intelligence document property (see Chapter 2, Section 2.6), the Comment displayed in the Report Comment property defines which message of the thread must be displayed in the comment and shown in the report.
   • If it is set to The last comment in the thread, which is the default value, then the last message is displayed in the comment.
   • Otherwise, if it is set to The first comment in the thread, then the first message of the thread will always be displayed in the comment.

Figure 18.13    Discussion through Comments

Document Comment

Although you must to be in Design mode to add a document comment, this is not the case to reply to a document, block, or cell comment. You can be either in Reading or Design mode.

Through this comment mechanism, several people can exchange document content and read this discussion in the Comments side panel. As described in next section, this side panel has also some more general purposes.

18.5.2    Managing Comments

In the Comments side panel, you can read and add comments, as well as manage them:

• You can delete a specific message in the thread by clicking the Delete Comment icon beside the message to delete.
• On top of the side panel, you can click Copy all to open a dialog box containing the whole thread in text format. You can copy it completely or only partly in the clipboard and paste it in another application.
• You can edit a comment by clicking it and modifying its text. Click OK to confirm the change.

18.5.3    Comments Function

To enforce comments, a new function, Comment, has been introduced in Web Intelligence language formula (see Chapter 11, Section 11.2). When you add a comment through a predefined cell, its text is saved in the comment database. The cell contains only a call to this function that retrieves the text from the database and displays it in the cell. The returned text is the first or the last comment, depending on the value of the Comment displayed in the Report option you selected for the document (Section 18.5.1).

Annotating Tables

This function can be used to annotate a table. In Design mode, add a column to your table. In its definition, simply add =Comment() then save your document. Now, in Reading mode, any user can select a cell in this extra column and type a comment. The comment will then be displayed in the table, as seen in Figure 18.14.

Figure 18.14    Additional Column to Display Cell Comments

In the comment database, comments are saved with the document CUID and a path that identifies the commented cell or block. The table containing the comments has four extra columns you can customize for your own use if you have access to the comments database and the right to write in it:

• These column names are OptionKey1, OptionKey2, ..., OptionKey4.
• You can fill the column cell with any content and assign a value for each comment. Setting these values can be done programmatically through another application.

You can use these columns to define a conditional display through two optional arguments this function supports:

Comment("ColumnName";"Text"), where:

• "ColumnName" is the name of one of the four extra columns.
• "Text" is the string to check in this column for this comment.

The function returns and displays the text in the cell, only if the string "Text" is found in the extra column "ColumnName".

Comments Conditional Display

Comment("OptionKey1";"Yes") displays the comment only if the text "Yes" is found in the column "OptionKey1". Comment() always displays the comment.

This conditional display requires you to access and write into the database. But it offers powerful capabilities to implement workflows around documents with the comments.