How to Integrate Synaptica with the Squirro Classifier

How to Integrate Synaptica with the Squirro Classifier#

Feature status notice

The Squirro Classifier is still in development. As we continue to refine and improve it, you may encounter some inconsistencies or issues. Please visit the Squirro Support website to share your feedback.

This guide explains how project administrators can integrate Synaptica with Squirro Classifier to enable features such as Linked Categories. The integration allows Squirro to connect with Synaptica’s Graphite API v2 to access taxonomies and controlled vocabularies.

Profile: Project Administrator

Introduction#

Synaptica is a leading provider of taxonomy and controlled vocabulary management solutions. By integrating Synaptica with Squirro Classifier, you can enable enhanced classification capabilities using your organization’s existing taxonomies.

The integration works by connecting to Synaptica’s Graphite API v2, which provides access to concepts that are used for classification. Squirro Classifier categories that are linked to Synaptica concepts are called Linked Categories. These categories enable Entity Linking, by associating entities detected by the Classifier with Synaptica concepts.

Prerequisites#

Before setting up the integration, ensure you have:

  1. Squirro Project Administrator access - You must have admin permissions to configure integrations

  2. Synaptica account - Active Synaptica account with API access

  3. Graphite API v2 access - Your Synaptica installation must support Graphite API v2

  4. API credentials - Username and password for Graphite API access

Integration Configuration Options#

Squirro provides two levels of Synaptica integration configuration:

Project-Level Integration (integrations.graphite.project)#

Project-level integrations apply only to the specific project where they are configured. This option is ideal when:

  • Different projects need different Synaptica 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. This option is recommended when:

  • All projects should use the same Synaptica 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:

    {
    "integrations.graphite.project": {
        "your_integration_name": {
            "base_url": "https://your-synaptica-domain.synaptica.net/rest/v2/",
            "username": "your_api_username",
            "password_config_key": "integrations.graphite.your_integration_name.password"
        }
    }
}

    Replace the following values:

    • your_integration_name - A unique identifier for this integration

    • your-synaptica-domain - Your Synaptica domain

    • your_api_username - Your Synaptica API username

  3. Configure Password Secret

    The password must be stored separately as a secret configuration setting. Set the password using the key specified in password_config_key:

    {
    "integrations.graphite.your_integration_name.password": "your_api_password"
}

Setting Up Server-Level Integration#

  1. Access Server Configuration

    Navigate to the server configuration settings in your Squirro instance.

  2. Configure Graphite Integration

    Add the following configuration to your server settings under integrations.graphite.server:

    {
    "integrations.graphite.server": {
        "your_integration_name": {
            "base_url": "https://your-synaptica-domain.synaptica.net/rest/v2/",
            "username": "your_api_username",
            "password_config_key": "integrations.graphite.your_integration_name.password"
        }
    }
}

  3. Configure Password Secret

    Set the password as a server-level secret:

    {
    "integrations.graphite.your_integration_name.password": "your_api_password"
}

Configuration Parameters#

The Synaptica integration requires the following configuration parameters:

Base URL#

  • Parameter: base_url

  • Description: The API endpoint for your Synaptica Graphite API v2

  • Format: https://your-domain.synaptica.net/rest/v2/

  • Required: Yes

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.<integration-name>.password

  • Required: Yes

Testing the Integration#

After configuring the integration, you can test the connection by:

  1. Verifying Configuration

    Ensure all required parameters are properly set and the password secret is configured.

    For example, by using the Python Squirro client:

    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 list available Synaptica 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 Synaptica Graphite API endpoint. Also, confirm that the API user has appropriate permissions to access the required Synaptica projects, schemes and concepts.

    Using the Squirro Client:

    graphite_instance_id = "your_integration_name"
graphite_projects = client.get_graphite_projects(PROJECT_ID, graphite_instance_id)
print(graphite_projects)

# Output should list available Synaptica 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

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 Synaptica 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 (currently 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 Synaptica integration contact Squirro Support.

Contents