SuiteScript 2.x Record Actions and Macros

Overview

Macro and action APIs provide ease and flexibility for your scripting. These APIs are supported for all SuiteScript 2.0 client and server script types. Macro and action APIs also can lower governance usage because they can execute complex business logic in one API call instead of multiple API calls.

For actions, governance is charged per individual action executed, and varies depending upon the type of action. For macros, no governance is charged, because changes executed by macros are saved as part of record submits.

Record actions provide a convenient way to update the state of one or more records that are in view mode. Changes that the execution of an action API makes to records are persisted in the database immediately.These actions can be applied to a single record or to multiple records of the same type, as a bulk process. When an approve or reject action is executed on a record, the approval status of the record is saved immediately

Record macros provide an automated way to execute business logic on a record as it is edited. Changes that the execution of a macro API makes to a record are not persisted until the record is saved.A macro API is applied only to a single record at a time. After changes to the record are saved, changes to other dependent records may occur as a result.

You need to use two different types of APIs to call record macros and actions in your scripts:

1. Generic APIs to get and execute actions or macros:

Record action APIs are part of the N/action Module.

Record macro APIs are part of the N/record Module.

2. Individual APIs that implement specific logic on a specific record type:

A limited number of Individual actions for specific record types are supported.

A limited number of individual macros for specific record types.

Supported Record Actions

Examples:

Record Type:Bonus,Action :cancel

Record Type:Invoice,Action :Markforgrouping

Record Type:Weekly Time Sheet,Action :Approve

Supported Record Macros

Examples:

Record Type: Transaction record macros,Action :calculateTax

Record Type: sales order,Action :autoAssignLocations

Sample Scripts

The following server script sample finds and executes an action on the timebill record without promises.

/**
 * @NApiVersion 2.x
 */
require(['N/action', 'N/record'], function(action, record) {
    // create timebill record
    var rec = record.create({
        type: 'timebill',
        isDynamic: true
    });
    rec.setValue({
        fieldId: 'employee',
        value: 104
    });
    rec.setValue({
        fieldId: 'location',
        value: 312
    });
    rec.setValue({
        fieldId: 'hours',
        value: 5
    });
    var recordId = rec.save();

    var actions = action.find({
        recordType: 'timebill',
        recordId: recordId

    });

    log.debug("We've got the following actions: " + Object.keys(actions));
    if (actions.approve) {
        var result = actions.approve();
        log.debug("Timebill has been successfully approved");
    } else {
        log.debug("The timebill is already approved");
    }
});

// Outputs the following:
// We've got the following actions: approve, reject
// Timebill has been successfully approved

The following sample shows you how to call a calculateTax macro on a sales order record. To execute a macro on a record, the record must be created or loaded in dynamic mode. Note that the SuiteTax feature must be enabled to successfully execute the macro used in this sample.

/**
 * @NApiVersion 2.x
 */

require(['N/record'],
    function(record) {

     var recordObj = record.create({
         type: record.Type.SALES_ORDER,
         isDynamic: true
     });

     var ENTITY_VALUE = 1;
     var ITEM_VALUE = 1;
     recordObj.setValue({
         fieldId: 'entity',
         value: ENTITY_VALUE
    });
    recordObj.selectNewLine({
         sublistId: 'item'
    });
    recordObj.setCurrentSublistValue({
         sublistId: 'item',
         fieldId: 'item',
         value: ITEM_VALUE
    });
    recordObj.setCurrentSublistValue({
         sublistId: 'item',
         fieldId: 'quantity',
         value: 1
    });
    recordObj.commitLine({
         sublistId:'item'
    });

    var totalBeforeTax = recordObj.getValue({fieldId: 'total'});

    // get macros available on the record
    var macros = recordObj.getMacros();

    // execute the macro
    if ('calculateTax' in macros)
    {
        macros.calculateTax(); // For promise version use: macros.calculateTax.promise()
    }
    // Alternative (direct) macro execution
    // var calculateTax = recordObj.getMacro({id: 'calculateTax'});
    // calculateTax(); // For promise version use: calculateTax.promise()
    var totalAfterTax = recordObj.getValue({fieldId: 'total'});

    var recordId = recordObj.save({
       enableSourcing: false,
       ignoreMandatoryFields: false
    });
});