# 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

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>"
}