Integrations
Last updated
Last updated
Polarity integrations connect to third-party data sources and provide real-time awareness of information relevant to recognized entities.
You can access Integrations by navigating to the Integrations page located in the navigation menu on the left side of Polarity.
To navigate to the Integrations page:
Right click on the Polarity icon in the system tray / macOs menu bar
Click the Configure Polarity button.
Select Integrations from under the Advanced Settings menu.
Alternatively, Integrations can be accessed via the Subscriptions page of the Overlay Window.
Go HERE to see all the integrations that Polarity currently provides.
On the integrations page you will see all integrations that your Polarity admin has installed on your server and that you have access to.
Each integration row contains the following information and actions:
Integration Name -The integration name is color coordinated with the color that you have selected for the integration.
Integration Description - Brief description of what the integration does.
Color Picker & Identifier - The Color picker allows you to select a color to represent the integration. An abbreviated version of the integration name is used as an identifier. This same abbreviation is displayed in the Polarity Overlay along with the chosen color.
Subscription Status -This toggle represents subscription status and allows to you subscribe/unsubscribe from an integration by clicking on it.
As with Channels, you can subscribe to and unsubscribe from integrations by toggling the On/Off subscribe button on the Integration page.
You can also edit the subscription status directly from the Polarity Overlay. To do this:
Open the Polarity Overlay and click on the Configure gear icon.
You will now be on the Integrations tab of the Subscriptions page.
Click the ON/OFF toggle of the desired integration(s).
If you are unsubscribed from an integration you will not receive information from it.
If the integration has been stopped by a Polarity admin then its row will be blocked out. You will not receive notifications from a stopped integration even if you are subscribed to it.
Below is a an example of how a stopped integration would appear on the Integrations page:
On the integrations page, you can filter integrations by name using the filter text field at the top of the integrations page to input your search query.
You can also use the quick filter to filter out integrations:
My Subscribed Integrations - Displays integrations you are subscribed to.
Running Integrations - Displays all integrations that are running.
Integrations with Errors - Displays integrations which have returned errors.
The color set for an integration will be the color displayed for its notifications that show up in the Polarity Overlay or onscreen highlights.
Select the appropriate color from the drop down menu to change the Integration color.
You can also change an Integration's colors directly from the Integrations tab on the Settings page of the Polarity Overlay.
Some Integrations require specific configurations such as an API Key, a Username/Password, or a hostname/URL.
Certain Integration settings can only be viewed or edited by your Admin or an Integration Manager.
To configure an integration, navigate to the integrations page and click on the Settings button for the appropriate integration.
Once you have made the necessary configurations, click the Apply Changes button in the top right to save the changes.
Required options can vary depending on the integration. If an integration is missing required options, you cannot be subscribed to the integration.
Certain Integration settings can only be viewed or edited by your Admin or an Integration Manager.
Each integration has unique options that have built-in permissions which can be set by an admin or integration manager. Each option has the following permission settings:
Only admins can view and edit - Non-admin users won't see the option but will inherit the option value set by the Polarity Admin. For example, if the integration option is "API Key" and an admin has set the permission level to "Only admins can view and edit", each user will use the "API Key" value set by the admin but will not be able to see that API key value.
User can view only - Non-admin users will see the option and its value, but the value will not be editable by the non-admin user. All users will inherit the option value set by the Polarity Admin. For example, if the integration option is "API Key" and an admin has set the permission level to "Users can view only", each user will use the "API Key" value set by the admin and will be able to see what that API key value is.
User can view and edit - Non-admin users will be able to see the option and set its value. Each user will have their own option value. For example, if the integration option is "API Key" and an admin has set the permission level to "User can view and edit", then each user will be required to input their own API Key and will not share an API key with other users.
Once you are done making changes, ensure that you click the Apply Changes button to save any changes made.
If you set the Integration Option permission so that a user can view the value, they will be able to view values including passwords.
This feature can be used for integrations that have API key request limits or integrations that take a while to execute searches. On-Demand integrations are searched when using web search, searching from the Overlay Window search bar, using the On-Demand shortcut key, or using Polarity Focus Mode.
Admins or integration managers can specify if an integration only looks up data when an On-Demand lookup has occurred by setting the integration to On-Demand Only mode. (i.e. the "Search my clipboard" feature). Entities for an Integration that have been set to On-demand only will not be recognized unless an On-demand search is run on them.
To enable On Demand Only, navigate to the integration options page and select the On Demand checkbox.
On the integration page, users will see the below view if an integration has been set to On-Demand only.
You must be subscribed to an on-demand integration to have it searched when using any on-demand search modes.
See Polarity Recognition Modes for more information about the On-Demand mode.
Polarity displays integration error information to admins for troubleshooting purposes. By default, the last 10 errors are logged for an integration. Admins can clear errors by clicking on the Clear Error button.
Log information can be viewed within the settings for an integration under the 'Errors' tab. Most errors will not cause the integration to stop running but if a fatal error occurs the following banner will be shown at the top of the integration settings page:
Integration errors includes errors from all users.
Admins can Stop, Start, and Restart integrations server wide by navigating to the Actions link in the top right-hand corner of an integration's settings page.
Integrations have built-in integration specific caches to help improve integration performance and reduce the number of lookups being made to an external data source.
The cache settings operate on a per-integration basis and can be accessed by clicking on the Cache tab on the Integration settings page.
All cached entities for an integration can be cleared by clicking on the Reset Cache button located in the cache tab of an integration's settings page.
From there you will be presented with the following cache options:
Enable or Disable Cache - Turns on or off the cache for an integration. Turning off the cache while running in a production environment is not recommended. However, turning off the cache while developing an integration is recommended.
Per User Cache - If enabled, each user will have their own cache for an integration. If disabled, all users will share the same cache.
Disabling "Per User Cache" allows users to see other user's cached results. However, there may be cases where you don't want users sharing cache information (e.g., users have access to different data) in which case you should enable "Per User Cache".
Note that the cache must be enabled for this setting to have an affect.
Cache Time to Live - Specifies how long an item will live in the cache in seconds.
Cache Miss Time to Live - Specifies how long a cache miss should be cached in seconds. A cache miss is when the integration attempts to look up information on an entity but there are no results. Caching the miss means that future lookups will not need to query the integration if the entity in question has already been looked up and no data was found.
Cache Lookup Misses - If checked, the cache will keep track of entities that had no results. The should be enabled to improve integration performance.
Cache Compression - If checked, the the cache will compress stored data. This setting is recommended if the integration returns large amounts of data. Enabling this saves memory but at the cost of CPU usage since data needs to be to compressed and decompressed.
Users can manage which entity types an integration receives.
For example, even if an integration supports recognition for IPv4 and Emails you can set it to only receive IPv4 addresses using the Manage Integration Data option.
This option is only available if your admin has not locked it for that integration.
The types of data an integration can receive is dependent on the integration itself.
To manage integration data:
Click on the Settings button for the desired integration
Navigate to the Options tab.
Under Manage Integration Data click the Click Here button. This shows all entity types that the integration supports and which entity types the integration is currently receiving.
From within the Manage Integration Data list you can set which entity types you want the integration to receive, as well as configure an integration to only search entities from specific channels.
If a channel entity filter is set, an integration will only receive entities that are tagged in the specified channel(s).
To add a channel entity filter, click the add channel entity filter button then type in the name of the Channels you wish to specify.
To view the status of the cache and further metrics click on the Metrics button located at the top of the main integration page.
Only Admins can see the Integration Cache settings on this page.
Here you will be able to see the health statistics of the overall Cache. The integration cache metrics are for the overall cache and are not a per-integration metric.
By default, the integration cache uses up to 10% of the memory on your Polarity Server. Once the cache is full, the least recently used cache entities will be removed to make space for new entries.
The Cache Metrics will provide the following metrics:
Overall Health - An overall health indicator for your integration cache.
Used Memory Peak - The maximum amount of memory used by your cache since the caching service was started. This value is only reset if you restart the redis-integration-cache service.
Cache Ops/Sec - A near real-time indicator of how many operations per second the cache is taking to service lookup requests.
Net Output Bytes - The total number of bytes that have been written to the network from the cache. This value is only reset if you restart the redis-integration-cache service.
Keys - The total number of keys stored in the cache. A key is an entry in the cache and each cached entity requires multiple keys to store efficiently.
Evicted Keys - Keys are evicted from the cache if it is full. Keys are evicted using a LRU (least recently used) strategy. If your Evicted Keys count is high, it means your cache frequently reaches capacity you should increase the default cache size or add additional memory to your Polarity Server instance.
Cache Hit Rate - Provides a rough estimate of how often an item is returned when your cache is checked. The longer your Cache Time to Live, the higher your hit rate will be. Also, if your users frequently view the same or similar data, the higher your hit rate will be.
