Skip to main content

ToolJump Chrome Extension Architecture

The ToolJump Chrome Extension is a context-aware browser extension that automatically extracts the most relevant information from the pages you are visiting, provides them to the ToolJump Server and receives back actionable links and insights about the page you're looking at.

How does it work?​

The Chrome extension has a number of adapters embedded that know how to extract key information from a number of tools.

Once you are visiting a supported tool, the extension extracts the most relevant information in that page, structures it as a context (in JSON format), and then sends it to the ToolJump server.

The ToolJump server then returns the suggested insights and links that are relevant for the page the user is viewing, adding them in a context bar that sits at the top of the page.

Everytime the url changes, or the DOM changes within the page1, the extension extracts the information on the page again and provides a new set of insights and links, based on what the user is visiting.

Understanding the Page​

Each adapter provides functionality for a given tool. At this moment, the extension includes an AWS adapter and a GitHub adapter, which extract detailed information from these platforms.

For all other unsupported tools, you can contribute with an adapter to the source code, or use the Generic adapter, which only provides the URL (which you can process from your integrations).

Adapters generate the context of the page with the help of collectors, which are small bits of code that are responsible for one key aspect of the page.

info

The extracted page information is only sent to your ToolJump server.

Example​

For example, for the AWS adapter, we have the following collectors:

  • AWSAccountCollector (only collects information about the current account number)
  • AWSRegionCollector (only collects information about the current region)
  • AWSLambdaCollector (runs on pages of the Lambda service)
  • AWSDynamoDBCollector (runs on pages of the Dynamo service)
  • AWSS3Collector (runs on pages of the S3 service)

So, when you are viewing a Lambda function, your context will look like:

{
  // the URL is present for any website
  "url": "https://eu-central-1.console.aws.amazon.com/lambda/home?region=eu-central-1#/functions/my-test-lambda-function?tab=code",
  // the type depends on the current adapter (eg: aws, github, generic)
  "type": "aws",
  // everything below this is generated by the AWS collectors
  "global": {
    "accountId": "123456789012" // generated by AWSAccountCollector
  },
  "scope": {
    "region": "eu-central-1" // generated by AWSRegionCollector
  },
  // generated by AWSLambdaCollector
  "service": {
    "name": "lambda",
    "section": "functions",
    "resourceName": "my-test-lambda-function",
    "arn": "arn:aws:lambda:eu-central-1:123456789012:function:my-test-lambda-function"
  }
}

The generic adapter​

At this moment, the extension provides context for a number of AWS services and GitHub.

However, for any other tool which is not natively supported by the extension, you have two options:

  1. Use the Generic context
  2. Create a new context (see below)

The Generic context allows running the extension on any desired website.

The only information the Generic context provides is the url of the page, which you can parse and process from your integrations to provide meaningful insights.

Example:

{
  // the URL is present for any website
  "url": "https://any-other-tool",
}

In this way, integrations can only take decisions based on the URL of the page.

tip

You will need to enable permissions for the custom websites used in the Providers tab of the extension's settings.

Creating new adapters​

If you want to create a new adapter, you can get inspiration from the AWS or GitHub provider.

You will need to cover the following functionality:

  • matches() method, used for returning whether the context should run or not - preferably using location.hostname
  • inject() method, used for the logic of where to render the context bar in the page (the DOM)
  • getStyle() method, used for the CSS style of the bar
  • getContextType() method, should return the short name of the context
  • getCollectors() method, should return the array of the collectors that build the context for this adapter

Each collector should be a class implementing the Collector interface, with the following methods:

  • shouldRun() method, used for returning true or false depending on whether this collector should run. Example: the AWS Lambda collector should only run when the URL's path contains /lambda/
  • run(context, previousContext) method, used for updating the context based on the information found in the page

Security Considerations​

For a detailed overview of security practices and recommendations regarding the ToolJump extension, please refer to the Security documentation.

Learn how these contexts power your custom integrations.

For server-side processing, see server architecture.

Footnotes​

  1. Every change is debounced every few hundreds of milliseconds, so a large number of changes in the page will not affect the performance of the page. If the context remains the same, it will not be sent again to the server. ↩