feat: workflow docs (#2082)

## Description Provide a concise summary of the changes made in this pull request. - A new section for Workflows added to the sidebar - Workflows - [Overview](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/workflows) - A brief about workflows, components, and links to get started. - Tutorial - [Create a basic workflow](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/workflows/tutorials/create-workflow) - Trigger it from the Appsmith app - Integrate on Appsmith events and execute the workflow - Added an interactive Arcade so that users can learn in an interactive mode - How-To guides - [Create Approval Workflow](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/workflows/how-to-guides/create-approval-workflow) - How to create an approval workflow that showcases a refund approval example - Create a workflow to handle automated approvals and manual approval/rejections - Trigger workflow to add new refund requests to the workflow - Read the pending refund requests in the Appsmith app - Take action in the Appsmith app - Resolve requests in Workflow - Notify users of the outcome - Reference - [Workflow Queries](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/workflows/reference/workflow-queries) - To give information on the type of workflow queries and their parameters - [Workflow Functions](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/workflows/reference/workflow-functions) - [Concept](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/workflows/concepts/workflows-in-appsmith) - To provide information on the Workflow feature in Appsmith and its key capabilities. - Granular Access Control - [ Roles >> Application resources](https://appsmith-docs-git-feat-workflow-tutorial-get-appsmith.vercel.app/advanced-concepts/granular-access-control/roles#application-resources) - Updates to add Workflow permissions ## Type of PR Check the appropriate box: - [ ] Review Fixes - [ ] Documentation Overhaul - [x] Feature/Story - Link one or more Engineering Tickets * - [ ] A-Force - [ ] Error in documentation ## Documentation tickets Link to one or more documentation tickets: - #2076 - #2118 - #2100 - #2099 ## Checklist Choose only the ones that are applicable. - [x] Checked for Grammarly suggestions. - [x] Adhered to the writing checklist. - [x] Adhered the media checklist. - [ ] Verified and updated cross-references or added redirect rules. - [ ] Tested the redirect rules on deploy preview. - [ ] Validated the modifications made to the content on deploy preview. - [ ] Validated the CSS modifications on different screen sizes.
appsmithorg · Mar 11, 2024 · f45cd4c · f45cd4c
1 parent da999be
commit f45cd4c
Show file tree

Hide file tree

Showing 11 changed files with 754 additions and 5 deletions.
diff --git a/.github/styles/config/vocabularies/technical/accept.txt b/.github/styles/config/vocabularies/technical/accept.txt
@@ -38,4 +38,36 @@ Login
 Signup
 reCAPTCHA
 Edition
-Embed
+Embed
+Datasources
+Workflow
+Workflows
+Webhook
+workflow
+SMTP
+Postman
+assignRequest
+message
+resolutions
+requestName
+metadata
+requestToUsers
+requestToGroups
+Metadata
+Queries
+queries
+Functions
+functions
+JavaScript
+javascript
+Datasource
+datasource
+Human-in-the-Loop
+workflowInstanceId
+resolution
+payload
+executeWorkflow
+data
+Data
+Resolution
+workflows
diff --git a/website/docs/advanced-concepts/granular-access-control/roles.md b/website/docs/advanced-concepts/granular-access-control/roles.md
@@ -41,7 +41,7 @@ In this section, you'll find permissions related to the application and its reso
 | **App** | Create pages and queries inside the app | Edit pages and queries inside the app. | Delete the app and its pages and queries. | View the app and its pages and queries. | - | Make the application public | Export that particular application. |
 | **Page** | Create queries on the page. | Edit the page and its queries. | Delete the page and its queries. | View the page and its queries. | - | - | - |
 | **Query** | - | Edit the query. | Delete the query. | View the query. | Execute the query. | - | - |
-
+| **Workflows** | Create new workflows and resources inside a workflow. | Required to make changes to the Workflow.| Required to delete a workflow. Users will need **Edit** permission to delete individual actions inside the workflow. | An **Edit** permission also enables the permission to view workflow run history.| An **Edit** permission also enables the **Execute** permission to run workflow.| - | -|
 
 ### Datasource and environments
 

diff --git a/website/docs/workflows/README.md b/website/docs/workflows/README.md
@@ -1,5 +1,60 @@
 ---
-description: This page gives you an overview of workflows feature in Appsmith.
+description: This page provides an overview of the workflows feature in Appsmith, detailing its key components and functionality.
+title: Overview
+hide_title: true
 ---
+<!-- vale off -->
 
-# Overview 
+<div className="tag-wrapper">
+ <h1>Overview </h1>
+
+<Tags
+tags={[
+{ name: "Business", link: "https://www.appsmith.com/pricing", additionalClass: "business" }
+]}
+/>
+
+</div>
+
+<!-- vale on -->
+
+Appsmith Workflows are essential for automating tasks and orchestrating processes within applications. By integrating code-based and node-based systems, they provide a practical solution for automating tasks, managing workflows, enabling human-in-the-loop (HITL) interactions, and integrating with external services.
+
+## Workflow capabilities
+
+Appsmith Workflows are versatile and designed to handle a wide range of scenarios:
+
+### Automate business-critical processes
+
+Using app-building capabilities of Appsmith in workflows, developers can automate critical tasks based on business rules and requirements. From ticket assignments in customer support workflows to complex data processing operations, Workflows streamline processes efficiently.
+
+### Enable Human-in-the-Loop interactions
+
+Appsmith Workflows allow for human interventions within automated processes, facilitating informed decision-making through the Appsmith app. Decision points within workflows empower users to review and take appropriate actions, enhancing the efficiency and effectiveness of workflows.
+
+## Explore trigger types
+
+Appsmith supports different trigger types to configure actions and processes within workflows:
+
+- **Webhook**- Triggered by external events or HTTP requests, Webhook triggers enable real-time data processing and action execution based on incoming data. Learn how to use the Webhook triggers in the [Getting started with workflows](#getting-started-with-workflows) tutorial.
+
+- **Integrated Datasource for use in Appsmith Apps**- Seamlessly connect workflows with Appsmith applications using prebuilt integrations. This allows for seamless execution of operations within the app and direct management of workflows from the Appsmith interface. Delve deeper into integrated datasource triggers using Appsmith app in the [Getting started with workflows](#getting-started-with-workflows) tutorial.
+
+- **Scheduled Jobs (Cron Jobs)**- Scheduled to run at specific times or intervals, Scheduled Jobs automate tasks using Cron expressions. Stay tuned for updates on the availability and usage of Scheduled Jobs within Appsmith. (**Coming Soon**)
+
+## Getting started with workflows
+
+Begin exploring Appsmith Workflows with the comprehensive getting started tutorial. 
+
+<div className="containerGridSampleApp">
+   <div className="containerColumnSampleApp columnGrid column-one">
+    <div className="containerCol">
+      </div> 
+      <b><a href="/workflows/tutorials/create-workflow">Create Basic Workflow</a></b>
+      <div className="containerDescription">
+        Learn how to create your first workflow, configure webhook trigger to connect with external system, and integrate workflow natively with Appsmith app.
+      </div>
+   </div>
+   <div className="columnGrid column-two" style={{margin: "10px"}}>
+   </div>
+</div>
diff --git a/website/docs/workflows/how-to-guides/create-approval-workflow.md b/website/docs/workflows/how-to-guides/create-approval-workflow.md
@@ -0,0 +1,163 @@
+---
+description: This page provides detailed steps to set up an approval Webhook workflow on Appsmith.
+title: Create Approval Workflow
+hide_title: true
+---
+<!-- vale off -->
+
+<div className="tag-wrapper">
+ <h1>Create Approval Workflow</h1>
+
+<Tags
+tags={[
+{ name: "Business", link: "https://www.appsmith.com/pricing", additionalClass: "business" }
+]}
+/>
+
+</div>
+
+<!-- vale on -->
+
+In a human-in-the-loop approval workflow, such as processing refund requests, you can use workflows in Appsmith. The human intervention can happen through your Appsmith app. This page shows how to set up a human-in-the-loop approval workflow using Appsmith. 
+
+<ZoomImage
+  src="/img/appsmith-workflow-overview.png" 
+  alt="Human-in-the-Loop Approval Workflow"
+  caption="Human-in-the-Loop Approval Workflow"
+/> 
+
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+* A self-hosted instance of Appsmith. Refer to the [Appsmith installation guides](/getting-started/setup/installation-guides) for detailed instructions on setting up your Appsmith instance.
+* Basic knowledge of creating a basic workflow in Appsmith. For more information, see [Tutorial - Create Basic Workflow](/workflows/tutorials/create-workflow).
+* Configured your datasource that manages your data and SMTP datasource (to notify users) in your workspace. If not, configure these datasources. For more information on configuring datasource, see the available [Datasources](/connect-data/reference) in Appsmith.
+
+## Create workflow
+
+Follow these steps to set up a webhook workflow within your workspace. 
+
+1. Create a new workflow (_Refunds_) in your workspace.
+2. Configure it as a webhook workflow.
+3. Create a query to fetch order details (_getOrderDetails_) details. For example, the below query fetches the order details for the given `order_id` from the `orders` table.
+    ```sql
+    -- The order_id is a parameter, and replaced by actual value passed by the application
+    select * from public. "orders" where order_id = {{this.params.order_id}};
+    ``` 
+4. Create a query to update the order status once a refund is processed. For example, once a refund is approved, update the order status in the `order` table to `Refund Processed`. In case of rejection, the order status remains unchanged.
+    ```sql
+    -- The order_id are parameters and replaced by actual value passed by the application
+    -- highlight-next-line
+    Update public. "orders" set status = 'Refund Processed' where order_id = {{this.params.order_id}};
+    ```
+5. Create queries to send emails to inform users of the outcome. For example, you can create two queries:
+    *  To notify approval (_notifyUser_):
+        * Parameterize the query to include:
+            * Customer name (`{{this.params.customer_name}}`) who raised the request.
+            * Customer email (`{{this.params.customer_email}}`) to send email notification. 
+    * To notify rejection (_notifyRejectionToUser_):
+        * Parameterize the query to include:
+            * Customer name (`{{this.params.customer_name}}`) who raised the request.
+            * Customer email (`{{this.params.customer_email}}`) to send email notification.
+            * Rejection reason (`{{this.params.rejection_reason}}`). 
+    * Pass these parameters from your app to the workflow.
+
+6. Click the **Publish** button to publish the workflow.
+
+## Set up automatic refunds
+
+When a user submits a refund request through your application, you may want to process automatic refunds based on predefined business rules. For example, you might automatically approve refunds where the refund amount is less than $10. Here's how you can handle this scenario:
+
+1. In your workflow, go to **Main** under _JS Objects_. In the JS code editor, replace the auto-generated code with the following snippet. This code fetches the order details with the given `order_id`. If the order value is less than $10, it initiates a refund and notifies the customer via email.
+
+    ```javascript
+    export default {
+    async executeWorkflow(order) {
+            if (order && order.order_id) {
+                console.log('data' + order.order_id);
+                // Fetch refund details based on the given refund detail
+                const order = await getOrderDetails.run({ "order_id":  order.order_id });
+                // Iterate through requests 
+                if(order){
+                    // Verify the order value
+                    if (order.amount < 10) {
+                        // Add logic for refund processing if any
+                        // Initiate refund for amounts less than $10 
+                        await initiateRefund.run({
+                            "id": order.order_id,
+                            "status": 'Refund Processed'
+                        });
+                        // Send refund approval email to the customer 
+                        await notifyUser.run({
+                            "customer_email": refund_req.customer_email ,
+                            "customer_name": refund_req.customer_name
+                        });
+                    }
+                }
+            }
+        }
+    }                              
+    ```
+2. Click the **Publish** button in the top right corner to apply your changes.
+3. Execute the workflow whenever a user submits a new refund request.
+
+## Handle approvals or rejections
+
+When managing approvals or rejections, create refund requests and track user actions for further processing. Follow these steps:
+
+1. In your workflow, go to **Main** under _JS Objects_, and add the following function. This function generates a pending request using the `assignRequest` workflow function. For more information, see the [assignRequest](/workflows/reference/workflow-functions#assign-request) function. 
+    ```javascript
+    // manage refunds for amounts equal to or more than $10 
+    async createandManageRequests(order) {
+        const response = await appsmith.workflows.assignRequest({
+            requestName: "getPendingRefundRequests", 
+            message: "Refund raised by " + order.customer_name+ " for amount " + order.amount, 
+            requestToUsers: [order.approver_email], 
+            resolutions: ["Approve", "Reject"],
+            metadata: { "order": order } 
+        });
+
+        if (response && response.resolution === "Approve") {
+            //Add logic for refund processing if any
+            // Initiate refund when user approves
+            await initiateRefund.run({
+                "id": order.order_id,
+                "status": 'Refund Processed'
+            });
+            // Send refund approval email to the customer 
+            await notifyUser.run({
+                "customer_email": refund_req.customer_email ,
+                "customer_name": refund_req.customer_name
+
+            });
+        } else if (resolution && response.resolution === "Reject") {
+            // Send refund rejection email to the customer 
+            // Supply the rejection reason as a parameter
+            await notifyRejectionToUser.run({
+                    "customer_email": refund_req.customer_email ,
+                    "customer_name": refund_req.customer_name,
+                    "rejection_reason": refund_req.rejection_reason
+                });
+        }
+    }          
+    ```
+2. Call the above function when the order value is equal to or more than $10.
+3. In your app, create a workflow query (_getRefundReqs_) to fetch these requests. Configure it as follows:
+    * **Workflow name** - Select **Refunds**.
+    * **Request type** - Select **Get requests**.
+    * **Request name** - Add `getPendingRefundRequests` to it. It is the same request name you added in your workflow _Main_ JS object in `appsmith.workflows.assignRequest()` in the step 1 of this section.
+4. Drag a Table widget and bind the **getRefundReqs** query to it. You may need to transform data based on your user interface requirements. In which case, use a JS object to execute the query, perform transformations, and bind the transformed data to the Table widget.
+5. Create another workflow query (_resolveReqs_) to capture **Approve** or **Reject** actions:
+    * **Workflow name** - Select **Refunds**.
+    * **Request type** - Select **Resolve Requests**.
+    * **Request Id** - Add `{{this.params.requestId}}` to it.
+    * **Resolution** - Add `{{this.params.resolution}}` to it.
+    * **Metadata** - Add `{"rejectionReason" : {{this.params.rejectionReason}}}` to it.
+6. Bind the query (_resolveReqs_) to the `onClick` event of **Approve** and **Reject** buttons, and pass appropriate parameters. 
+7. Deploy your app to test the workflow.
+
+## Troubleshooting
+
+If you face issues, contact the support team using the chat widget at the bottom right of this page.