Enterprise GuideCommunity Edition GuideDeveloper Guide

Entities and Annotations

Entities

Entities drive Polarity. They are the text or strings that contextual information displayed for in the Overlay window. Our software recognizes Entities in any active application window on your screen.

For example, if you are interested in information that is related to the IP Address 127.0.0.1, Polarity would store the IP as an Entity. Contextual information related to the IP Address (the Entity) would be stored as a annotation. You can think of annotations as short notes or tags.

Annotations

Users can record notes about Entities, these notes are referred to as Annotations. An Annotation and its associated Entity are referred to as an Entity-Annotation pair.

For example, if Alice wants to let all her team members know that there is sensitive customer data on the server with the IP address 192.168.54.123, she would apply the annotation Sensitive Customer Data to the IP. If any of her team members ever have that IP come up on their screen they will be shown that entity and its associated annotations.

Methods for Applying Annotations

Using the Shortcut Key

To quickly annotate you can use a system-wide shortcut key to open the Apply-Annotation window. You can also highlight the text that you wish to apply the annotation to and it will populate in the Apply-Annotation window as the Entity.

Control + C + C

Some Linux applications block the use of shortcut keys.

Using the System Tray/Menu Bar

Right click on the Polarity Icon, the location varies depending on which Polarity-Client you are using.

  1. Navigate to the system tray

  2. Right click on the Polarity Icon. This will bring up the Polarity menu.

  3. From there click Annotate.

From the Main Window

When in the main Polarity application, click on the "Annotate" button in the top left of the window in the navigation bar on the left hand side.

From the Overlay Window

When in the Polarity Overlay, right click anywhere within the window and select the Annotate menu item. Additionally, users can hover their mouse pointer over an Entity's card in the Overlay window and click on the + icon that appears to open the Annotate modal.

Entering Information into the Annotate Window

If you have opened the Annotate window within the Polarity application, please ensure that you are on the Manual tab. Applying annotations via bulk annotating will be covered lower down on this page.

  1. Type 127.0.0.1 in the first form field called "Entities". This is the text/string that Polarity will look for on a user's screen.

  2. Press "Enter" or "Tab" to complete the entity.

  3. Type localhost in the second field "Annotations". This is the associated information for that Entity and creates the first Entity-Annotation pair.

  4. Select the appropriate Channel that the Entity-Annotation pair should be applied in.

  5. OPTIONAL - Click Show Additional Options and populate other fields. Here you can add a start date and end date of the information, set a confidence value, and add a comment for the Entity and Annotations you are applying.

  6. Click the "Annotate" button to apply the annotation localhost to the entity 127.0.0.1

Once applied, the system will recognize the entity 127.0.0.1 on your screen and provide any relevant information via the Polarity Overlay.

Polarity does not monitor your network traffic, it simply notifies you about `127.0.0.1` being associated with `localhost` because the text "127.0.0.1" was displayed on your screen. Polarity only recognizes content on the screen as it is updated in the active windows that it has permissions to monitor.

Editing Annotations

Users who have added annotations can edit them by clicking on the Edit annotation icon that appears to the right of the annotation in the Overlay Window.

Annotations can also be edited from the Configure Polarity Window:

  1. Navigate to Explorer.

  2. Search for the annotation to be edited.

  3. Click on on the Edit annotation icon that appears to the right of the entity that the annotation is paired with.

URL Annotations

You can also create clickable URL annotations that will open in your default browser when clicked. The annotation must start with https:// or http:// in order for it to be linkable.

To navigate to the URL, just click the annotation and you will be presented with a dialog box asking you to confirm.

Bulk Annotating CSV Format

Polarity allows you to import multiple Entity-Annotation pairs through its Comma Separated Value (CSV) importer function in Polarity-Client and Polarity-Web.

To use the Import Annotations functionality, open the Annotate modal from within the Polarity-Client, Polarity-Web or by using the annotation keyboard shortcut, and click on the Import Annotations (CSV)tab which is located in the top right of the Annotate modal.

Polarity will treat the first column of your CSV as the Entity and all proceeding columns as Annotations to that entity.

For example, a CSV that looks like this:

"My Entity", "annotation1", "annotation2"
"Another Entity", "annotation3"

Will result in the following Entity-Annotation pairs being imported:

My Entity -> annotation1
My Entity -> annotation2
Another Entity -> annotation3

How to Upload a CSV

  1. Click the "Click to select your file" button.

  2. Select a CSV from your computer's file system.

  3. Select the appropriate box if the CSV has a "Header Row" and/or if the system should "Skip Invalid Annotations" or "Skip Invalid Entities"

  4. Select the appropriate channel that the entities and annotations will apply to.

  5. Once you have selected the appropriate channel click the "Annotate" button in the bottom right corner.

Additional CSV options

  • You can set a Start Date of Information (DOI) and End DOI to represent the time frame that the Entity-Annotation pair is valid. (Note that Entity-Annotation pairs are not removed after the End DOI has passed).

  • You can apply a confidence value to all Entity-Annotation pairs imported by the CSV importer.

  • You can add a comment to all Entity-Annotation pairs imported through the CSV loader.

Deleting Annotations

To delete an Annotation from the Configure Polarity Window:

  1. From the Explore section of Polarity-Web or Polarity-Client, select one or more Entities or Annotations, then click on the Remove Entity or Remove Annotation button.

  2. A Remove Annotations modal will appear prompting you to delete the selected Entities or Annotations.

  3. To completely delete them from Polarity, click the Delete Annotations button.

To delete an Annotation from the Overlay Window:

  1. Click on the Edit annotation icon that appears to the right of the annotation in the Overlay Window.

  2. Click the Delete button on the Edit annotation page that appears.

Deleting an Entity or Annotation will remove all Entity-Annotation relationships for the deleted Annotation.

Ignoring Entities and Annotations

If you no longer want Polarity to return information about a specific entity you can ignore it.

To ignore an entity from the Polarity Overlay, click on the clear button located at the top right corner of the entity card and then select YES when presented with the confirmation question.

Entities can also be ignored from the Explorer page and the Ignore Manager page.

Voting

To allow better communication between team members on annotations and entities Polarity allows you to up-vote and down-vote Entity-Annotation pairs. Voting can be done from the Explorer page or from the Overlay window.

Up-Voting

To up-vote an Annotation for a specific Entity click on the Up-Vote button in the right Entity-Annotation details panel of the Explorer page.

The number that is displayed indicates the amount of up-votes that the Annotation has already received by other users.

Down-Voting

To down-vote an annotation for a specific entity click on the Down-Vote button in the right Entity-Annotation details panel of the Explore interface.

The number that is displayed indicates the amount of down-votes that the annotation has already received by other users.

See Voting from the Overlay for more info.

Commenting

Users have the option to comment on Entities and Annotations. Commenting can be done either from the Explorer page or from the Overlay Window.

To delete a comment:

  1. Right click on the hamburger menu to the right of the desired comment

  2. Click delete

  3. Click delete comment on the confirmation screen that pops up.

Comments can be edited from either from the Explorer page or from the Overlay Window but can only be deleted from within the Overlay Window.

The commenting text editor supports markdown.

PreviousOverlay WindowNextChannels

Last updated