How to use data pinning in n8n?

Data pinning in n8n allows you to save specific data from a workflow execution for future use, making it accessible across different workflow runs. This feature is particularly useful for storing reference data, configuration settings, or any information that needs to be persistently available without relying on external storage solutions.

 

Step 1: Understanding Data Pinning in n8n

 

Data pinning is a feature in n8n that allows you to save specific data from your workflow execution and make it available for future workflow runs. When you pin data, it gets stored in the n8n database and can be accessed using specific n8n expressions. This is particularly useful for:

• Storing configuration settings
• Saving API tokens or credentials
• Persisting reference data that doesn't change frequently
• Creating simple key-value storage within n8n
• Passing data between different workflows

Data pinning helps you avoid making unnecessary API calls to retrieve data that doesn't change often and provides a simple storage mechanism within n8n itself.

 

Step 2: Accessing the Data Pinning Feature

 

To access the data pinning feature in n8n:

• Run your workflow (manually or automatically)
• After the workflow execution completes, view the execution details
• Click on the output of any node where you want to pin data
• Look for the pin icon in the node output view

The pin icon allows you to save specific data items or the entire output of a node for future use.

 

Step 3: Pinning Data from a Node Output

 

To pin data from a node's output:

• Execute your workflow to generate output data
• Open the workflow execution
• Click on the node containing the data you want to pin
• In the output panel, identify the specific data item you want to pin
• Click the pin icon next to that data item
• Enter a name for your pinned data (use a descriptive name for easy reference)
• Click "Pin" to save the data

The pinned data will now be stored in the n8n database and can be accessed in future workflow executions.

 

Step 4: Pinning JSON Data Example

 

Here's a practical example of pinning JSON data:

1. Create a new workflow with a "Code" node
2. Configure the Code node to output some JSON data

// In the Code node
return [
  {
    json: {
      configSettings: {
        apiUrl: 'https://api.example.com',
        maxRetries: 3,
        timeout: 5000,
        features: ['logging', 'caching', 'compression']
      }
    }
  }
];

1. Execute the workflow
2. View the output of the Code node
3. Hover over the "configSettings" object and click the pin icon
4. Name your pinned data "appConfig"
5. Click "Pin" to save it

This configuration data is now pinned and available for use in any workflow.

 

Step 5: Using Pinned Data in Workflows

 

To access pinned data in your workflows:

• Use the $pinData expression followed by the name of your pinned data
• You can access specific properties within pinned data using dot notation

For example, to use the previously pinned "appConfig" data:

// In an Expression node or field
$pinData.appConfig.apiUrl
// Returns: https://api.example.com

$pinData.appConfig.features[0]
// Returns: logging

This allows you to access any part of your pinned data structure in expressions throughout your workflows.

 

Step 6: Creating a Workflow that Uses Pinned Data

 

Let's create a workflow that uses the pinned configuration data:

1. Create a new workflow
2. Add an "HTTP Request" node
3. Configure the HTTP Request node using pinned data:

• URL: {{ $pinData.appConfig.apiUrl }}/users
• Timeout: {{ $pinData.appConfig.timeout }}

1. Add a "Function" node after the HTTP Request to implement retry logic:

// In the Function node
const maxRetries = $pinData.appConfig.maxRetries;
const items = $input.all();

// Implement retry logic using the pinned maxRetries value
return items.map(item => {
  item.json.maxRetries = maxRetries;
  return item;
});

This workflow now uses the pinned configuration data for making HTTP requests and implementing retry logic.

 

Step 7: Managing Pinned Data

 

To manage your pinned data in n8n:

• Navigate to the Settings menu in n8n
• Look for the "Pinned Data" section
• Here you can view all your pinned data items
• You can delete pinned data items you no longer need
• You can also export pinned data for backup purposes

Regular management of pinned data is important to avoid cluttering your n8n instance with unnecessary data.

 

Step 8: Updating Pinned Data

 

To update existing pinned data:

• Create a workflow that generates the new data
• Run the workflow and view the execution output
• Pin the new data with the same name as the data you want to update
• Confirm that you want to overwrite the existing pinned data

Alternatively, you can use the n8n API to programmatically update pinned data.

 

Step 9: Advanced Use Case: Creating a Key-Value Store

 

You can use data pinning to create a simple key-value store in n8n:

1. Create a workflow with a "Code" node
2. Use the following code to create or update your key-value store:

// Get existing store or create a new one
const existingStore = $pinData.keyValueStore || {};

// Update or add new key-value pairs
const updatedStore = {
  ...existingStore,
  lastRun: new Date().toISOString(),
  counter: (existingStore.counter || 0) + 1,
  userIds: [1, 2, 3, 4, 5]
};

return [
  {
    json: {
      keyValueStore: updatedStore
    }
  }
];

1. Run the workflow
2. Pin the "keyValueStore" object
3. Each time you run this workflow, it will update the store while preserving existing values

This pattern allows you to implement a simple persistent storage mechanism within n8n.

 

Step 10: Using Pinned Data with Expressions in Various Nodes

 

Data pinning works with any node that supports expressions. Here are some examples:

1. In an "IF" node condition:

{{ $pinData.thresholds.errorLevel > $input.item.errorCount }}

1. In a "Set" node to combine pinned data with current data:

{
  "apiEndpoint": "{{ $pinData.appConfig.apiUrl }}/{{ $input.item.json.endpoint }}",
  "headers": {
    "Authorization": "Bearer {{ $pinData.credentials.apiToken }}",
    "Content-Type": "application/json"
  }
}

1. In a "Function" node for more complex logic:

// Process items based on pinned configuration
const config = $pinData.processingConfig;
const items = $input.all();

return items.map(item => {
  if (config.enableProcessing) {
    // Apply transformations based on config
    item.json.processed = true;
    
    if (config.applyNormalization) {
      item.json.value = normalizeValue(item.json.value, config.normalizationFactor);
    }
    
    if (item.json.category in config.categoryMappings) {
      item.json.mappedCategory = config.categoryMappings[item.json.category];
    }
  }
  
  return item;
});

function normalizeValue(value, factor) {
  return (value / factor).toFixed(2);
}

These examples demonstrate how pinned data can be used in different contexts within your workflows.

 

Step 11: Sharing Pinned Data Between Workflows

 

One powerful aspect of data pinning is the ability to share data between different workflows:

• Workflow A can pin data that Workflow B can then access
• This creates a simple way to pass information between workflows
• It's useful for creating central configuration workflows that update settings for other workflows

For example, create a "Configuration Manager" workflow that pins updated configuration data, then have other workflows reference this pinned data to always use the latest settings.

 

Step 12: Best Practices for Data Pinning

 

Follow these best practices when using data pinning in n8n:

• Use descriptive names for pinned data to make them easy to identify
• Pin only the specific data you need, not entire node outputs
• Regularly clean up unused pinned data to avoid cluttering your n8n instance
• Document which workflows use which pinned data for easier maintenance
• Use a naming convention for pinned data (e.g., "config_", "cred_", "ref\_" prefixes)
• Be cautious about pinning sensitive information (consider encryption if necessary)
• Create dedicated workflows for updating frequently changed pinned data
• Use version numbers or timestamps in pinned configuration data to track changes

Following these practices will help you maintain a clean and efficient data pinning system in n8n.

 

Step 13: Troubleshooting Data Pinning Issues

 

If you encounter issues with data pinning:

• Verify that the pinned data exists by checking the Pinned Data section in Settings
• Ensure you're using the correct syntax: $pinData.yourPinnedDataName
• Check for typos in pinned data names (they are case-sensitive)
• Make sure you're not trying to access properties that don't exist in your pinned data
• Try accessing top-level pinned data first before drilling down into nested properties
• Use the "Debug" node to check if pinned data is being accessed correctly

For debugging, add a Function node with this code:

// Debug pinned data access
return [
  {
    json: {
      availablePinnedData: Object.keys($pinData || {}),
      myPinnedData: $pinData.yourPinnedDataName || 'Not found',
      fullPinData: $pinData
    }
  }
];

This will help you see what pinned data is available and diagnose access issues.

 

Step 14: Data Pinning Limitations and Considerations

 

Be aware of these limitations when using data pinning:

• Storage limits: While convenient, n8n's database isn't designed for large-scale data storage
• Performance: Accessing very large pinned data structures may impact workflow performance
• Security: Pinned data is stored in the n8n database, so sensitive information should be handled with care
• No automatic cleanup: Pinned data remains until manually deleted
• No versioning: Updating pinned data overwrites the previous version completely
• Instance-specific: Pinned data exists only within a single n8n instance and isn't shared across instances

For large datasets or highly sensitive information, consider using dedicated storage solutions like databases or secret management systems instead.

 

Step 15: Practical Example: Creating a Configuration Manager Workflow

 

Let's put it all together with a complete configuration management system using data pinning:

1. Create a new workflow called "Configuration Manager"
2. Add a "Manual Trigger" node as the starting point
3. Add a "Code" node with the following code:

// Get existing configuration or initialize with defaults
const existingConfig = $pinData.systemConfig || {
  version: 0,
  lastUpdated: null,
  environments: {}
};

// Create updated configuration
const newConfig = {
  version: existingConfig.version + 1,
  lastUpdated: new Date().toISOString(),
  environments: {
    development: {
      apiUrl: 'https://dev-api.example.com',
      timeout: 10000,
      debugMode: true,
      features: ['logging', 'detailed-errors']
    },
    production: {
      apiUrl: 'https://api.example.com',
      timeout: 5000,
      debugMode: false,
      features: ['logging', 'caching', 'rate-limiting']
    },
    ...existingConfig.environments // Preserve any other existing environments
  }
};

return [
  {
    json: {
      systemConfig: newConfig
    }
  }
];

1. Execute the workflow
2. Pin the "systemConfig" data
3. Now create a second workflow called "API Service"
4. Add an "HTTP Request" node configured with pinned data:

• URL: {{ $pinData.systemConfig.environments.production.apiUrl }}/data
• Timeout: {{ $pinData.systemConfig.environments.production.timeout }}
• Headers: Content determined dynamically based on environment

1. Add a "Function" node to implement environment-specific processing:

// Get configuration for current environment
const env = 'production'; // Could be dynamically determined
const config = $pinData.systemConfig.environments[env];
const items = $input.all();

// Apply environment-specific processing
return items.map(item => {
  item.json.processedWith = {
    configVersion: $pinData.systemConfig.version,
    environment: env,
    features: config.features,
    debugMode: config.debugMode
  };
  
  // Apply debug logging if enabled
  if (config.debugMode) {
    console.log('Processing item in debug mode:', item.json);
  }
  
  return item;
});

This example demonstrates a complete configuration management system using data pinning, with a dedicated workflow for updating configurations and another workflow that uses those configurations.

 

Conclusion

 

Data pinning in n8n provides a powerful way to store and access persistent data across workflow executions. By following this guide, you've learned how to pin data, access it using expressions, update it, and implement advanced patterns like key-value stores and configuration management systems. Data pinning is particularly useful for storing configuration settings, credentials, reference data, and creating simple storage mechanisms within n8n itself.

Remember to follow the best practices outlined in this guide to maintain a clean and efficient data pinning system. For larger datasets or highly sensitive information, consider using dedicated storage solutions instead of relying solely on n8n's data pinning capability.