Entities and Annotations

Entities

Entities drive Polarity.  They are the text or strings that contextual information displayed for in the Overlay window.  Entities may also be thought of as “selectors” or “indicators”.

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 could store the IP as an Entity, with contextual information related to the IP stored as an annotation.  

Annotations

Think of Annotations as short notes or tags.  Users record notes about Entities, and 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 can apply the Annotation Sensitive Customer Data to the IP address and save it in a shared Annotation Channel.  If any of her team members ever have that IP address show up on their screens, they will be shown that Entity and its associated Annotations automatically.

Note

For the Annotation to be recognized automatically, the team members must be using an automatic passive recognition mode, such as Stream or Highlight mode.

Additionally, the Annotation must be stored in a shared Annotation Channel that the other team members are subscribed to.

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.

Windows & Linux

• Control + C + C

Some Linux applications block the use of shortcut keys.

macOS

• Command + C + C

MacOS users will need to enable accessibility settings for Polarity to use 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.

Windows

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.

macOS

1. In the menu bar of macOS you will see the Polarity icon. 

2. Click on the icon to open the Polarity menu. 

3. From there click Annotate.

Linux

1. In the system tray bar of your Linux machine, you will see the Polarity icon.

2. Click on the icon to open 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 window.

Entering Information into the Annotate Window

If you have opened the Annotate window within the Polarity Desktop Client, please ensure that you are on the Manual tab.

Adding bulk Annotations is covered below.

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 saved 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.

NOTE

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 displayed in the active window 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 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 Desktop Client and Polarity Web.

To use the Import Annotations functionality, open the Annotate window from within the Polarity Desktop 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 window.

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

These additional options are only metadata and do not affect how Entities are recognized.

• Start Date of Information and End Date of Information - Represent a time frame that the Entity-Annotation pair is valid or was seen. (Selectable month, day, year, and time) (Note that Entity-Annotation pairs are not removed after the End Date of Information has passed.)

• Confidence Value - applied to all Entity-Annotation pairs imported by the CSV importer. (High, Low, or N/A)

• Comments - applied to all Entity-Annotation pairs imported through the CSV loader. (Rich text)

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.

WARNING

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.

Note

The Entity is only ignored for searches from your account.  No other user is affected.

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 number 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 number 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.