# Recipe lifecycle management
The following endpoints are available to Embedded partners only. These endpoints allow you to create and manage export manifests programmatically. You can also use these endpoints to import and export a package to or from a customer workspace using one set of API credentials.
If you plan to import or export packages to or from your own environments (not customer workspaces), use the endpoints listed in the Developer API documentation.
GLOSSARY
Manifest: A container of different assets, including recipes, lookup tables, connections, and more.
Package: The build of a manifest. Contains the source code of each asset within a manifest. It includes the latest version of the asset available when the package was created.
# Quick reference
Type | Resource | Description |
---|---|---|
GET | /api/managed_users/:managed_user_id/export_manifests/folder_assets | View assets in a folder. |
POST | /api/managed_users/:managed_user_id/export_manifests | Create an export manifest. |
PUT | /api/managed_users/:managed_user_id/export_manifests/:id | Update an export manifest. |
GET | /api/managed_users/:managed_user_id/export_manifests/:id | View an export manifest. |
DELETE | /api/managed_users/:managed_user_id/export_manifests/:id | Delete an export manifest. |
POST | /api/managed_users/:id/imports | Import package into a folder in a customer workspace. |
GET | /api/managed_users/:id/imports/:package_id | Get status of an imported package. |
POST | /api/managed_users/:managed_user_id/exports/:manifest_id | Export package based on the manifest ID. Requires the oem_vendor privilege. |
GET | /api/managed_users/:managed_user_id/exports/:package_id | Returns the status of a package export. Requires the oem_vendor privilege. |
# View assets in a folder
View assets in a folder. You can use this endpoint to help you create or update an export manifest.
GET /api/managed_users/:managed_user_id/export_manifests/folder_assets
# URL parameters
Name | Type | Description |
---|---|---|
managed_user_id | string required | Embedded customer Account ID or External ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
folder_id | integer optional | The ID of the folder containing the asset. Defaults to the root folder. |
include_test_cases | boolean optional | This parameter includes test cases from the list of assets. Defaults to false. |
include_data | boolean optional | This parameter includes data from the list of assets. Defaults to false. |
# Sample request
curl -X GET 'https://www.workato.com/api/managed_users/91928/export_manifests?folder_id=423' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"result": {
"assets": [
{
"id": 12,
"name": "Copy of Recipeops",
"type": "recipe",
"version": 1,
"folder": "",
"absolute_path": "All projects",
"root_folder": false,
"unreachable": false,
"zip_name": "copy_of_recipeops.recipe.json",
"checked": true
}
]
}
}
# Create an export manifest
Create an export manifest.
POST /api/managed_users/:managed_user_id/export_manifests
# URL parameters
Name | Type | Description |
---|---|---|
managed_user_id | string required | Embedded customer ID or external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Payload
Name | Type | Description |
---|---|---|
name | string required | Name of the new manifest. |
assets | object required | Dependent assets. |
id | integer required | ID of the dependency. |
type | string required | Type of dependent asset. |
checked | boolean optional | Determines if the asset is included in the manifest. Defaults to true . |
version | integer optional | The version of the asset. Defaults to the latest version. |
folder | string optional | The folder that contains the asset. Defaults to "" . |
absolute_path | string optional | The absolute path of the asset. Defaults to root folder. |
root_folder | boolean optional | Name the root folder. Defaults to false . |
unreachable | boolean optional | Whether the asset is unreachable. Defaults to false . |
zip_name | string optional | Name in the exported zip file. By default, Workato auto-generates a name with this structure: asset_#{index}.#{type}.json . |
folder_id | integer optional | The ID of the folder containing the asset. Defaults to the root folder. |
auto_generate_assets | boolean optional | Auto-generates assets from a folder. Defaults to false. |
include_test_cases | boolean optional | This parameter includes test cases from automatic asset generation. Defaults to false. |
include_data | boolean optional | This parameter includes data from automatic asset generation. Defaults to false. |
auto_run | boolean optional | Starts export package generation automatically. Defaults to false. |
include_tags | boolean optional | Specifies whether to include tags assigned to assets in the export manifest. Tags are excluded from the manifest when set to false . Set to false by default. |
# Sample request
curl -X POST 'https://www.workato.com/api/managed_users/91928/export_manifests' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"export_manifest": {
"name": "Test Manifest",
"assets": [
{
"id": 12,
"name": "Copy of Recipeops",
"type": "recipe",
"version": 1,
"folder": "",
"absolute_path": "All projects",
"root_folder": false,
"unreachable": false,
"zip_name": "copy_of_recipeops.recipe.json",
"checked": true
}
],
"folder_id": 112,
"include_tags": true
}
}'
# Auto-generate assets
If you plan for Workato to auto-generate your assets, you can pass the parameter auto_generate_assets
into the payload of the request. You must specify the folder_id
you plan to have auto-generated. You can also choose to include test cases and data by including the include_test_cases
or include_data
parameters. Otherwise, they are excluded by default.
Additionally, you can include auto_run
in the payload to generate the package automatically.
# Sample request
curl -X POST 'https://www.workato.com/api/managed_users/91928/export_manifests' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"export_manifest": {
"name": "Test Manifest",
"folder_id": 112,
"auto_generate_assets": true,
"include_test_cases": true,
"include_data": true,
"auto_run": true
}
}'
# Response
{
"result": {
"id": 12,
"name": "Test Manifest",
"last_exported_at": null,
"created_at": "2023-02-27T02:44:59.447-08:00",
"updated_at": "2023-02-27T02:44:59.447-08:00",
"deleted_at": null,
"project_path": "Folder 1",
"status": "working"
}
}
# Possible statuses
Status | Definition |
---|---|
working | Active. |
archived | Deleted. |
# Update an export manifest
Update an export manifest.
PUT /api/managed_users/:managed_user_id/export_manifests/:id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the dependency. |
managed_user_id | string required | Embedded customer ID or external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Payload
Update the properties contained in assets[]
to replace the assets previously defined.
Name | Type | Description |
---|---|---|
name | string optional | Name of the manifest. Update this value to change the manifest name. Defaults to previous name. |
assets | object required | Dependent assets. |
id | integer required | ID of the dependency. |
type | string required | Type of dependent asset. |
checked | boolean optional | Determines if the asset is included in the manifest. Defaults to true . |
version | integer optional | The version of the asset. Defaults to the latest version. |
folder | string optional | The folder that contains the asset. Defaults to "" . |
absolute_path | string optional | The absolute path of the asset. Defaults to root folder. |
root_folder | boolean optional | Name root folder. Defaults to false . |
unreachable | boolean optional | Whether the asset is unreachable. Defaults to false . |
zip_name | string optional | Name in the exported zip file. By default, Workato auto-generates a name with this structure: asset_#{index}.#{type}.json . |
folder_id | integer optional | The ID of the folder containing the asset. Defaults to the root folder. |
auto_generate_assets | boolean optional | Auto-generates assets from folder. Defaults to false. |
include_test_cases | boolean optional | Includes test cases in auto generation assets. Defaults to false. |
include_data | boolean optional | Includes data in auto generation assets. Defaults to false. |
auto_run | boolean optional | Starts export package generation automatically. Defaults to false. |
# Sample request
curl -X PUT 'https://www.workato.com/api/managed_users/91928/export_manifests/12' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"export_manifest": {
"name": "Test Manifest",
"assets": [
{
"id": 12,
"name": "Copy of Recipeops",
"type": "recipe",
"version": 1,
"folder": "",
"absolute_path": "All projects",
"root_folder": false,
"unreachable": false,
"zip_name": "copy_of_recipeops.recipe.json",
"checked": true
}
],
"folder_id": 112
}
}
'
# Auto-generate assets
If you plan for Workato to auto-generate your assets, you can pass the parameter auto_generate_assets
into the payload of the request. You must specify the folder_id
you plan to have auto-generated. You can also choose to include test cases and data by including the include_test_cases
or include_data
parameters. Otherwise, they are excluded by default.
Additionally, you can include auto_run
in the payload to generate the package automatically.
# Sample request
curl -X PUT 'https://www.workato.com/api/managed_users/91928/export_manifests/12' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"export_manifest": {
"name": "Test Manifest",
"folder_id": 112,
"auto_generate_assets": true,
"include_test_cases": true,
"include_data": true,
"auto_run": true
}
}
'
# Response
{
"result": {
"id": 12,
"name": "Test Manifest",
"last_exported_at": null,
"created_at": "2023-02-27T02:44:59.447-08:00",
"updated_at": "2023-02-27T02:44:59.447-08:00",
"deleted_at": null,
"project_path": "Folder 1",
"status": "working"
}
}
# View an export manifest
View an export manifest.
GET /api/managed_users/:managed_user_id/export_manifests/:id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | The ID of the dependency. |
managed_user_id | string required | Embedded customer ID or external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Sample request
curl -X GET 'https://www.workato.com/api/managed_users/91928/export_manifests/12' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"result": {
"id": 12,
"name": "Test Manifest",
"last_exported_at": null,
"created_at": "2023-02-27T02:44:59.447-08:00",
"updated_at": "2023-02-27T02:44:59.447-08:00",
"deleted_at": null,
"project_path": "Folder 1",
"status": "working"
}
}
# Delete an export manifest
Delete an export manifest.
DELETE /api/managed_users/:managed_user_id/export_manifests/:id
# URL parameters
Name | Type | Description |
---|---|---|
id | string required | Export manifest ID. |
managed_user_id | string required | Embedded customer ID or external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Sample request
curl -X DELETE 'https://www.workato.com/managed_users/12345/api/export_manifests/12' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"result": {
"success": true,
"status": "destroyed"
}
}
# Import package into a customer workspace
Import a package in zip file format into a specified folder in a customer workspace. This endpoint allows an API client to create or update assets, such as recipes, lookup tables, event topics, and message templates, through package imports.
PACKAGE IMPORT RATE LIMIT
Workato enforces a strict limit of 500 package import requests per hour per customer workspace. If this limit is exceeded, the system denies additional requests until the following hour when the request allowance resets.
POST /api/managed_users/:managed_user_id/imports
This is an asynchronous request. Use the Get package status endpoint to get details of the imported the package.
The input (zip file) is an application/octet-stream
payload containing package content. The query parameter restart_recipes
must be set to true
if the running recipes need to be restarted upon import.
# URL parameters
Name | Type | Description |
---|---|---|
managed_user_id | string required | Embedded customer ID or external ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ). |
# Query parameters
Name | Type | Description |
---|---|---|
folder_id | string required | Folder ID. |
restart_recipes | boolean optional | Value must be true to allow the restarting of running recipes during import. Packages cannot be imported if there are running recipes and this parameter equals false or is not provided. |
include_tags | boolean optional | Specifies whether to preserve tags assigned to assets when importing the package into the folder. Tags are excluded from the import when set to false . Set to false by default. |
# Sample request
curl -X POST 'https://www.workato.com/api/managed_users/91928/imports?folder_id=1827&include_tags=true' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/octet-stream' \
-F 'path/to/local/file.zip'
# Response
{
"id":251,
"operation_type":"import",
"status":"completed"
}
# Get status of package import
Get details of a package imported into a customer workspace.
GET /api/managed_users/:managed_user_id/imports/:package_id
# URL parameters
Name | Type | Description |
---|---|---|
managed_user_id | string required | Embedded customer ID or external ID. External ID must be prefixed with an E (for example, EA2300 ) and the resulting ID should be URL encoded. |
package_id | string required | Package ID. |
# Sample request
curl -X GET 'https://www.workato.com/api/managed_users/91829/imports/198' \
-H 'Authorization: Bearer <api_token>'
# Responses
# Successful import
The following response is returned when an import is completed successfully.
IMPORT RESULTS
For any completed import, it is important to also check each recipe's import_result
. Learn more about the possible import_result values.
{
"id":242,
"operation_type":"export",
"status":"completed",
"recipe_status":[
{
"id": 12345,
"import_result": "no_update_or_update_without_restart"
},
{
"id": 12346,
"import_result": "restarted"
},
{
"id": 12347,
"import_result": "stopped"
}
]
}
# Failed import
The following response is returned when an import fails.
IMPORT RESULTS
For any failed import, not all recipes may be returned in recipe_status
as they may not have been updated before the import failed. Learn more about the possible import_result values.
{
"id":198,
"operation_type":"export",
"status":"failed",
"error":"error_message",
"recipe_status":[
{
"id": 12345,
"import_result": "no_update_or_update_without_restart"
},
{
"id": 12346,
"import_result": "restarted"
},
{
"id": 12347,
"import_result": "stopped"
}
]
}
# Recipe import_result values
There are a total of six (6) possible results:
no_update_or_update_without_restart
- This indicates no restart was needed for the recipe. Either recipe could be updated without it or no update was made. Successful importnot_found
- Unexpected error when recipe cannot be found. Should not often be seen. Import has failed with no update to recipe.stop_failed
- For recipes that need to be restarted, we attempt to stop the recipe. This state indicates we could not stop the recipe. Import has failed with no update to recipe.stopped
- Workato stopped the recipe but recipe was not restarted due to errors in the recipe. Import has failed with recipe updated but not restartedrestart_failed
- Workato attempted to restart recipe but failed to do so. Import has failed with recipe updated but not restartedrestarted
- Workato successfully restarted recipe after update. Successful import
# Export package
Export a package using the manifest ID. This action requires the oem_vendor
privilege.
Use the Get export status endpoint to retrieve details on the exported package.
WARNING
Providing an API client with privilege to this endpoint indirectly gives it the ability to create/update other assets like recipes, lookup tables, Event topics and message templates by examining the resultant zip file.
POST /api/managed_users/:managed_user_id/exports/:manifest_id
INCLUDE TAGS WHEN CREATING THE EXPORT MANIFEST
To include tags in the exported package, set the include_tags
attribute to true
when calling the Create an export manifest endpoint.
# URL parameters
Name | Type | Description |
---|---|---|
managed_user_id | string required | Embedded customer Account ID or External ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ) and the resulting ID should be URL encoded. |
manifest_id | string required | The ID of the manifest you plan to export. |
# Sample request
curl -X POST 'https://www.workato.com/api/managed_users/91829/exports/508' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"id":365,
"operation_type":"export",
"status":"in_progress",
"export_manifest_id":508,
"download_url":"nil"
}
# Get export status
Returns the status of an exported package. Requires the oem_vendor
privilege.
GET /api/managed_users/:managed_user_id/exports/:package_id
# URL parameters
Name | Type | Description |
---|---|---|
managed_user_id | string required | Embedded customer Account ID or External ID. The External ID must be URL encoded and prefixed with an E (for example, EA2300 ) and the resulting ID should be URL encoded. |
package_id | string required | The ID of the package. |
# Sample request
curl -X GET 'https://www.workato.com/api/managed_users/91829/exports/370' \
-H 'Authorization: Bearer <api_token>'
# Response
{
"id":370,
"operation_type":"export",
"status":"completed",
"export_manifest_id":513,
"download_url":"<https://www.example.com>"
}
Last updated: 12/2/2024, 3:05:38 PM