Directives

Directives are a powerful feature of the Propeller REST API that allows you to control the behavior of bulk operations without requiring multiple API calls. They provide fine-grained control over how data is processed, updated, and managed during bulk create and update operations.

Overview

Directives are only available in bulk endpoints and enable you to perform complex operations that would otherwise require multiple individual API calls. They help optimize performance and reduce complexity when working with large datasets.

How Directives Work

Directives are specified in the request payload and control specific aspects of the bulk operation:

• Field-level behavior: Control how individual fields are updated
• Resource management: Handle parent-child relationships and hierarchies
• Translation management: Manage multi-language content efficiently
• Creation control: Skip creation of new resources when needed

Available Directives

Directive	Purpose	Fields	Use Case
skipIfNotEmpty	Skip updating non-empty fields	Array of field names	Preserve existing data
skipMoveOnUpdate	Prevent resource relocation	Empty array	Maintain hierarchy
skipCreate	Only update existing resources	Empty array	Update-only operations
mergeTranslationsOnUpdate	Reset translations not in payload	Empty array	Clean translation management

Detailed Directive Descriptions

Skip If Not Empty

• Directive: skipIfNotEmpty
• Purpose: Preserve existing data by skipping updates to non-empty fields
• Fields: Array of field names to protect
• Use Case: When importing data from external systems but want to preserve manually maintained content in Propeller.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "names": [{"language": "EN", "value": "Updated Product Name"}],
      "descriptions": [{"language": "EN", "value": "Updated description"}]
    }
  ],
  "directives": {
    "skipIfNotEmpty": ["names", "descriptions"]
  }
}

Behavior:

• If names or descriptions already have content, they won't be overwritten
• Empty fields will still be updated
• Useful for preserving manually curated content

Skip Move On Update

• Directive: skipMoveOnUpdate
• Purpose: Prevent resources from being moved to different parent containers
• Fields: Empty array (no specific fields)
• Use Case: When updating product data but want to maintain the current category structure.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "parent": {"sourceId": "NEW_CATEGORY", "source": "ERP_SYSTEM"},
      "names": [{"language": "EN", "value": "Updated Product"}]
    }
  ],
  "directives": {
    "skipMoveOnUpdate": []
  }
}

Behavior:

• Product data will be updated
• Product will remain in its current category
• Parent relationship changes are ignored

Skip Create

• Directive: skipCreate
• Purpose: Only update existing resources, skip creation of new ones
• Fields: Empty array (applies to entire operation)
• Use Case: When you want to update only existing products without creating new ones.

{
  "products": [
    {
      "sourceId": "EXISTING_PROD",
      "source": "ERP_SYSTEM",
      "names": [{"language": "EN", "value": "Updated Name"}]
    },
    {
      "sourceId": "NEW_PROD",
      "source": "ERP_SYSTEM",
      "names": [{"language": "EN", "value": "New Product"}]
    }
  ],
  "directives": {
    "skipCreate": []
  }
}

Behavior:

• EXISTING_PROD will be updated
• NEW_PROD will be skipped (not created)
• Only update operations are performed

Merge Translations On Update

• Directive: mergeTranslationsOnUpdate
• Purpose: Replace all translations with only those provided in the payload
• Fields: Empty array (applies to all translation fields)
• Use Case: When you want to completely replace all language versions with a new set.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "names": [
        {"language": "EN", "value": "English Name"},
        {"language": "NL", "value": "Dutch Name"}
      ]
    }
  ],
  "directives": {
    "mergeTranslationsOnUpdate": []
  }
}

Behavior:

• Only English and Dutch translations will remain
• All other language translations will be deleted
• Complete replacement of translation set

Advanced Patterns

Combined Directives

Use multiple directives together for complex scenarios:

{
  "products": [...],
  "directives": {
    "skipIfNotEmpty": ["names", "descriptions"],
    "skipMoveOnUpdate": [],
    "mergeTranslationsOnUpdate": []
  }
}

Performance Considerations

Optimization Benefits

• Reduced API Calls: Single bulk operation instead of multiple individual calls
• Atomic Operations: All changes processed in single transaction
• Network Efficiency: Less overhead from multiple requests
• Processing Speed: Optimized bulk processing algorithms

Resource Usage

• Memory: Bulk operations use more memory but are more efficient overall
• Processing Time: Initial setup takes longer but total time is reduced
• Error Handling: Bulk operations provide comprehensive error reporting

Directives provide powerful control over bulk operations, enabling efficient data management while preserving important content and relationships. Use them strategically to optimize your data integration workflows.