Skip to main content
Applies to BloodHound Enterprise and CE This guide walks you through creating and testing OpenGraph data using a simple example JSON file. By following these steps, you’ll learn how to:
  • Create a properly structured OpenGraph JSON file and upload it to BloodHound
  • Define custom icons and colors for your node types to enhance visualization
  • Validate the data using search and Cypher queries in the Explore page
  • Remove the example data in the Administration > Database Management page when finished
Use this guide to get hands-on experience with the OpenGraph structure and validate custom nodes and edges in BloodHound.

​
Create example data

This example defines two custom (Manager for Bob and Employee for Alice) connected by a Manages to demonstrate the structure of an OpenGraph payload.
It also includes an optional (but recommended) source_kind property in the metadata section to facilitate easy cleanup later.
You can expand on this example to create more complex graphs with additional nodes, edges, and properties as needed.
1

Create a new JSON file

First, you need to define your OpenGraph payload in a JSON file.At minimum, every OpenGraph payload must follow this basic structure:
{
  "metadata": {
    "source_kind": "EXBase"
  },
  "graph": {
    "nodes": [],
    "edges": []
  }
}
See the OpenGraph schema for required fields and the full structure.
  1. Create a new file called opengraph-example.json using a plain text editor (UTF-8 encoding).
  2. Copy and paste the following example, which includes two nodes (bob as a Manager and alice as an Employee) connected by a Manages edge. 
    {
  "metadata": {
    "source_kind": "EXBase"
  },
  "graph": {
    "nodes": [
      {
        "id": "123",
        "kinds": [
          "Manager"
        ],
        "properties": {
          "displayname": "bob",
          "property1": "property1",
          "objectid": "123",
          "name": "BOB"
        }
      },
      {
        "id": "234",
        "kinds": [
          "Employee"
        ],
        "properties": {
          "displayname": "alice",
          "property1": "property1",
          "objectid": "234",
          "name": "ALICE"
        }
      }
    ],
    "edges": [
      {
        "kind": "Manages",
        "start": {
          "value": "123",
          "match_by": "id"
        },
        "end": {
          "value": "234",
          "match_by": "id"
        }
      }
    ]
  }
}
    The following table describes the structure and properties of the example JSON file:
    SectionPropertyDescription
    metadatasource_kindOptional data source identifier for grouping and managing nodes (e.g., “EXBase”)
    graph.nodesidUnique identifier for the node
    kindsArray of node types; the first determines the node’s icon and display
    propertiesObject containing node properties (e.g., name, displayname, objectid, and custom properties)
    graph.edgeskindThe edge type name (e.g., “Manages”)
    startSource node reference; can match a node in this payload or any pre-existing node
    endTarget node reference; can match a node in this payload or any pre-existing node
    About source kinds and node types:
    • The source_kind value automatically applies to all nodes in the payload, enabling grouped management and bulk deletion in Database Management. Alternatively, you can add source_kind to individual nodes if you don’t declare it in metadata.
    • Each node must have at least one kind. The first kind is the Primary Kind that determines which node type it is and which icon and color represents it.
    • Edges can reference nodes from different payloads. You can create all your nodes first, then create edges between them in a separate payload.
    BloodHound Enterprise only: All nodes must have at least one edge connecting them to other nodes. Nodes without any edges are automatically removed by the built-in reconciliation process. Ensure every node has at least one edge pointing to or from it.
2

Save the file

Save the opengraph-example.json file to a location you can easily access for uploading in the next step.
3

Upload the JSON file

Use the BloodHound web interface to upload the opengraph-example.json file directly through the browser.
  1. Log in to your BloodHound instance.
  2. In the left menu, click Quick Upload.
  3. Click the Upload Files screen to open a file system dialog or drag and drop the opengraph-example.json file.
  4. Click Upload and wait for the upload to complete. You should see a confirmation message indicating the file was successfully ingested.
    If you receive an error, validate your JSON file using a linter and ensure all required properties are present.

​
Customize nodes

To enhance the visualization of the node types on the graph and in the Entity panel, you can define custom icons and colors.
This is done separately from the OpenGraph data payload and must be uploaded through the BloodHound API. Stay tuned for a more streamlined process for managing icons and colors!
1

Prepare your custom type definition

This example creates custom definitions for the Manager and Employee node types defined in the example JSON file. It specifies that Manager nodes should display with a briefcase icon in blue, and Employee nodes should display with a user icon in green.The custom type definition is a JSON object with the following structure:
{
  "custom_types": {
    "Manager": {
      "icon": {
        "type": "font-awesome",
        "name": "briefcase",
        "color": "#0066CC"
      }
    },
    "Employee": {
      "icon": {
        "type": "font-awesome",
        "name": "user",
        "color": "#00AA00"
      }
    }
  }
}
The following table describes the properties in the custom type definition:
PropertyDescription
custom_typesObject containing custom type definitions, where each key is a node type and the value defines the visualization properties for that type
icon.typeFont Awesome is the icon library used for custom icons
icon.nameFont Awesome icon name (without “fa-” prefix)
icon.colorHex color code in #RGB or #RRGGBB format (the # is required)
2

Run a POST request

Use a POST request to the BloodHound API to upload your custom type definitions.Here’s an example request body for the Manager and Employee node types:
curl -X POST \
  https://your-bloodhound-instance/api/v2/graphs/custom_nodes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_types": {
      "Manager": {
        "icon": {
          "type": "font-awesome",
          "name": "briefcase",
          "color": "#0066CC"
        }
      },
      "Employee": {
        "icon": {
          "type": "font-awesome",
          "name": "user",
          "color": "#00AA00"
        }
      }
    }
  }'
After running this request, any nodes of type Manager or Employee in your graph display with the specified icons and colors. You can modify these custom type definitions as needed with a PUT request with updated properties.

​
Validate example data

After uploading the OpenGraph example data and custom node icons/colors, it’s important to validate that BloodHound ingested everything correctly and displays it as expected.
1

Open the Explore page

Log in to your BloodHound instance and navigate to the Explore page.
2

Search for nodes and edges

Use the Search features to find the example nodes and edges, and verify that properties and custom icons/colors are displayed correctly.

​
Delete example data

After you’ve finished testing, you should clean up your example data by deleting the example OpenGraph payload.
1

Delete example data

Use the BloodHound web interface to delete nodes by source_kind.
  1. Log in to your BloodHound instance.
  2. In the left menu, click Administration > Database Management.
  3. Under All graph data, check the EXBase data checkbox.
The name of the checkbox is based on the value of the source_kind property in the metadata section of the example JSON file.
  1. Click Delete and confirm the deletion.
This action permanently deletes all nodes with the EXBase source kind, including any edges connected to those nodes.
2

Verify deletion

Run the following Cypher query to confirm the example OpenGraph data is gone:
MATCH (n)
WHERE n:EXBase
RETURN n
You should see a No results match your criteria message confirming that all nodes from the EXBase source have been deleted.
The Cypher query results may be cached. If you don’t see the expected results immediately, try refreshing the Cypher page to clear the cache and confirm the deletion.

​
Troubleshooting

This section provides solutions to common issues you may encounter when testing your OpenGraph data.
  • Validate your JSON using JSONLint
  • Ensure all required sections are present
  • Verify that node IDs within the current payload are unique
  • Check that node IDs referenced in edges match nodes either in the current payload or from pre-existing data
  • Verify the icon name is correct and does not include a prefix, such as fa- (see FontAwesome to confirm available icons)
  • Ensure the color is in valid HEX format (#RGB or #RRGGBB) and includes the # symbol
  • Run a GET request to api/v2/graphs/custom_nodes to confirm your BloodHound instance contains the custom type definition you want to use
  • Verify the edge kind name is spelled correctly and matches your JSON file
  • Ensure the id values in the start and end references match your node id values exactly (labeled as Object ID in the Entity panel on the graph, but referenced as id in the payload)
  • Check that both referenced nodes were created successfully

​
Next steps

After you’re comfortable with this process, consider:
  • Creating more complex node types with additional properties
  • Testing multiple edge types between different node kinds
  • Reading the OpenGraph Schema documentation for advanced configurations
  • Reviewing OpenGraph Best Practices before deploying production data