Add Comment to Policy Assertion

The Add Comment to Policy assertion allows you to insert a comment at any point in a policy path or within a policy folder in the policy development window. The Add Comment to Policy assertion is useful for self-documenting complex polices, especially those with nested assertions and policy folders.
gateway93
The
Add Comment to Policy
assertion allows you to insert a comment at any point in a policy path or within a policy folder in the policy development window. The Add Comment to Policy assertion is useful for self-documenting complex polices, especially those with nested assertions and policy folders.
The Add Comment to Policy assertion has no effect on the runtime processing of a policy (in other words, it returns neither a "true" nor "false" when processed).
Contents:
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the Comment Properties automatically appear; when modifying the assertion, right-click
    Comment 
    in the policy window and select
    Comment Properties
    or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Enter or edit the comment . You do not need to include the normal XML comment delimiter characters (e.g., "<!--comment text-->"), as the Policy Manager will add these for you.
  4. Click [
    OK
    ] when done. 
Working with Comments
It may be useful to annotate your policy with comments. This will make it easier for others to understand the policy logic or to assist you during policy troubleshooting.
Add a Comment
There are two different ways to add a comment to your policy:
  • Use the Add Comment to Policy assertion. This assertion can be placed anywhere in the policy and is intended for comments not specific to any assertion (for example, to document the policy logic). You can add as many of these assertions as necessary.
  • Append a comment directly to an item in the policy development window, such as an assertion, folder, or policy fragment. This method ensures that the comment remains with the item even after repositioning, copying/pasting, or exporting/importing the item.
To add a comment to an assertion or folder
:
  1. In the policy window, right-click the assertion or folder and then select Add Comment. The Enter Comment dialog is displayed. 
  2. Type your comments in the "Left" and "Right" boxes:
    1. Left Comment
      will appear before the item, left-aligned in the policy window. The maximum for this comment is 100 characters.
    2. Right Comment
      will appear after the item, right-aligned in the policy window. The maximum for this comment is 4000 characters.
  3. Here are some tips when entering comments:
    • By default, only the first 30 characters of the left comment and first 100 characters of the right comment are displayed in the policy development window. These can be changed in the Preferences.
    • Comments will be displayed in a tooltip when you hover the mouse pointer over the assertion in the policy window. This is useful to read long comments that have been truncated. 
      Exception
      : Comments are not visible if the tooltip is displaying a warning that should be resolved. For example, you might see this warning message in a tooltip: "The policy may be invalid due to warnings. The assertion might now work as configured." 
    • You can prefix the comment with any separator character but you are not required to do so. The comments will be displayed in a different font color in the policy window to make them stand out.
  4. Click [
    OK
    ]. The comment is displayed next to the assertion or folder in the policy window unless comments have been hidden.
Show a Comment
You can use Show Comment option to view the comments that are set locally or Globally.
Perform
one
of the following:
  1. Set the Show Comments Globally:
    • Navigate to 
      File
      Preferences
       in the Policy Manager.
    • Select 
      Show Comments 
      and click
       Ok.
    The show comments appear automatically for the new Policy tabs.
  2. Set the Show Comments Per Tab:
    • In the Policy Toolbar, click
      Show Comments
      .
    • Under the View menu, select 
      Show Comments 
      or 
      Hide Show Comments
      .
Edit a Comment
To edit a comment in the policy window
:
  • If the comment appears as "
    Comment
    : <
    comment text
    >", then double-click it to edit the comment.
  • If the comment is in light grey text aligned to the left or right of an assertion or folder:
    1. Right-click the assertion or folder and select
      Edit Comment
      .
    2. Modify the comment as required.
Delete a Comment
To delete a comment in the policy window
:
  • If the comment appears as "
    Comment
    : <
    comment text
    >", then right-click it and select
    Delete Assertion
    . The entire "Comment:" line is removed. For more information, see Add, Delete, Enable, Disable Assertions.
  • If the comment is in light grey text aligned to the left or right of an assertion or folder, then right-click it and select
    Delete Comment
    . The comment text is removed after confirmation.
    If both left and right comments exist, they will both be removed. If you wish to remove only one of the comments, edit the comment instead and remove the desired comment.