1. Installation

Install Simple Azure Storage Connector (Blob) from Forge into your OutSystems environment.

After installation, open your consuming application and add a dependency to the required actions:

• Blob_CreateOrUpdate
• Blob_Delete
• Blob_Get
• Blob_GetByURL
• Blob_GetList

Publish the consuming application after adding the dependency.

2. Required Configuration

Before using the connector, configure the required settings.

StorageAccount_Name

Azure Storage Account name used to build the Azure Blob Storage request URL.

StorageAccount_Key

Azure Storage Account access key used server-side to generate short-lived SAS tokens.

This value is sensitive. Do not expose it in:

• Client-side logic
• Logs
• Screen outputs
• Emails
• API responses
• Error messages

DefaultSASExpiryMinutes

Default validity period, in minutes, for generated short-lived SAS tokens.

Recommended value:

• 10

PrivateGatewayPort

OutSystems Private Gateway port for the mapped Azure Blob endpoint.

Use:

• 0 for public Azure Blob Storage access
• for private endpoint access through OutSystems Private Gateway

3. Azure Storage Prerequisites

Before using this component, make sure the following are already available:

• Azure Storage Account
• Azure Blob container
• Storage Account name
• Storage Account access key
• Blob container name
• Blob name or blob path

For private endpoint scenarios, configure the following separately:

• Azure Private Endpoint
• Private DNS or equivalent name resolution
• Network or firewall rules
• OutSystems Private Gateway
• Private Gateway port mapping

4. Basic Usage

After the settings are configured, call the blob actions from server-side logic.

Recommended pattern:

1. Validate the file, container name, blob name, and user permission.
2. Call the required blob action.
3. Handle the response.
4. Show a user-friendly success or error message.
5. Do not expose StorageAccount_Key or SAS generation details to the client.

5. Create or Update Blob

Use Blob_CreateOrUpdate to upload a new blob or replace an existing blob.

Typical use cases:

• Upload file attachments
• Save generated reports
• Store exported documents
• Replace existing files

Recommended flow:

1. Get the file content from an Upload widget or server-side process.
2. Define the container name.
3. Define the blob name or blob path.
4. Call Blob_CreateOrUpdate.
5. Store only the blob reference or blob URL if needed.

Example blob paths:

• documents/sample.pdf
• reports/yyyy/report-001.xlsx
• attachments/request-id/file.png

6. Get Blob

Use Blob_Get to retrieve a blob from Azure Blob Storage.

Typical use cases:

• Download stored files
• Read file content for processing
• Retrieve attachment content

Recommended flow:

1. Provide the container name.
2. Provide the blob name or path.
3. Call Blob_Get.
4. Use the returned content in the consuming application.

7. Get Blob by URL

Use Blob_GetByURL when the full blob URL is already available.

Typical use cases:

• Retrieve a file using a stored blob URL
• Download a file from a saved reference
• Access a blob when the application already stores the complete URL

Recommended flow:

1. Get the blob URL from your application record.
2. Call Blob_GetByURL.
3. Process or return the file content as needed.

8. Delete Blob

Use Blob_Delete to remove a blob from Azure Blob Storage.

Typical use cases:

• Delete obsolete files
• Remove replaced attachments
• Clean up temporary files
• Delete generated documents

Recommended flow:

1. Confirm the blob should be deleted.
2. Provide the container name.
3. Provide the blob name or path.
4. Call Blob_Delete.
5. Update the application record if the blob reference is stored in the database.

9. List Blobs

Use Blob_GetList to retrieve blobs from a container.

Typical use cases:

• Display files in a container
• List files under a folder or prefix
• Check available generated reports
• Build a simple file browser

Recommended flow:

1. Provide the container name.
2. Provide prefix or path filter if applicable.
3. Call Blob_GetList.
4. Display or process the returned blob list.

Example prefixes:

• documents/
• reports/yyyy/
• attachments/request-id/

10. Public Azure Blob Storage Access

For public Azure Blob Storage access, configure:

StorageAccount_Name

StorageAccount_Key

DefaultSASExpiryMinutes

• 10

PrivateGatewayPort

• 0

In this mode, the connector uses the standard Azure Blob Storage public endpoint.

11. Private Endpoint Access

For private endpoint scenarios, configure Azure networking and OutSystems Private Gateway separately.

Then configure:

StorageAccount_Name

StorageAccount_Key

DefaultSASExpiryMinutes

• 10

PrivateGatewayPort

The component uses the configured Private Gateway port to route requests to the mapped Azure Blob endpoint.

12. Security Recommendations

Keep DefaultSASExpiryMinutes short. Recommended value is 10 minutes.

Keep StorageAccount_Key server-side only. Do not expose it in:

• Client actions
• Screens
• Logs
• Emails
• API responses
• Error messages
• JavaScript
• Browser developer tools

Do not store generated SAS URLs permanently unless the expiry and access scope are understood.

Validate files before upload, including:

• File size
• File extension
• MIME type
• User permission
• Business record ownership

13. Error Handling

Common error causes include:

• Invalid StorageAccount_Name
• Invalid StorageAccount_Key
• Container does not exist
• Blob does not exist
• Expired SAS token
• Incorrect PrivateGatewayPort
• Private Gateway mapping issue
• Azure private endpoint or DNS issue
• Firewall or network restriction
• Request timeout
• File size too large

Recommended handling:

1. Log technical details only on the server side.
2. Show a simple user-friendly message to the end user.
3. Avoid exposing SAS tokens, StorageAccount_Key, or internal error details.
4. Retry only when the issue is likely transient.

14. Recommended Implementation Pattern

For better maintainability, create wrapper server actions in the consuming application.

Example wrapper actions:

• UploadDocumentToBlob
• DownloadDocumentFromBlob
• DeleteDocumentFromBlob
• ListRequestAttachments

This keeps business validation, permission checks, and blob naming rules inside the consuming application while using this component only for Azure Blob operations.