mirror of
https://github.com/Skyvern-AI/skyvern.git
synced 2025-09-03 19:20:31 +00:00
209 lines
8.4 KiB
Text
209 lines
8.4 KiB
Text
---
|
||
title: Running Workflows
|
||
description: 'Executing complex multi-step workflows'
|
||
---
|
||
|
||
## Running workflows
|
||
|
||
### `POST /workflows/{workflow_permanent_id}/run`
|
||
|
||
You can see the generic endpoint definition below. We’ll go into the specifics of the invoice retrieval workflow in the next section.
|
||
|
||
### Body
|
||
|
||
| Parameter | Type | Required? | Sample Value | Description |
|
||
| --- | --- | --- | --- | --- |
|
||
| data | JSON | no | \{ <br/>"website_url": "YOUR_URL",<br/>"invoice_retrieval_start_date": "2024-04-15"<br/> \}, | The data field is used to pass in required and optional parameters that a workflow accepts. For the invoice retrieval workflow, required fields are website_url and invoice_retrieval_start_date |
|
||
| webhook_callback_url | String | no | … | Our system will send the webhook once it is finished executing the workflow run. |
|
||
| proxy_location | String | no | RESIDENTIAL | Proxy location for the web browser. Please pass RESIDENTIAL. <br /> If we use residential proxies, Skyvern’s requests to the websites will be less suspicious. |
|
||
|
||
### Response
|
||
|
||
| Parameter | Type | Always returned? | Sample Value | Description |
|
||
| --- | --- | --- | --- | --- |
|
||
| workflow_permanent_id | String | yes | wpid_123456 | The workflow id |
|
||
| workflow_run_id | String | yes | wr_123456 | The workflow run id that represents this specific workflow run. <br/> You can use this id to match the webhook response to the initial request. |
|
||
|
||
### Sample Request & Response - Invoice retrieval
|
||
|
||
```bash
|
||
-- Sample Request
|
||
curl --location 'https://api.skyvern.com/api/v1/workflows/wpid_123456/run' \
|
||
--header 'x-api-key: <USE_YOUR_API_KEY>' \
|
||
--header 'Content-Type: application/json' \
|
||
--data '{
|
||
"data": {
|
||
"website_url": "your_website",
|
||
"invoice_retrieval_start_date": "2024-04-15"
|
||
},
|
||
"proxy_location": "RESIDENTIAL",
|
||
"webhook_callback_url": "<your-endpoint>"
|
||
}'
|
||
|
||
-- Sample Response
|
||
{
|
||
"workflow_id": "wpid_123456",
|
||
"workflow_run_id": "wr_123456"
|
||
}
|
||
```
|
||
|
||
## Retrieving workflow runs
|
||
|
||
### `GET /workflows/{workflow_id}/runs/{workflow_run_id}`
|
||
|
||
### Response
|
||
|
||
| Parameter | Type | Sample value | Description |
|
||
| --- | --- | --- | --- |
|
||
| workflow_id | String | wpid_123456 | |
|
||
| workflow_run_id | String | wr_123456 | |
|
||
| status | String | completed | Status of the workflow run. Possible values: created, running, failed, terminated, completed |
|
||
| proxy_location | JSON | RESIDENTIAL | |
|
||
| webhook_callback_url | String | 127.0.0.1:8000/api/v1/webhook | |
|
||
| created_at | Timestamp | 2024-05-16T08:35:24.920793 | Timestamp for when the workflow run is created |
|
||
| modified_at | Timestamp | 2024-05-16T08:42:32.568908 | Last modified timestamp for the workflow run |
|
||
| parameters | JSON | see sample response below | The parameters that the workflow run was triggered with. For the invoice retrieval workflow, this field will have the website_url and invoice_retrieval_start_date values you sent. |
|
||
| screenshot_urls | list[String] | see sample response below | Final screenshots for the last 3 tasks in the workflow. |
|
||
| recording_url | String | see sample response below | The full browser recording. |
|
||
| outputs | JSON | see sample response below | See the explaining outputs section |
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"workflow_id": "wpid_123456",
|
||
"workflow_run_id": "wr_123456",
|
||
"status": "completed",
|
||
"proxy_location": "RESIDENTIAL",
|
||
"webhook_callback_url": "127.0.0.1:8000/api/v1/webhook",
|
||
"created_at": "2024-05-16T08:35:24.920793",
|
||
"modified_at": "2024-05-16T08:42:32.568908",
|
||
"parameters": {
|
||
"website_url": "YOUR_WEBSITE_URL",
|
||
"invoice_retrieval_start_date": "2024-04-15"
|
||
},
|
||
"screenshot_urls": [
|
||
"https://skyvern-artifacts.s3.amazonaws.com/...",
|
||
"https://skyvern-artifacts.s3.amazonaws.com/...",
|
||
"https://skyvern-artifacts.s3.amazonaws.com/..."
|
||
],
|
||
"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/...",
|
||
"outputs": {
|
||
"login_output": {
|
||
"task_id": "tsk_1234",
|
||
"status": "completed",
|
||
"extracted_information": null,
|
||
"failure_reason": null,
|
||
"errors": []
|
||
},
|
||
"get_order_history_page_url_and_qualifying_order_ids_output": {
|
||
"task_id": "tsk_258409009008559418",
|
||
"status": "completed",
|
||
"extracted_information": {
|
||
...
|
||
},
|
||
"failure_reason": null,
|
||
"errors": []
|
||
},
|
||
"iterate_over_order_ids_output": [
|
||
[
|
||
{
|
||
...
|
||
}
|
||
]
|
||
],
|
||
"download_invoice_for_order_output": {
|
||
"task_id": "tsk_258409361195877732",
|
||
"status": "completed",
|
||
"extracted_information": null,
|
||
"failure_reason": null,
|
||
"errors": []
|
||
},
|
||
"upload_downloaded_files_to_s3_output": [
|
||
"s3://skyvern-uploads/..."
|
||
],
|
||
"send_email_output": {
|
||
"success": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Webhooks
|
||
|
||
Skyvern always sends webhooks when a workflow run is executed. The status for an executed workflow run can be: `completed, failed, terminated`.
|
||
|
||
The webhook body is the same as the get workflow run endpoint.
|
||
|
||
### Webhook Headers
|
||
|
||
| Parameter | Type | Required? | Sample Value | Description |
|
||
| --- | --- | --- | --- | --- |
|
||
| x-skyvern-signature | String | yes | v0=a2114d57b48eac39b9ad189dd8316235a7b4a8d21a10bd27519666489c69b503 | Authentication token that allows our service to communicate with your backend service via callback / webhook <br/> <br/> We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |
|
||
| x-skyvern-timestamp | String | yes | 1531420618 | Timestamp used to decode and validate the incoming webhook call
|
||
|
||
We’ll be using the same strategy slack uses, as defined here: https://api.slack.com/authentication/verifying-requests-from-slack#making__validating-a-request |
|
||
|
||
## Explaining `outputs`
|
||
|
||
If you checked out the sample response, you probably thought “What the heck is this field right here?”.
|
||
|
||
We previously went over that workflows are essentially a list of building blocks. `outputs` field has the output for every single block that a workflow has. Before we start analyzing the `outputs` from the sample above, let’s go over the building blocks for the invoice retrieval workflow.
|
||
|
||
### Building blocks of invoice retrieval workflow:
|
||
|
||
| # | Block type | Block label | Purpose |
|
||
| --- | --- | --- | --- |
|
||
| 1 | TaskBlock | login | Find login page, login to the website |
|
||
| 2 | TaskBlock | get_order_history_page_url_and_qualifying_order_ids | Find the order history page, extract order history page url, contact emails, and order details for orders after the start date |
|
||
| 3 | ForLoopBlock | iterate_over_order_ids | The contents of the ForLoop is executed for each order id that’s extracted from the previous step. |
|
||
| 4 | TaskBlock [within ForLoopBlock] | download_invoice_for_order | For a given order id, find a way to download the invoice, download it. |
|
||
| 5 | UploadToS3Block | upload_downloaded_files_to_s3 | Upload all downloaded invoices to S3 |
|
||
| 6 | SendEmailBlock | send_email | Send an email attaching all the downloaded invoices |
|
||
|
||
### ⚠️ Still in development, not a blocker
|
||
|
||
1. The blocks within the ForLoop show up twice: within the ForLoop output and as a root block.
|
||
2. UploadToS3Block output is S3 URIs at the moment. They’ll be updated with signed urls instead.
|
||
3. Add block type to each object in `outputs`, define the output structure for each block for easier integration.
|
||
|
||
|
||
```json
|
||
...
|
||
"outputs": {
|
||
"login_output": {
|
||
"task_id": "tsk_1234",
|
||
"status": "completed",
|
||
"extracted_information": null,
|
||
"failure_reason": null,
|
||
"errors": []
|
||
},
|
||
"get_order_history_page_url_and_qualifying_order_ids_output": {
|
||
"task_id": "tsk_1234",
|
||
"status": "completed",
|
||
"extracted_information": {
|
||
...
|
||
},
|
||
"failure_reason": null,
|
||
"errors": []
|
||
},
|
||
"iterate_over_order_ids_output": [
|
||
...
|
||
],
|
||
"download_invoice_for_order_output": {
|
||
"task_id": "tsk_1234",
|
||
"status": "completed",
|
||
"extracted_information": null,
|
||
"failure_reason": null,
|
||
"errors": []
|
||
},
|
||
"upload_downloaded_files_to_s3_output": [
|
||
"s3://skyvern-uploads/...",
|
||
"s3://skyvern-uploads/..."
|
||
],
|
||
"send_email_output": {
|
||
"success": true
|
||
}
|
||
}
|
||
...
|
||
```
|