Workflows as XML Definitions

Create and manage workflows using SuiteCloud Development Framework (SDF). You can model a workflow definition in a SuiteCloud project and deploy the project to a target NetSuite account. You can either create new workflows in your project or import existing workflows from a NetSuite account. For information about working with workflows in a NetSuite account, see:

• Required Permissions for SuiteFlow

• Account Component Imports to SuiteCloud Projects

Start designing a workflow SDF custom object by specifying definition fields. These fields contain basic information about the workflow and are similar to the properties specified on the workflow definition page, such as the name, description, record types, and release status. For more information about all available definition fields and how they are defined in SDF, see the following:

• workflow

• Workflow Definition Page

• Workflow Base Record

• Execution Contexts and Workflows

• Context Type Examples

SDF supports both event-based and scheduled workflow types. The workflow type determines which fields should be specified in the workflow object.

Basic Definition Fields

There are some basic fields that are used to define a workflow. The following example defines them for a workflow used for approvals:

            <workflow scriptid="customworkflow_approvals">
...
    <isinactive>F</isinactive>
    <islogenabled>T</islogenabled>
    <keephistory>ALWAYS</keephistory>
    <name>Approval Workflow</name>
    <recordtypes>[scriptid=customrecord_approval_routing]</recordtypes>
    <releasestatus>RELEASED</releasestatus>
    <runasadmin>F</runasadmin>
...
</workflow> 

          

In the preceding example, the workflow is set to generate an execution log when the workflow runs, and to always keep the history by saving the logs. The workflow is active and its release status is set to run for all users. The workflow does not require administrator permission to run.

The following fields provide the basic definition of a workflow:

• isinactive – The isinactive field specifies that the workflow does not initiate at any time. The default value is F. For more information, see Inactivating a Workflow.

• islogenabled – The islogenabled field specifies whether the workflow generates a workflow execution log when the workflow runs. The default value is F.

• keephistory – The keephistory field specifies when the workflow instance, workflow history, and workflow logs are saved for a workflow. Options include ALWAYS, NEVER, and ONLYWHENTESTING. The default value is ONLYWHENTESTING. For more information, see Disabling History for a Workflow.

• recordtypes – All workflows must have a base record type, specified using the recordtypes field. For Customer, Item, and Transaction records, you can also specify a sub type. For more information, see Workflow Base Record.

• releasestatus – You can define the release status using the releasestatus field, which is a property that controls how the workflow can or cannot be initiated. That property can be useful when you want to test the workflow, release it to users, stop it from being run, or suspend its execution. The default value is NOTINITIATING.

  You can specify the following release statuses:

  • NOTINITIATING - The workflow no longer runs in testing or released mode, but still appears on the Workflow list page. New workflow instances cannot be initiated, but existing instances are still active and execute their actions and transitions. For more information, see Viewing Existing Workflows.

    Note:

    The NOTINITIATING status has replaced the NOTRUNNING status. Although NOTINITIATING is used for new objects created in NetSuite, the NOTRUNNING status is still supported in SDF for backward compatibility.

  • RELEASED - The workflow to runs for all users. For more information, see Defining the Workflow Audience and Users Who Can Create and View Workflows.

  • SUSPENDED - Disables all workflow execution. When you set the releasestatus of a workflow to SUSPENDED, the following are true:

    • No new instances of the suspended workflow are created.

    • No existing instances of the suspended workflow are executed.

    • None of the following are executed when they exist in a suspended workflow: actions, transitions, and scheduled workflows.

    • It is not possible to initiate a suspended workflow from SuiteScript, or by using the Initiate Workflow or Mass Update actions in SuiteFlow.

    To resume a suspended workflow, change the releasestatus to RELEASED. Suspended workflows resume from the point the workflow was at when it was suspended.

  • TESTING - Tests a workflow. For more information, see Workflow Execution Log.

  For more information about the releasestatus property and its statuses, see Release Status.

• runasadmin – The runasadmin field specifies that the workflow runs as a user with administrator permissions. The default value is F.

  Note:

  Only administrators should use the runasadmin field. When deploying a workflow to an account with a non-administrator role, the runasadmin field is ignored.

Event-Based Workflows

Event-based workflows are created by specifying most of the workflow object fields that have an init prefix, such as initoncreate, initonvieworupdate, or initcondition. These fields are similar to the properties specified on the workflow definition page. For more information about all available event-based fields, see the following:

• Workflow Triggers

• Triggers Reference

• Workflow Conditions

• Defining a Condition with the Condition Builder

• Defining a Condition with Formulas

• Condition Examples

• Workflow Event Types

• Event Types Reference

• Examples of Event Types

The following example shows a workflow object that is set to run before a user submits a new Estimate record:

            <workflow scriptid="customworkflow1">
    <name>My custom workflow</name>
    <recordtypes>ESTIMATE</recordtypes>
    <initoncreate>T</initoncreate>
    <initonvieworupdate>F</initonvieworupdate>
    <inittriggertype>BEFORESUBMIT</inittriggertype>
    ...
</workflow> 

          

The initcondition workflow object field supports formulas, expressions, and conditions created with the visual builder in the workflow condition builder. You can define complex conditions and expressions using record field value comparisons. These conditions can be used with workflow initiation, workflow actions, and workflow transitions.

The initcondition element is composed of the following:

• A formula element that defines the condition. The formula element can contain a formula, expression, or condition.

• The type of condition, which can be one of the following:

  • FORMULA – denoting a formula to define the condition. For more information, see Defining a Condition with Formulas.

  • VISUAL_BUILDER – denoting a condition or expression defined by the visual builder in NetSuite. For more information, see Defining a Condition with the Condition Builder.

• If the formula element contains a condition or expression, it is followed by a parameters element containing a list of parameters that assign values to the fields in the formula. When defining the parameters:

  • Each name element must correspond to a field name in the formula. Field names are encapsulated by double quotation marks (") in the formula.

  • Each value element must be a valid value for the corresponding field.

  • The record type can be specified for the field using selectrecordtype.

The following example shows a visual builder expression used in the initiation statement of a workflow object:

            ...
<initcondition>
    <formula><![CDATA["User" IN ("Current User") AND "Alt. Phone" = '555-123-1234' AND "Role" IN ("Role1","Role2","Role3") AND "Days Overdue" = 100 AND "Account" = "Old Record:Account"]]</formula>
    <type>VISUAL_BUILDER</type>
    <parameters>
        <parameter>
            <name>User</name>
            <value>STDUSERUSER</value>
        </parameter>
        <parameter>
            <name>Current User</name>
            <selectrecordtype>-4</selectrecordtype>
            <value>@CURRENTUSER@</value>
        </parameter>
        <parameter>
            <name>Alt. Phone</name>
            <value>STDENTITYALTPHONE</value>
        </parameter>
        <parameter>
            <name>Role</name>
            <value>STDENTITYACCESSROLE</value>
        </parameter>
        <parameter>
            <name>Role1</name>
            <selectrecordtype>-118</selectrecordtype>
            <value>ADMINISTRATOR</value>
        </parameter>
        <parameter>
            <name>Role2</name>
            <selectrecordtype>-118</selectrecordtype>
            <value>CEO</value>
        </parameter>
        <parameter>
            <name>Role3</name>
            <selectrecordtype>-118</selectrecordtype>
            <value>[appid=com.samples.myapp, scriptid=customrole_sdfdeveloper]</value>
        </parameter>
        <parameter>
            <name>Days Overdue</name>
            <value>STDENTITYDAYSOVERDUE</value>
        </parameter>
        <parameter>
            <name>Account</name>
            <value>STDENTITYACCOUNTNUMBER</value>
        </parameter>
        <parameter>
            <name>Old Record:Account</name>
            <value>@OLDRECORD@:STDENTITYACCOUNTNUMBER</value>
        </parameter>
    </parameters>
</initcondition>
... 

          

Rather than use SDF to create complex conditions and expressions in workflow objects, you should import workflows created in an account with such conditions and expressions defined using visual builder. The following example shows a workflow object created using the tutorial in Creating Your First Workflow. The workflow initiates when an Opportunity record is created and the user saves the opportunity with a status of In Discussion, In Negotiation, In Progress, or Qualified. An action is triggered to go to the Opportunities page.

            <workflow scriptid="customworkflow_opportunity">
    <description></description>
    <initcontexts></initcontexts>
    <initeventtypes></initeventtypes>
    <initoncreate>T</initoncreate>
    <initonvieworupdate>F</initonvieworupdate>
    <initsavedsearchcondition></initsavedsearchcondition>
    <inittriggertype>BEFORELOAD</inittriggertype>
    <isinactive>F</isinactive>
    <islogenabled>T</islogenabled>
    <keephistory>T</keephistory>
    <name>First Workflow</name>
    <recordtypes>OPPORTUNITY</recordtypes>
    <releasestatus>TESTING</releasestatus>
    <runasadmin>F</runasadmin>
    <initcondition>
        <formula><![CDATA["Opportunity/Estimate Status" IN ("Entity Status1","Entity Status2","Entity Status3","Entity Status4")]]></formula>
        <type>VISUAL_BUILDER</type>
        <parameters>
             <parameter>
                 <name>Opportunity/Estimate Status</name>
                 <value>STDBODYENTITYSTATUS</value>
             </parameter>
             <parameter>
                 <name>Entity Status1</name>
                 <selectrecordtype>-104</selectrecordtype>
                 <value>In Discussion</value>
             </parameter>
             <parameter>
                 <name>Entity Status2</name>
                 <selectrecordtype>-104</selectrecordtype>
                 <value>In Negotiation</value>
                 </parameter>
             <parameter>
                 <name>Entity Status3</name>
                 <selectrecordtype>-104</selectrecordtype>
                 <value>In Progress</value>
             </parameter>
             <parameter>
                 <name>Entity Status4</name>
                 <selectrecordtype>-104</selectrecordtype>
                 <value>Qualified</value>
             </parameter>
         </parameters>
    </initcondition>
    <workflowstates>
        <workflowstate scriptid="workflowstate1">
            <description></description>
            <donotexitworkflow>F</donotexitworkflow>
            <name>State 1: Entry</name>
            <positionx>243</positionx>
            <positiony>133</positiony>
            <workflowactions triggertype="ONENTRY">
                <setfieldmandatoryaction scriptid="workflowaction1">
                    <clienttriggerfields></clienttriggerfields>
                    <conditionsavedsearch></conditionsavedsearch>
                    <contexttypes></contexttypes>
                    <eventtypes></eventtypes>
                    <field>STDBODYTITLE</field>
                    <isinactive>F</isinactive>
                    <ismandatory>T</ismandatory>
                    <initcondition>
                        <formula></formula>
                        <type>VISUAL_BUILDER</type>
                    </initcondition>
                 </setfieldmandatoryaction>
            </workflowactions>
            <workflowtransitions>
                <workflowtransition scriptid="workflowtransition1">
                <buttonaction></buttonaction>
                <conditionsavedsearch></conditionsavedsearch>
                <contexttypes></contexttypes>
                <eventtypes></eventtypes>
                <scheduledelay></scheduledelay>
                <scheduletimeunit></scheduletimeunit>
                <tostate>[scriptid=customworkflow1.workflowstate2]</tostate>
                <triggertype>AFTERSUBMIT</triggertype>
                <waitforworkflow></waitforworkflow>
                <waitforworkflowstate></waitforworkflowstate>
                <initcondition>
                    <formula></formula>
                    <type>VISUAL_BUILDER</type>
                </initcondition>
                </workflowtransition>
            </workflowtransitions>
        </workflowstate>
        <workflowstate scriptid="workflowstate2">
            <description></description>
            <donotexitworkflow>F</donotexitworkflow>
            <name>State 2: See Opportunities</name>
            <positionx>473</positionx>
            <positiony>133</positiony>
            <workflowactions triggertype="ONENTRY">
                <gotopageaction scriptid="workflowaction2">
                    <conditionsavedsearch></conditionsavedsearch>
                    <contexttypes></contexttypes>
                    <eventtypes></eventtypes>
                    <isinactive>F</isinactive>
                    <targetpage>LIST_TRAN_OPPRTNTY</targetpage>
                    <initcondition>
                        <formula></formula>
                        <type>VISUAL_BUILDER</type>
                    </initcondition>
                </gotopageaction>
           </workflowactions>
        </workflowstate>
    </workflowstates>
</workflow> 

          

When you use SDF to modify expressions in workflow objects, consider the following:

• During the import into a SuiteCloud project, parameter fields with account specific values have the value set to [ACCOUNT_SPECIFIC_VALUE] in the workflow object definition. For deployment to succeed when Action on Account-Specific Values is set to ERROR, change the value to one that is valid for either a custom field in the project or a field in the target account. For more information, see Account-Specific Values Validation in SuiteCloud Projects.

• Removing the initcondition block from a workflow object in SDF does not remove that condition from that object in the target account during deployment. To delete the condition from the object, specify an empty formula. For example:

                  ...
  <initcondition>
      <formula></formula>
      <type>VISUAL_BUILDER</type>
  </initcondition>
  ... 
  
                

• Validation errors are returned when the initcondition block is defined with any of the following:

  • A parameter exists in the formula field but there is no corresponding parameter name.

  • The formula is invalid, containing a syntax error.

  • The parameter’s assigned value is incorrect for its field.

  • The value requires a feature that it is not compatible with the target NetSuite account, and consequently cannot be added to the manifest. If the feature can be set, the required feature is provided in the validation log so that it can be added to the manifest.

  • Parameter fields with a value of [ACCOUNT_SPECIFIC_VALUE] when Action on Account-Specific Values is set to ERROR.

• Validation is only performed on supported record types. If the parameter is a field for an unsupported selectrecordtype value, the parameter cannot be validated.

• Only valid fields for the record type specified in r ecordtypes can be specified as parameters. Specifying fields for other record types returns a reference key error on deployment.

• All system fields are deployed to the target account in English. All custom fields are deployed to the target account in the language defined for the field object in the SuiteCloud project.

For more information about event-based workflows and creating them with the NetSuite UI, see the following:

• Initiating a Workflow on an Event

• Creating a Workflow

Scheduled Workflows

Scheduled workflows are created by specifying the initsavedsearchfilter field, initsavedsearchcondition field, and recurrence field group in the workflow object. Use the initsavedsearchfilter and initsavedsearchcondition fields to specify the saved search on which to run the workflow object. Use the recurrence field group to schedule the workflow’s execution. You can indicate a repeating schedule by specifying the startdate and enddate fields that are available in any recurrence selection.

Note:

When you remove the enddate element from a recurrence in your project and deploy it to a target account, any enddate value for that recurrence that already exists in the account is preserved. The enddate value is only deleted when you change the recurrence type in the project and deploy it to the target account.

For more information about scheduled workflow fields, see the following:

• workflow

• recurrence

The following example shows a workflow object that runs a custom search every weekday at 7:00am from mid-September until mid-October:

            <workflow scriptid="customworkflow1">
    <name>My custom workflow</name>
    <recordtypes>CUSTOMER</recordtypes>
    ...
    <initsearchcondition>[scriptid=customsearch1]</initsearchcondition>
    <initsearchfilter>[scriptid=customsearch1]</initsearchfilter>
    <recurrence>
        <everyweekday>
            <startdate>2020-09-14</startdate>
            <enddate>2020-10-14</enddate>
            <starttime>07:00:00Z</starttime>
        </everyweekday>
    </recurrence>
    ...
</workflow> 

          

Note:

The format of the time and date values is based on the UTC standard and is ISO compliant. For more information about how to format time and date values, see Date and Time Formats in SDF Custom Objects.

For more information scheduled workflows and creating them with the NetSuite UI, see the following:

• Initiating a Workflow on a Schedule

• Scheduling a Workflow

Workflow Custom Fields

You can create custom fields in either an event-based workflow or a scheduled workflow. In a workflow object, custom fields are grouped within the workflowcustomfields structure. In this structure, you can create as many custom fields as needed by specifying a workflowcustomfield structure for each one. The elements that are available in a workflowcustomfield are similar to the properties that you can specify in the fields subtab of the workflow definition page. For more information about the available elements that you can specify for a custom field, see the following:

• workflowcustomfield

• Workflow Definition Page Fields Subtab

• Workflow Custom Fields

• Creating and Using Workflow Fields

The following example shows a workflow object that defines two custom fields:

            <workflow scriptid="customworkflow1">
    <name>My custom workflow</name>
    <recordtypes>LEAD</recordtypes>
    ...
    <workflowcustomfields>
        <workflowcustomfield scriptid="custworkflow1">
            <applyformatting>F</applyformatting>
            <defaultchecked>F</defaultchecked>
            <displaytype>NORMAL</displaytype>
            <fieldtype>SELECT</fieldtype>
            <label>Webinar.Response</label>
            <selectrecordtype>[scriptid=customrecordtype1]</selectrecordtype>
            <storevalue>T</storevalue>
        </workflowcustomfield>
        <workflowcustomfield scriptid="custworkflow2">
            <applyformatting>F</applyformatting>
            <defaultchecked>F</defaultchecked>
            <displaytype>NORMAL</displaytype>
            <fieldtype>SELECT</fieldtype>
            <label>CaseStudy.Response</label>
            <selectrecordtype>[scriptid=customrecordtype1]</selectrecordtype>
            <storevalue>T</storevalue>
        </workflowcustomfield>
     </workflowcustomfields>
    ...
</workflow> 

          

For information about how to create workflow states, see Workflow State Creation.

Related Topics

• Scripting
• User Event Scripts as XML Definitions
• Scheduled Scripts as XML Definitions
• SDF Installation Scripts as XML Definitions
• Translation Collections as XML Definitions
• Map/Reduce Script Objects as XML Definitions
• Portlet Scripts as XML Definitions
• Client Scripts as XML Definitions
• Integration Records as XML Definitions
• Mass Update Scripts as XML Definitions
• Suitelet Scripts as XML Definitions
• RESTlet Scripts as XML Definitions
• Secrets as XML Definitions
• Single Page Applications as XML Definitions

General Notices