Recipe Syntax & Schema

Last updated: September 08, 2018

Recipe Syntax

Recipes are basically JSON files that follow a special schema. If you’re comfortable working with standard JSON, then creating and customizing Recipes will be very easy.

One bit that is specific to SFDX-Falcon Recipes: Certain key/value pairs, like the top-level handlers property or the skipGroups and skipActions properties inside of the options object are listed as “optional”, but must still be present.

If you choose not to add data for these properties, that’s OK. Just make sure to add (depending on the property’s type) an empty string "", empty array [], or empty object {} as a value.

Recipe Schema

Recipes are basically JSON files that follow a special schema. Here’s a high-level overview of the structure.

  • Recipe Header: Basic info about the overall Recipe
  • Options: Specific settings that determine how the Recipe is invoked
    • Target Orgs: Detailed info about the Orgs that a Recipe can be run against
  • Step Groups: One or more collections of Steps, usually grouped by purpose or function
    • Steps: One or more individual work items that execute specific Actions thar are made available by the Recipe Engine.
      • Actions Can be a simple wrapper of a single Salesforce CLI command, or represent a multi-step process that leverages multiple Salesforce APIs to complete a complex task.
  • Handlers: Optional step-like work items that can be executed independently as a result of other Steps succeeding or failing

Top-Level Properties

Here’s what a Recipe looks like at a very high level. We’ll dive deeper into properties like options, recipeStepGroups, and handlers in the following sections.

Sample of Top-level Recipe JSON
{
  "recipeName":       "Build ADK Demo Org",
  "description":      "FSC-DriveWealth Demo",
  "recipeType":       "appx:demo-recipe",
  "recipeVersion":    "1.0.0",
  "schemaVersion":    "1.0.0",
  "options":          { /*EXAMPLES_BELOW*/ },
  "recipeStepGroups": [{/*EXAMPLES_BELOW*/}],
  "handlers":         [{/*EXAMPLES_BELOW*/}]
}
Top-level Recipe Properties
Property Key Type Required? Description
recipeName string Required Name of the Recipe.
description string Required Short description of the Recipe.
recipeType string Required Determines which Engine will be used to execute the Recipe. Possible values are appx:demo-recipe and appx:package-recipe.
recipeVersion string Required Developer-defined version (SemVer) of the Recipe. Developers should use this to keep track of Recipe versions over time.
schemaVersion string Required Version of the SFDX-Falcon Recipe Schema being used by the Recipe.
options object Required Recipe Options object. See the Options section for more detail.
recipeStepGroups [object] Required Array of Recipe Step Group objects. See the Step Groups section for more detail.
handlers [object] Required Array of Handler objects. Specify an empty array [] when not in use. NOTE: The Handlers feature is not yet implemented. Please leave this set to an empty array [].

Options

The options property points to a single Options object which contains information and settings that follow a general structure, but which can be highly specialized depending on the Engine used by the Recipe.

Sample of “options” JSON
"options":  {
  "haltOnError":     true,
  "haltOnFailure":   true,
  "noCustomInstall": false,
  "skipGroups":   ["group-name"],
  "skipActions":  ["action-name"],
  "targetOrgs":   [{/*EXAMPLES_BELOW*/}]
}
Properties of the “options” Object
Property Key Type Required? Description
haltOnError boolean Required When true, causes Errors that are normally caught to bubble and halt Recipe execution
haltOnFailure boolean Required When true, causes the Engine to throw an Error is a Action returns with a Failure
noCustomInstall boolean Required When true, prevents the user from setting Advanced Options when the Recipe is initialized
skipGroups [string] Optional Array of names of Step Groups that should be skipped when the Recipe is executed (see the Step Groups section for more detail)
skipActions [string] Optional Array of names of Actions that should be skipped when the Recipe is executed
targetOrgs [object] Required Array of Target Org objects. See the Target Orgs section for more detail.

Target Orgs

The targetOrgs property holds an array of Target Org objects. Each Target Org defines an org that the Recipe can be executed against. Both Scratch and Standard Orgs can function as Target Orgs.

Sample JSON for the targetOrgs Key
"targetOrgs": [
  {
    "orgName":        "Scratch Org Demo",
    "alias":          "my-scratch-org-demo",
    "description":    "Installs demo in a Scratch Org",
    "isScratchOrg":    true,
    "scratchDefJson": "demo-scratch-def.json"
  },
  {
    "orgName":        "Trial Org Demo",
    "alias":          "my-trial-org-demo",
    "description":    "Installs demo in a Trial EE org",
    "isScratchOrg":    false,
    "orgReqsJson":    "demo-org-reqs.json"        
  }
]
Properties of the targetOrgs Object
Property Key Type Required? Description
orgName string Required Label for the Target Org - Displayed to the user during target selection
alias string Required Alias that the Salesforce CLI will use to refer to the Target Org in SFDX commands
description string Required Short description explaining the purpose of this Target Org
isScratchOrg boolean Required When true indicates that the Target Org is a Scratch Org
scratchDefJson string *Optional Salesforce DX “scratch org definition” filename. Must point to a JSON file located inside the project’s config directory. Required when isScratchOrg is true
orgReqsJson string Optional SFDX-Falcon “org requirements” filename. Must point to a JSON file located inside the project’s config directory. Only used when isScratchOrg is false

Step Groups

The recipeStepGroups property holds an array of Step Group objects. Each Step Group is itself a collection of Step objects. Step Groups are executed in the order in which they are defined, with each Step Group executing its steps in their defined order before continuing with the next Group.

Sample of “recipeStepGroups” JSON
"recipeStepGroups": [
  {
    "stepGroupName": "Install Packages",
    "alias":         "install-packages",
    "description":   "Installs all managed and unmanaged packages needed by the demo",
    "recipeSteps": [{/*EXAMPLES_BELOW*/}]
  }
]
Properties of the “recipeStepGroups” Object
Property Key Type Required? Description
stepGroupName string Required Label for the Step Group. Displayed to the user if they choose to set advanced options when the Recipe is initialized.
alias string Required Alias for the Step Group. Used by other keys when a reference to a Step Group is required (ie. for specifing Step Groups in the options.skipGroups array.
description string Required Short description explaining the purpose of the Step Group.
recipeSteps [object] Required Array of Recipe Step objects. See the Steps and Actions section for more detail.

Steps

Step objects represent individual work items that synchronously executes specific Actions that are made available by the Recipe Engine. Each Step is executed in the order it was defined in the recipeSteps array.

Sample of Step Object JSON
"recipeSteps": [
  {
    "stepName":    "Install FSC Managed Package",
    "description": "Installs v214.3.0 of the FSC Managed Package",
    "action":      "install-package",
    "options": {
      "packageName":      "FSC Managed Package, Version 214.3.0",
      "packageVersionId": "04t1N000001bW4g"
    }
  },
  {
    "stepName":    "Install FSC Extension Package",
    "description": "Installs vWM_extv1.0 of the FSC extension package",
    "action":      "install-package",
    "options": {
      "packageName":      "FSC Extension Package, Version WM_extv1.0",
      "packageVersionId": "04t360000011vqy"
    }
  }
]
Properties of the “recipeStepGroups” Object
Property Key Type Required? Description
stepName string Required Label for the Step. Displayed to the user via a status message when your Recipe is being executed.
description string Required Short description explaining the purpose of the Step.
action string Required Name (identifier) of the Action to be executed as part of this Step.
options [any] Varies Array of zero or more properties of any type that might be required by the specific Action being executed.

Handlers

Handlers are optional step-like work items that can be executed independently as a result of other Steps succeeding or failing. As of September 2018 they are part of the Recipe Schema but are not yet a functional part of any Recipe Engines.

At this time, you should give an empty array value [] to this property.

Actions

Actions are the actual workers inside of a Recipe. They are defined and implemented as part of a specific Recipe Engine, which means that a Recipe of type appx:demo-recipe will implement different Actions than one of type appx:package-recipe.

Actions can be a simple wrapper of a single Salesforce CLI command, or represent a multi-step process that leverages multiple Salesforce APIs to complete a complex task. Each Action is called with a set of zero-or-more options which are also defined in the Step.

configure-admin-user

Allows you to perform configuration tasks like changing profiles or assigning permission sets to the user that is associated with the Salesforce DX alias for the target org.

In all cases where the Target Org is a Scratch Org, this will be the SysAdmin user that was created automatically when the Scratch Org was created.

Sample Step Using This Action
{
  "stepName":     "Configure Admin User",
  "description":  "Configures the Admin User based on admin-user-def.json",
  "action":       "configure-admin-user",
  "options": {
    "definitionFile": "admin-user-def.json"
  }
}
Options Used by This Action
Option Name Type Required? Description
definitionFile string Required Name of a JSON file located inside your project’s config directory. This file must use the standard Salesforce DX User Definition schema.

create-scratch-org

Creates a scratch org using the Developer Hub specified by the user when they created/cloned their ADK or APK project and a Salesforce DX Scratch Org Definition JSON file located in the project’s config directory.

Sample Step Using This Action
{
  "stepName":     "Create Scratch Org",
  "description":  "Creates a new scratch org",
  "action":       "create-scratch-org",
  "options":  {
    "scratchOrgAlias":  "my-demo-scratch-org",
    "scratchDefJson":   "demo-scratch-def.json"
  }
}
Options Used by This Action
Option Name Type Required? Description
scratchOrgAlias string Required Alias that will be used by the User’s local Salesforce DX environment to refer to the new Scratch Org. IMPORTANT: Make sure to delete the scratch org associated with this alias before creating a new scratch org, otherwise the Salesforce CLI’s link to the old scratch org will be lost.
scratchDefJson string Required Name of a JSON file located inside your project’s config directory. This file must use the standard Salesforce DX Scratch Org Definition schema.

create-user

Creates a new Salesforce User in the Target Org based on the contents of a Salesforce DX User Definition JSON file.

Sample Step Using This Action
{
  "stepName":     "Create User",
  "description":  "Creates a new user based on demo-user.json",
  "action":       "create-user",
  "options": {
    "definitionFile": "demo-user.json",
    "sfdxUserAlias":  "scratch-org-demo-user"
  }
}
Options Used by This Action
Option Name Type Required? Description
definitionFile string Required Name of a Salesforce DX User Definition JSON file located inside your project’s config directory.
sfdxUserAlias string Required Alias to use when storing a login reference to this user in the local Salesforce DX environment.

delete-scratch-org

Marks the Scratch Org pointed to by scratchOrgAlias for deletion. This is an important step to ensure that your Dev Hub org does not reach it’s limit for total acive scratch orgs.

Sample Step Using This Action
{
  "stepName":     "Delete Scratch Org",
  "description":  "Deletes an existing scratch org",
  "action":       "delete-scratch-org",
  "options":  {
    "scratchOrgAlias":  "my-demo-scratch-org"
  }
}
Options Used by This Action
Option Name Type Required? Description
scratchOrgAlias string Required Alias of the Scratch Org that should be marked for deletion.

deploy-metadata

Performs an MDAPI Deploy against the Target Org.

Metadata being deployed needs to be in its own directory inside of the ADK / APK project’s mdapi-source directory and must contain a valid package.xml file that describes the entities in the directory structure.

For more information on creating MDAPI source and package.xml files, see Working with the Zip File and Sample package.xml Manifest Files in the Metadata API Developer Guide

Sample Step Using This Action
{
  "stepName":     "Deploy App Config",
  "description":  "Deploys metadata found in mdapi-source/app-config",
  "action":       "deploy-metadata",
  "options": {
    "mdapiSource": "app-config"
  }
}
Options Used by This Action
Option Name Type Required? Description
mdapiSource string Required Name of a directory inside of your project’s mdapi-source directory. Must be the root of the directory tree that contains the metadata source files to deploy. The directory must contain a valid package.xml file describing the entities in the directory structure.

import-data-tree

Imports data into the Target Org using the force:data:import command under the hood. That command, in turn, relies on the Composite API which requires the creation of data-plan.json and data-source.json files.

For more information on creating these files, see Using Composite Resources in the REST API Developer Guide.

Sample Step Using This Action
{
  "stepName":     "Import Sample Data",
  "description":  "Imports sample Account and Contact data",
  "action":       "import-data-tree",
  "options": {
    "plan": "sample-customers/data-plan.json"
  }
}
Options Used by This Action
Option Name Type Required? Description
plan string Required Path inside of your project’s data directory to a data-plan.json file. This file can be used to insert simple single-object record sets or multiple data files that have master-detail relationships.

install-package

Installs a managed or unmanaged first-generation package to the Target Org. Requires you to know the 04t (Package Version ID) of the package that you want to install.

Sample Step Using This Action
{ 
  "stepName":     "Install Package",
  "description":  "Installs version 1.2 (Beta 10) of the Falcon-X package",
  "action":       "install-package",
  "options": {
    "packageName":      "Falcon-X, Version 1.2 (Beta 10)",
    "packageVersionId": "04t1N000001bW4g"
  }
}
Options Used by This Action
Option Name Type Required? Description
packageName string Required The human-readable name of the package you want to install. This string is displayed to the user via a status message when your Recipe is being executed.
packageVersionId string Required The 04t Package Version ID of the package that you want to install.