Merge pull request #4433 from activepieces/docs/pieces-customization

docs: improve embed docs and document project pieces filter

docs/admin-console/appearance.mdx

@@ -6,12 +6,11 @@ icon: "palette"
 
 <Snippet file="enterprise-feature.mdx" />
 
-To tweak how your platform looks, head to the **Appearance** section under **Settings**. Here, you can customize:
-- Logo
-- Logo Icon
-- Favicon
+Customize the brand by going to the **Appearance** section under **Settings**. Here, you can customize:
+
+- Logo / FavIcon
 - Primary color
 - Default Language
 
-![Appearance](/resources/screenshots/appearance.png)
-
+<video controls autoplay muted loop playsinline className="w-full aspect-video" src="https://cdn.activepieces.com/videos/showcase/appearance.mp4">
+</video>

docs/admin-console/manage-pieces.mdx

@@ -6,14 +6,15 @@ icon: "puzzle-piece"
 
 <Snippet file="enterprise-feature.mdx" />
 
-## Hide / Show Pieces 
+## Customize Pieces for Each Project
 
-You can show or hide pieces by clicking on the eye icon next to each piece.
+In each **project settings** you can customize the pieces for the project.
 
 ![Manage Projects](/resources/screenshots/manage-pieces.png)
 
-## Add New Piece
+## Install Piece
 
-You can install custom pieces for all your projects by clicking on "Add Piece" and then filling in the piece package information. You can choose to install it from npm or upload a tar file directly for private pieces.
+You can install custom pieces for all your projects by clicking on "Install Piece" and then filling in the piece package information. 
+You can choose to install it from npm or upload a tar file directly for private pieces.
 
 ![Manage Projects](/resources/screenshots/install-piece.png)

docs/admin-console/manage-projects.mdx

@@ -7,11 +7,11 @@ icon: "building"
 <Snippet file="enterprise-feature.mdx" />
 
 This feature helps you unlock these use cases:
-1. Set up projects for your agency customers.
-2. Set up projects for different teams inside the company.
-3. Set up projects automatically using the embedding feature for your SaaS customers.
+1. Set up projects for different teams inside the company.
+2. Set up projects automatically using the embedding feature for your SaaS customers.
 
 
 You can **create** new projects and sets **limits** on the number of tasks and users for each project.
 
-![Manage Projects](/resources/screenshots/manage-projects.png)
+<video controls autoplay muted loop playsinline className="w-full aspect-video" src="https://cdn.activepieces.com/videos/showcase/projects.mp4">
+</video>

docs/admin-console/manage-templates.mdx

@@ -8,5 +8,6 @@ icon: "star"
 
 You can create custom templates for your users within the Platform dashboard's.
 
-![Manage Templates](/resources/screenshots/manage-templates.png)
 
+<video controls autoplay muted loop playsinline className="w-full aspect-video" src="https://cdn.activepieces.com/videos/showcase/templates.mp4">
+</video>

docs/embedding/customize-pieces.mdx

@@ -0,0 +1,32 @@
+---
+title: "Customize Pieces"
+description: ""
+icon: "puzzle"
+---
+
+This documentation explains how to customize access to pieces depending on projects.
+
+<Steps>
+    <Step title="Tag Pieces">
+        You can tag pieces in bulk using **Admin Console**
+
+        ![Bulk Tag](../resources/screenshots/tag-pieces.png)
+    </Step>
+    <Step title="Add Tags to Provision Token">
+        We need to specify the tags of pieces in the token, check how to generate token in [provision-users](./provision-users).
+
+        You should specify the `pieces` claim like this:
+        ```json
+        {
+            /// Other claims
+            "pieces": {
+                "filterType": "ALLOWED",
+                "tags": [ "free" ]
+            }
+        }
+        ```
+
+        Each time the token is used in the frontend, it will sync all pieces with these tags to the project. 
+        The project's pieces list will **exactly match** all pieces with these tags at the moment of using the iframe.
+    </Step>
+</Steps>

docs/embedding/configuration/initialize-embed.mdx → docs/embedding/embed-builder.mdx

@@ -1,25 +1,25 @@
 ---
 title: "Embed Builder"
 description: ""
+icon: "wrench"
 ---
 
-To embed Activepieces within your own web app, follow these steps:
+This documentation explains how to embed the Activepieces iframe inside your application and customize it.
 
+## Configure SDK
 
+Adding the embedding SDK script will initialize an object in your window called `activepieces`, which has a method called `configure` that you should call after the container has been rendered.
+<Tip>
+The following scripts shouldn't contain the `async` or `defer` attributes.
+</Tip>
 
-## Step 1: Generate a JWT token
-
-Follow the instructions in the [generate jwt](./generate-jwt) page
-
-## Step 2: Configure SDK
 
-Adding the embedding sdk script will initialize an object in your window `activepieces`, it has a method `configure`, which you should call after the container has been rendered.
 <Tip>
-The following scripts shouldn't contain async or defer attributes.
+These steps assume you have already generated a JWT token from the backend. If not, please check the [provision-users](./provision-users) page.
 </Tip>
 
 ```html
-<script src="https://cdn.activepieces.com/sdk/embed/0.2.3.js">
+<script src="https://cdn.activepieces.com/sdk/embed/0.2.4.js">
 </script>
 <script>
 activepieces.configure(

docs/embedding/embed-connections.mdx

@@ -0,0 +1,51 @@
+---
+title: "Create Connections"
+description: ""
+icon: "cards"
+---
+
+You can use the embedded SDK to create connections.
+
+<Steps>
+    <Step title="Initialize the SDK">
+        Follow the instructions in the [Initialize SDK](../configuration/initialize-embed) in Embed builder.
+    </Step>
+    <Step title="Call Connect Method">
+        After initializing the SDK, you will have access to a property called `activepieces` inside your `window` object. Call its `connect` method to open a new connection dialog as follows.
+
+        ```html
+        <script> 
+        activepieces.connect({pieceName:'@activepieces/piece-google-sheets'});
+        </script>
+        ```
+
+        **Connect Parameters:**
+
+        | Parameter Name | Required | Type   | Description                                 |
+        | -------------- | -------- | ------ | ------------------------------------------- |
+        | pieceName      | ✅       | string | The name of the piece you want to create a connection for.
+
+        **Connect Result**
+
+        The `connect` method returns a `promise` that resolves to the following object:
+
+        ```ts
+        {
+            connection?: {
+                id: string,
+                name: string
+            }
+        }
+        ```
+
+        <Info>
+        `connection` is undefined if the user closes the dialog and doesn't create a connection.
+        </Info>
+
+        <Tip>
+        You can use the `connections` piece in the builder to retrieve the created connection using its name.
+        ![Connections in Builder](/resources/screenshots/connections-piece.png)
+        ![Connections in Builder](/resources/screenshots/connections-piece-usage.png)
+        </Tip>
+    </Step>
+</Steps>

docs/embedding/overview.mdx

@@ -0,0 +1,23 @@
+---
+title: 'Overview'
+description: 'Understanding how embedding works'
+icon: "cube"
+---
+
+<Snippet file="enterprise-feature.mdx" />
+
+This section provides an overview of how to embed the Activepieces builder in your application and automatically provision the user.
+
+The embedding process involves the following steps:
+
+<Steps>
+    <Step title="Provision Users">
+        Generate a JSON Web Token (JWT) to identify your customer and pass it to the frontend.
+    </Step>
+    <Step title="Embed Builder">
+        Use the Activepieces SDK and the JWT to embed the Activepieces builder as an iframe, and customize using the SDK.
+    </Step>
+    <Step title="Optional Step">
+        Optionally, you can embed a Connections dialog to collect user connections.
+    </Step>
+</Steps>

docs/embedding/configuration/generate-jwt.mdx → docs/embedding/provision-users.mdx

@@ -1,23 +1,38 @@
 ---
-title: "Generate JWT Token"
-description: "if you own SaaS, you can authenticate your users from your app to the dashboard without asking them to login"
+title: "Provision Users"
+description: "Automatically authenticate your users to your activepieces instance"
+icon: 'user'
 ---
 
 <Snippet file="enterprise-feature.mdx" />
 
+## Overview
+
+In Activepieces, there are **Projects** and **Users**. Each project is provisioned with their corresponding workspace, project, or team in your SaaS. The users are then mapped to the respective users in Activepieces.
+
+To achieve this, your backend will generate a signed token that contains all the necessary information to automatically create an user and project. If the user or project already exists, It will skip the creation and login the user directly.
+
+
 ## Step 1: Obtain Signing Key
 
 You can generate a signing key by going to **Platform Settings -> Signing Keys -> Generate Signing Key**.
 
 This will generate a public and private key pair. The public key will be used by Activepieces to verify the signature of the JWT tokens you send. The private key will be used by you to sign the JWT tokens.
 
-**Note: Please store your private key in a safe place, as it will not be stored in activepieces.**
+<Warning>
+Please store your private key in a safe place, as it will not be stored in activepieces.**
+</Warning>
 
 ## Step 2: Generate a JWT
 
 The signing key will be used to generate JWT tokens for the currently logged-in user on your website, which will then be sent to Activepieces Iframe as a query parameter to authenticate the user.
 
 To generate these tokens, you will need to add code in your backend to generate the token using the RS256 algorithm, so the JWT header would look like this:
+
+<Tip>
+To obtain the `SIGNING_KEY_ID`, refer to the signing key table and locate the value in the first column.
+</Tip>
+
 ```json
 {
   "alg": "RS256",
@@ -36,7 +51,10 @@ The signed tokens must include these claims in the payload:
   "lastName": "Doe",
   "email": "john@example.com",
   "role": "EDITOR",
-	"exp": 1856563200
+  "pieces": {
+    "filterType": "NONE"
+  },
+  "exp": 1856563200
 }
 ````
 
@@ -49,7 +67,7 @@ The signed tokens must include these claims in the payload:
 | email             | Email address of the user                        |
 | role              | Role of the user in the activepieces project (e.g., **EDITOR**, **VIEWER**)           |
 | exp               | Expiry timestamp for the token (Unix timestamp)  |
-
+| pieces            | Customize project pieces, check the section below  |
 
 You can use any JWT library to generate the token. Here is an example using the jsonwebtoken library in NodeJs:
 
@@ -70,6 +88,9 @@ let token = jwt.sign(
     lastName: "Doe",
     role: "EDITOR",
     email: "john@example.om",
+    pieces: {
+      filterType: "NONE"
+    },
     exp: currentTime + (24 * 60 * 60), // 1 day from now
   },
   process.env.ACTIVEPIECES_SIGNING_KEY,
@@ -83,4 +104,4 @@ let token = jwt.sign(
 
 ```
 
-Once you have generated the token, Please check embedding docs to know how to embed the token in the iframe.
+Once you have generated the token, Please check embedding docs to know how to embed the token in the iframe.

docs/mint.json

@@ -260,33 +260,15 @@
         "developers/architecture/repo-structure"
       ]
     },
-    {
-      "group":"Customer Portal",
-      "pages":[
-        "customer-portal/overview",
-        "customer-portal/activity",
-        "customer-portal/connections",
-        "customer-portal/inviting-customer"      
-      ]
-    },
     {
       "group": "Embedding",
       "pages": [
-        {
-          "group": "Configuration",
-          "icon": "code",
-          "pages": [
-            "embedding/configuration/generate-jwt",
-            "embedding/configuration/initialize-embed"
-          ]
-        },
-        {
-          "group": "Connections",
-          "icon": "cards-blank",
-          "pages": [
-            "embedding/connections/create-connection"
-          ]
-        }
+        "embedding/overview",
+        "embedding/provision-users",
+        "embedding/embed-builder",
+        "embedding/customize-pieces",
+        "embedding/embed-connections"
+
       ]
     },
     {