Complete examples & documentation

.github/workflows/regenerate-connector.yaml

@@ -0,0 +1,66 @@
+name: Regenerate OpenAPI Connector
+
+on:
+  workflow_dispatch:
+    inputs:
+      openapi-url:
+        description: "URL of the OpenAPI JSON"
+        required: false
+        type: string
+      flatten-openapi:
+        description: "Enable OpenAPI Flattening"
+        required: false
+        type: boolean
+        default: false  # Enabling flatten will cause errors in the types.bal file requiring sanitization
+      additional-flatten-flags:
+        description: "Additional flags for OpenAPI Flattening"
+        required: false
+        type: string
+        default: ""
+      align-openapi:
+        description: "Enable OpenAPI Alignment"
+        required: false
+        type: boolean
+        default: true
+      additional-align-flags:
+        description: "Additional flags for OpenAPI Alignment"
+        required: false
+        type: string
+        default: ""
+      additional-generation-flags:
+        description: "Additional flags for OpenAPI Generation"
+        required: false
+        type: string
+        default: ""
+      distribution-zip:
+        description: "Distribution of the Ballerina version to be used"
+        required: false
+        type: string
+        default: ""
+      auto-merge:
+        description: "Enable auto-merge of the PR"
+        required: false
+        type: boolean
+        default: true
+      ballerina-version:
+        description: "Ballerina Language Version"
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  call_workflow:
+    name: Run Regenerate Connector Workflow
+    if: ${{ github.repository_owner == 'ballerina-platform' }}
+    uses: ballerina-platform/ballerina-library/.github/workflows/regenerate-connector-template.yml@main
+    secrets: inherit
+    with:
+      openapi-url: ${{ inputs.openapi-url }}
+      flatten-openapi: ${{ inputs.flatten-openapi }}
+      additional-flatten-flags: ${{ inputs.additional-flatten-flags }}
+      align-openapi: ${{ inputs.align-openapi }}
+      additional-align-flags: ${{ inputs.additional-align-flags  }}
+      additional-generation-flags: ${{ inputs.additional-generation-flags }}
+      distribution-zip: ${{ inputs.distribution-zip }}
+      auto-merge: ${{ inputs.auto-merge }}
+      ballerina-version: ${{ inputs.ballerina-version }}

.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/Ballerina.toml

@@ -2,10 +2,10 @@
 distribution = "2201.12.0"
 org = "ballerinax"
 name = "smartsheet"
-version = "0.1.0"
+version = "1.0.0"
 license = ["Apache-2.0"]
 authors = ["Ballerina"]
-keywords = [] # TODO: Add keywords
+keywords = ["smartsheet", "project-management", "task-automation", "workflow-automation", "spreadsheet-integration"] 
 # icon = "icon.png" # TODO: Add icon
 repository = "https://github.com/ballerina-platform/module-ballerinax-smartsheet"
 

ballerina/Dependencies.toml

@@ -76,7 +76,7 @@ dependencies = [
 [[package]]
 org = "ballerina"
 name = "http"
-version = "2.14.3"
+version = "2.14.4"
 dependencies = [
 	{org = "ballerina", name = "auth"},
 	{org = "ballerina", name = "cache"},
@@ -333,7 +333,7 @@ modules = [
 [[package]]
 org = "ballerinax"
 name = "smartsheet"
-version = "0.1.0"
+version = "1.0.0"
 dependencies = [
 	{org = "ballerina", name = "constraint"},
 	{org = "ballerina", name = "data.jsondata"},

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.
+

build-config/resources/Ballerina.toml

@@ -5,7 +5,7 @@ name = "smartsheet"
 version = "@toml.version@"
 license = ["Apache-2.0"]
 authors = ["Ballerina"]
-keywords = [] # TODO: Add keywords
+keywords = ["smartsheet", "project-management", "task-automation", "workflow-automation", "spreadsheet-integration"] 
 # icon = "icon.png" # TODO: Add icon
 repository = "https://github.com/ballerina-platform/module-ballerinax-smartsheet"
 

examples/README.md

@@ -1,15 +1,18 @@
 # 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 = "1.0.0"
+
+[[dependency]]
+org = "ballerinax"
+name = "smartsheet"
+version = "1.0.0"
+repository = "local"
+
+