Skip to content

TEMPLATE_REFERENCE.md

Latest commit

 

History

History
611 lines (495 loc) · 11.7 KB

TEMPLATE_REFERENCE.md

File metadata and controls

611 lines (495 loc) · 11.7 KB
Raw

Template Technical Reference

Complete technical specifications for Local Falcon n8n workflow templates.

JSON Schema

Root Structure

{
  "name": "string",           // Required: Template display name
  "nodes": [],                // Required: Array of node objects
  "connections": {},          // Required: Node connection map
  "pinData": {},              // Optional: Pinned test data
  "meta": {
    "templateCredsSetupCompleted": true
  }
}

Node Types

Local Falcon Node

{
  "parameters": {
    "resource": "string",     // See Resources table
    "operation": "string",    // See Operations table
    // ... operation-specific parameters
  },
  "id": "string",             // Unique node ID
  "name": "string",           // Display name
  "type": "@local-falcon/n8n-nodes-localfalcon.localFalcon",
  "typeVersion": 1,
  "position": [x, y],         // [number, number]
  "credentials": {
    "localFalconApi": {
      "id": "",               // MUST be empty string
      "name": "Local Falcon API"
    }
  }
}

Sticky Note Node

{
  "parameters": {
    "content": "string",      // Markdown content
    "height": number,         // Pixels
    "width": number,          // Pixels
    "color": number           // 0-7, see Color table
  },
  "id": "string",
  "name": "Sticky Note",      // or "Sticky Note1", etc.
  "type": "n8n-nodes-base.stickyNote",
  "typeVersion": 1,
  "position": [x, y]
}

Schedule Trigger Node

{
  "parameters": {
    "rule": {
      "interval": [
        {
          "field": "weeks",   // seconds, minutes, hours, days, weeks, months
          "weeksInterval": 1,
          "triggerAtDay": [1], // 0=Sunday, 1=Monday, etc.
          "triggerAtHour": 9,
          "triggerAtMinute": 0
        }
      ]
    }
  },
  "id": "string",
  "name": "Schedule Trigger",
  "type": "n8n-nodes-base.scheduleTrigger",
  "typeVersion": 1.2,
  "position": [x, y]
}

Manual Trigger Node

{
  "parameters": {},
  "id": "string",
  "name": "Manual Trigger",
  "type": "n8n-nodes-base.manualTrigger",
  "typeVersion": 1,
  "position": [x, y]
}

Webhook Trigger Node

{
  "parameters": {
    "httpMethod": "POST",     // GET, POST, PUT, DELETE
    "path": "unique-path",    // URL path segment
    "responseMode": "onReceived"  // or "lastNode"
  },
  "id": "string",
  "name": "Webhook",
  "type": "n8n-nodes-base.webhook",
  "typeVersion": 2,
  "position": [x, y],
  "webhookId": "unique-webhook-id"
}

Local Falcon Resources & Operations

Account

Operation Parameters Description
getInfo None Returns credits, subscription info 
{
  "resource": "account",
  "operation": "getInfo"
}

Scan

Operation Parameters Description
run platform, keyword, placeId, gridSize, gridDistance, etc. Execute a scan
listReports additionalFields.limit List scan reports 
// Run a scan
{
  "resource": "scan",
  "operation": "run",
  "platform": "google",
  "keyword": "={{ $json.keyword }}",
  "placeId": "={{ $json.placeId }}",
  "gridSize": "3x3",
  "gridDistance": "1"
}

// List reports
{
  "resource": "scan",
  "operation": "listReports",
  "additionalFields": {
    "limit": 50
  }
}

Campaign

Operation Parameters Description
create name, keyword, placeId, platform, etc. Create campaign
list None List all campaigns 
// Create campaign
{
  "resource": "campaign",
  "operation": "create",
  "campaignName": "={{ $json.name }}",
  "keyword": "={{ $json.keyword }}",
  "placeId": "={{ $json.placeId }}",
  "platform": "google"
}

// List campaigns
{
  "resource": "campaign",
  "operation": "list"
}

Location

Operation Parameters Description
search platform, name, proximity Search for locations
save platform, placeId Save location to account 
// Search locations
{
  "resource": "location",
  "operation": "search",
  "platform": "google",
  "name": "Business Name",
  "proximity": "City, State"
}

// Save location
{
  "resource": "location",
  "operation": "save",
  "platform": "google",
  "placeId": "ChIJ..."
}

Report

Operation Parameters Description
listTrend additionalFields List trend reports 
{
  "resource": "report",
  "operation": "listTrend",
  "additionalFields": {
    "limit": 100
  }
}

Falcon Guard

Operation Parameters Description
addLocation placeId Add location to monitoring
listLocations None List monitored locations 
// Add to Falcon Guard
{
  "resource": "falconGuard",
  "operation": "addLocation",
  "placeId": "ChIJ..."
}

// List monitored locations
{
  "resource": "falconGuard",
  "operation": "listLocations"
}

Platform IDs

ID Display Name Use Case
google Google Local Pack Traditional local search rankings
chatgpt ChatGPT OpenAI assistant recommendations
gemini Google Gemini Google's AI assistant
gaio Google AI Overview AI-generated search summaries
grok Grok X/Twitter AI assistant
aimode AI Mode Google's conversational search

Sticky Note Colors

Value Color Use
0 Gray Neutral notes
1 Blue Information
2 Green Success/completed
3 Yellow-Green Caution
4 Orange Warning
5 Yellow Main sticky (REQUIRED)
6 Red Error/alert
7 Pink Special notes

Positioning Constants

Standard Values

// Main sticky note
MAIN_STICKY_POSITION = [100, -180]
MAIN_STICKY_WIDTH = 460
MAIN_STICKY_HEIGHT = 500

// Context sticky (optional, beside main)
CONTEXT_STICKY_POSITION = [580, -180]

// Workflow nodes
NODE_ROW_Y = 440
NODE_SPACING_X = 260

// Step sticky notes
STEP_STICKY_Y = 660  // NODE_ROW_Y + 220
STEP_STICKY_WIDTH = 200
STEP_STICKY_HEIGHT = 100

// Vertical gap between nodes and step stickies
VERTICAL_GAP = 220

Centering Formula

// Center a step sticky under its node
step_sticky_x = node_x - (STEP_STICKY_WIDTH / 2)
// Example: node at x=400, sticky width=200
// step_sticky_x = 400 - 100 = 300

Node Sequence Example

// 4-node workflow horizontal positions
Node1_X = 140
Node2_X = 400   // 140 + 260
Node3_X = 660   // 400 + 260
Node4_X = 920   // 660 + 260

// Corresponding step sticky X positions (width=200)
Sticky1_X = 40   // 140 - 100
Sticky2_X = 300  // 400 - 100
Sticky3_X = 560  // 660 - 100
Sticky4_X = 820  // 920 - 100

Connections Format

{
  "connections": {
    "Source Node Name": {
      "main": [
        [
          {
            "node": "Target Node Name",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Multiple Outputs

For nodes with multiple outputs (like IF):

{
  "IF Node": {
    "main": [
      // Output 0 (true)
      [{ "node": "True Branch", "type": "main", "index": 0 }],
      // Output 1 (false)
      [{ "node": "False Branch", "type": "main", "index": 0 }]
    ]
  }
}

Common Nodes Reference

Set Node

{
  "parameters": {
    "mode": "raw",
    "jsonOutput": "={{ JSON.stringify({ key: 'value' }) }}"
  },
  "type": "n8n-nodes-base.set",
  "typeVersion": 3.4
}

IF Node

{
  "parameters": {
    "conditions": {
      "options": { "caseSensitive": true },
      "conditions": [
        {
          "leftValue": "={{ $json.value }}",
          "rightValue": 5,
          "operator": { "type": "number", "operation": "lt" }
        }
      ]
    }
  },
  "type": "n8n-nodes-base.if",
  "typeVersion": 2
}

Code Node

{
  "parameters": {
    "jsCode": "// JavaScript code here\nreturn items;"
  },
  "type": "n8n-nodes-base.code",
  "typeVersion": 2
}

HTTP Request Node

{
  "parameters": {
    "url": "https://api.example.com/endpoint",
    "method": "POST",
    "sendBody": true,
    "bodyParameters": {
      "parameters": [
        { "name": "key", "value": "={{ $json.value }}" }
      ]
    }
  },
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 4.2
}

Send Email Node

{
  "parameters": {
    "fromEmail": "reports@company.com",
    "toEmail": "={{ $json.recipient }}",
    "subject": "Report Subject",
    "emailType": "html",
    "html": "<h1>Report</h1><p>Content here</p>"
  },
  "type": "n8n-nodes-base.emailSend",
  "typeVersion": 2.1,
  "credentials": {
    "smtp": { "id": "", "name": "SMTP" }
  }
}

Slack Node

{
  "parameters": {
    "resource": "message",
    "operation": "post",
    "channel": { "value": "#channel-name" },
    "text": "Message text"
  },
  "type": "n8n-nodes-base.slack",
  "typeVersion": 2.2,
  "credentials": {
    "slackApi": { "id": "", "name": "Slack API" }
  }
}

Expression Syntax

Basic Expressions

// Access current item data
={{ $json.fieldName }}

// Access nested data
={{ $json.data.nested.value }}

// Access array element
={{ $json.items[0].name }}

Common Functions

// Format date
={{ DateTime.now().toFormat('yyyy-MM-dd') }}

// Conditional
={{ $json.value > 5 ? 'High' : 'Low' }}

// String operations
={{ $json.name.toLowerCase() }}
={{ $json.text.substring(0, 100) }}

// Math
={{ Math.round($json.value * 100) / 100 }}

// JSON
={{ JSON.stringify($json) }}
={{ JSON.parse($json.jsonString) }}

Accessing Previous Nodes

// By node name
={{ $('Node Name').item.json.field }}

// All items from previous node
={{ $('Node Name').all() }}

// First item
={{ $('Node Name').first().json.field }}

Credential Types Reference

Service Credential Key Typical Name
Local Falcon localFalconApi Local Falcon API
Slack slackApi Slack API
Google Sheets googleSheetsOAuth2Api Google Sheets OAuth2
Gmail gmailOAuth2 Gmail OAuth2
SMTP smtp SMTP
HubSpot hubspotApi HubSpot API
Pipedrive pipedriveApi Pipedrive API
Airtable airtableApi Airtable API
Notion notionApi Notion API
Monday.com mondayComApi Monday.com API
Telegram telegramApi Telegram API
Discord discordWebhookApi Discord Webhook
Zoho CRM zohoCrmOAuth2Api Zoho CRM OAuth2
Salesforce salesforceOAuth2Api Salesforce OAuth2
ClickUp clickUpApi ClickUp API
BigQuery googleBigQueryOAuth2Api Google BigQuery OAuth2

ID Generation

Node IDs should be unique and descriptive:

// Sticky notes
"sticky-main"
"sticky-step1"
"sticky-step2"
"sticky-context"

// Workflow nodes (use UUID or descriptive)
"schedule-trigger"
"local-falcon-get-reports"
"format-email"
"send-email"

// Or use UUIDs
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Validation Rules

Required for All Templates

  1. Node type: Must be @local-falcon/n8n-nodes-localfalcon.localFalcon
  2. Credentials: All id fields must be empty strings ""
  3. Main sticky: Must have "color": 5 (yellow)
  4. API URL: Must include https://www.localfalcon.com/api/credentials

JSON Validation

# Validate JSON syntax
cat template.json | jq . > /dev/null

# Check node type
grep "@local-falcon/n8n-nodes-localfalcon" template.json

# Check for non-empty credential IDs
grep -E '"id": "[^"]' template.json | grep -v '""'

# Check for yellow sticky
grep '"color": 5' template.json

See also: Template Guide | Checklist