How to Integrate Synaptica with the Squirro Classifier

How to Integrate Synaptica with the Squirro Classifier#

Feature status notice

Squirro Classifier is still in development. If you have suggestions for improvement, visit the Squirro Support website and submit a feedback request.

Profile: Project Administrator

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 the Synaptica 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 Synaptica concepts are called Linked Categories. These categories enable Entity Linking, by associating entities detected by the classifier with the Synaptica concepts.

Prerequisites#

Before setting up the integration, ensure you have:

  1. Squirro project administrator access - Administrator rights to configure integrations.

  2. Synaptica account - Active Synaptica account with API access.

  3. Graphite API v2 access - Synaptica instance with support for Graphite API v2.

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

Integration Configuration Options#

When configuring Synaptica 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 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 and are recommended for:

  • 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:

    {
    "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"
    }
}

    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:

    {
     "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"
     }
}

  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 the 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