# Recipe lifecycle management

The following endpoints are available to Workato Embedded partners only. They allow you to programmatically 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.

# Quick reference

Type Resource Description
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.

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

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 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

  • This shows the response from the retrieval of a completed import.

NOTE

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"
      }
   ]
}
  • This shows the response from the retrieval of a failed import.

NOTE

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 'x-user-email: <email>' \
      -H 'x-user-token: <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 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
      "id":370,
      "operation_type":"export",
      "status":"completed",
      "export_manifest_id":513,
      "download_url":"<https://www.example.com>"
}