Add Azure Files connector documentation and examples

en/docs/connectors/catalog/index.mdx

@@ -45,6 +45,7 @@ Find the right connector for your integration. Use the search bar or filter by c
     { name: "AWS SQS", description: "Fully managed message queuing with standard and FIFO queues, batch operations, and event-driven consumption", operations: "Send, Receive, Delete, Batch Send, Batch Delete, Queue Management", auth: "AWS IAM (Access Key + Secret Key)", link: "messaging/aws.sqs/aws-sqs-connector-overview", category: "Messaging", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_aws.sqs_4.1.3.png" },
     { name: "Azure AI Search", description: "Azure AI Search service management for indexes, indexers, data sources, skillsets, and synonym maps", operations: "Create, Read, Update, Delete, List, Run, Reset, Analyze, Statistics", auth: "API Key", link: "ai-ml/azure.ai.search/azure-ai-search-connector-overview", category: "AI & ML", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_azure.ai.search_1.0.1.png" },
     { name: "Azure AI Search Index", description: "AI-powered cloud search with full-text, semantic, and vector search over indexed documents", operations: "Search, Lookup, Index, Suggest, Autocomplete, Count", auth: "API Key", link: "ai-ml/azure.ai.search.index/azure-ai-search-index-connector-overview", category: "AI & ML", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_azure.ai.search.index_1.0.1.png" },
+    { name: "Azure Files", description: "Azure Files shares with directory and file management, transfers, copies, SAS generation, and event-driven file monitoring", operations: "Upload, Download, List, Copy, Delete, Rename, Snapshot, Poll", auth: "Access Key / SAS / Connection String / Entra ID", link: "storage-file/azure.storage.files/overview", category: "Storage & Files" },
     { name: "Azure Service Bus", description: "Enterprise message broker with queues, topics, subscriptions, and event-driven message processing", operations: "Send, Receive, Schedule, Settle, Admin, Listen", auth: "Connection String", link: "messaging/asb/azure-service-bus-connector-overview", category: "Messaging", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_asb_3.9.1.png" },
     { name: "Azure Storage Service", description: "Azure Blob Storage with container management, blob CRUD, and SAS token support", operations: "Create, Read, Delete, List, Upload, Download", auth: "Connection String / SAS Token", link: "storage-file/azure_storage_service/overview", category: "Storage & Files" },
     { name: "Candid", description: "Nonprofit data platform with search, profiles, financials, and PDF report downloads", operations: "Search, Profile, Lookup, PDF Download", auth: "API Key", link: "productivity-collaboration/candid/connector-overview", category: "Productivity & Collaboration", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_candid_0.2.0.png" },

en/docs/connectors/catalog/storage-file/azure.storage.files/overview.md

@@ -0,0 +1,63 @@
+---
+connector: true
+connector_name: "azure.storage.files"
+title: "Azure Files"
+description: "Overview of the ballerinax/azure.storage.files connector for WSO2 Integrator."
+---
+
+[Azure Files](https://learn.microsoft.com/en-us/azure/storage/files/storage-files-introduction) offers fully managed file shares in the cloud, accessible via the industry-standard SMB and NFS protocols and a REST API. The `ballerinax/azure.storage.files` connector (v1.0.0) connects WSO2 Integrator to Microsoft Azure Files, managing shares and the directories and files within them: uploads, downloads, copies, renames, byte ranges, snapshots, and SAS token generation. A polling `Listener` turns files arriving on a share into service events.
+
+## Key features
+
+- Share-scoped `Client` for directory and file operations, transfers, copies, and byte ranges
+- Account-level `AdminClient` for creating, listing, deleting, and restoring shares
+- Polling `Listener` that routes files arriving on a watched path to raw, typed, or streaming content handlers, with an optional `onError` error handler
+- Share snapshots
+- Authentication with shared key, SAS tokens, connection strings, and Microsoft Entra ID
+- GraalVM compatible for native image builds
+
+## Actions
+
+Actions are operations you invoke on Azure Files from your integration: uploading and downloading files, managing directories and shares, copying, generating SAS tokens, and more. The connector exposes actions through two clients.
+
+| Client | Actions |
+|--------|---------|
+| `Client` | Directory, file, transfer, copy, range, snapshot, and SAS operations within one share |
+| `AdminClient` | Account-level share management and file-service configuration |
+
+See the **[Action Reference](action-reference.md)** for the full list of operations, parameters, and sample code for each client.
+
+## Triggers
+
+Triggers let your integration react to files arriving on a file share. The connector uses a polling `Listener` that periodically scans a watched path on a share and routes each file present there to the matching content handler of your service.
+
+| Event | Callback | Description |
+|-------|----------|-------------|
+| Any file without a dedicated typed handler | `onFile` | Receives the raw file content |
+| Text file (`.txt`) | `onFileText` | Receives the content as a string |
+| JSON file (`.json`) | `onFileJson` | Receives the parsed JSON content |
+| XML file (`.xml`) | `onFileXml` | Receives the parsed XML content |
+| CSV file (`.csv`) | `onFileCsv` | Receives the parsed rows |
+| Listener error | `onError` | Receives poll failures, content-read failures, and content-binding failures |
+
+See the **[Trigger Reference](trigger-reference.md)** for listener configuration, the service model, and callback signatures.
+
+## Documentation
+
+* **[Setup Guide](setup-guide.md)**: How to create a storage account and file share, and obtain credentials.
+
+* **[Action Reference](action-reference.md)**: Full reference for both clients: operations, parameters, return types, and sample code.
+
+* **[Trigger Reference](trigger-reference.md)**: Reference for event-driven integration using the listener and service model.
+
+* **[Example](example.md)**: Learn how to build and configure an integration using the **Azure Files** connector, including connection setup, operation configuration, execution flow, and event-driven trigger setup.
+
+## How to contribute
+
+As an open source project, WSO2 welcomes contributions from the community.
+
+To contribute to the code for this module, please create a pull request in the following repository.
+
+* [Azure Files Module GitHub repository](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files)
+
+Check the issue tracker for open issues that interest you. We look forward to receiving your contributions.

en/docs/connectors/catalog/storage-file/azure.storage.files/setup-guide.md

@@ -0,0 +1,70 @@
+---
+connector: true
+connector_name: "azure.storage.files"
+title: "Setup Guide"
+description: "How to set up and configure the ballerinax/azure.storage.files connector."
+---
+
+# Setup Guide
+
+This guide walks you through preparing an Azure storage account and obtaining the credentials the `ballerinax/azure.storage.files` connector needs to authenticate with Azure Files.
+
+## Prerequisites
+
+- An Azure subscription. If you do not have one, [sign up for a free Azure account](https://azure.microsoft.com/free/).
+
+## Create a storage account
+
+1. Sign in to the [Azure portal](https://portal.azure.com/), search for **Storage accounts**, and open it.
+2. Select **+ Create**.
+3. On the **Basics** tab, select a subscription and resource group, provide a globally unique storage account name, and pick a region. The **Standard** performance tier is sufficient for SMB file shares; choose **Premium** with the **File shares** account type only if you need provisioned performance or NFS.
+4. Select **Review + create**, then **Create**, and wait for the deployment to complete. For the full set of options, see the [Azure documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create).
+
+## Create a file share
+
+1. Open the deployed storage account and navigate to **Data storage** > **File shares**.
+2. Select **+ File share**, provide a name, and select **Create**. The share name is what you pass to the connector at initialization. For details, see the [Azure Files documentation](https://learn.microsoft.com/en-us/azure/storage/files/storage-how-to-create-file-share).
+
+## Obtain credentials
+
+The connector accepts any one of the following credential types. An access key is the most capable credential: share-level administrative operations and key-based SAS token generation require it. (User delegation SAS is the exception; it requires a Microsoft Entra ID identity instead, as described below.)
+
+### Access keys
+
+1. In the storage account, navigate to **Security + networking** > **Access keys**.
+2. Select **Show** next to **key1**, then copy the storage account name and the key value. These two values are the account name and account key the connector's shared key authentication uses.
+
+### SAS token or SAS URL
+
+1. In the storage account, navigate to **Security + networking** > **Shared access signature**.
+2. Select the allowed services, resource types, permissions, and an expiry window, then select **Generate SAS and connection string**.
+3. Copy the **SAS token**, or the **File service SAS URL** if you prefer a single value that carries both the endpoint and the token.
+
+A SAS credential is limited to the services, resource types, permissions, and expiry it was minted with. The portal's **Shared access signature** page mints an account SAS; minted with the File service and the container resource type, it can also perform share-level administrative operations. A share- or file-scoped SAS cannot. No SAS credential can mint further SAS tokens.
+
+### Connection string
+
+The portal shows a connection string alongside each access key under **Security + networking** > **Access keys**. Select **Show** next to the **Connection string** field and copy the value. It carries the account name, the credential, and the service endpoints in one string.
+
+### Microsoft Entra ID
+
+The connector can authenticate as a Microsoft Entra ID identity: a service principal (via a client secret or certificate), a managed identity, a federated workload identity, or the default credential chain of the environment it runs in.
+
+To use a service principal:
+
+1. In the Azure portal, open **Microsoft Entra ID** > **App registrations** and select **+ New registration**. After registering, note the **Directory (tenant) ID** and **Application (client) ID** from the app's overview page.
+2. Under the app's **Certificates & secrets**, create a client secret (or upload a certificate) and copy its value.
+
+The role requirements apply regardless of which Entra ID credential kind you use, and they split by operation family:
+
+- For file and directory data operations, the identity must hold the **Storage File Data Privileged Reader** or **Storage File Data Privileged Contributor** role on the storage account. The connector sends the backup intent on every request; this requires the privileged roles and bypasses file and directory ACLs.
+- Share-level and account-level management operations (the admin operations, and the operations on the share itself) authorize against the storage account's management permissions instead: the identity needs a role carrying the `Microsoft.Storage/storageAccounts/fileServices/shares/` read, write, and delete actions, such as **Contributor** on the storage account. The privileged data roles alone do not cover these operations.
+- Generating user delegation SAS tokens additionally requires the **Storage File Delegator** role.
+
+An identity covering the full connector surface holds a privileged data role and a management role together. Assign the roles in the storage account under **Access control (IAM)** > **Add** > **Add role assignment**.
+
+## Next steps
+
+- [Actions](action-reference.md): the operations available on the connector's clients.
+- [Triggers](trigger-reference.md): event-driven integration with the polling listener.
+- [Example](example.md): step-by-step walkthroughs using the credentials from this guide.