Graphistry supports creating new pivots. Adding custom pivots simplifies accessing new data sources and taking common actions. We strongly recommend leveraging custom pivots to simplify use for new and busy users!

The pivot system is constantly improving, so if you have requests or challenges, please do not hesitate to reach out. Combine custom pivots into sequences by creating investigation templates from directly within the UI.

Concepts and architecture

The extensible pivot system combines several parts:

• Connectors: Low-level APIs for communicating with HTTP, Splunk, Neo4j, and other systems with custom protocols. Instantiated with settings such as database credentials. Graphistry-provided with configuration by admins.
• Pivots: Visual components for interacting with the graph through connectors
  • Base pivots: Generic and Graphistry-provided
  • Derived pivots: Added and customized by admins
• Investigations: User-configured instantiations of pivots that are chained together and run

Connectors

Configuring a connector such as a Splunk will automatically enable it in the settings panel. See [main config docs](configure.md) and [investigation configuration](configure-investigation.md). Connectors get instantiated during system start, and may defer some initialization activity such database schema indexing.

The built-in HTTP connector enables generic use of many web APIs for which Graphistry does not have a native connector. We are constantly adding and upgrading the system-provided connectors, and planning to expose user-defined connectors, so please contact if critical for your use case.

Pivots

The investigation UI instantiates, configures, and runs pivots. Pivots can be both base pivots and derived pivots. Pivots work over the graph and a connector to generate new subgraphs that the investigation runner merges into the graph. When an investigation gets saved, it also saves its instantiated pivot settings, which you can inspect in `data/investigation/pivots/*.json`.

Base pivots

Each connector comes with several base pivots. Enabling a connector will cause its base pivots to load at start and appear as available pivots within an investigation. On system start, the logs will print which pivots successfully loaded as well, including user-defined ones.

For reference, see the list of system-provided base pivots for each connector.

For example, consider the following loaded pivot:

    Loaded pivot [expand-neo4j-neo4j-connector][Neo4j: Expand]
      Connector: [neo4j-connector][Neo4j]
      Parameters: 
        [ref][Any field in:]:pivotCombo - (undefined), visible: true,
        [pivotFields][Expand on types:]:multi - (undefined), visible: true,
        [targetTypes][Target node types:]:multi - (undefined), visible: true,
        ...

The above base pivot contains several parts:

• ID: Unique pivot ID string `expand-neo4j-neo4j-connector`, typically detailing both the pivot action and the connector instance ID
• Label: Friendly UI-visible string `Neo4j: Expand`
• Parameters: Base settings for controlling the pivot, both UI visible and not. Reference these when creating derived pivots. Each parameter has several fields:
  • name: Identifier string unique within the parameter list
  • inputType: String controlling form element type - `text`, `textarea`, `bool`, `multi`, and `combo`
  • defaultValue: JSON based on inputType
  • isVisible: Boolean flag whether to show in the UI
  • isSensitive: Boolean flag whether to further restrict handling, such as for passwords
  • Based on the inputType, additional fields, such as label and options

Derived pivots

Derived pivots are new user-facing pivots generated by declaratively configuring base pivots.

Loading

Define declarative pivots as values in `config/pivot-db/config/config` under `{"systemTemplates": {"pivots": [ ... ]} }`.

Upon success, system start logs will print:

• In debug mode:

      Derived system pivot {
        id: 'neo4j-schema-neo4j-connector',
        ...
      

• Followed by, in production mode:

      ✅ Loaded pivot [neo4j-schema-neo4j-connector][Neo4j: View schema]...
      

Overriding parameters

One of the most common use cases is creating derived pivots that simplify more general pivots by hard-coding default values and providing a slimmed down UI.

For example, consider expanding based on IP. The base Splunk expand pivot `expand-splunk-plain` could be simplified via:

{
    "id": "expand-splunk-ip",
    "name": "Splunk: Expand by IP",
    "template": "expand-splunk-plain",
    "parameters": [
        {
            "name": "pivotFields",
            "defaultValue": ["src_ip", "dest_ip", "ip"]
        },
        {
            "name": "colMatch",
            "defaultValue": false
        },
        {
            "name": "filter",
            "defaultValue": "index=devices"
        },
        {
            "name": "timeout",
            "defaultValue": 10,
            "visible": false
        },
        {
            "name": "fuzzyMatchMode",
            "defaultValue": false,
            "visible": false
        }
    ]
}

The above creates a new derived pivot with more IP-specific default values than `expand-splunk-plain`. Most of the options are still exposed to the user in case they may want to change them, but parameters such as `fuzzyMatchMode` might not make sense to change for IP lookups. The result is a common action now has a preconfigured pivot that is faster and simpler to use.