SuiteScript API: N/task

Introduction

This post will discuss how to use the N/task module. Here is a complete list of the capabilities of this module:

• Trigger a scheduled or map/reduce script
• Run and save a query/search/suiteql query to the file cabinet
• Import CSV records
• Merge duplicate records
• Trigger a workflow

The function for creating a task is task.create(options). The options parameter has only one parameter that is required for all tasks: taskType.

The options are stored in a task.TaskType enum. Some values of this enum are task.TaskType.CSV_IMPORT, task.TaskType.ENTITY_DEDUPLICATION, and task.TaskType.MAP_REDUCE.

In this post we will look at the first three capabilities.

Trigger a Scheduled or Map/Reduce Script

The task.TaskType enum has two values that are used to trigger a scheduled or map/reduce script: task.TaskType.SCHEDULED_SCRIPT and task.TaskType.MAP_REDUCE.

Here are parameters in task.create for triggering scripts:

• taskType: task.TaskType.SCHEDULED_SCRIPT or task.TaskType.MAP_REDUCE
• scriptId: The internal ID of the script to trigger
• deploymentId: The internal ID of the deployment to trigger
• params: An object containing the parameters to pass to the script (optional)

The params object contains any values that you want to assign a value to. These parameters have to be defined in the script deployment. They will then be available in the script as runtime.getCurrentScript().getParameter({name: 'paramName'}).

If you have a large amount of data to pass to the script, you can save the data to a file cabinet using N/file and pass the internal ID of the file to the script as a parameter. Another option is to use N/cache to store the data in the cache and pass the cache key to the script as a parameter.

N/cache, N/runtime, and N/file will be discussed in future posts.

The task.create function returns a task object. To start the task, use the task.submit() function.

Here is an example of how to trigger a scheduled script:

const myTask = task.create({
    taskType: task.TaskType.SCHEDULED_SCRIPT,
    scriptId: 'customscript_my_scheduled_script',
    deploymentId: 'customdeploy_my_scheduled_script',
    params: {
        param1: 'value1',
        param2: 'value2'
    }
});

const mapreducetaskid = myTask.submit();

After submitting the task, you can use the task.checkStatus function to check the status of the task. This will return a status object that has a few properties to indicate the status of the task.

const statusObj = task.checkStatus({
    taskId: mapreducetaskid
});

const status = statusObj.status;
const stage = statusObj.stage; // Only available for map/reduce tasks
const percentCompleted = statusObj.getPercentageCompleted();

and more.

Run and Save a Query/Search to the File Cabinet

We trigger this this task using task.TaskType.SEARCH, task.TaskType.SUITE_QL or task.TaskType.QUERY.

Here the parameters for task.create:

• taskType: task.TaskType.SEARCH or task.TaskType.SUITE_QL
• fileId or filePath: The internal ID or path of the file to save the results to (mutually exclusive)
• query: string containing the query to run if taskType is task.TaskType.SUITE_QL or a query object if taskType is task.TaskType.QUERY
• savedSearchId: The internal ID of the saved search to run (required for task.TaskType.SEARCH)

Let’s look at an example of running a SuiteQL query and saving the results to a file:

const myTask = task.create({
    taskType: task.TaskType.SUITE_QL,
    filePath: 'SavedQueries/CustomerQuery.csv',
    query: 'SELECT * FROM customer'
});

const taskid = myTask.submit();

We can query the status of the task using task.checkStatus as we did in the previous section.

const statusObj = task.checkStatus({
    taskId: taskid
});

const status = statusObj.status;

Import CSV Records

To import CSV records, we use task.TaskType.CSV_IMPORT.

Here are the parameters for task.create:

• taskType: task.TaskType.CSV_IMPORT
• importFile: A file object loaded using N/file or a string containing the contents of the file.
• mappingId: The internal ID of the mapping to use. This can be found in Setup > Import/Export > Saved CSV Imports
• name: The name of the import task. This will be shown in Setup > Import/Export > View CSV Import Status
• queueId: This parameter can be used to specify a queue number for the import. This is useful if you have a SuiteCloud Plus license and will not be discussed in this post.
• linkedFiles: This parameter is used when running csv imports that have multiple files. For example if I’m importing an assembly and want to import bom and bom revision data I would have to specify the bom and bom revision files here: linkedFiles: {bom: bomfile, bomrevision: bomRevisionFile}

Here is an example of importing a CSV file:

const myTask = task.create({
    taskType: task.TaskType.CSV_IMPORT,
    importFile: file.load({
        id: 1234
    }),
    mappingId: 1234,
    name: 'My CSV Import'
});


const taskid = myTask.submit();

We can also get the status of the task using task.checkStatus as we did in the previous section.

const statusObj = task.checkStatus({
    taskId: taskid
});

const status = statusObj.status;

Wrapping up

Triggering map/reduce scripts is a very useful feature of the N/task module. The status object of the task contains a lot of useful information about the task such as the amount of records, the amount of memory used, and the amount of time it took to complete the task.

A common pattern is to create a Suitelet that triggers a map/reduce script and then polls the status of the task until it is complete and provide useful information to the user.