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.

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

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

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

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

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

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 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

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

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

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

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

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

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