🧩 Building Custom Portlets in NetSuite (Dashboard Widgets with SuiteScript)

Introduction

Portlets in NetSuite are dashboard widgets that display dynamic data — from saved searches and KPIs to custom HTML, charts, and external data feeds.

While NetSuite provides standard portlets like Reminders, Key Performance Indicators, and Trend Graphs, you can take dashboards further by building Custom Portlets using SuiteScript 2.x.

Custom Portlets allow you to:

• Display custom HTML interfaces, tables, and buttons.
• Embed charts or KPIs from saved searches.
• Call external APIs (e.g., Shopify orders, Salesforce updates).
• Improve visibility for users and executives with tailored dashboards.

💡 What Is a Custom Portlet?

A Custom Portlet is a SuiteScript-based dashboard component that you can deploy to any user’s Home dashboard. It’s written using the Portlet script type in SuiteScript 2.x or 2.1.

⚙️ When to Use a Custom Portlet

Use a custom portlet when you need:

• Dynamic dashboards tailored to business roles.
• Interactive data summaries (e.g., Open Sales Orders, Recent Fulfillments).
• Integration dashboards (display external API data).
• Quick-action widgets (buttons to trigger Suitelets or RESTlets).

🧱 Step-by-Step: Creating a Custom Portlet

Step 1: Create a SuiteScript 2.1 Portlet File

Navigate to:
Customization → Scripting → Scripts → New → Portlet

Paste the following example:

/**
 * @NApiVersion 2.1
 * @NScriptType Portlet
 * @NModuleScope SameAccount
 */
define(['N/search', 'N/format'], (search, format) => {
    const render = (params) => {
        const portlet = params.portlet;
        portlet.title = 'Top 5 Open Sales Orders';

        // Create a simple table header
        let html = "<table style='width:100%; border-collapse:collapse;'>";
        html += "<tr style='background-color:#f3f3f3;'><th>Order #</th><th>Customer</th><th>Total</th></tr>";

        // Run a saved search dynamically
        const soSearch = search.create({
            type: search.Type.SALES_ORDER,
            filters: [['status', 'anyof', 'SalesOrd:A']], // Open
            columns: ['tranid', 'entity', 'total']
        });

        soSearch.run().each(result => {
            html += `<tr>
                <td>${result.getValue('tranid')}</td>
                <td>${result.getText('entity')}</td>
                <td>${format.format({value: result.getValue('total'), type: format.Type.CURRENCY})}</td>
            </tr>`;
            return true;
        });

        html += "</table>";
        portlet.html = html;
    };

    return { render };
});

This script builds a dashboard widget that lists Top 5 Open Sales Orders dynamically.

Step 2: Deploy the Portlet

1. Go to Customization → Scripting → Scripts.
2. Select your Portlet Script → click Deploy Script.
3. Set the title (e.g., Sales Dashboard Widget).
4. Assign the deployment to roles or users (e.g., Sales Manager).
5. Set Status → Released.

Step 3: Add the Portlet to Dashboard

1. Go to your Home dashboard.
2. Click Personalize → Custom Portlet.
3. Choose your new portlet from the dropdown (e.g., Sales Dashboard Widget).
4. Click Save.

🎉 Done — your dashboard now displays a live, custom table of open Sales Orders.

🧮 Example: Integrating a Saved Search

To use an existing saved search instead of building one inside the script:

const mySearch = search.load({ id: 'customsearch_open_invoices' });
const results = mySearch.run().getRange({ start: 0, end: 10 });

Then loop through results and inject them into your HTML structure.

📈 Example: Adding Simple Charts in Portlet

Use inline HTML and JavaScript libraries such as Chart.js (CDN accessible) for a quick chart portlet:

portlet.html = `
    <canvas id="salesChart"></canvas>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <script>
        new Chart(document.getElementById('salesChart'), {
            type: 'bar',
            data: {
                labels: ['Jan','Feb','Mar','Apr'],
                datasets: [{ label: 'Sales', data: [200,300,250,400] }]
            }
        });
    </script>
`;

✅ Tip: Keep scripts lightweight; heavy JS may slow dashboard load.

🧠 Advanced Use Cases

⚡ Styling and UX Tips

• Use <table> with border-collapse: collapse; for clean layout.
• Add colors for headers and totals.
• Limit rows (5–10 max) for fast dashboard rendering.
• Use icons via HTML entities (✅, ⚠️, ⏳).
• Wrap content in <div style="overflow:auto; max-height:200px;"> for scrollable widgets.

🔒 Permissions and Deployment Control

• Deploy portlets by role (e.g., Accountant, Sales Manager).
• Control visibility through Audience tab.
• You can have multiple deployments per script — each with a different layout or data source.

🧰 Debugging and Maintenance

• Check the Execution Log under Customization → Scripting → Script Deployments.
• Add log.debug() inside the render function.
• If HTML doesn’t render, check for missing <table> closures or invalid tags.
• Always test in Sandbox first.

🧩 Best Practices

• Cache static data when possible.
• Avoid running large saved searches on load — preload with summary data.
• Keep portlet width manageable (no horizontal scroll).
• Combine data visualization and quick links for better UX.

📚 Related Tutorials

• 👉 SuiteAnalytics Workbook for Reporting
• 👉 Custom Buttons and Form Actions
• 👉 Advanced PDF Templates in NetSuite

❓ FAQ

Q1. Can I use RESTlet or external API data in a portlet?
Yes — but ensure the data call executes quickly (<2 s) to avoid dashboard timeouts.

Q2. How many custom portlets can a user have?
Up to five per dashboard, depending on screen size and layout.

Q3. Can I make the portlet interactive (e.g., click to open record)?
Yes — embed hyperlinks to NetSuite records using record IDs in your HTML.

Q4. Can portlets auto-refresh?
Not natively; use JavaScript timers (setInterval()) or reload manually.

🧭 Summary

Custom Portlets empower you to turn NetSuite dashboards into actionable, data-driven interfaces.
Whether displaying KPIs, search summaries, or external data — portlets bridge the gap between backend analytics and real-time visibility.

They’re one of the simplest yet most powerful ways to personalize user experience in NetSuite.