Product UpdatesStatus PageAutomation Institute
▼ 日本語
Workato Embedded API
Resources

# Recipe lifecycle management

The following endpoints are available to Workato Embedded partners only. They allow you to create and manage export manifests programmatically. They also enable you to import and export a package to/from a customer account using one set of API credentials.

If you plan to import/export packages to/from your own environments (not customer accounts), use the endpoints listed in the Developer API.

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
POST /api/export_manifests Create an export manifest.
PUT /api/export_manifests/:id Update an export manifest.
GET /api/export_manifests/:id View an export manifest.
POST /api/managed_users/:id/imports Import package into a folder in a customer account.
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.

# Create an export manifest

Create an export manifest.

POST /api/export_manifests

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

# Sample request

curl  -X POST 'https://www.workato.com/api/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
            }
          }
          '

# 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/export_manifests/:id

# URL parameters

Name Type Description
id integer
string		 The ID of the dependency.

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

# Sample request

curl  -X PUT 'https://www.workato.com/api/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
            }
          }
          '

# 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/export_manifests/:id

# URL parameters

Name Type Description
id integer
string		 The ID of the dependency.

# Sample request

curl  -X GET 'https://www.workato.com/api/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"
  }
}

# Import package into a customer account

Import a package into a specified folder in a customer account.

WARNING

Providing an API client with privilege to this endpoint indirectly gives it the ability to create/update other assets like recipes, lookup tables, pubsub topics and message templates through importing packages.

POST /api/managed_users/: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. URL 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		 Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
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.

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/91928/imports?folder_id=1827' \
      -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 account.

GET /api/managed_users/:id/imports/:package_id

# URL parameters

Name Type Description
managed_user_id string
required		 Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: 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 import
  • not_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 restarted
  • restart_failed - Workato attempted to restart recipe but failed to do so. Import has failed with recipe updated but not restarted
  • restarted - 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, pubsub topics and message templates by examining the resultant zip file.

POST /api/managed_users/:managed_user_id/exports/:manifest_id

# URL parameters

Name Type Description
managed_user_id string
required		 Embedded user account ID or external ID. External ID must be 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 user account ID or external ID. An external ID must be 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>"
}
← Start poll-now recipe
Roles →


Last updated: 11/20/2023, 7:33:33 PM

On this page