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.
Add Comment to Policyassertion 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).
Using the Assertion
- 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.
- When adding the assertion, the Comment Properties automatically appear; when modifying the assertion, right-clickCommentin the policy window and selectComment Propertiesor double-click the assertion in the policy window. The assertion properties are displayed.
- 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.
- 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.
If your comments are not visible in the policy window, click [Show Comments] in the Policy Tool Bar.
To add a comment to an assertion or folder:
- In the policy window, right-click the assertion or folder and then select Add Comment. The Enter Comment dialog is displayed.
- Type your comments in the "Left" and "Right" boxes:
- Left Commentwill appear before the item, left-aligned in the policy window. The maximum for this comment is 100 characters.
- Right Commentwill appear after the item, right-aligned in the policy window. The maximum for this comment is 4000 characters.
- 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.
- Click [OK]. The comment is displayed next to the assertion or folder in the policy window, unless comments have been hidden.
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:
- Right-click the assertion or folder and selectEdit Comment.
- 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 selectDelete 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 selectDelete 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.