---
title: Working with Interfaces
slug: working-with-interfaces
docTags: 
createdAt: 2026-03-31T07:11:29.000Z
---

## Overview

This section of the Turbine User Guide describes the interfaces available in Turbine Solutions. Interfaces are standard data formats that enable components to work together seamlessly. Use interfaces to standardize data transformation across security operations workflows.

When you apply an interface to a component, it automatically configures the component's input and output data structures. This standardization allows you to easily swap components in your playbooks without manual re-configuration, as long as they use the same interface.

This guide covers:

- What interfaces are and how they work
- How to use interfaces when building components
- Available interface catalogs for SOC, AI SOC, and VRM workflows
- Best practices for working with interfaces

### Interface catalogs

Full interface contracts for each solution area live in these guides:

- **[SOC Interfaces](docId\:uIUwfCgOFmXzYU0uj7Aih)** — 22 Classic SOC interface contracts
- **[AI SOC Interfaces](docId:9DlFwvaOR278W_nDZ8P_K)** — 4 AI SOC interface contracts
- **[VRM Interfaces](docId:5A2WtMf7fVGYTML3FNVy8)** — 6 VRM interface contracts

For complete data model field definitions, see **[Turbine Schema Reference (Classic SOC)](docId\:AbBcN4v4tRb5C1gqZvd2-)**, **[Turbine Schema Reference (AI SOC)](docId\:XeFTuqkOsig4KR6tnWJTj)**, and **[Turbine Schema Reference (VRM)](docId\:zO6hALeEmnspLjyAmh2ad)**.

## What Are Interfaces?

An **interface** defines the data structure that a component expects to receive (inputs) and the data structure it produces (outputs). Think of it as a standard template that ensures components can work together seamlessly.

### Key Concepts

- **Component**: A reusable automation flow that performs a specific task. Components are used within playbooks to build automation workflows.
- **Interface**: A standard data format that components can use. When multiple components use the same interface, they can easily be swapped with each other because they all accept and produce data in the same format.
- **Input Schema**: Defines what data your component needs to receive to work properly.
- **Output Schema**: Defines what data your component will produce when it runs.

### Example

Imagine you have multiple threat intelligence enrichment components:

- Enrich via VirusTotal
- Enrich via Recorded Future
- Enrich via URLHaus

If they all use the same "Simple Observable to Enrichment" interface, they all:

- Accept the same input format (an observable like an IP address)
- Produce the same output format (enriched observable data)

This means you can swap between these components in your playbook without changing any other parts of your workflow.

**Note:** You can still create components without applying an interface, but they will not benefit from standardization and easy swapping.

## Benefits of Using Interfaces

Interfaces provide powerful benefits that make your automation workflows more flexible and easier to manage:

- **Easy Component Swapping**: Components that use the same interface can be swapped in and out of playbooks with a single click. No manual re-configuration or re-mapping of data needed.
- **Search by Functionality**: You can search for components based on what they do, regardless of which vendor technology they use. For example, find all enrichment components that work with observables, even if they use different threat intelligence sources.
- **Guaranteed Compatibility**: Components built with interfaces are guaranteed to work seamlessly with playbooks and other components that use the same interface.
- **Standardized Data Flow**: Interfaces ensure that data flows correctly between components, reducing errors and making your playbooks more reliable.
- **Vendor Flexibility**: You can easily switch between different vendor technologies (such as VirusTotal, Recorded Future, or URLHaus) without changing your playbook structure, as long as the components use the same interface.

## How to Use Interfaces

Interfaces are available in Turbine Canvas when building components. When you create or edit a component:

1. **Open the component builder** in Turbine Canvas
2. **Navigate to the "Data" tab** in the side panel
3. **Select an interface** from the dropdown list of available interfaces
4. **The interface automatically configures** the component's input and output schemas

Once an interface is applied, your component will have standardized inputs and outputs that match other components using the same interface, making them easily swappable in playbooks.

## Understanding Interface Schemas

Each interface defines two key parts:

- **Input Schema**: Specifies what data your component expects to receive
- **Output Schema**: Specifies what data your component will produce

When you apply an interface to a component, these schemas are automatically configured, ensuring your component accepts and produces data in the correct format.

***

## Usage Patterns

### Pattern 1: Data Ingestion Pipeline

```text
Source Data → Ingestion Interface → Normalized Data → Processing Interface → Output
```

Example:

```text
Email → Email to Email → Processed Email → Extract Observables → Observable Array
```

### Pattern 2: Enrichment Workflow

```text
Observable → Simple Observable to Enrichment → Enriched Observable → Alert Creation
```

### Pattern 3: Remediation Workflow

```text
Vulnerability Finding → Remediation Item to Ticket → Ticket Created → Remediation Item Check → Status Updated
```

### Pattern 4: Bulk Processing

```text
Array of Objects → Array to Array Interface → Normalized Array → Individual Processing
```

***

## Best Practices

Follow these guidelines when working with interfaces:

1. **Use the latest version**: Always use the latest version of interfaces when available. Check the `version` field to ensure compatibility.
2. **Include required fields**: Include all `required` fields in input schemas. Missing required fields cause transformation failures.
3. **Validate data before transformation**: Validate input data against the interface schema before transformation to catch errors early.
4. **Handle errors**: Implement error handling for transformation failures, especially in automated workflows.
5. **Choose the right interface**: Select interfaces that match your data flow:
   - Use "to None" interfaces for ingestion and logging
   - Use transformation interfaces for data conversion
   - Use remediation interfaces for automated actions
6. **Extract observables from text**: Use "Text to Array of Observables" to extract IOCs from unstructured text.
7. **Process bulk data efficiently**: Use array interfaces to process multiple items efficiently.
8. **Validate remediation actions**: Validate action parameters before executing remediation actions to prevent unintended consequences.

***

## Playbook Integration

### How Interfaces Work in Playbooks

Interfaces define the input and output schemas for playbook transformations. When you create a playbook component using a BuilderIntent interface:

1. **Input schema**: Defines what data the playbook expects
2. **Output schema**: Defines what data the playbook produces
3. **Validation**: Ensures data matches schemas at runtime
4. **Type Safety**: Provides type information for the UI

### Creating a Playbook with an Interface

**Example Playbook YAML**:

```yaml
schema: playbook/2
name: observable-enrichment-playbook
title: Observable Enrichment Playbook
description: Enriches observables with threat intelligence

# Reference to the interface schema
inputSchemaReferenceId: simple-observable-to-enrichment-v1-0-2-06fbe

actions:
  enrich_observable:
    actionType: jsonata
    inputs:
      expression: |
        {
          "observable": $.observable,
          "enrichment": {
            "enrichment_type": "reputation",
            "enrichment_provider": "threat-intel",
            "enrichment_verdict": "malicious",
            "enrichment_timestamp": $now(),
            "enrichment_context": "Enriched via playbook"
          }
        }
      data:
        observable:
          observable_type: string
          observable_value: string

publish:
  enrichment: $.enrich_observable.enrichment
```

### Connecting Multiple Interfaces

You can chain multiple interfaces together in a playbook:

```yaml
actions:
  # Step 1: Extract observables from text
  extract_observables:
    actionType: jsonata
    inputs:
      expression: |
        {
          "observables": $split($.text_value, " ")
        }
      data:
        text_value: string
  
  # Step 2: Enrich each observable
  enrich_observable:
    actionType: jsonata
    next: create_alert
    inputs:
      expression: |
        {
          "enrichment": {
            "enrichment_type": "reputation",
            "enrichment_provider": "threat-intel",
            "enrichment_verdict": "suspicious"
          }
        }
      data:
        observable: object
  
  # Step 3: Create alert from enriched observable
  create_alert:
    actionType: jsonata
    inputs:
      expression: |
        {
          "alert": {
            "alert_title": "Threat Detected",
            "alert_severity": "high",
            "observables": [$.enrich_observable.observable]
          }
        }
      data:
        enrichment: object
```

## Troubleshooting and Common Pitfalls

### Issue 1: Schema Validation Failures

**Symptom**: Transformation fails with validation error

**Causes**:

- Missing required fields
- Wrong data types
- Invalid enum values
- Extra fields not in schema (if `additionalProperties: false`)

**Solution**:

1. Validate input data against schema before transformation
2. Use schema validation tools
3. Check interface documentation for required fields
4. Remove or map extra fields

**Example Fix**:

```json
// Before (fails validation)
{
  "observable": {
    "type": "ip",  // Wrong field name
    "value": "192.168.1.1"  // Wrong field name
  }
}

// After (passes validation)
{
  "observable": {
    "observable_type": "ip",  // Correct field name
    "observable_value": "192.168.1.1"  // Correct field name
  }
}
```

### Issue 2: Transformation Timeouts

**Symptom**: Transformation fails with timeout error

**Causes**:

- External API calls taking too long
- Large data processing
- Network latency
- Insufficient timeout configuration

**Solution**:

1. Increase timeout for slow operations
2. Optimize transformation logic
3. Use async processing for long operations
4. Implement retry logic with exponential backoff

### Issue 3: Incorrect Interface Selection

**Symptom**: Data does not match expected format

**Causes**:

- Using wrong interface for data type
- Confusing similar interfaces
- Version mismatch

**Solution**:

1. Review interface documentation
2. Check input/output schemas
3. Verify interface version compatibility
4. Test with sample data first

**Example**:

```javascript
// Wrong: Using "Simple Observable to Enrichment" for array
// Correct: Use "Array of Simple Observable to None" or process individually
```

### Issue 4: Remediation Action Failures

**Symptom**: Remediation actions return error messages

**Causes**:

- Invalid action parameter
- System permissions
- Target system unavailable
- Invalid observable format

**Solution**:

1. Validate action parameters before execution
2. Check system connectivity
3. Verify permissions
4. Review error messages for specific issues

**Example**:

```json
// Invalid action
{
  "action": "ban"  // Should be "block" or "unblock"
}

// Valid action
{
  "action": "block"
}
```

### Issue 5: Data Type Mismatches

**Symptom**: Numbers passed as strings, dates in wrong format

**Causes**:

- Data source provides wrong types
- Missing type conversion
- Schema expects specific format

**Solution**:

1. Convert data types before transformation
2. Use transformation functions for type conversion
3. Validate data types match schema

**Example**:

```json
// Before (may fail)
{
  "alert": {
    "alert_risk_score": "85"  // String
  }
}

// After (correct)
{
  "alert": {
    "alert_risk_score": 85  // Integer
  }
}
```

## Frequently Asked Questions

### Where Can I See a List of Available Interfaces That I Can Use?

Currently, the only way to view the list of available interfaces would be through the component builder in Turbine Canvas. You can select a component or create a new one, go to the "Data" tab in the side panel, and use the dropdown there to view the list of supported interfaces.

### Can I Create My Own Interfaces?

No, currently you can only use the available interfaces that Swimlane provides. Custom interface creation is on the roadmap as a future feature enhancement.

### How Do I Know Which Interface to Use for My Component?

Choose an interface that matches your component's purpose:

- **Ingestion components**: Use interfaces that end with "to None" (such as "Alert to None")
- **Enrichment components**: Use interfaces like "Simple Observable to Enrichment"
- **Transformation components**: Use interfaces that transform one data type to another (such as "Email to Email")
- **Remediation components**: Use remediation action interfaces (such as "Block/Unblock Observable Remediation Action")

### What Happens if I Do Not Use an Interface?

You can still create components without applying an interface. However, you will need to manually configure inputs and outputs, and the component will not benefit from standardization or easy swapping with other components that use the same interface.

### Can I Use Multiple Interfaces on the Same Component?

No, each component can only have one interface applied to it. The interface defines both the input and output schemas for that component.

***

## References

- **[JSON Schema Specification](https://json-schema.org/)**
- **[MITRE ATT\&CK Framework](https://attack.mitre.org/)**