Complete examples & documentation

.gitignore

@@ -56,3 +56,5 @@ build
 
 # Ignore Docker env file
 docker.env
+
+examples/**/Dependencies.toml

README.md

@@ -8,21 +8,110 @@
 
 ## Overview
 
-[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
+[Smartsheet](https://www.smartsheet.com/) is a cloud-based platform that enables teams to plan, capture, manage, automate, and report on work at scale, empowering you to move from idea to impact, fast.
+
+The `ballerinax/smartsheet` package offers APIs to connect and interact with [Smartsheet API](https://developers.smartsheet.com/api/smartsheet/introduction) endpoints, specifically based on [Smartsheet API v2.0](https://developers.smartsheet.com/api/smartsheet/openapi).
+
 
 ## Setup guide
 
-[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
+To use the Smartsheet connector, you must have access to the Smartsheet API through a [Smartsheet developer account](https://developers.smartsheet.com/) and obtain an API access token. If you do not have a Smartsheet account, you can sign up for one [here](https://www.smartsheet.com/try-it).
+
+### Step 1: Create a Smartsheet Account
+
+1. Navigate to the [Smartsheet website](https://www.smartsheet.com/) and sign up for an account or log in if you already have one.
+
+2. Ensure you have a Business or Enterprise plan, as the Smartsheet API is restricted to users on these plans.
+
+### Step 2: Generate an API Access Token
+
+1. Log in to your Smartsheet account.
+
+2. On the left Navigation Bar at the bottom, select Account (your profile image), then Personal Settings.
+
+3. In the new window, navigate to the API Access tab and select Generate new access token.
+
+![generate API token ](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-smartsheet/refs/heads/main/docs/setup/resources/generate-api-token.png)
+
+
+> You must copy and store this key somewhere safe. It won't be visible again in your account settings for security reasons
 
 ## Quickstart
 
-[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
+To use the `Smartsheet` connector in your Ballerina application, update the `.bal` file as follows:
+
+### Step 1: Import the module
+
+Import the `smartsheet` module.
+
+```ballerina
+import ballerinax/smartsheet;
+```
+
+### Step 2: Instantiate a new connector
+
+1. Create a `Config.toml` file and configure the obtained access token as follows:
+
+```toml
+token = "<Your_Smartsheet_Access_Token>"
+```
+
+2. Create a `smartsheet:ConnectionConfig` with the obtained access token and initialize the connector with it.
+
+```ballerina
+configurable string token = ?;
+
+final smartsheet:Client smartsheet = check new({
+    auth: {
+        token
+    }
+});
+```
+
+### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+#### Create a new sheet
+
+```ballerina
+public function main() returns error? {
+    smartsheet:SheetsBody newSheet = {
+        name: "New Project Sheet",
+        columns: [
+            {
+                title: "Task Name",
+                type: "TEXT_NUMBER",
+                primary: true
+            },
+            {
+                title: "Status",
+                type: "PICKLIST",
+                options: ["Not Started", "In Progress", "Complete"]
+            },
+            {
+                title: "Due Date",
+                type: "DATE"
+            }
+        ]
+    };
+
+    smartsheet:WebhookResponse response = check smartsheet->/sheets.post(newSheet);
+}
+```
+
+### Step 4: Run the Ballerina application
+
+```bash
+bal run
+```
+
 
 ## Examples
 
 The `Smartsheet` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-smartsheet/tree/main/examples/), covering the following use cases:
 
-[//]: # (TODO: Add examples)
+1. [Project task management](https://github.com/module-ballerinax-smartsheet/tree/main/examples/project_task_management) -  Demonstrates how to automate project task creation using Ballerina connector for Smartsheet.
 
 ## Build from the source
 

ballerina/Dependencies.toml

@@ -5,7 +5,7 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.12.0"
+distribution-version = "2201.12.7"
 
 [[package]]
 org = "ballerina"

ballerina/README.md

@@ -1,17 +1,108 @@
 ## Overview
 
-[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
+[Smartsheet](https://www.smartsheet.com/) is a cloud-based platform that enables teams to plan, capture, manage, automate, and report on work at scale, empowering you to move from idea to impact, fast.
+
+The `ballerinax/smartsheet` package offers APIs to connect and interact with [Smartsheet API](https://developers.smartsheet.com/api/smartsheet/introduction) endpoints, specifically based on [Smartsheet API v2.0](https://developers.smartsheet.com/api/smartsheet/openapi).
+
 
 ## Setup guide
 
-[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
+To use the Smartsheet connector, you must have access to the Smartsheet API through a [Smartsheet developer account](https://developers.smartsheet.com/) and obtain an API access token. If you do not have a Smartsheet account, you can sign up for one [here](https://www.smartsheet.com/try-it).
+
+### Step 1: Create a Smartsheet Account
+
+1. Navigate to the [Smartsheet website](https://www.smartsheet.com/) and sign up for an account or log in if you already have one.
+
+2. Ensure you have a Business or Enterprise plan, as the Smartsheet API is restricted to users on these plans.
+
+### Step 2: Generate an API Access Token
+
+1. Log in to your Smartsheet account.
+
+2. On the left Navigation Bar at the bottom, select Account (your profile image), then Personal Settings.
+
+3. In the new window, navigate to the API Access tab and select Generate new access token.
+
+![generate API token ](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-smartsheet/refs/heads/main/docs/setup/resources/generate-api-token.png)
+
+
+> You must copy and store this key somewhere safe. It won't be visible again in your account settings for security reasons
 
 ## Quickstart
 
-[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
+To use the `Smartsheet` connector in your Ballerina application, update the `.bal` file as follows:
+
+### Step 1: Import the module
+
+Import the `smartsheet` module.
+
+```ballerina
+import ballerinax/smartsheet;
+```
+
+### Step 2: Instantiate a new connector
+
+1. Create a `Config.toml` file and configure the obtained access token as follows:
+
+```toml
+token = "<Your_Smartsheet_Access_Token>"
+```
+
+2. Create a `smartsheet:ConnectionConfig` with the obtained access token and initialize the connector with it.
+
+```ballerina
+configurable string token = ?;
+
+final smartsheet:Client smartsheet = check new({
+    auth: {
+        token
+    }
+});
+```
+
+### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+#### Create a new sheet
+
+
+```ballerina
+public function main() returns error? {
+    smartsheet:SheetsBody newSheet = {
+        name: "New Project Sheet",
+        columns: [
+            {
+                title: "Task Name",
+                type: "TEXT_NUMBER",
+                primary: true
+            },
+            {
+                title: "Status",
+                type: "PICKLIST",
+                options: ["Not Started", "In Progress", "Complete"]
+            },
+            {
+                title: "Due Date",
+                type: "DATE"
+            }
+        ]
+    };
+
+    smartsheet:WebhookResponse response = check smartsheet->/sheets.post(newSheet);
+}
+```
+
+### Step 4: Run the Ballerina application
+
+```bash
+bal run
+```
+
 
 ## Examples
 
 The `Smartsheet` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-smartsheet/tree/main/examples/), covering the following use cases:
 
-[//]: # (TODO: Add examples)
+1. [Project task management](https://github.com/module-ballerinax-smartsheet/tree/main/examples/project_task_management) - Demonstrates how to automate project task creation using Ballerina connector for Smartsheet.
+

examples/README.md

@@ -1,15 +1,17 @@
 # Examples
 
-The `ballerinax/smartsheet` connector provides practical examples illustrating usage in various scenarios.
+The `ballerinax/smartsheet` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-smartsheet/tree/main/examples), covering use cases like project task management integration.
 
-[//]: # (TODO: Add examples)
-1. 
-2. 
+1. [Project task management integration](https://github.com/ballerina-platform/module-ballerinax-smartsheet/tree/main/examples/project_task_management) - Automate project task creation using Ballerina connector for Smartsheet. When a new project is created, the system automatically creates initial tasks in Smartsheet and sends a summary notification message to Slack.
 
 ## Prerequisites
 
-[//]: # (TODO: Add prerequisites)
+1. Generate Smartsheet credentials to authenticate the connector as described in the [Setup guide](https://central.ballerina.io/ballerinax/smartsheet/latest#setup-guide).
 
+2. For each example, create a `Config.toml` file the related configuration. Here's an example of how your `Config.toml` file should look:
+
+    ```toml
+    smartsheetToken = "SMARTSHEET_ACCESS_TOKEN"
 ## Running an example
 
 Execute the following commands to build an example from the source:

examples/project_task_management/.github/README.md

@@ -0,0 +1 @@
+../Project Task Management Integration.md

examples/project_task_management/Ballerina.toml

@@ -0,0 +1,12 @@
+[package]
+org = "wso2"
+name = "project_task_management"
+version = "0.1.0"
+
+[[dependency]]
+org = "ballerinax"
+name = "smartsheet"
+version = "0.1.0"
+repository = "local"
+
+

examples/project_task_management/Project Task Management Integration.md

@@ -0,0 +1,49 @@
+# Project Task Management Integration
+
+This example demonstrates how to automate project task creation using Ballerina connector for Smartsheet. When a new project is created, the system automatically creates initial tasks in Smartsheet and sends a summary notification message to Slack.
+
+## Prerequisites
+
+1. **Smartsheet Setup**
+   - Create a Smartsheet account (Business/Enterprise plan required)
+   - Generate an API access token
+   - Create two sheets:
+     - "Projects" sheet with columns: Project Name, Start Date, Status
+     - "Tasks" sheet with columns: Task Name, Assigned To, Due Date, Project Name
+
+   > Refer the [Smartsheet setup guide](https://github.com/ballerina-platform/module-ballerinax-smartsheet/blob/main/ballerina/README.md) here.
+
+2. **Slack Setup**
+   - Refer the [Slack setup guide](https://github.com/ballerina-platform/module-ballerinax-slack/blob/master/ballerina/README.md) here.
+
+3. For this example, create a `Config.toml` file with your credentials. Here's an example of how your `Config.toml` file should look:
+
+```toml
+smartsheetToken = "SMARTSHEET_ACCESS_TOKEN"
+projectsSheetName = "PROJECT_SHEET_NAME"
+tasksSheetName = "TASK_SHEET_NAME"
+slackToken = "SLACK_TOKEN"
+slackChannel = "SLACK_CHANNEL"
+```
+
+## Run the Example
+
+1. Execute the following command to run the example:
+
+```bash
+bal run
+```
+
+2. The service will start on port 8080. You can test the integration by sending a POST request to create a new project:
+
+```bash
+curl -X POST http://localhost:8080/projects \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectName": "Website Redesign",
+    "startDate": "2025-08-25",
+    "status" : "ACTIVE",
+    "assignedTo": "developer@example.com"
+  }'
+```
+