Steptypes.json Syntax

The steptypes.json file, which describes custom job steps, requires a specific JSON syntax. If a steptypes.json file contains errors, the errors are logged and the steps are not registered. The system then loads steps from the steptypes.json files of other cartridges. A typical error message for an invalid steptypes.json file is Invalid step [Step1]! Type with id [custom.MyCustomStep1] is unknown!.

Steptypes.json Schema File

To check the syntax of your steptypes.json file, access the steptypes.schema file here.

Table 1. Elements in the steptypes.json File
Element Contained By Contains Required or Optional Notes
@code status   Required for status Must not contain leading or trailing white space.
@name parameter   Required for parameter Must not contain leading or trailing whitespace.
@required parameter   Optional

Must have value true or false. Default is true. If true, parameter is required. If false, parameter is optional.
@supports-organization-context pipeline-step, chunk-script-module-step, and script-module-step   Optional Must have value true or false. Default is true. If true, steps of this type can be used for flows with organization scope. If false, steps of this type can't be used for flows with organization scope. @supports-organization-context and @supports-site-context cannot both have the same true or false setting. If @supports-site-context is false, @supports-organization-context must be true and vice versa.
@supports-parallel-execution pipeline-step, chunk-script-module-step, and script-module-step   Optional Must have value true or false. Default is true. If false, split flows that contain steps of this type are always executed sequentially and never in parallel. If true, split flows that contain steps of this type are executed in parallel, as long as:
  • The split flows don't contain steps with supports-parallel-execution = false.
  • The split flows ae not configured to be executed sequentially.
  • There are enough resources available to do parallel execution.
@supports-site-context pipeline-step, chunk-script-module-step, and script-module-step   Optional Must have value true or false. Default is true. If true, steps of this type can be used for flows with one or more sites as scope. If false, steps of this type can't be used for flows with one or more sites as scope. @supports-organization-context and @supports-site-context cannot both have the same true or false setting. If @supports-site-context is false, @supports-organization-context must be true and vice versa.
@target-type parameter   Optional The type to which the parameter value is converted, either long or date, after the user enters a value in Business Manager. Can be present only when @type is datetime-string, date-string, or time-string. If @target-type is not defined, date is the default value.
@trim parameter   Optional Specifies whether leading and trailing whitespace for the parameter value entered in Business Manager is removed before the value is validated. Must not contain leading or trailing whitespace. Must have value true or false. Default is true.
@type parameter   Required

Indicates the data type of the parameter value. Must not contain leading or trailing whitespace. Must have value of boolean, string, long, double, datetime-string, date-string, or time-string.
@type-id pipeline-step, chunk-script-module-step, and script-module-step   Required Identifies the step. This is the name that users will see in Business Manager, so make it descriptive. Must begin with custom.. Must not contain leading or trailing white space or more than 100 characters. Must be unique within the job definition. You can't register multiple steps with the same @type-id in different cartridges. The @type-id is validated as unique by parsing the steptypes.json files from all cartridges on the cartridge path. If there is a step with the same @type-id, the step isn't loaded. The @type-id value can't be the same as any system step, for example, ExecutePipeline or IncludeStepsFromJob.
after-chunk-function chunk-script-module-step   Optional References the function of the chunk-oriented script module to be executed after a chunk has finished. If not defined, no after-chunk logic is used.
after-step-function chunk-script-module-step   Optional References the function of the chunk-oriented script module to be executed after the step has finshed. If not defined, no after-step logic is used.
before-chunk-function chunk-script-module-step   Optional References the function of the chunk-oriented script module to be executed before a chunk begins. If not defined, no before-chunk logic is used.
before-step-function chunk-script-module-step   Optional References the function of the chunk-oriented script module to be executed before the step begins. If not defined, no before-step logic is used.
chunk-module-script-step step-types
  • @type-id
  • @supports-parallel-execution
  • @supports-site-context
  • @supports-organization-context
  • description
  • module
  • before-step-function
  • total-count-function
  • before-chunk-function
  • read-function
  • process-function
  • write-function
  • after-chunk-function
  • after-step-function
  • chunk-size
  • transactional
  • parameters
  • status-codes
Required if no pipeline-step or script-module-step Defines a chunk-oriented step.
chunk-size chunk-script-module-step   Required for status element Must be a numeric value. Must not contain leading or trailing white space.
default-value parameter   Optional Default when no value is entered for the parameter. Must have a valid data type value for the parameter (boolean, string, long, double, datetime-string, date-string, or time-string). If the parameter is assigned enum-values, the default-value must match one of the list of enum values.
description parameter   Required

Must not contain leading or trailing whitespace or more than 256 characters.
description pipeline-step, chunk-script-module-step, script-module-step, and status   Optional Description of the step or status code. Not shown in Business Manager. Must not exceed 4000 characters.
enum-values parameter value Optional Allowed values for the parameter. The value entered by the user in Business Manager is validated against this list. Must not contain leading or trailing white spaces.
function script-module-step   Optional The function of the script module to execute. Must not contain leading or trailing white space. If not defined, the script module must export a function named execute.
max-length parameter   Optional Maximum length of a string value for this parameter. String entered in Business Manager is validated against this restriction. Only applicable if @type is set to string. Must be at least 1 and greater than or equal tomin-length. If not defined, string length is not restricted other than by the general requirement that parameter values cannot exceed 1000 characters.
max-value parameter   Optional Maximum numerical value for the parameter. Only applicable if @type is long,double, datetime-string, or time-string. Must be greater than or equal to min-value. The maximum valid value for a long is 9223372036854775807 and for a double is 1.7976931348623157E308. If you do not explicitly define a max-value, those values are considered the max-values for long and double parameters. For datetime-string or time-string parameters, if not defined, there are no restrictions other than the general restriction that parameter values cannot exceed 1000 characters.
min-length parameter   Optional Minimum length of the string value for the parameter. Only applicable if @type is string. Must be at least 1 and less than max-length. If not defined, there are no restrictions other than the general restriction that parameter values cannot exceed 1000 characters.
min-value parameter   Optional Minimum value for the parameter. Must not exceed the max-value. The minimum valid value for a long is -9223372036854775808 and for a double is4.9E-324. If you do not explicitly define a min-value, those values are considered the min-values for long and double parameters. For datetime-string or time-string parameters, if you do not define a min-value, there are no restrictions other than the general restriction that parameter values cannot exceed 1000 characters.
module script-module-step and chunk-script-module-step   Required Path to the script module to be executed. Must not contain leading or trailing white space.
parameter parameters
  • name
  • type
  • target-type
  • required
  • trim
  • default-value
  • enum-values
  • description
  • pattern
  • min-length
  • max-length
  • min-value
  • max-value
Required if parameters is present A parameter for the step, which the user configures in Business Manager.
parameters pipeline-step and script-module-step parameter Required Parameters for the step, which the user configures in Business Manager. Contains one or more parameter elements.
pattern parameter   Optional Regular expression that defines the allowed values for the parameter. Applicable only if @type is string.
pipeline pipeline-step   Required Pipeline to execute for the step. Format must be <PipelineName>-<StartNodeName>. For example: Search-Show
pipeline-step step-types
  • @type-id
  • @supports-parallel-execution
  • @supports-site-context
  • @supports-organization-context
  • pipeline
  • description
  • parameters
  • status-codes
Required if no script-module-step or chunk-script-module-step Defines a pipeline for the step.
process-function chunk-module-script-step   Optional Process function of the chunk script. If not defined, script must export a function named process.
read-function chunk-module-script-step   Optional Read function of the chunk script. If not defined, script must export a function named read.
script-module-step step-types
  • @type-id
  • @supports-parallel-execution
  • @supports-site-context
  • @supports-organization-context
  • description
  • module
  • function
  • transactional
  • timeout-in-seconds
  • parameters
  • status-codes
Required if no pipeline-step or chunk-script-module-step Defines a task-oriented script for the step.
status status-codes
  • @code
  • description
 Required for status-codes. Defines the error codes and descriptions for the step.
status-codes pipeline-step, chunk-script-module-step, and script-module-step status Optional Defines the meta data for status codes returned for the step.
step-types Root object.
  • script-module-step
  • pipeline-step
  • chunk-script-module-step
Required  
timeout-in-seconds script-module-step   Optional Must be an integer that sets the timeout in seconds for the script module's function. There is no default timeout, but setting a limit is recommended.
total-count-function chunk-script-module-step   Optional References the function to be executed to determine the total number of items. If not defined, no total count is used.
transactional script-module-step and chunk-script-module-step   Optional Indicates if the module requires a database transaction. Must have value true or false. Default is false. If this value is set to true, the job step executes as a single, potentially very large, transaction. To avoid a negative impact on system performance and allow more granular transaction control, keep the default setting of false. Implement transaction handling within the job step using the dw.system.Transaction API.
value enum-values   Required for enum-values Comma-separated list of values allowed for the parameter
write-function chunk-script-module-step   Optional References the write function of the chunk script. If not defined, script must export a function named write.

Job Scope and Execution

The following table shows the results of possible settings of the supports-organization-context and supports-site-context elements in the steptypes.json file.
supports-organization-context supports-site-context Status
true true Invalid configuration.
true false Job is executable only if other steps in the same flow can be executed for the entire organization.
false true Job is executable only if other steps in the same flow can be executed for one or more sites.
false false Invalid configuration.
Related concepts
Steptypes.json Example
Related tasks
Create a Custom Job Step

© Copyright 2000-2023, Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners.

 Show URL Submit FeedbackPrivacy Policy
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.