Build, Manage, Schedule, and Run CRM Analytics Recipes with REST APIs

Describe and Discover Recipes

Retrieve all your CRM Analytics recipes with the GET wave/recipes endpoint. You can filter the recipes collection returned by:

• format— specifies current Data Prep recipes: (R3) or Data Prep Classic recipes (R2).
  1/wave/recipes?format=R2

• licenseType— specifies the CRM Analytics license type: EinsteinAnalytics or Sonic.
  1/wave/recipes?licenseType=EinsteinAnalytics

• pageSize— the number of items to be returned in the collection for pagination. The minimum is 1, maximum is 200, and default is 25.
  1/wave/recipes?pageSize=50

• q— Use search terms to find recipes by name or label. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string.
  1/wave/recipes?q=My Recipe

• sort— The type of sort order to be applied to the returned collection. Valid values are App, CreatedBy, CreatedDate, LastModified, LastModifiedBy, Mru, Name, and Type.
  1/wave/recipes?sort=Name

Describe an existing recipe by specifying the recipeId (starts with 05vB) and the format of the recipe: R3 or R2.

1/wave/recipes/05vB0000000xxxxxxx?format=R3

The GET request returns a RecipeRepresentation response, which contains the recipe definition (nodes and UI metadata), schedule attributes, and validation details. It also contains the targetDataflowId, used to run the recipe. For example, GET /wave/recipes/05vB0000000xxxxxxx?format=R3 returns this RecipeRepresentation JSON response:

1{
2    ...
3    "format" : "R3",
4    "id" : "05vB0000000xxxxxxx",
5    "label" : "MyTestRecipe",
6    "name" : "MyTestRecipe",
7    ...
8    "recipeDefinition" : {
9        ...
10    },
11    "scheduleAttributes" : {
12        ...
13    }, 
14    "targetDataflowId" : "02KB000000xxxxxxxx",
15    ...
16    "validationDetails" : [ ]
17}

Use the RecipeRepresentation JSON response to work with the recipe as detailed.

Inspect Recipe Nodes

The RecipeDefinition contains the recipe name, the recipe API version, the UI metadata for recipe display (used by CRM Analytics Studio), and a Map of RecipeNodeRepresentation objects.

Here’s a closer look at the Map of RecipeNodeRepresentation objects in the RecipeDefinition object from the RecipeRepresentation JSON response. The example response is a simple recipe that loads data created from the Opportunities sObject, filters the data by Closed Won, and saves the results to a new dataset named Opptys Closed Won.

1{
2    ...
3    "recipeDefinition": {
4        "nodes" : {
5            "LOAD_DATASET0" :  {
6                "action" : "load", 
7                "parameters": {
8                    "dataset" : {
9                        "label" : "Opportunities",
10                        "name" : "opportunity",
11                        "type" : "analyticsDataset"
12                    },
13                    "fields" : ["AccountId", "Amount", "OpenClosedWonLost", ...]
14                },
15                "sources" : []
16            },
17            "FILTER0" : {
18                "action" : "filter",
19                "parameters" : {
20                    "filterExpressions" : [ {
21                        "field" : "OpenClosedWonLost",
22                        "operands" : [ "Closed Won" ],
23                        "operator" : "EQUAL", 
24                        "type" : "TEXT"
25                    } ]
26                },
27                "sources": [ "LOAD_DATASET0" ]
28            },
29            "OUTPUT0" : {
30                "action" : "save", 
31                "parameters": {
32                    "dataset" : {
33                        "folderName" : "SharedApp",
34                        "label" : "Opptys Closed Won",
35                        "name" : "OpptysClosedWon",
36                        "type" : "analyticsDataset"
37                    },
38                    "fields" : []
39                },
40                "sources" : [ "FILTER0" ]
41            }
42        },
43        "ui" : { ... }, 
44        "version" : "52.0"
45    },
46    ...
47}

Delete a Recipe

To delete a recipe, use the DELETE /wave/recipes/<recipeId> endpoint. This action deletes the recipe and any associated dataflow jobs. No request body is required and the response is a success or error message.

Work with Recipe Histories

Each time a user updates and saves a recipe, a version history is created, tracking the changes to the recipe over time. To see all of the histories for a recipe, use the GET /wave/recipes/<recipeId>/histories endpoint.

1{
2    "historyId" : "0RmB0000000xxxxxxx",
3    "historyLabel" : "Reverting to version x"
4}

Schedule a Recipe

While the scheduleAttributes are part of the RecipeRepresentation, to update a schedule, the /wave/asset/<assetId>/schedule endpoint must be used.

To see the current schedule, use GET /wave/asset/<assetId>/schedule, where <assetId> is the recipe id. The request returns a ScheduleRepresentation response.

To create or update the schedule, use PUT /wave/asset/<assetId>/schedule. See Schedule Dataflows, Recipes, and Data Syncs for example ScheduleInputRepresentation requests.

To delete a schedule, use DELETE /wave/asset/<assetId>/schedule.

Run a Recipe

To run a recipe, with or without a schedule, use the /wave/dataflowjobs POST endpoint.

The POST takes a dataflowId and a command to start the dataflow job. For a recipe, the dataflowId is the targetDataflowId from the RecipeRepresentation. For recipes, the targetDataflowId starts with 02KB.

1{
2    "dataflowId": "02KB000000xxxxxxxx",
3    "command": "start"
4}

1{
2    "command": "stop"
3}

Recipe Notifications

1{
2    "notificationLevel" : "Always",
3    "longRunningAlertInMins" : 90
4}