/catalyst-smartbrowz

Catalyst SmartBrowz — Browser Automation & Document Generation Basics

Catalyst SmartBrowz is a cloud-based browser service that enables headless browser automation, visual document generation, and parallel browser operations. All remote browsers run securely in Catalyst's cloud environment.

What is Catalyst SmartBrowz?

SmartBrowz provides 6 independent components in a unified platform:

1. Headless — Connect to remote Chrome/Firefox with Puppeteer, Playwright, or Selenium
2. Browser Logic — Serverless functions for browser automation (Java/Node.js)
3. PDF & Screenshot — Generate visual documents from webpages
4. Templates — Design and store templates for dynamic content
5. Browser Grid (Early Access) — Parallel headless browsers with auto-scaling
6. Dataverse — Data scraping APIs

Current browser support:

• Headless & Browser Logic: Chrome only
• Browser Grid: Chrome (v137.0.7151.55) and Firefox (v136.0.4)

Component 1: Headless

Connect to a remote browser in Catalyst cloud environment using popular automation libraries.

Supported Automation Libraries

• Puppeteer — Node.js library for Chrome DevTools Protocol
• Playwright — Cross-browser automation (connects via CDP)
• Selenium — WebDriver-based automation

Setup Steps

1. Console → SmartBrowz → Headless
2. Configure Remote Browser Options:
   • Memory: Select memory allocation for remote browser
   • Browser Version: Chrome version (currently only Chrome supported)
3. Copy Endpoints:
   • CDP Endpoint (for Puppeteer/Playwright)
   • Webdriver Endpoint (for Selenium)
4. Copy API Key from "View Key" option
5. Copy Code Snippets in Java, Node.js, or Python

Connection Code Snippets

Puppeteer (Node.js)

const puppeteer = require('puppeteer-core');

(async () => {
  // Connect using only the CDP endpoint — no api-key header needed
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'YOUR_CDP_ENDPOINT'
  });
  
  const page = await browser.newPage();
  await page.goto('https://example.com');
  // Your automation logic here
  
  await browser.disconnect();
})();

Playwright (Node.js)

const pw = require('playwright-core');

(async () => {
  // Connect using only the CDP endpoint — no api-key needed
  const browser = await pw.chromium.connectOverCDP('YOUR_CDP_ENDPOINT');
  const context = browser.contexts().length ? browser.contexts()[0] : await browser.newContext();
  const page = await context.newPage();
  
  await page.goto('https://example.com');
  // Your automation logic here
  
  await browser.close();
})();

Selenium (Java)

import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--headless");

// Connect using only the Webdriver endpoint — no api-key capability needed
RemoteWebDriver driver = new RemoteWebDriver(
    new URL("YOUR_WEBDRIVER_ENDPOINT"),
    options
);

driver.get("https://example.com");
// Your automation logic here

driver.quit();

Code Recipes

Console provides pre-built Code Recipes for testing automation libraries. Access them in Console → SmartBrowz → Headless → Code Recipes.

Example recipes:

• Web page navigation
• Form filling
• Screenshot capture
• Element interaction
• Data extraction

Component 2: Browser Logic

Browser Logic is a Serverless Function type for browser automation tasks. Unlike regular functions, Browser Logic functions are created via CLI and contain a specialized structure for browser operations.

Supported Languages

• Java
• Node.js

NOT Python — Browser Logic currently does not support Python.

Creating Browser Logic Functions

Via CLI (required for initial creation):

# Initialize project
catalyst init

# Create Browser Logic function
catalyst functions:create
# Select: Browser Logic
# Enter function name
# Select runtime: Java or Node.js

# Function structure is auto-generated

Function Structure (Node.js — Puppeteer):

// index.js — boilerplate generated by CLI
// 'page' is the Puppeteer Page object injected by SmartBrowz — do NOT connect manually
module.exports.puppeteer = async (request, response, page) => {
  await page.goto('https://example.com/', { waitUntil: 'domcontentloaded' });
  const pageTitle = await page.title();
  response.setHeader('Content-Type', 'application/json');
  response.write(JSON.stringify({ output: pageTitle }));
  response.end();
};

Function Structure (Java — Selenium):

// Boilerplate generated by CLI for Java + Selenium
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.openqa.selenium.chrome.ChromeDriver;
import com.catalyst.browserlogic.SeleniumHandler;
import org.json.simple.JSONObject;

public class BrowserLogicExample implements SeleniumHandler {
  @Override
  public void runner(HttpServletRequest request, HttpServletResponse response,
                     ChromeDriver driver) throws Exception {
    JSONObject responseData = new JSONObject();
    driver.get("https://www.example.com");
    responseData.put("message", "Title: " + driver.getTitle());
    response.setContentType("application/json");
    response.getWriter().write(responseData.toString());
    response.setStatus(200);
  }
}

The page (Node.js) and ChromeDriver driver (Java) are injected by SmartBrowz — you do not connect to the browser manually inside Browser Logic functions.

Deploying Browser Logic Functions

From CLI:

# Test locally
catalyst serve

# Deploy to console
catalyst deploy --only functions:browser_logic_function_name

From Console: You can also upload a Browser Logic function directly to Console → SmartBrowz → Browser Logic → Upload Function.

Browser Logic vs Regular Functions

Component 3: PDF & Screenshot

Generate visual documents from webpages programmatically.

Input Formats

1. HTML — Provide raw HTML string
2. URL — Provide webpage URL
3. Template — Use pre-designed templates with dynamic data

Output Formats

• PDF — Generate PDF document
• Screenshot — Generate image (PNG/JPEG) with device viewport options

Console Playground

Console → SmartBrowz → PDF & Screenshot → Playground

Test document generation directly in console:

1. Select Input Type: HTML, URL, or Template
2. Provide input
3. Select Output Type: PDF or Screenshot
4. Configure options (page size, margins, device viewport)
5. Click Generate

SDK Usage

Java SDK

import com.zc.component.smartbrowz.ZCSmartBrowz;
import com.zc.component.smartbrowz.ZCSmartBrowzConvertDetails;
import com.zc.component.smartbrowz.ZCSmartBrowzPDFOptions;
import com.zc.component.smartbrowz.ZCSmartBrowzNavigationOptions;
import com.zc.component.smartbrowz.ZCSmartBrowzPageOptions;
import com.zc.component.smartbrowz.beans.MarginDetails;
import java.io.InputStream;

ZCSmartBrowz smartBrowz = ZCSmartBrowz.getInstance();

// Convert to PDF from HTML
ZCSmartBrowzConvertDetails convertDetails = ZCSmartBrowzConvertDetails.getInstance();
ZCSmartBrowzPDFOptions pdfOptions = ZCSmartBrowzPDFOptions.getInstance();
pdfOptions.setFormat("A4");
MarginDetails margin = new MarginDetails();
margin.setTop("10"); margin.setBottom("10");
margin.setLeft("10"); margin.setRight("10");
pdfOptions.setMargin(margin);
pdfOptions.setPrintBackground(true);
ZCSmartBrowzNavigationOptions navOptions = new ZCSmartBrowzNavigationOptions();
navOptions.setWaitUntil("domcontentloaded");
navOptions.setTimeout(30000);
convertDetails.setPdfDetails(pdfOptions);
convertDetails.setNavigationDetails(navOptions);
convertDetails.setHtml("<html>Hello</html>");
InputStream outputStream = smartBrowz.convertToPdf(convertDetails);

// Convert to PDF from URL
convertDetails.setUrl("https://example.com");
InputStream outputStream = smartBrowz.convertToPdf(convertDetails);

// Generate from Template
import com.zc.component.smartbrowz.ZCSmartBrowzTemplateOptions;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

ObjectMapper mapper = new ObjectMapper();
JsonNode templateData = mapper.createObjectNode();
((ObjectNode) templateData).put("name", "John Doe");
ZCSmartBrowzTemplateOptions templateOptions = ZCSmartBrowzTemplateOptions.getInstance();
templateOptions.setPdfDetails(pdfOptions);
templateOptions.setNavigationDetails(navOptions);
templateOptions.setTemplateInput(templateData);
templateOptions.setTemplateId(2075000000021001L);
InputStream outputStream = smartBrowz.generateFromTemplate(templateOptions);

Node.js SDK

const smartbrowz = app.smartbrowz();

// Generate PDF from HTML
const result = await smartbrowz.convertToPdf('<html>Hello</html>', {
  pdf_options: {
    format: 'A4',
    margin: { top: '20', bottom: '20', left: '10', right: '10' },
    landscape: false,
    print_background: true,
    scale: 1.0
  },
  page_options: {
    javascript_enabled: true,
    viewport: { height: 800, width: 600 }
  },
  navigation_options: {
    timeout: 30000,
    wait_until: 'domcontentloaded'
  }
});

// Generate PDF from URL — same method, pass URL string instead of HTML
const result = await smartbrowz.convertToPdf('https://example.com', { pdf_options: { format: 'A4' } });

// Generate from Template
const result = await smartbrowz.generateFromTemplate('2075000000021001', {
  pdf_options: { format: 'A4', landscape: false },
  page_options: { javascript_enabled: true },
  navigation_options: { timeout: 30000, wait_until: 'domcontentloaded' },
  output_options: { output_type: 'pdf' },
  template_data: { name: 'John Doe', course: 'Web Dev' }
});

Python SDK

smart_browz = app.smart_browz()

# Convert to PDF from HTML
result = smart_browz.convert_to_pdf(
    '<h1>Welcome</h1>',
    pdf_options={
        'format': 'A4',
        'scale': 1,
        'display_header_footer': True,
        'print_background': False,
        'landscape': False,
    },
    page_options={
        'css': {'content': 'body { font-size: 12px; }'},
        'viewport': {'width': 1440, 'height': 900},
        'javascript_enabled': True,
    },
    navigation_options={'timeout': 5000, 'wait_until': 'networkidle0'},
)

# Convert to PDF from URL — same method, pass URL string
result = smart_browz.convert_to_pdf('https://catalyst.zoho.com/', pdf_options={'format': 'A4'})

# Take a screenshot from URL
output_screenshot = smart_browz.take_screenshot(
    source='https://example.com',
    output_options={'output_type': 'screenshot'},
    screenshot_options={
        'type': 'jpeg',
        'quality': 100,
        'full_page': False,
    },
    page_options={
        'viewport': {'width': 1440, 'height': 900},
        'javascript_enabled': True,
    },
    navigation_options={'timeout': 5000, 'wait_until': 'networkidle0'},
)

# Generate from Template
result = smart_browz.generate_from_template(
    '153000000009001',  # template ID
    template_data={'name': 'John Doe'},
    output_options={'output_type': 'pdf'},
    pdf_options={'format': 'A4', 'scale': 1},
    navigation_options={'timeout': 5000, 'wait_until': 'networkidle0'},
)

API Usage

OAuth scope required: ZohoCatalyst.pdfshot.EXECUTE

# Generate PDF from HTML or URL
curl -X POST '{api-domain}/browser360/v1/project/{project_id}/convert' \
  -H 'Authorization: Zoho-oauthtoken {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "format": "A4",
    "print_background": true,
    "margin": { "top": "10", "bottom": "10", "left": "10", "right": "10" }
  }'

Component 4: Templates

Design and store templates for generating multiple documents with dynamic content.

Creating Templates

1. Console → SmartBrowz → Templates → Create Template
2. Design using HTML/CSS:
   • Use standard HTML5 tags
   • Style with inline CSS or <style> tag
   • Add placeholders for dynamic data: {{variable_name}}
3. Save Template with a unique name

Template Example

<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: Arial; padding: 20px; }
    h1 { color: #333; }
    .info { margin: 10px 0; }
  </style>
</head>
<body>
  <h1>Certificate of Achievement</h1>
  <div class="info">
    <p>This certifies that <strong>{{student_name}}</strong></p>
    <p>has successfully completed <strong>{{course_name}}</strong></p>
    <p>on {{completion_date}}</p>
  </div>
</body>
</html>

Using Templates

Generate PDF with dynamic data (Node.js):

const smartbrowz = app.smartbrowz();

const result = await smartbrowz.generateFromTemplate('2075000000021001', {
  output_options: { output_type: 'pdf' },
  pdf_options: { format: 'A4' },
  template_data: {
    student_name: 'John Doe',
    course_name: 'Web Development',
    completion_date: '2026-06-29'
  }
});

Use cases:

• Certificates and diplomas
• Invoices and receipts
• Reports with dynamic data
• Marketing materials
• Personalized documents

Component 5: Browser Grid (Early Access)

Run multiple headless browsers in parallel with auto-scaling.

Note: This feature is in Early Access. Contact support@zohocatalyst.com to enable it.

What is Browser Grid?

Browser Grid allows you to configure and run multiple headless browsers concurrently across multiple nodes (virtual machines). The Hub (controller) automatically spawns nodes and browsers based on your configuration and request load.

Architecture:

Hub (Controller) → Nodes (VMs) → Browsers (Headless Chrome/Firefox)

Browser Grid Configurations

1. Basic Configuration

• Nodes: 1-10 nodes
• Memory per node: 1 GiB
• vCPU per node: 1
• Browsers per node: 1
• Max concurrent browsers: 10

Best for: Light request loads, simple automation tasks

2. Advanced Configurations

Light Node Type (1 GiB Memory, 1 vCPU)

• Nodes: 1-10 nodes
• Browsers per node: 1
• Max concurrent browsers: 10

Moderate Node Type (2 GiB Memory, 2 vCPU)

• Nodes: 1-5 nodes
• Browsers per node: 1-2
• Max concurrent browsers: 10

Heavy Node Type (4 GiB Memory, 4 vCPU)

• Nodes: 1-2 nodes
• Browsers per node: 1-4
• Max concurrent browsers: 8

Best for: Heavy request loads, complex automation tasks requiring more processing power

Configuration Comparison Table

Creating a Browser Grid

1. Console → SmartBrowz → Browser Grid → Create Browser Grid
2. Select Endpoint Type:
   • CDP Endpoint (for Puppeteer/Playwright)
   • Webdriver Endpoint (for Selenium)
3. Choose Configuration:
   • Basic
   • Advanced: Light / Moderate / Heavy
4. Configure Nodes and Browsers based on selected configuration
5. Click Create

Default Browser Grids: When you first access Browser Grid, two pre-configured grids are provided:

• Puppeteer_Grid — CDP endpoint, Basic configuration
• Selenium_Grid — Webdriver endpoint, Basic configuration

Connecting to Browser Grid

Connection code is identical to Headless, but uses the Browser Grid endpoint:

Puppeteer

const puppeteer = require('puppeteer-core');

(async () => {
  // Connect using only the Browser Grid CDP endpoint — no api-key header needed
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'YOUR_BROWSER_GRID_CDP_ENDPOINT'
  });
  
  const page = await browser.newPage();
  await page.goto('https://example.com');
  
  await browser.disconnect();
})();

Selenium

import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--headless");

// Connect using only the Webdriver endpoint — no api-key capability needed
RemoteWebDriver driver = new RemoteWebDriver(
    new URL("YOUR_BROWSER_GRID_WEBDRIVER_ENDPOINT"),
    options
);

driver.get("https://example.com");
driver.quit();

Browser Grid Workflow

1. User connects to Browser Grid via code
2. Hub receives request and checks for available node
3. If node available → Request sent to browser in node
4. If no node available:
   • If node limit not reached → Hub creates new node with browser
   • If node limit reached → Request is queued
5. Queue duration:
   • Selenium: 30 seconds
   • Puppeteer/Playwright: 5 minutes
6. After queue timeout → Request is killed, alert raised

Browser Grid States

• Inactive — Default state after creation, grid not processing requests
• Active — Grid connected via code, nodes and browsers spawning as needed
• Idle — Grid active but no requests being processed, all nodes/browsers scaled down

Browser Grid Alerts

Alerts appear in Console → SmartBrowz → Browser Grid → {grid_name} → Dashboard → Alerts

Clearing Alerts: Alerts persist until you update the grid configuration. Resolving the underlying issue doesn't automatically clear alerts.

Browser Grid Dashboard

Console → SmartBrowz → Browser Grid → {grid_name} → Dashboard

Real-time stats:

• Number of nodes running
• Number of browsers spawned
• Max and average CPU core usage
• Max and average memory usage
• Alert history

Performance Graphs:

• Node creation timeline
• Browser spawn timeline
• CPU usage over time
• Memory usage over time

Refresh button — Click to update stats to latest values

Ideal Practices for Browser Grid

1. Right-size your configuration — Don't over-provision. Start with Basic, scale up only if needed.

2. Check free sessions before sending requests — Use the Browser Grid SDK to manage grid lifecycle, then use the REST API to check free_sessions (no SDK equivalent exists for this specific stat):

   SDK — manage grid (Node.js):

   const grid = app.smartbrowz().browserGrid();
   
   // Get all grids and their details
   const gridList = await grid.getGrid();
   
   // Get node details for a specific grid
   const nodeDetails = await grid.getGridNodes('YOUR_GRID_ID');
   
   // Stop grid when done
   await grid.stopGrid('YOUR_GRID_ID');

   REST API — check free sessions before connecting (api-key required here):

   curl 'https://console.catalyst.zoho.com/browser360/v1/project/{project_id}/browser-grid/{grid_id}/stats?data_to_fetch=live_stats' \
   -H 'api-key: YOUR_API_KEY'

   Response:

   {
     "status": "success",
     "data": {
       "free_sessions": 10
     }
   }

   If free_sessions: 0, wait until at least 1 browser is available before connecting.

   ⚠️ The api-key header is only required for REST API calls like this one. It is not used when connecting via Puppeteer/Playwright/Selenium — those use only the endpoint URL.

3. Monitor alerts — Regularly check Dashboard for alerts. Address issues before they cause request failures.

4. Test with small loads first — Validate your configuration with small request volumes before scaling up.

5. Stop grid when not in use — Browser Grid is auto-scaling, but stopping it completely when idle saves resources. Use grid.stopGrid('YOUR_GRID_ID') via SDK.

Regenerating API Key

Console → Browser Grid → {grid_name} → Overview → Regenerate

Consequences:

• Grid must be Inactive to regenerate key
• All grid stats are reset
• You must update your code with new endpoint/key
• Reconnection is treated as first request

Component 6: Dataverse

Dataverse is a SmartBrowz component for data extraction from the web. It provides three modules via Node.js SDK:

Lead Enrichment — getEnrichedLead()

Fetches publicly available details about an organization. Provide at least one of: leadName, websiteUrl, or email.

const smartbrowz = app.smartbrowz();
const response = await smartbrowz.getEnrichedLead({
  leadName: 'zoho',
  websiteUrl: 'https://www.zoho.com',
  email: 'contact@example.com'
});
// Returns: employee_count, address, social, description, ceo, revenue, industries, etc.

Tech Stack Finder — findTechStack()

Fetches the technologies and frameworks used by an organization.

const response = await smartbrowz.findTechStack('https://www.zoho.com');
// Returns: website, technographic_data (frameworks, SSL, email hosting, etc.), organization_name

Similar Companies — getSimilarCompanies()

Returns a list of organizations offering similar products or services.

const response = await smartbrowz.getSimilarCompanies({
  leadName: 'zoho',
  websiteUrl: 'https://www.zoho.com'
});
// Returns: array of company name strings

Important: Only use Dataverse on publicly available data or domains that permit scraping.

SmartBrowz Dashboard

Console → SmartBrowz → Dashboard

Unified view of all SmartBrowz component usage:

Graphs (filterable by time period):

• Headless usage — Number of connections and executions
• Browser Logic usage — Function invocations, success/failure count
• PDF & Screenshot usage — Document generation count

Recent Browser Logic Executions:

• Filter by: All Status, Successful, Failed
• Shows: Function name, timestamp, execution status

Use dashboard to:

• Track component usage over time
• Identify performance issues
• Debug failed executions
• Monitor resource consumption

Related Skills

• catalyst-functions — for creating Browser Logic functions and understanding serverless function concepts
• catalyst-datastore — if storing automation results or fetching data for templates
• catalyst-stratus — if storing generated PDFs/screenshots
• catalyst-signals — if triggering browser automation based on events

Common Errors