Skip to main content

​
Template Variables

gsTemplate variables in SPIN let you parameterize notebooks with dynamic values, making them more flexible and reusable. Users can customize inputs without modifying the underlying code.

​
Overview

Template variables are defined at the notebook level and can be used in any cell parameter using the {{variable_name}} syntax. When a notebook session starts, template variables are compiled and executed, making their values available for substitution throughout the notebook.

​
Variable Types

SPIN supports three types of template variables:

​
1. Text Input Variables (input)

Text input variables provide a simple text field for user input. 
{
  "name": "search_term",
  "kind": "input",
  "default": "error",
  "description": "Search term for log queries"
}
Properties:
  • name: Variable identifier used in {{variable_name}} substitution
  • kind: Must be "input"
  • default: Default value displayed in the text field
  • description: Helper text shown to users

​
2. Static List Variables (static)

Static list variables provide a dropdown with predefined options. 
{
  "name": "environment",
  "kind": "static",
  "options": ["dev", "staging", "prod"],
  "default": "dev",
  "description": "Target environment"
}
Properties:
  • name: Variable identifier
  • kind: Must be "static"
  • options: Array of string values for the dropdown
  • default: Default selected option
  • description: Helper text

​
3. Dynamic List Variables (code_python)

Dynamic list variables execute Python code to generate dropdown options at runtime. 
{
  "name": "gcp_project",
  "kind": "code_python",
  "code": "import subprocess\nresult = subprocess.run(['gcloud', 'projects', 'list', '--format=value(projectId)'], capture_output=True, text=True)\nprojects = result.stdout.strip().split('\\n')\nprojects",
  "description": "Available GCP projects"
}
Properties:
  • name: Variable identifier
  • kind: Must be "code_python"
  • code: Python code that returns a list of strings
  • description: Helper text
The Python code must return a list of strings to populate the dropdown options.

​
Using Template Variables

​
In Cell Parameters

Substitute template variables in cell parameters using double curly braces: 
{
  "type": "rest",
  "params": {
    "url": "https://api.example.com/search",
    "body": {
      "query": "{{search_term}}",
      "environment": "{{environment}}"
    }
  }
}

​
In Splunk Queries

{
  "type": "logging",
  "connection": "splunk_prod",
  "params": {
    "query": "index=app_logs level=error | search {{search_term}}",
    "earliest": "{{time_range}}"
  }
}

​
In Shell Commands

{
  "type": "shell",
  "params": {
    "argv": "kubectl get pods -n {{namespace}} | grep {{pod_filter}}"
  }
}

​
Advanced Features

​
Connection Variable Substitution

Template variables can reference runtime files and environment variables in connection configurations:
  • {{runtime_file:<path>}}: Replaces with contents of a file in the runtime
  • {{runtime_env:<var>}}: Replaces with environment variable value
  • {{variable_name}}: Standard template variable substitution

​
Auto-Application

Template variables are automatically applied when a notebook session connects. The system:
  1. Compiles template variables into executable Python code
  2. Executes the code in the Jupyter runtime to set variable values
  3. Makes variables available for substitution in cell parameters
  4. Replaces {{variable_name}} patterns with actual values during cell execution

​
Best Practices

​
Naming Conventions

  • Use descriptive names: log_level instead of level
  • Use snake_case for consistency
  • Avoid spaces and special characters

​
Default Values

  • Always provide sensible defaults for better user experience
  • Use common values that work in most scenarios
  • For time ranges, use relative values like -24h, -1d

​
Descriptions

  • Write clear, concise descriptions
  • Explain the purpose and expected format
  • Include examples when helpful

​
Dynamic Variables

  • Keep Python code simple and fast
  • Handle errors gracefully
  • Cache expensive operations when possible
  • Return an empty list [] if no options are available

​
Example: Complete Notebook with Template Variables

{
  "template_vars": [
    {
      "name": "environment",
      "kind": "static",
      "options": ["dev", "staging", "prod"],
      "default": "dev",
      "description": "Target environment"
    },
    {
      "name": "time_range",
      "kind": "input",
      "default": "-1h",
      "description": "Time range for queries (e.g., -1h, -24h)"
    },
    {
      "name": "service_name",
      "kind": "code_python",
      "code": "import requests\nresponse = requests.get('http://service-registry/services')\nservices = response.json()\n[s['name'] for s in services]",
      "description": "Available services"
    }
  ],
  "cells": [
    {
      "type": "logging",
      "connection": "splunk_{{environment}}",
      "params": {
        "query": "index=services service={{service_name}} | head 100",
        "earliest": "{{time_range}}"
      }
    }
  ]
}
This creates a notebook that allows users to select an environment, specify a time range, choose from dynamically-loaded services, and run queries with those parameters automatically substituted.