spida-api 1.0.5

No project description provided

SPIDA FORMS - API Library + Webhook & Form Manager

Overview

This project provides a Webhook & Form Manager for interacting with SPIDA Studio forms. The application allows users to:

• Manage Webhooks: Register and unregister webhooks for form updates.
• Edit Forms: Fetch and update SPIDA forms.
• View Webhook Events: Monitor real-time webhook event logs.

This document provides instructions on how to set up and use the system.

---

API Library

Add to requirements.in

spida-api

# Read SPIDA API values from .env
SPIDA_SERVER = os.getenv("SPIDA_SERVER")
SPIDA_API_KEY = os.getenv("SPIDA_API_KEY")
SPIDA_USERNAME = os.getenv('SPIDA_USERNAME')
SPIDA_PASSWORD = os.getenv('SPIDA_PASSWORD')
SPIDA_COMPANY_ID = os.getenv('SPIDA_COMPANY_ID')

spida_api = SpidaAPI(SPIDA_USERNAME, SPIDA_PASSWORD, SPIDA_SERVER)
spida_api.switch_company(SPIDA_COMPANY_ID)

SPIDA Documentation

• SPIDA Webhook API Docs: SPIDA Webhook API
• Production SPIDA: techserv.spidastudio.com
• Test SPIDA: test-techserv.spidastudio.com

Form Templates

Form Name	Template URL
Oncor Work Order Form (JUMR)	Edit Template 849
Oncor JUFR Work Order Form	Edit Template 951317

---

Installation & Setup

Prerequisites

Ensure you have the following installed:

• Node.js (for local testing, if required)
• Python & Flask (for backend services)

Environment Variables (.env)

Create a .env file in the project root and add the following credentials:

# Admin user for both (Ask Keagan/Logan)
SPIDA_USERNAME=
SPIDA_PASSWORD=
# Oncor
SPIDA_COMPANY_ID=145

# PROD
# SPIDA_SERVER=techserv.spidastudio.com
# SPIDA_API_KEY=

# TEST
SPIDA_SERVER=test-techserv.spidastudio.com
SPIDA_API_KEY=

Running the Server

# Clone the repository
git clone https://github.com/TechServ-Consulting-Training-Ltd/spida_api
cd spida_api

# Install dependencies
pip install -r requirements-dev.txt

# Start the Flask server
python server.py

Running the Web App

The frontend runs directly in the browser using Babel. To start:

# Ensure you are in the project root
python -m http.server 8000

Then, open http://localhost:8000 in your browser.

---

Features & Usage

Manage Webhooks

• View all registered webhooks.
• Register a new webhook by providing a URL, channel, and event regex.
• Unregister existing webhooks.

Example UI for Production:

Example Cloudwatch logs for Production:

To test webhook registrations:

1. Navigate to the test SPIDA manager: Test Project Manager SPIDA UI:
2. Modify a form and submit changes.
3. View logs to verify webhook events.

Webhook Expiration

We have a scheduler that hits a Lambda every 4 hours that refreshes all of our webhooks for another 24 hours.

• Code for Lambda: https://github.com/TechServ-Consulting-Training-Ltd/oncor/blob/staging/src/webhook_lambda_handler.py?#L32
• Lambda function in AWS: https://us-east-1.console.aws.amazon.com/lambda/home?region=us-east-1#/functions/spida_webhook?subtab=triggers&tab=configure
• Event definition: https://us-east-1.console.aws.amazon.com/events/home?region=us-east-1#/eventbus/default/rules/spida_daily_webhook_cron_job
• Lambda Logs: https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:log-groups/log-group/$252Faws$252Flambda$252Fspida_webhook

Edit Forms

• Retrieve a form by entering its Form ID.
• Update form field values and submit changes.
• View API responses directly in the UI.

View Webhook Events

• Monitor incoming webhook events in real-time.
• Uses WebSockets for dynamic updates.

---

Using Ngrok for Webhook Debugging

To test webhooks locally, use ngrok to expose your local server.

ngrok http 5003

Then register https://your-ngrok-url/webhooks as a webhook URL in the SPIDA UI.

---

Example Webhook Payload

{
  "channel": "Form",
  "eventName": "update:TEST_02_14_2025:Oncor Work Order Form",
  "hookId": "257b38c2-2d3b-4d14-b660-22feb8b2417a",
  "payload": {
    "form": {
      "fields": {
        "Email Subject Field": "Oncor Action Required: Need WR Approval in WMIS (WR Number shown below)",
        "Oncor Work Order Name": "3334452",
        "Oncor Work Order Number": "3334452"
      },
      "projectLevelRequiredFor": "PROJECT",
      "template": "849",
      "title": "Oncor Work Order Form"
    },
    "parentId": 15672587,
    "parentName": "TEST_02_14_2025",
    "projectId": 15672587,
    "projectName": "TEST_02_14_2025",
    "user": "[e-mail]"
  },
  "timestamp": 1739905831161
}