Creating Apps and Blocks via SDK

To initiate the creation of Apps and Blocks using the SDK, the first step involves instantiating the app_client and block_client.

For detailed guidance on Press Apps and Blocks, refer to the Reference Documentation and practical usage examples.

API Documentation is linked with every function in the Reference Documentation which would help in understanding the schema of the payload.

Creating Resource Dependencies with Artifacts

If we want to create a resource which is dependent on an Image (such as Block Spec) but we don’t want it to be source directly from the code repository, we can package the required files for image creation into a zip archive known as an Artifact.

More information for Artifact can be found in Artifact and Compression Document.

Providing Instance Type and Storage in Workflow Block Spec

When defining a workflow step in workflow block spec, we have the option to set the instance type and storage by including them in the resources key in the following format:

"resources": {
    "instanceTypeId": 23,
    "storage": "20GB"
}

A list of all available instances along with their corresponding instanceTypeId can be obtained using the list-instance-options function.

Adding the resources section is optional. If we don’t specify it for a particular step, the default values will be used. We can retrieve the default values by using get_default_resources function.

Providing Instance Type in Service Block Spec

When defining the config in service block spec, we have the option to set the instance type by including them in the resources key in the following format:

"resources": {
    "instanceTypeId": 1,
}

Session Stickiness in Service Block

This is only applicable for Service Blocks of kind web-app.

By default, session stickiness is disabled (false). You can activate session stickiness by setting the sessionStickiness parameter to true.

Session stickiness ensures that each user’s requests are consistently directed to a particular server. This feature is especially valuable for stateful applications like web applications that rely on server-stored session data.

Note that employing session stickiness may lead to unpredictable behavior and is not recommended if you plan to scale your application.

Providing Build Parameters in Blocks

We can define values to be build parameters in the config of a block spec, and then provide their values while creating the block deployment.

In block spec, we can define build parameters in the following format:

workflow_block_spec_body = {
    "version": "1",
    "kind": "workflow",
    "metadata": {
        "name": "workflow-block-new",
        "title": "Workflow Block",
        "summary": "Creating a new workflow block spec.",
        "description": "Creating a new workflow block spec from SDK.",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": {
        "images": {
            "image1": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {"npm_token": "random_token"},
            },
            "image2": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {"npm_token": "random_token"},
            },
        },
        "steps": {
            "step1": {
                "command": "@param:step_1_cmd",
                "type": "standard",
                "imageRef": "image1",
                "resources": {
                    "instanceTypeId": "@param:step_1_instance",
                    "storage": "@param:step_1_storage",
                },
            },
            "step2": {
                "command": "echo world",
                "type": "standard",
                "imageRef": "image2",
                "resources": {"instanceTypeId": 21, "storage": "20GB"},
            },
        },
    },
}
workflow_parameters = {
    "build": [
        {
            "defaultValue": "echo hello",
            "description": "Set the command to run with step 1",
            "name": "step_1_cmd",
            "required": False,
            "title": "Step One cmd",
            "type": "string",
        },
        {
            "defaultValue": 21,
            "description": "Select the instance type for step 1",
            "name": "step_1_instance",
            "options": [
                {"title": "Small", "value": 20},
                {"title": "Medium", "value": 21},
                {"title": "Large", "value": 32},
            ],
            "required": False,
            "title": "Step One Instance Type",
            "type": "number",
        },
        {
            "defaultValue": "10Mb",
            "description": "Specify storage for step one",
            "name": "step_1_storage",
            "required": False,
            "title": "Step One Storage",
            "type": "string",
        },
        {
            "description": "Provide build arguments",
            "name": "build_args",
            "title": "Build Arguments",
            "type": "object_array",
            "properties": [
                {
                    "name": "git_token",
                    "title": "Git Token",
                    "type": "string",
                },
                {
                    "name": "npm_token",
                    "title": "NPM Token",
                    "type": "string",
                },
            ],
        },
        {
            "description": "Provide watcher details",
            "name": "watchers",
            "title": "Watchers",
            "type": "object_array",
            "properties": [
                {
                    "name": "user",
                    "title": "User",
                    "type": "string",
                },
                {
                    "name": "webhook",
                    "title": "Webhook",
                    "type": "string",
                },
                {
                    "name": "email",
                    "title": "Email",
                    "type": "string",
                },
            ],
        },
    ]
}

workflow_block_spec = client.create_spec(
    body=workflow_block_spec_body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
    parameters=workflow_parameters,
    auto_run_on_deploy=True,
)

The response includes the id of the newly generated spec, which is useful when creating the deployment.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051690"
}

We can provide the values of these parameters while creating the block deployment in the following format:

body = {
    "metadata": {
        "description": "This Workflow loads Opportunities and Accounts table from Salesforce into Peak-managed Snowflake.",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "name": "lso-deployment",
        "summary": "Load Opportunities and Accounts table from Salesforce.",
        "tags": [{"name": "salesforce"}],
        "title": "LSO Deployment",
    },
    "parameters": {
        "build": {
            "step_1_cmd": "main.py",
            "step_1_instance": 23,
            "step_1_storage": "30GB",
            "build_args": "@param:build_args",
            "watchers": [
                {
                    "user": "user1@peak.ai",
                    "webhook": "https://abc.com/post",
                    "email": "user1@peak.ai",
                },
                {
                    "user": "user2@peak.ai",
                    "webhook": "https://abc.com/post",
                    "email": "user2@peak.ai",
                },
            ],
        }
    },
    "revision": {"notes": "This is the initial revision"},
    "spec": {
        "id": "0bddb4c6-40c5-45c3-b477-fceb2c051690",
        "release": {"version": "1.0.0"},
    },
}

workflow_block_deployment = block_client.create_deployment(body)

It returns the id of the newly created block deployment.

{
    "id": "056b3eb4-79e7-4c00-9762-d8838177ebb5"
}

Providing Run Parameters in Blocks

We can define run parameters in the block spec and provide their values while creating the block deployment. The values for these parameters can be updated even after the deployment has been done.

The following types of parameters are supported: boolean, string, string_array, number, number_array, object and object_array.

In block spec, we can define run parameters in the following format:

"parameters": {
    "run": [
        {
            "defaultValue": "AVG",
            "description": "Select an aggregation function (e.g., AVG, SUM, COUNT)",
            "name": "agg_type",
            "required": false,
            "title": "Agg Type",
            "type": "string",
        },
        {
            "defaultValue": false,
            "description": "Enable email notifications",
            "name": "email_notifications",
            "required": false,
            "title": "Email Notifications",
            "type": "boolean",
        },
        {
            "defaultValue": 10,
            "description": "Select the number of iterations",
            "name": "num_iterations",
            "options": [
                {
                    "title": "Low",
                    "value": 10,
                },
                {
                    "title": "Medium",
                    "value": 50,
                },
                {
                    "title": "High",
                    "value": 100,
                },
            ],
            "required": false,
            "title": "Number of Iterations",
            "type": "number",
        },
        {
            "defaultValue": ["input.csv", "output.csv"],
            "description": "Specify input and output file names",
            "name": "file_names",
            "required": true,
            "title": "File Names",
            "type": "string_array",
        },
        {
            "description": "Specify database configuration",
            "name" : "db_config",
            "title" : "Database Configuration",
            "type" : "object",
            "properties": [
                {
                    "name": "host",
                    "title": "Host",
                    "type": "string",
                    "required": true
                },
                {
                    "name": "port",
                    "title": "Port",
                    "type": "number",
                    "required": true
                },
                {
                    "name": "db_credentials",
                    "title": "Database Credentials",
                    "type": "object",
                    "properties": [
                        {
                            "name": "username",
                            "title": "Username",
                            "type": "string",
                            "required": true
                        },
                        {
                            "name": "password",
                            "title": "Password",
                            "type": "string",
                            "required": true
                        }
                    ]
                }
            ],
        },
        {
            "description": "Specify chart attributes",
            "name" : "chart_attributes",
            "title" : "Chart Attributes",
            "type" : "object_array",
            "properties": [
                {
                    "name": "chart_name",
                    "title": "Chart Name",
                    "type": "string",
                },
                {
                    "name": "chart_type",
                    "title": "Chart Type",
                    "type": "string",
                },
                {
                    "name": "chart_data",
                    "title": "Chart Data",
                    "type": "string_array",
                }
            ],
        }
    ],
}

We can provide the values of these parameters while creating the block deployment in the following format:

"parameters": {
    "run": {
        "agg_type": "AVG",
        "email_notifications": true,
        "num_iterations": 50,
        "file_names": ["input.csv", "output.csv"],
        "db_config": {
            "host": "localhost",
            "port": 5432,
            "db_credentials": {
                "username": "admin",
                "password": "admin123"  // pragma: allowlist secret
            }
        },
        "chart_attributes": [
            {
                "chart_name": "chart1",
                "chart_type": "line",
                "chart_data": ["data1", "data2"]
            },
            {
                "chart_name": "chart2",
                "chart_type": "bar",
                "chart_data": ["data3", "data4"]
            }
        ]
    },
}

Please see the end-to-end examples for how to utilize run parameters within your source code

Providing Triggers in Workflow Block Spec

For Workflow Blocks, triggers can be one of the following: Time based, Webhook based or Manual.

// For Time Based Trigger, cron expression is required
"triggers": [
    {
        "cron": "0 0 * * *",
    },
]

// For Webhook Based Trigger, we need to provide webhook key which is a boolean
"triggers": [
    {
        "webhook": true,
    },
]

// For Manual Trigger, we can either skip this key or provide an empty list
"triggers": []

Providing Watchers in Workflow Block Spec

For Workflow Blocks, we can set multiple watchers which can be User Based or Webhook Based.

// For User Based Watcher, user email is required. We also need to specify the events for which we want to receive notifications.
"watchers": [
    {
        "user": "someone@peak.ai",
        "events": {
            "success": false,
            "fail": true,
        },
    },
]

// For Webhook Based Watcher, we need to provide webhook details such as webhook url and payload along with the events for which we want to receive notifications.
"watchers": [
    {
        "webhook": {
            "name": "info",
            "url": "https://abc.com/post",
            "payload": "{'pingback-url':'https:/workflow/123'}",
        },
        "events": {
            "success": false,
            "fail": true,
            "runtimeExceeded": 10,
        },
    },
]

// For Email Based Watcher, we need to provide details such as email watcher name, recipients and events for which we want to receive notifications.
"watchers": [
    {
        "email": {
            "name": "info",
            "recipients": ["user1@peak.ai", "user2@peak.ai"],
        },
        "events": {
            "success": false,
            "fail": true,
            "runtimeExceeded": 10,
        },
    },
]

// We can also add multiple watchers of different types
"watchers": [
    {
        "user": "someone@peak.ai",
        "events": {
            "success": false,
            "fail": true,
        },
    },
    {
        "webhook": {
            "name": "info",
            "url": "https://abc.com/post",
            "payload": "{'pingback-url':'https:/workflow/123'}",
        },
        "events": {
            "success": false,
            "fail": true,
            "runtimeExceeded": 10,
        },
    },
    {
        "email": {
            "name": "info",
            "recipients": ["user1@peak.ai", "user2@peak.ai"],
        },
        "events": {
            "success": false,
            "fail": true,
            "runtimeExceeded": 10,
        },
    },
]

Providing Image Details for Block Specs

For creating block specs, there are three ways of providing image details.

1. Using imageRef: Multiple image configurations can be included in block config and referenced in workflow steps as shown in following example.

{
    "config": {
        "images": {
            "image1": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {
                    "npm_token": "random_token"
                }
            },
            "image2": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {
                    "npm_token": "random_token"
                }
            }
        },
        "steps": {
            "step1": {
                "command": "echo hello",
                "type": "standard",
                "imageRef": "image1",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB"
                }
            },
            "step2": {
                "command": "echo world",
                "type": "standard",
                "imageRef": "image2",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "20GB"
                }
            }
        }
    }
}

2. Using inline image: Image configuration can be directly provided within the workflow step or service.

{
    "config": {
        "steps": {
            "step1": {
                "command": "echo hello",
                "type": "standard",
                "image": {
                    "context": ".",
                    "dockerfile": "Dockerfile",
                    "version": "0.0.1",
                    "buildArguments": {
                        "npm_token": "random_token"
                    }
                },
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB"
                }
            }
        }
    }
}

3. Using imageDetails: Existing image versions can be utilized in workflow steps and services. The block’s scope should be private when using existing image details.

{
    "config": {
        "steps": {
            "step1": {
                "command": "echo world",
                "type": "standard",
                "imageDetails": {
                    "id": 1,
                    "versionId": 1
                },
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "20GB"
                }
            }
        }
    }
}

Usage Examples

Block Specs

Creating a Block Spec

A block spec can be created by using Block create_spec function.

To execute the resources of the block deployment, we can set the autoRunOnDeploy parameter to True in the block spec. This will execute the resources upon complete deployment of the block.

Consider the following example:

workflow_block_spec_body = {
    "version": "1",
    "kind": "workflow",
    "metadata": {
        "name": "workflow-block-shared",
        "title": "Workflow Block",
        "summary": "Creating a new workflow block spec.",
        "description": "Creating a new workflow block spec from SDK.",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": {
        "triggers": [],
        "images": {
            "image1": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {"npm_token": "random_token"},
            },
            "image2": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {"npm_token": "random_token"},
            },
        },
        "steps": {
            "step1": {
                "command": "@param:step_1_cmd",
                "type": "standard",
                "imageRef": "image1",
                "resources": {
                    "instanceTypeId": "@param:step_1_instance",
                    "storage": "@param:step_1_storage",
                },
            },
            "step2": {
                "command": "echo world",
                "type": "standard",
                "imageRef": "image2",
                "resources": {"instanceTypeId": 21, "storage": "20GB"},
            },
            "step3": {
                "type": "http",
                "method": "get",
                "url": "https://peak.ai",
                "auth": {
                    "type": "oauth",
                    "clientId": "client-id",
                    "clientSecret": "client-secret",  # pragma: allowlist secret
                    "authUrl": "https://get-access-token",
                },
                "payload": "{}",
                "headers": {
                    "absolute": {
                        "x-auth-tenant": "some-tenant",
                    },
                    "secrets": {
                        "x-auth-token": "token",
                    },
                },
            },
            "step4": {
                "type": "sql",
                "sqlQueryPath": "path/to/sql",
                "parameters": {
                    "env": {
                        "key": "value",
                    },
                    "inherit": {
                        "key": "value",
                    },
                },
            },
            "step5": {
                "type": "export",
                "parents": ["stepName3"],
                "schema": "schema_name",
                "table": "table_name",
                "sortBy": "column_name",
                "sortOrder": "asc",
                "compression": False,
            },
        },
    },
}

workflow_parameters = {
    "build": [
        {
            "defaultValue": "echo hello",
            "description": "Set the command to run with step 1",
            "name": "step_1_cmd",
            "required": false,
            "title": "Step One cmd",
            "type": "string",
        },
        {
            "defaultValue": 1,
            "description": "Select the instance type for step 1",
            "name": "step_1_instance",
            "options": [
                {
                    "title": "Small",
                    "value": 1,
                },
                {
                    "title": "Medium",
                    "value": 17,
                },
                {
                    "title": "Large",
                    "value": 32,
                },
            ],
            "required": false,
            "title": "Step One Instance Type",
            "type": "number",
        },
        {
            "defaultValue": "10Mb",
            "description": "Specify storage for step one",
            "name": "step_1_storage",
            "required": false,
            "title": "Step One Storage",
            "type": "string",
        },
    ],
    "run": [
        {
            "defaultValue": "AVG",
            "description": "Select an aggregation function (e.g., AVG, SUM, COUNT)",
            "name": "agg_type",
            "required": False,
            "title": "Agg Type",
            "type": "string",
        },
        {
            "defaultValue": False,
            "description": "Enable email notifications",
            "name": "email_notifications",
            "required": False,
            "title": "Email Notifications",
            "type": "boolean",
        },
        {
            "defaultValue": 10,
            "description": "Select the number of iterations",
            "name": "num_iterations",
            "options": [
                {
                    "title": "Low",
                    "value": 10,
                },
                {
                    "title": "Medium",
                    "value": 50,
                },
                {
                    "title": "High",
                    "value": 100,
                },
            ],
            "required": False,
            "title": "Number of Iterations",
            "type": "number",
        },
        {
            "defaultValue": ["input.csv", "output.csv"],
            "description": "Specify input and output file names",
            "name": "file_names",
            "required": True,
            "title": "File Names",
            "type": "string_array",
        },
    ],
}

workflow_block_spec = block_client.create_spec(
    body=workflow_block_spec_body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
    parameters=workflow_parameters,
    auto_run_on_deploy=True,
)

The response includes the id of the newly generated spec, which is useful for creating apps or new block spec releases.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609"
}

More examples for creating the block spec can be found here.

Creating a new Block Spec Release

To modify the configuration of an existing block spec, a new block spec release needs to be generated. This can be achieved using the create_spec_release function. (Note that this example changes the config and removes build parameters).

To execute the resources of the block deployment, we can set the autoRunOnDeploy parameter to True in the block spec. This will execute the resources upon full deployment of the block.

body = {
    "config": {
        "triggers": [],
        "images": {
            "example-image": {
                "buildArguments": {
                    "CHUNK_SIZE": "1000",
                },
                "context": ".",
                "dockerfile": "Dockerfile",
                "secrets": ["SECRET_1"],
                "useCache": False,
                "version": "0.0.1",
            },
        },
        "steps": {
            "step-1": {
                "type": "standard",
                "imageRef": "example-image",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB",
                },
                "command": "python main.py",
            },
            "step2": {
                "type": "http",
                "method": "get",
                "url": "https://peak.ai",
                "auth": {
                    "type": "oauth",
                    "clientId": "client-id",
                    "clientSecret": "client-secret",  # pragma: allowlist secret
                    "authUrl": "https://get-access-token",
                },
                "payload": "{}",
                "headers": {
                    "absolute": {
                        "x-auth-tenant": "some-tenant",
                    },
                    "secrets": {
                        "x-auth-token": "token",
                    },
                },
            },
            "step3": {
                "type": "sql",
                "sqlQueryPath": "path/to/sql",
                "parameters": {
                    "env": {
                        "key": "value",
                    },
                    "inherit": {
                        "key": "value",
                    },
                },
            },
            "step4": {
                "type": "export",
                "parents": ["stepName3"],
                "schema": "schema_name",
                "table": "table_name",
                "sortBy": "column_name",
                "sortOrder": "asc",
                "compression": False,
            },
        },
    },
    "release": {
        "version": "2.0.0",
        "notes": "This is a revised release",
    },
}

workflow_parameters = {
    "run": [
        {
            "defaultValue": "AVG",
            "description": "Select an aggregation function (e.g., AVG, SUM, COUNT)",
            "name": "agg_type",
            "required": False,
            "title": "Agg Type",
            "type": "string",
        },
        {
            "defaultValue": False,
            "description": "Enable email notifications",
            "name": "email_notifications",
            "required": False,
            "title": "Email Notifications",
            "type": "boolean",
        },
        {
            "defaultValue": 10,
            "description": "Select the number of iterations",
            "name": "num_iterations",
            "options": [
                {
                    "title": "Low",
                    "value": 10,
                },
                {
                    "title": "Medium",
                    "value": 50,
                },
                {
                    "title": "High",
                    "value": 100,
                },
            ],
            "required": False,
            "title": "Number of Iterations",
            "type": "number",
        },
        {
            "defaultValue": ["input.csv", "output.csv"],
            "description": "Specify input and output file names",
            "name": "file_names",
            "required": True,
            "title": "File Names",
            "type": "string_array",
        },
    ],
}

new_spec_release = block_client.create_spec_release(
    spec_id="0bddb4c6-40c5-45c3-b477-fceb2c051609",
    body=body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
    parameters=workflow_parameters,
    auto_run_on_deploy=True,
)

The response provides the id and release version of the newly generated spec release.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
    "release": {
        "version": "2.0.0"
    }
}

Block Deployments

Creating a new Block Deployment

The blocks can be deployed using create_deployment function.

Consider the following example, where we are creating a new block deployment from the block spec release which we created in the previous step.

body = {
    "metadata": {
        "description": "Creating a new workflow block deployment.",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "name": "new-deployment",
        "summary": "Creating new deployment.",
        "tags": [
            {
                "name": "sdk",
            },
        ],
        "title": "New Deployment",
    },
    "parameters": {
        "run": {
            "agg_type": "AVG",
            "email_notifications": True,
            "num_iterations": 50,
            "file_names": ["input.csv", "output.csv"],
        },
    },
    "revision": {
        "notes": "This is the initial revision",
    },
    "spec": {
        "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
        "release": {
            "version": "1.0.0",
        },
    },
}

workflow_block_deployment = block_client.create_deployment(body)

It returns the id of the newly created block deployment.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609"
}

Block Deployments Revisions

Creating a new Block Deployment Revision

Consider the following example, where we are creating a new block deployment revision from the block deployment above.

body = {
    "release": {"version": "1.0.0"},
    "revision": {"notes": "This is a new revision"},
    "parameters": {
        "run": {
            "agg_type": "AVG",
            "email_notifications": False,
            "num_iterations": 20,
            "file_names": ["input.csv", "output.csv"],
        }
    },
}

workflow_block_deployment_revision = block_client.create_deployment_revision(
    deployment_id="0bddb4c6-40c5-45c3-b477-fceb2c051609", body
)

It returns the id and revision number for the newly created revision. In this case we are expecting a second revision because the first deployment created the first revision automatically.

{
    "id": "e04e308d-98dc-4443-bb02-c4ef990a3fdc",
    "revision": 2
}

App Specs

Creating an App Spec

An app can be considered as a collection of blocks. We can create an app spec by using existing block specs or block spec releases. It can be generated using the create_spec function.

It’s worth noting that the creation of an app spec with a shared scope is possible only when all the associated blocks are also shared with those tenants.

To execute the resources of the app deployment, we can set the autoRunOnDeploy parameter to True corresponding to the block spec in the config section. This will execute the resources upon full deployment of the app.

Consider the following example, where we are creating an app spec using existing block specs.

spec_body = {
    "version": "1",
    "kind": "app",
    "metadata": {
        "name": "sdk",
        "title": "New App Spec",
        "summary": "Create new app spec",
        "description": "Creating app spec from SDK",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-spec-pics.com/image-1.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": [
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "1.0.0",
            },
            "autoRunOnDeploy": True,
        },
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "2.0.0",
            },
            "autoRunOnDeploy": False,
        },
    ],
}


created_app_spec = app_client.create_spec(
    body=spec_body,
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
)

The response includes the id of the newly generated app spec.

{
    "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd"
}

Creating a new App Spec Release

Similar to blocks, a new app spec release can be generated to modify the spec configuration. We can create a new app spec release by using create_spec_release function.

To execute the resources of the app deployment, we can set the autoRunOnDeploy parameter to True corresponding to the block spec in the config section. This will execute the resources upon full deployment of the app.

Consider the following example, where we are creating a new app spec release from the app spec which we created in the previous step.

body = {
    "config": [
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "1.0.0",
            },
            "autoRunOnDeploy": True,
        },
    ],
    "release": {
        "version": "2.0.0",
        "notes": "This is a revised release",
    },
}


new_spec_release = app_client.create_spec_release(
    spec_id="a3e77006-86f3-4829-8c43-f21ad462dbbd",
    body=body,
)

The response provides the id and release version of the newly generated spec release.

{
    "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
    "release": {
        "version": "2.0.0"
    }
}

App Deployments

Creating a new App Deployment

Deploying an app spec leads to deployment of all constituent blocks. We can create a new app deployment by using create_deployment function.

deployment = app_client.create_deployment(
    body={
        "metadata": {
            "description": "Creating a new deployment.",
            "descriptionContentType": "text/markdown",
            "imageUrl": "https://my-spec-pics.com/image-1.jpg",
            "name": "new-deployment",
            "summary": "This creates a new deployment",
            "tags": [
                {
                    "name": "sdk",
                },
            ],
            "title": "New Deployment",
        },
        "parameters": {
            "block-1": {
                "run": {
                    "agg_type": "AVG",
                    "email_notifications": True,
                    "num_iterations": 50,
                    "file_names": ["input.csv", "output.csv"],
                },
            },
            "block-2": {
                "run": {
                    "agg_type": "MAX",
                    "email_notifications": False,
                    "num_iterations": 10,
                    "file_names": ["input.csv", "output.csv"],
                },
            },
        },
        "revision": {
            "notes": "This is the initial revision",
        },
        "spec": {
            "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
            "release": {
                "version": "1.0.0",
            },
        },
    },
)

The response includes the id of the newly created app deployment.

{
    "id": "e04e308d-98dc-4443-bb02-c4ef990a3fdc"
}

App Deployments Revision

Creating a new App Deployment Revision

We can create a new app deployment revision by providing the id of the deployment we want to to revise and a json object of the changes you want to revise. The deployment Id provided in this case would be an app deployment Id which could contain new blocks, and parameters. So when revising this block you can provide details according to the data you want to update. See example below

body = {
    "release": {"version": "1.0.0"},
    "revision": {"notes": "This is a new revision"},
    "parameters": {
        "block-spec-name-a": {
            "build": {
                "storage": "10Mb",
                "instance_type": 21,
                "use_cache": true,
                "secrets": ["API_KEY", "GITHUB_TOKEN"],
            },
            "run": {
                "agg_type": "AVG",
                "max_retries": 1,
                "enable_download": true,
                "tab_rendering": ["tab1", "tab2"],
            },
        },
        "block-spec-name-b": {
            "build": {"storage": "10Mb", "instance_type": 21, "use_cache": true},
            "run": {
                "agg_type": "AVG",
                "shell_path": "sh",
                "enable_flux_capacitor": true,
            },
        },
    },
}

deployment_revision = app_client.create_deployment_revision(
    deployment_id="e04e308d-98dc-4443-bb02-c4ef990a3fdc", body
)

It returns the id and revision number for the newly created revision.

{
    "id": "db283fc2-9164-4027-b09e-8c1ecedb122b",
    "revision": 2
}

Fetching related Blocks within an App

If your Block is designed to be part of an App of connected Blocks, you may need to fetch certain aspects of those related Blocks within your source code. Here is how you would do that:

• In the source code, you need to get the details of related blocks, so that you can use them in your script. To do so, you can use the peak-sdk’s get_related_block_details function.

• The function uses the PRESS_DEPLOYMENT_ID environment variable to get the related block details. This environment variable is automatically injected in blocks when they are deployed using Press. So, you can just add the following statement to your Python script

  from peak.press import blocks
  
  client: blocks.Block = blocks.get_client()
  
  parameters = get_related_block_details()
  

• But we won’t have a Press Deployment ID when we are testing the block locally, or when we deploy it without the Press. So, how do we test out the workflow?

  • Turns out it is quite easy, the get_related_block_details function has an optional argument called fallback_details_file which can help in this. To use it, create a YAML file and add in all the details that the block needs. Example:

    ```yaml
    # fallback.yml
    
    - id: "694cb34f-c869-45aa-96e8-0b9bdeef5ea8"
      resource_id: "6789"
      kind: workflow
      name: my-workflow
      status: deployed
    ```
    

  • Then, pass in the path to this file to the fallback_details_file parameter. Now, whenever the Press Deployment ID isn’t available, the data from the file will automatically be returned by the get_related_block_details function. And thus the block can run absolutely fine.

    ```python
    from peak.press import blocks
    
    client: blocks.Block = blocks.get_client()
    
    parameters = client.get_related_block_details(fallback_details_file="fallback.yml")
    ```
    

• This method will return an empty List if a Block is not part of an App, adequate error handling and fallbacks should be employed

Executing the resources of an app or block deployment

The execute_resources method can be used to execute resources of the latest revision an app or block deployment for whom the autoRunOnDeploy is enabled. This property can be enabled or disabled while creating the app or block spec or spec release.

execute_response: dict[str, Any] = client.execute_resources(
    deployment_id="e04e308d-98dc-4443-bb02-c4ef990a3fdc"
)

This method executes the resources of the specified deployment. The deployment must be in the deployed state for this method to work. It returns the response in the following format:

{
    "executeResponse": [
        {
            "blockSpecId": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "version": "1.0.0",
            "executionId": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
            "status": "executed"
        }
    ]
}