FlowLens Documentation

FlowLens is a workflow debugger for HubSpot. It helps you understand why your workflows didn't behave as expected by capturing checkpoint data and providing intelligent explanations.

Quick Start

git clone https://github.com/umara25/FlowLens.git
cd FlowLens/my-app
npm install
npm run build
npm start

FLOWLENS_HMAC_SECRET=your-secure-secret
HUBSPOT_ACCESS_TOKEN=your-hubspot-private-app-token

cd hubspot-extension
hs auth
hs project upload

Installation

Prerequisites

• Node.js 18+ installed
• A HubSpot account with workflow access
• A HubSpot Private App with CRM deals read scope

Local Development

# Clone the repository
git clone https://github.com/umara25/FlowLens.git
cd FlowLens/my-app

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Edit .env.local with your values
# Then start the dev server
npm run dev

Production Deployment

FlowLens can be deployed to any Node.js hosting platform. We recommend Vercel for the easiest setup.

# Deploy to Vercel
npx vercel

# Or build for other platforms
npm run build
npm start

Configuration

Environment Variables

Creating a HubSpot Private App

1. Go to HubSpot Settings → Integrations → Private Apps
2. Click "Create a private app"
3. Give it a name like "FlowLens"
4. Under Scopes, add crm.objects.deals.read
5. Create the app and copy the access token
6. Add the token to your .env.local file

Workflow Instrumentation

To capture workflow execution data, add Custom Code actions at three key checkpoints in your HubSpot workflow.

Checkpoint Types

Custom Code Template

Add this as a Custom Code action in your HubSpot workflow. Update the checkpoint type and step name for each placement.

const axios = require('axios');
const crypto = require('crypto');

exports.main = async (event, callback) => {
  const FLOWLENS_URL = 'https://your-flowlens-url.com/api/log';
  const FLOWLENS_SECRET = 'your-hmac-secret';
  
  const body = JSON.stringify({
    portalId: event.origin.portalId.toString(),
    workflowId: event.origin.workflowId.toString(),
    objectType: 'deal',
    objectId: event.object.objectId.toString(),
    checkpoint: 'START', // Change to 'BRANCH' or 'ACTION'
    stepName: 'Workflow Started', // Describe this checkpoint
    conditions: {
      // For BRANCH checkpoints, include condition details:
      // property: 'dealstage',
      // op: 'EQ',
      // value: 'contractsent',
      // result: true,
      // actual: event.inputFields['dealstage']
    },
    payload: {
      // Any additional context you want to capture
      dealstage: event.inputFields['dealstage'],
      amount: event.inputFields['amount']
    }
  });

  const signature = crypto
    .createHmac('sha256', FLOWLENS_SECRET)
    .update(body)
    .digest('hex');

  try {
    await axios.post(FLOWLENS_URL, body, {
      headers: {
        'Content-Type': 'application/json',
        'x-flowlens-signature': signature
      }
    });
  } catch (err) {
    console.error('FlowLens logging failed:', err.message);
  }

  callback({ outputFields: {} });
};

HubSpot Sidebar Extension

The HubSpot UI Extension adds a FlowLens debugging card directly inside HubSpot Deal records, allowing you to debug workflows without leaving HubSpot.

Prerequisites

• HubSpot CLI installed globally
• A HubSpot developer account
• FlowLens backend deployed and accessible

1. Install HubSpot CLI

npm install -g @hubspot/cli

2. Authenticate with HubSpot

hs auth

Follow the prompts to authenticate with your HubSpot account.

3. Clone and Configure Extension

git clone https://github.com/umara25/FlowLens.git
cd FlowLens/hubspot-extension

# Edit src/app/extensions/FlowLensCard.jsx
# Update FLOWLENS_API_URL to your deployed URL
# Update workflowId to your workflow ID

4. Deploy to HubSpot

# For development (watches for changes)
hs project dev

# For production deployment
hs project upload

Using the Extension

API Reference

{
  "portalId": "123456",
  "workflowId": "789",
  "objectType": "deal",
  "objectId": "456",
  "checkpoint": "START",
  "stepName": "Workflow Start",
  "conditions": { ... },
  "payload": { ... }
}

{ "ok": true, "id": "uuid" }

{
  "ok": true,
  "summary": "Brief summary of what happened",
  "likely_cause": "The most probable reason for the issue",
  "evidence": [
    "Supporting fact 1",
    "Supporting fact 2"
  ],
  "where": {
    "checkpoint": "BRANCH",
    "stepName": "Check Deal Stage",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "fix": [
    "Suggested fix 1",
    "Suggested fix 2"
  ],
  "debug": {
    "rules_hit": ["BRANCH_CONDITION_FAILED"],
    "missing_data": []
  },
  "meta": {
    "logsAnalyzed": 5,
    "dealFetched": true
  }
}

Explanation Logic

FlowLens uses a rule-based system to analyze checkpoint logs and determine why a workflow didn't behave as expected.

Detection Rules

Troubleshooting