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:

Squirro project administrator access - Administrator rights to configure integrations.
Synaptica account - Active Synaptica account with API access.
Graphite API v2 access - Synaptica instance with support for Graphite API v2.
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#

Access Project Configuration

Navigate to your Squirro project and access the project configuration settings.
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.
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:
```
{
    "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 actual Synaptica API password.
Note

Configuration key names must follow specific naming conventions. For detailed formatting rules and examples, see Configuration Key Naming Conventions.

Setting Up Server-Level Integration#

Access Server Configuration

Navigate to the server configuration settings in your Squirro instance.

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

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:
```
{
    "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 actual Synaptica API password.
Note

Configuration key names must follow specific naming conventions. For detailed formatting rules and examples, see Configuration Key Naming Conventions.

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

Note

The secret configuration key must follow Squirro’s naming conventions. See Configuration Key Naming Conventions for detailed formatting rules.

Testing the Integration#

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

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'}]

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.