# How to Integrate Graphite with Squirro Classifier > **Feature status notice** > > [Squirro Classifier](../../features/squirro-classifier.md#squirro-classifier) is still in development. If you have suggestions for improvement, visit the [Squirro Support website](https://go.squirro.com/support) and submit a feedback request. Profile: Project Administrator This guide explains how project administrators can integrate [Squirro Graphite](index.md#graphite) with [Squirro Classifier](../../features/squirro-classifier.md#squirro-classifier) to use features such as Linked Categories. The integration allows Squirro to connect with the Graphite API v2 to access taxonomies and controlled vocabularies, providing access to the concepts that are used for classification. Squirro Classifier categories that are linked to Graphite concepts are called Linked Categories. These categories support Entity Linking, by associating entities detected by the classifier with the Graphite concepts. ## Prerequisites Before setting up the integration, ensure you have: 1. **Squirro project administrator access** - Administrator rights to configure integrations. 2. **Graphite account** - Active Graphite account with API access. 3. **Graphite API v2 access** - A Graphite instance that supports Graphite API v2. 4. **API credentials** - Username and password for the Graphite API access. ## Integration Configuration Options When configuring the Graphite integration, you have two options: Project-Level Integration and Server-Level Integration. Choose the one that best fits your organization’s needs. **Project-Level Integration (integrations.graphite.project)** - Project-level integrations are specific to a single project and are ideal for: - Different projects need different Graphite configurations. - You want to test the integration on a specific project first. - Projects have distinct taxonomy requirements. **Server-Level Integration (integrations.graphite.server)** - Server-level integrations apply to all projects on the Squirro server and are recommended for: - All projects should use the same Graphite configuration. - You want to standardize taxonomy access across your organization. - Managing multiple identical configurations would be inefficient. ## Step-by-Step Configuration ### Setting Up Project-Level Integration 1. **Access Project Configuration** Navigate to your Squirro project and access the project configuration settings. 2. **Configure Graphite Integration** Add the following configuration to your project settings under `integrations.graphite.project`: ```json { "your-integration-name": { "base_url": "https://your-synaptica-domain.synaptica.net/rest/v2", "username": "your-api-username", "password_config_key": "integrations.graphite.password.your-integration-name", "web_app_base_url": "https://your-synaptica-domain.synaptica.net" } } ``` Replace the following values: - `your-integration-name` - A unique identifier for this integration. - `your-synaptica-domain` - The subdomain of your Graphite instance. - `your-api-username` - Your Graphite API username. [](https://s3.amazonaws.com/download.squirro.net/docs/technical/classifier/classifier-project-config-v2.png) 3. **Configure Password Secret** The password must be stored separately as a **secret configuration setting**. Create a new secret configuration key with the name specified in `password_config_key` from the previous step: ```json { "integrations.graphite.password.your-integration-name": "your-api-password" } ``` Replace the following values: - `your-integration-name` - The same integration identifier used in step 2. - `your-api-password` - Your Graphite API password. > **Note** > > Configuration key names must follow specific naming conventions. For detailed formatting rules and examples, see [Configuration Key Naming Conventions](../admin/configuration/key-naming-conventions.md#configuration-key-naming-conventions). [](https://s3.amazonaws.com/download.squirro.net/docs/technical/classifier/classifier-project-config-with-secret-example.png) ### Setting Up Server-Level Integration To set up a Server-Level Integration, navigate to the Server Configuration and follow the same steps as [Setting Up Project-Level Integration](#setting-up-project-level-integration). At the server level, use the `integrations.graphite.server` configuration (the `integrations.graphite.project` configuration does not exist at the server level). ## Configuration Parameters The Graphite integration requires the following configuration parameters: ### Base URL - **Parameter**: `base_url` - **Description**: The API endpoint for your Graphite API v2. - **Format**: `https://your-domain.synaptica.net/rest/v2` - **Required**: Yes > **Warning** > > Do not add a trailing slash at the end of the `base_url` value. A trailing slash prevents Squirro from reaching the Graphite API, and requests such as listing the available Graphite projects fail with a server error. ### Username - **Parameter**: `username` - **Description**: API username for authentication. - **Required**: Yes ### Password Config Key - **Parameter**: `password_config_key` - **Description**: Reference to the secret configuration key containing the API password. - **Recommended format**: `integrations.graphite.password.` - **Required**: Yes > **Note** > > The secret configuration key must follow Squirro’s naming conventions. See [Configuration Key Naming Conventions](../admin/configuration/key-naming-conventions.md#configuration-key-naming-conventions) for detailed formatting rules. ## Testing the Integration After configuring the integration, you can test the connection by: 1. **Verifying the Configuration** Ensure all required parameters are properly set and the password secret is configured. For example, by using the Python Squirro client: ```python from squirro_client import SquirroClient client = SquirroClient(None, None, cluster=CLUSTER) client.authenticate(refresh_token=USER_TOKEN) graphite_instances = client.get_graphite_instances(PROJECT_ID) print(graphite_instances) # Output lists the available Graphite instances for the project: # [{'id': 'your_integration_name', 'host': 'https://your-domain.synaptica.net/rest/v2', 'username': 'your_api_username'}] ``` 2. **Check API Connectivity and Validate Permissions** Test that Squirro can successfully connect to your Graphite API endpoint. Also, confirm that the API user has appropriate permissions to access the required Graphite projects, schemes, and concepts. Using the Squirro Client: ```python graphite_instance_id = "your_integration_name" graphite_projects = client.get_graphite_projects(PROJECT_ID, graphite_instance_id) print(graphite_projects) # Output should list the available Graphite projects: # [{'uri': 'https://your-domain.synaptica.net/project/your-project-id', 'label': 'Your Project Label', 'id': 'your-project-id'}], ``` ## Troubleshooting ### Common Issues and Solutions **Connection Failed** - Verify the `base_url` points to the correct Graphite API v2 endpoint. - Ensure the URL includes the `/rest/v2` path. - Ensure the URL has no trailing slash. A `base_url` ending in `/` causes requests to fail with a server error, for example when listing the available Graphite projects. **Authentication Errors** - Check that the username and password are correct. - Verify the password is stored in the correct secret configuration key. - Ensure the API user has necessary permissions. **Integration Not Available** - Confirm the integration is configured at the appropriate level (project or server). - Check that the integration name matches across all configuration references. - Verify the configuration has been applied and services restarted if necessary. ## Security Considerations When configuring the Graphite integration: - **Password Security**: Always store passwords in separate secret configuration settings, never in plain text. - **Access Control**: Limit API user permissions to only the required taxonomies and operations. Only read operations are supported. - **Network Security**: Use HTTPS for all API communications. - **Regular Updates**: Periodically rotate API credentials and review access permissions. ## Support and Additional Resources For additional support with the Graphite integration, visit the [Squirro Support website](https://go.squirro.com/support) and submit a technical support request.