Add Custom Entity Types

Add a custom entity type to extend functionality of a supported integration

For certain integrations (e.g., LDAP), you may want to add a custom entity type so that the integration will search on additional data.

Modify config.js

To add a custom type you will need to modify the integration's config.js file which is located within the config directory of the integration's directory. Open it with a text editor on your server:

sudo vi /app/polarity-server/integrations/INTEGRATION_NAME/config/config.js

Once the config.js file is open you will see an entityTypes property near the top of the file or in some cases a customTypes property. As an example, the LDAP integration will look similar to this:

module.exports = {
  name: 'LDAP',
  acronym: 'LDAP',
  description: 'Search your Lightweight Directory Access Protocol (LDAP) server by email address',
  entityTypes: ['email'],
  ...
}

To add a custom type you will add the customTypes option to the config.js. If the customTypes option already exists then you will add an additional type to the customTypes array. As an example, here is what a single custom type called myCustomType will look like within the config.js file:

module.exports = {
  customTypes: [
    {
      key: 'myCustomType',
      regex: /regex/
    }
  ]
  ...
}

For an integration with multiple custom types it would look like this:

module.exports = {
  customTypes: [
    {
      key: 'myCustomType',
      regex: /regex/
    },
    {
      key: 'anotherCustomType',
      regex: /another_regex/
     }
  ]
  ...
}

The custom type objects have two properties. The first property key is used by the integration to identify the custom type. The key value should only include the character a-z, A-Z and underscores. You should not include spaces in the key value.

The regex property is a regex. It should start and end with forward slashes. We recommend using word boundaries on your regex (/b). For example, to match on a hostname that consists of 8 letters followed by 2 numbers you could use the following custom type:

customTypes: [
  {
    key: 'hostname',
    regex: /\b[-zA-Z]{8}\d{2}\b/
  }
]

Once you've made your changes, save the file.

A good place to test out your regex is https://regex101.com/

Increment Integration Version

In order for the Polarity Server to recognize the change in the integration, you will need to increment the integration's version. The version of the integration is located within the integration's package.json file. Open it with a text editor on your server:

sudo vi /app/polarity-server/integrations/INTEGRATION_NAME/package.json

Once open, find the version property and append a + (plus sign) and a counter to signify that you have made a modification to the integration. In the example below the base version was 3.3.0 and we modified it to be 3.3.0+1

{
  "main": "./integrations.js",
  "name": "LDAP",
  "description": "Polarity LDAP Integration",
  "version": "3.3.0+1",
  ...
}

We leave the base version as is so that we still know what version of the official integration you are running.

Restart the Server

Finally, you must restart the server process for the new custom type to be identified by the server and sent to clients. You can restart the polarity server process with the following command:

sudo systemctl restart polarityd

After the server restarts you should see your new custom type available from the integration's "Manage Integration Data" option:

View your custom type from the integration's "Manage Integration Data" option

When using custom types, we generally recommend setting the integration to be On-Demand Only for all users. You can do this by checking the "On-demand only" option and setting the permission on that option to "Users can view only"