N/workflow Module in NetSuite: Complete Guide to Triggering SuiteFlow Workflows in SuiteScript

NetSuite’s SuiteFlow gives administrators a point-and-click way to model business processes, but sometimes you need to start or advance those processes from code. That is exactly what the N/workflow module in SuiteScript 2.x is for. With the N/workflow module you can initiate a workflow on a record or trigger a workflow to move to its next state, bridging the gap between declarative SuiteFlow automation and scripted logic.

What Is the N/workflow Module?

The N/workflow module is a small but powerful API with two primary jobs: starting a workflow and transitioning a workflow. SuiteFlow workflows normally run when a record is created or edited, but the N/workflow module lets your scripts kick them off programmatically. This is useful when a workflow should begin only after some custom condition is met, or when an external event handled by a Suitelet or RESTlet needs to push a record into an approval or fulfillment process.

Initiating a Workflow

The workflow.initiate() method starts a workflow on a specific record. You pass the record type, the record’s internal ID, and the workflow ID. NetSuite then attaches the workflow instance to that record and runs its entry actions. The example below starts an approval workflow on a purchase order:

require(['N/workflow'], function(workflow) {
    var workflowId = workflow.initiate({
        recordType: 'purchaseorder',
        recordId: 1234,
        workflowId: 'customworkflow_po_approval'
    });
    log.audit('Workflow started', workflowId);
});

Transitioning a Workflow

The workflow.trigger() method advances a record that is already running a workflow to a new state, or fires a workflow action on it. Alongside the record type, record ID, and workflow ID, you supply the actionId or the target workflow state. This is how you move a record from, say, Pending Approval to Approved directly from a button or a scheduled script. The example below transitions a purchase order to its next state:

require(['N/workflow'], function(workflow) {
    var workflowId = workflow.trigger({
        recordType: 'purchaseorder',
        recordId: 1234,
        workflowId: 'customworkflow_po_approval',
        actionId: 'workflowaction_approve'
    });
    log.audit('Workflow transitioned', workflowId);
});

A Real-World Example

A common pattern is to start a workflow automatically from a user event script after a record is created, but only when a business rule is satisfied. Here the workflow begins only for purchase orders above a spending threshold:

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/workflow'], function(workflow) {

    function afterSubmit(context) {
        if (context.type !== context.UserEventType.CREATE) {
            return;
        }
        var rec = context.newRecord;
        var total = rec.getValue({ fieldId: 'total' });

        if (total > 5000) {
            workflow.initiate({
                recordType: 'purchaseorder',
                recordId: rec.id,
                workflowId: 'customworkflow_po_approval'
            });
        }
    }

    return { afterSubmit: afterSubmit };
});

When to Use the N/workflow Module

Reach for the N/workflow module when you need scripted control over processes that are otherwise managed declaratively in SuiteFlow. Typical scenarios include starting an approval flow only when custom conditions are met, advancing records in bulk from a scheduled or Map/Reduce script, integrating an external system that should push records into a workflow through a RESTlet, and adding a button to a form that lets users trigger the next workflow step on demand.

Best Practices

Confirm a record is not already running the target workflow before calling initiate, so you do not create duplicate instances. Wrap calls to the N/workflow module in try/catch blocks and log the returned workflow ID for easier troubleshooting. Keep heavy logic out of the workflow trigger itself and let SuiteFlow handle the state machine, using script only to start or advance it. Finally, store workflow and action IDs as script parameters rather than hardcoding them, so the same script can be reused across environments.

Used well, the N/workflow module connects your SuiteScript automation to NetSuite’s visual SuiteFlow engine, giving you the flexibility of code with the maintainability of point-and-click workflows.