Others

• Quotation Request Form (QRF) - broken down
• Step-by-step guide to using the OpenSTAAD API from Python
• Monetary / financial calculations inside your QRF → BOQ automation
• BIM/IFC models for QTO
• GHL
• Integration vCX with GHL
• n8n ↔ Zendesk Web Widget (Classic) – JWT Integration
• MCP -> wiring diagram

Quotation Request Form (QRF) - broken down

1. General project data
   • Project / building name
   • Exact site address (affects wind & seismic codes, freight, taxes)
   • Intended use / occupancy category
   • Required delivery / erection schedule
2. Geometry
   • Clear span width (outside-to-outside of main frames)
   • Building length (number of bays × bay spacing)
   • Eave height (bottom of knee connection to finished floor)
   • Roof slope (e.g., 1:10 or 2:12)
   • Required roof live load (kN/m² or psf)
   • Collateral loads (false ceiling, sprinklers, HVAC, lighting, etc.)
   • Floor live load (if mezzanine is requested)
3. Cladding specification
   • Roof sheeting: single-skin or insulated sandwich panel, thickness, color coating, finish
   • Wall sheeting: same detail as roof, plus liner panel if required
   • Skylight / daylight panels area (if any)
4. Environmental / code parameters
   • Basic wind speed (3-sec gust) or wind pressure
   • Seismic zone / design acceleration
   • Snow load (if applicable)
   • Temperature range for insulation calculation
   • Local building code and edition (IBC, Eurocode, IS 875, ASCE 7, etc.)
5. Structural add-ons
   • Overhead crane: capacity, hook height, class of usage, runway length
   • Mezzanine: area, floor loading, column grid
   • Canopies / lean-tos: width, projection, height
   • Parapet height, fascias, gutters, downpipes
6. Openings & accessories
   • Ridge vent or turbo vent area
   • Roll-up doors: clear opening width × height, quantity
   • Personnel doors: size, location, fire rating
   • Louvers / windows: size and quantity
   • Insulation: roof and/or wall R-value or U-value target
7. Architectural finishes & extras
   • Color chart reference for roof & wall
   • Special coatings (e.g., food-grade, coastal environment)
   • Fire-proofing requirements
   • Internal partitions (if supplied by PEB vendor)
8. Site constraints
   • Maximum truck length allowed to site
   • Crane reach restrictions for unloading / erection
   • Local welding restrictions or pre-approved vendors
9. Commercial terms
   • Scope split (supply-only vs. supply-and-erect)
   • Applicable taxes, duties, freight responsibility
   • Incoterms (EXW, FOB, CIF, DDP, etc.)
   • Payment milestones
   • Performance bond / insurance requirements

Step-by-step guide to using the OpenSTAAD API from Python

1. Install prerequisites

pip install comtypes pywin32 openstaad

2. Launch STAAD.Pro and connect

import subprocess, time, comtypes.client
from pythoncom import CoInitialize, CoUninitialize

CoInitialize()                       # Initialise COM
staad_path = r"C:\Program Files\Bentley\Engineering\STAAD.Pro 2024\STAAD\Bentley.Staad.exe"
subprocess.Popen([staad_path])
time.sleep(8)                        # Wait for STAAD to open

openstaad = comtypes.client.GetActiveObject("StaadPro.OpenSTAAD")

3. Create or open a model

from pathlib import Path
std_file_path = Path.cwd() / "my_model.std"
length_unit = 4   # 4 = metres
force_unit   = 5  # 5 = kN
openstaad.NewSTAADFile(str(std_file_path), length_unit, force_unit)
time.sleep(3)

4. Define material and section

prop = openstaad.Property
prop.SetMaterialName("STEEL")

# European IPE200 section
prop_no = prop.CreateBeamPropertyFromTable(
    country_code=7,        # 7 = European database
    section_name="IPE200",
    type_spec=0,           # single section from table
    add_spec_1=0.0,
    add_spec_2=0.0
)

5. Add nodes and beams

geom = openstaad.Geometry
geom.CreateNode(1, 0, 0, 0)
geom.CreateNode(2, 5, 0, 0)
geom.CreateBeam(1, 1, 2)          # Beam 1: node 1 → node 2
prop.AssignBeamProperty(1, prop_no)

6. Supports and loads

sup = openstaad.Support
sup_no = sup.CreateSupportFixed()
sup.AssignSupportToNode(1, sup_no)
sup.AssignSupportToNode(2, sup_no)

ld = openstaad.Load
case = ld.CreateNewPrimaryLoad("Self-Weight")
ld.SetLoadActive(case)
ld.AddSelfWeightInXYZ(case, -1.0)   # factor −1 in global Y

7. Run the analysis (silent mode)

cmd = openstaad.Command
cmd.PerformAnalysis(6)      # 6 = static analysis
openstaad.SetSilentMode(1)
openstaad.Analyze()
while openstaad.isAnalyzing():
    time.sleep(2)

8. Retrieve results

from openstaad import Output
out = Output()
fx, fy, fz, mx, my, mz = out.GetMemberEndForces(beam=1, start=True, lc=1)
print("Start-end forces:", fx, fy, fz, mx, my, mz)

9. Clean up

openstaad.SaveModel(1)
CoUninitialize()

10. Helper wrappers

pip install openstaad

from openstaad import Geometry, Root
print(Geometry().GetBeamList())
print(Root().GetSTAADFile())

Documentation & Community

• Official docs:
  C:\Program Files\Bentley\Engineering\STAAD.Pro 2024\OSAPP_Help
  (Examples are mainly VB/C++; Python help lives in the Bentley forums.)
• GitHub samples:
  viktor-platform/sample-staad-integration

Monetary / financial calculations inside your QRF → BOQ automation

1. Exact decimal precision (no binary-float rounding surprises).
2. Convenience helpers for currency formatting, FX, amortisation, etc.

1. Core precision → decimal

   from decimal import Decimal, ROUND_HALF_UP
   
   qty   = Decimal('12.50')     # kg
   rate  = Decimal('78.35')     # $/kg
   total = (qty * rate).quantize(Decimal('0.01'), ROUND_HALF_UP)

2. Money wrapper → money or py-moneyed

   from money import Money
   
   unit_price = Money('78.35', 'USD')
   line_total = Money('12.50', 'USD') * unit_price

3. Excel / reporting → openpyxl, xlsxwriter (they both preserve Decimal precision when you write values).
4. Optional extras
   • forex-python – real-time FX rates for multi-currency bids.
   • numpy-financial – NPV, IRR, loan amortisation if you need financing tables.
   • babel – locale-aware currency formatting.

from decimal import Decimal
from openpyxl import Workbook
from money import Money

wb = Workbook()
ws = wb.active
ws.append(['Item', 'Qty (kg)', 'Rate ($)', 'Amount ($)'])

for item, qty, rate in [
        ('Column UC203', Decimal('253.4'), Decimal('1.08')),
        ('Beam UB305', Decimal('417.9'), Decimal('1.08'))]:
    amount = Money(qty * rate, 'USD')
    ws.append([item, float(qty), float(rate), str(amount)])

wb.save('BOQ_financial.xlsx')

BIM/IFC models for QTO

1. Install the core IFC library

pip install ifcopenshell pandas openpyxl

2. Load the IFC file and list every structural element

import ifcopenshell, ifcopenshell.util.element as util
from pathlib import Path

model = ifcopenshell.open(Path("rfx_structural.ifc"))

# Example: grab every IfcBeam, IfcColumn, IfcMember, etc.
elements = (model.by_type("IfcBeam") +
            model.by_type("IfcColumn") +
            model.by_type("IfcMember"))

3. Extract the quantities you need

rows = []
for e in elements:
    # 1. Identity
    name   = e.Name or e.GlobalId
    ifc_ent= e.is_a()

    # 2. Geometry quantities (IfcElementQuantity)
    qs = util.get_psets(e).get("Pset_ElementQuantity", {})
    length_m = float(qs.get("Length", 0))
    weight_kg= float(qs.get("Weight", 0))     # if the modeller exported it
    area_m2  = float(qs.get("SurfaceArea", 0))

    # 3. Material grade (IfcMaterial)
    mat = util.get_material(e)
    grade = mat.Name if mat else "Unknown"

    rows.append({
        "Item"      : name,
        "Type"      : ifc_ent,
        "Material"  : grade,
        "Length_m"  : length_m,
        "Weight_kg" : weight_kg,
        "Area_m2"   : area_m2
    })

4. Build a Pandas DataFrame → instant QTO table

import pandas as pd

df = pd.DataFrame(rows)
# Aggregate identical sections
qto = (df
       .groupby(["Type", "Material"], as_index=False)
       .agg({"Length_m":"sum",
             "Weight_kg":"sum",
             "Area_m2":"sum"}))

5. Export to Excel (ready for BOQ merge)

qto.to_excel("IFC_QTO.xlsx", index=False)

6. Optional: validate IFC quality first

7. Handling federated models (multiple IFC files)

• BIMvision → IFC Merge plugin (permanent merge), or
• IfcOpenShell (memory merge) if you want to stay in Python.

8. When IFC lacks quantities

import ifcopenshell.geom as geom
settings = geom.settings()
shape = geom.create_shape(settings, e)
volume = shape.geometry.volume

9. Keep the workflow MVD-compliant

Summary of the integration pattern

GHL

Integration vCX with GHL

✅ Recommended Architecture

1. Push vCX Conversations into GHL

• Create or update a Contact using clientId as the unique identifier
• Create a Conversation under that contact
• Add each message as a Message object inside the conversation

All of this is supported via POST /conversations/{id}/messages and related endpoints .

2. Pull GHL Replies into vCX

• message.incoming
• conversation.updated

OAuth 2.0 is now required for all new integrations, so you’ll need to register your app in GHL’s Developer Portal .

🔑 Key GHL API Docs You’ll Need

vCX ↔ GoHighLevel – Two-Way Chat Sync (Node.js)

package.json (excerpt)

{
  "type": "module",
  "dependencies": {
    "axios": "^1.6.0",
    "dotenv": "^16.3.1",
    "express": "^4.18.2"
  }
}

npm install

server.js (top)

import 'dotenv/config';
import express from 'express';
import axios from 'axios';
import crypto from 'crypto';
const app = express();
app.use(express.json());

const PORT = process.env.PORT || 3000;

/* --- In-memory maps for demo purposes --- */
const tokenStore = new Map();          // locationId -> {access_token, refresh_token, expires_at}
const conversationMap = new Map();     // vcxConversationId -> ghlConversationId

app.listen(PORT, () => console.log(`Listening on :${PORT}`));

GET /install

app.get('/install', (req, res) => {
  const state = crypto.randomUUID();
  const url = `https://marketplace.gohighlevel.com/oauth/chooselocation?response_type=code&client_id=${process.env.GHL_CLIENT_ID}&redirect_uri=${encodeURIComponent(process.env.GHL_REDIRECT_URI)}&scope=contacts.write%20conversations.write%20conversations.read%20locations.read&state=${state}`;
  res.redirect(url);
});

GET /auth/callback

app.get('/auth/callback', async (req, res) => {
  const { code, locationId } = req.query;
  const { data } = await axios.post('https://services.leadconnectorhq.com/oauth/token', {
    client_id: process.env.GHL_CLIENT_ID,
    client_secret: process.env.GHL_CLIENT_SECRET,
    grant_type: 'authorization_code',
    code,
    redirect_uri: process.env.GHL_REDIRECT_URI
  });
  tokenStore.set(locationId, {
    access_token: data.access_token,
    refresh_token: data.refresh_token,
    expires_at: Date.now() + data.expires_in * 1000
  });
  res.send(`Sub-account ${locationId} connected.`);
});

async function getToken(locationId) {
  let t = tokenStore.get(locationId);
  if (!t) throw new Error('Location not authorized');

  if (Date.now() > t.expires_at - 60_000) {
    const { data } = await axios.post('https://services.leadconnectorhq.com/oauth/token', {
      client_id: process.env.GHL_CLIENT_ID,
      client_secret: process.env.GHL_CLIENT_SECRET,
      grant_type: 'refresh_token',
      refresh_token: t.refresh_token
    });
    t = {
      access_token: data.access_token,
      refresh_token: data.refresh_token,
      expires_at: Date.now() + data.expires_in * 1000
    };
    tokenStore.set(locationId, t);
  }
  return t.access_token;
}

POST /contact

app.post('/contact', async (req, res) => {
  const { locationId, clientId, email, phone, name } = req.body;
  const token = await getToken(locationId);

  // Search by externalId first
  const search = await axios.get(`https://rest.gohighlevel.com/v1/contacts/?query=${clientId}&locationId=${locationId}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
  let contactId = search.data.contacts?.[0]?.id;

  if (!contactId) {
    const { data } = await axios.post('https://rest.gohighlevel.com/v1/contacts/', {
      locationId,
      name,
      email,
      phone,
      source: 'vCX',
      tags: ['vCX'],
      customFields: [{ id: 'clientId', value: clientId }]
    }, { headers: { Authorization: `Bearer ${token}` } });
    contactId = data.contact.id;
  }
  res.json({ contactId });
});

POST /push-message

app.post('/push-message', async (req, res) => {
  const { locationId, clientId, vcxConversationId, fromUser, body, timestamp } = req.body;
  const token = await getToken(locationId);

  // 1. Ensure contact
  const { contactId } = (await axios.post(`http://localhost:${PORT}/contact`, {
    locationId, clientId, email: `${clientId}@example.com`, name: clientId
  })).data;

  // 2. Ensure conversation
  let ghlConvId = conversationMap.get(vcxConversationId);
  if (!ghlConvId) {
    const { data } = await axios.post('https://rest.gohighlevel.com/v1/conversations/', {
      locationId,
      contactId,
      type: 'chat'
    }, { headers: { Authorization: `Bearer ${token}` } });
    ghlConvId = data.conversation.id;
    conversationMap.set(vcxConversationId, ghlConvId);
  }

  // 3. Push message
  await axios.post(`https://rest.gohighlevel.com/v1/conversations/${ghlConvId}/messages`, {
    type: fromUser ? 'Inbound' : 'Outbound',
    message: body,
    dateAdded: new Date(timestamp).toISOString()
  }, { headers: { Authorization: `Bearer ${token}` } });

  res.sendStatus(200);
});

POST /webhook

app.post('/webhook', (req, res) => {
  const { type, locationId, conversationId, message } = req.body;

  if (type !== 'message.incoming') return res.sendStatus(200);

  // Reverse lookup
  let vcxConvId;
  for (const [vId, gId] of conversationMap.entries()) {
    if (gId === conversationId) vcxConvId = vId;
  }
  if (!vcxConvId) return res.sendStatus(200);

  // TODO: forward to vCX backend
  console.log('Forward to vCX:', { vcxConversationId: vcxConvId, fromUser: false, body: message, timestamp: Date.now() });

  res.sendStatus(200);
});

# 1. Start your server
node server.js

# 2. Install the app (open in browser)
open http://localhost:3000/install

# 3. Push a message
curl -X POST http://localhost:3000/push-message \
  -H "Content-Type: application/json" \
  -d '{"locationId":"LOC_ID","clientId":"c_abc123","vcxConversationId":"conv_456","fromUser":true,"body":"Hello from vCX","timestamp":1710000000000}'

Last updated 2024-07-20

n8n ↔ Zendesk Web Widget (Classic) – JWT Integration

Goal
Allow visitors authenticated through your n8n chat front-end to start a Zendesk Web Widget session, while still requiring a human agent to approve any ticket creation.

1. Prerequisites

2. High-Level Flow

1. Visitor loads your web-chat.
2. Front-end requests a JWT from n8n.
3. n8n signs and returns the JWT.
4. Zendesk Web Widget starts an authenticated chat session.
5. Human-in-the-Loop still controls ticket creation (Wait node).

3. n8n Endpoints

3.1 JWT Issuer (POST /webhook/zendesk-jwt)

Workflow Steps

Example cURL

curl -X POST \
  'https://your-n8n.com/webhook/zendesk-jwt?user_token=abc123' \
  -H 'Content-Type: application/json'

{"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

3.2 Optional Token Generator for Front-End (GET /webhook/chat-token)

4. Zendesk Configuration

5. Front-End Snippet

<script>
  // Replace with your n8n endpoint if you created /webhook/chat-token
  fetch('/api/n8n/get-chat-token', { credentials: 'include' })
    .then(r => r.json())
    .then(({ jwt }) => {
      zE('webWidget', 'chat:setJwtFn', callback => callback(jwt));
    });
</script>

If you let Zendesk call your endpoint directly, omit the fetch and simply use the JWT URL configured above.

6. Human-in-the-Loop Remains Intact

7. Security Checklist

• [ ] HTTPS only (n8n & Zendesk endpoints).
• [ ] Rotate Shared Secret periodically → update both Zendesk and n8n JWT node.
• [ ] Log every JWT issuance (iat, IP, user_token).
• [ ] Validate user_token strictly; deny unknown tokens immediately.

8. Troubleshooting Quick-Table

9. Change Log

MCP -> wiring diagram

• a React/JS chat UI
• talk to your existing backend over the WebSocket wss://backend.chatbuilder.com/events/listen
• which forwards every user sentence to your Node orchestrator (the “bot”)
• that hosts an LLM (Anthropic or OpenAI) and an MCP client
• which calls an MCP server (also Node) that owns the Airtable CRUD helpers
• and finally ships the answer back the same chain.

1. Component map

• The bot keeps the LLM API key and the MCP client.
• The MCP server only knows Airtable PAT + base ID and exports tools like
  airtable:select_records, airtable:create_record, …
• Both services are Dockerised and scale horizontally.

2. Airtable MCP server (Node, SSE transport)

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";
import Airtable from "airtable";
import "dotenv/config";

const app = express();
app.use(express.json());

const port = process.env.PORT || 8001;
const base = new Airtable({apiKey: process.env.AIRTABLE_PAT})
               .base(process.env.AIRTABLE_BASE_ID);

// 1. describe tools
const tools = [
  {
    name: "airtable:select_records",
    description: "List records from a table",
    inputSchema: {
      type: "object",
      properties: {
        table:   { type: "string" },
        filter:  { type: "string" },
        maxRecords: { type: "number", default: 10 }
      },
      required: ["table"]
    }
  },
  {
    name: "airtable:create_record",
    description: "Insert one record",
    inputSchema: {
      type: "object",
      properties: {
        table: { type: "string" },
        fields: { type: "object" }
      },
      required: ["table", "fields"]
    }
  }
];

// 2. instantiate MCP server
const server = new Server(
  { name: "airtable-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({ tools }));
server.setRequestHandler("tools/call", async (req) => {
  const { name, arguments: args } = req.params;
  if (name === "airtable:select_records") {
    const recs = await base(args.table)
      .select({ maxRecords: args.maxRecords || 10, filterByFormula: args.filter || "" })
      .all();
    return { 
      records: recs.map(r => ({ id: r.id, fields: r.fields })) 
    };
  }
  if (name === "airtable:create_record") {
    const created = await base(args.table).create([{ fields: args.fields }]);
    return { id: created[0].id };
  }
  throw new Error("Unknown tool");
});

// 3. expose SSE endpoints
app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/message", res);
  await server.connect(transport);
});

app.post("/message", (req, res) => {
  const transport = SSEServerTransport.get(req.query.sessionId);
  if (transport) transport.handlePostMessage(req, res);
});

app.listen(port, () => console.log(`Airtable MCP listening on :${port}`));

AIRTABLE_PAT=patXXXXXXXXXXX  
AIRTABLE_BASE_ID=appXXXXXXXXXXX  

3. Bot/orchestrator (Node, hosts LLM + MCP client)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
import axios from "axios";
import express from "express";
import "dotenv/config";

const app = express();
app.use(express.json());

// 1. connect MCP client to airtable server
const mcp = new Client({ name: "chat-bot", version: "1.0.0" });
const transport = new SSEClientTransport("http://localhost:8001/sse");
await mcp.connect(transport);
const tools = await mcp.listTools();

// 2. small helper: talk to LLM
async function callLLM(messages) {
  const body = {
    model: process.env.LLM_MODEL,        // "claude-3-5-sonnet-20241022" or "gpt-4-turbo"
    messages,
    tools: tools.map(t => t.inputSchema ? { ...t, function: t.inputSchema } : t),
    tool_choice: "auto",
    max_tokens: 2000
  };

  const url = process.env.LLM_PROVIDER === "anthropic"
    ? "https://api.anthropic.com/v1/messages"
    : "https://api.openai.com/v1/chat/completions";

  const headers = process.env.LLM_PROVIDER === "anthropic"
    ? { "x-api-key": process.env.ANTHROPIC_KEY, "content-type": "application/json" }
    : { "authorization": `Bearer ${process.env.OPENAI_KEY}`, "content-type": "application/json" };

  const { data } = await axios.post(url, body, { headers });
  return data;     // returns Claude or OpenAI shape
}

// 3. single HTTP endpoint that backend.chatbuilder.com will call
app.post("/handle_turn", async (req, res) => {
  const userSentence = req.body.text;          // comes from backend via HTTP
  const conversation = [{ role: "user", content: userSentence }];

  // first LLM call
  let llmResp = await callLLM(conversation);
  let assistantMsg = llmResp.content || llmResp.choices[0].message;

  // handle tool calls
  if (assistantMsg.tool_calls || assistantMsg.function_call) {
    const toolCalls = assistantMsg.tool_calls || [assistantMsg.function_call];
    for (const tc of toolCalls) {
      const name = tc.function?.name || tc.name;
      const args = JSON.parse(tc.function?.arguments || tc.arguments);
      const result = await mcp.callTool(name, args);
      conversation.push(assistantMsg);
      conversation.push({ role: "tool", tool_call_id: tc.id, content: JSON.stringify(result) });
    }
    // second call with tool results
    llmResp = await callLLM(conversation);
    assistantMsg = llmResp.content || llmResp.choices[0].message;
  }

  const replyText = assistantMsg.content || assistantMsg.text || assistantMsg;
  res.json({ reply: replyText });   // goes back to backend.chatbuilder.com
});

app.listen(3000, () => console.log("Bot/orchestrator on :3000"));

LLM_PROVIDER=anthropic        # or openai  
ANTHROPIC_KEY=sk-ant-xxx  
OPENAI_KEY=sk-xxx  
LLM_MODEL=claude-3-5-sonnet-20241022   # or gpt-4-turbo  

4. Glue inside backend.chatbuilder.com

// when a message arrives from UI
ws.on('message', async (data) => {
  const { text, userId } = JSON.parse(data);
  // forward to bot/orchestrator
  const { data: { reply } } = await axios.post(
    "http://bot-service:3000/handle_turn",
    { text, userId }
  );
  // send answer back to same websocket
  ws.send(JSON.stringify({ type: "bot_reply", text: reply }));
});

5. One-shot docker-compose for local dev

version: "3.8"
services:
  airtable-mcp:
    build: ./airtable-mcp
    ports: ["8001:8001"]
    env_file: ./airtable-mcp/.env
  bot:
    build: ./bot
    ports: ["3000:3000"]
    env_file: ./bot/.env
    depends_on: [airtable-mcp]

6. What you gained

• Chat UI ⇄ WSS stays untouched.
• Backend.chatbuilder.com only needs to forward text to the bot service; no Airtable keys, no LLM keys, no MCP logic.
• Airtable CRUD lives in its own container; expose extra tools (update, delete, linked tables, …) by editing only the MCP server.
• Swap Anthropic ↔ OpenAI by changing one env var.
• Add Google-Calendar MCP server on port 8002, register it in the bot startup loop—zero other changes.