Tutorial: Adding Watermarks to Excel Files with Aspose.Cells Cloud API

Prerequisites

Before starting this tutorial, make sure you have:

An Aspose Cloud account with an active subscription or free trial
Your Client ID and Client Secret from the Aspose Cloud Dashboard
Basic understanding of REST API concepts
Excel files for testing watermark operations
Familiarity with your preferred programming language

Understanding Excel Watermarks

Watermarks are semi-transparent text or images that appear behind the content of a document. In Excel files, watermarks serve several important purposes:

Branding: Adding company logos or names to spreadsheets
Security: Marking documents as “Confidential,” “Draft,” or “Internal Use Only”
Versioning: Indicating document status like “Preview” or “Beta”
Ownership: Establishing intellectual property rights
Documentation: Adding information about the document’s purpose

Aspose.Cells Cloud provides an easy-to-use API for adding watermarks to Excel files without requiring client-side Excel installations.

1. Adding a Text Watermark to Excel Files

The most common watermarking need is to add text watermarks like “Confidential” or “Draft” to documents.

Try It Yourself: Adding a Text Watermark

Follow these steps to add a text watermark to an Excel file:

Prepare your Excel file
Make the API request to add the watermark
Save the watermarked file

Using cURL

curl -X POST "https://api.aspose.cloud/v3.0/cells/watermark?text=CONFIDENTIAL&color=ff0000ff" \
-H "accept: application/json" \
-H "authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: multipart/form-data" \
-F "file=@sample.xlsx"

SDK Examples

Python

# Tutorial Code Example - Adding a Text Watermark to Excel
import requests
import json
import base64

# Configure authentication (get your own bearer token using client credentials)
bearer_token = "YOUR_ACCESS_TOKEN"

# API endpoint
url = "https://api.aspose.cloud/v3.0/cells/watermark"

# Watermark text and color (RRGGBBAA format - red with 100% opacity)
watermark_text = "CONFIDENTIAL"
watermark_color = "ff0000ff"  # Red with 100% opacity

# Local file path
file_path = "sample.xlsx"

# Prepare the request
headers = {
    "accept": "application/json",
    "authorization": f"Bearer {bearer_token}"
}

# Prepare the file
files = {
    "file": open(file_path, "rb")
}

# Submit the request
response = requests.post(
    f"{url}?text={watermark_text}&color={watermark_color}",
    headers=headers,
    files=files
)

# Remember to close the file handle
files["file"].close()

# Process the response
if response.status_code == 200:
    result = response.json()
    
    # The API returns the watermarked file in the response
    if "Files" in result and len(result["Files"]) > 0:
        file_info = result["Files"][0]
        filename = file_info["Filename"]
        file_content_base64 = file_info["FileContent"]
        
        # Decode the file content
        file_content = base64.b64decode(file_content_base64)
        
        # Save the watermarked file
        watermarked_filename = f"watermarked_{filename}"
        with open(watermarked_filename, "wb") as f:
            f.write(file_content)
        
        print(f"Watermarked file saved as {watermarked_filename}")
    else:
        print("No watermarked files returned in the response.")
else:
    print(f"Error adding watermark: {response.status_code}")
    print(response.text)

C#

// Tutorial Code Example - Adding a Text Watermark to Excel
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;
using System.Collections.Generic;

namespace AsposeCellsWatermarkExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Configure authentication (get your own bearer token using client credentials)
            string bearerToken = "YOUR_ACCESS_TOKEN";
            
            // API endpoint
            string url = "https://api.aspose.cloud/v3.0/cells/watermark";
            
            // Watermark text and color (RRGGBBAA format - red with 100% opacity)
            string watermarkText = "CONFIDENTIAL";
            string watermarkColor = "ff0000ff";  // Red with 100% opacity
            
            // Local file path
            string filePath = "sample.xlsx";
            
            // Create HttpClient
            using (var httpClient = new HttpClient())
            {
                // Set authorization header
                httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);
                
                // Create multipart form content
                using (var formData = new MultipartFormDataContent())
                {
                    // Add file to form data
                    var fileContent = new ByteArrayContent(File.ReadAllBytes(filePath));
                    fileContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/octet-stream");
                    formData.Add(fileContent, "file", Path.GetFileName(filePath));
                    
                    // Send the request
                    var response = await httpClient.PostAsync($"{url}?text={watermarkText}&color={watermarkColor}", formData);
                    
                    // Process the response
                    if (response.IsSuccessStatusCode)
                    {
                        var jsonString = await response.Content.ReadAsStringAsync();
                        var result = JsonSerializer.Deserialize<WatermarkResponse>(jsonString);
                        
                        // The API returns the watermarked file in the response
                        if (result.Files != null && result.Files.Count > 0)
                        {
                            var fileInfo = result.Files[0];
                            string filename = fileInfo.Filename;
                            string fileContentBase64 = fileInfo.FileContent;
                            
                            // Decode the file content
                            byte[] fileContent = Convert.FromBase64String(fileContentBase64);
                            
                            // Save the watermarked file
                            string watermarkedFilename = $"watermarked_{filename}";
                            File.WriteAllBytes(watermarkedFilename, fileContent);
                            
                            Console.WriteLine($"Watermarked file saved as {watermarkedFilename}");
                        }
                        else
                        {
                            Console.WriteLine("No watermarked files returned in the response.");
                        }
                    }
                    else
                    {
                        Console.WriteLine($"Error adding watermark: {(int)response.StatusCode}");
                        Console.WriteLine(await response.Content.ReadAsStringAsync());
                    }
                }
            }
        }
    }
    
    // Classes to deserialize the response
    public class WatermarkResponse
    {
        public List<FileInfo> Files { get; set; }
    }
    
    public class FileInfo
    {
        public string Filename { get; set; }
        public string FileContent { get; set; }
        public long FileSize { get; set; }
    }
}

2. Customizing Watermarks with Colors

You can customize your watermarks by specifying different colors. The color parameter uses an RRGGBBAA format (Red, Green, Blue, Alpha), where:

The first two hex digits represent the red component (00-FF)
The second two hex digits represent the green component (00-FF)
The third two hex digits represent the blue component (00-FF)
The last two hex digits represent the alpha (opacity) component (00-FF)

Try It Yourself: Colored Watermarks

Prepare your Excel file
Make the API request with a custom color code
Save the watermarked file

Color Examples

Description	Color Code	Result
Red (semi-transparent)	`ff000080`	Red text at 50% opacity
Green (solid)	`00ff00ff`	Green text at 100% opacity
Blue (semi-transparent)	`0000ff80`	Blue text at 50% opacity
Gray (semi-transparent)	`80808080`	Gray text at 50% opacity

Python Example with Custom Color

# Tutorial Code Example - Adding a Colored Watermark
import requests
import base64

# Configure authentication
bearer_token = "YOUR_ACCESS_TOKEN"
url = "https://api.aspose.cloud/v3.0/cells/watermark"

# Watermark text and color (RRGGBBAA format - green with 50% opacity)
watermark_text = "DRAFT"
watermark_color = "00ff0080"  # Green with 50% opacity

# Local file path
file_path = "sample.xlsx"

# Prepare request headers and files (similar to previous example)
# ...

# Submit the request
response = requests.post(
    f"{url}?text={watermark_text}&color={watermark_color}",
    headers=headers,
    files=files
)

# Process response (similar to previous example)
# ...

3. Processing Multiple Files in One Request

Aspose.Cells Cloud allows you to add watermarks to multiple Excel files in a single API call, which is more efficient for batch processing.

Try It Yourself: Batch Watermarking

Prepare multiple Excel files
Make the API request with all files
Save all the watermarked files

Using cURL

curl -X POST "https://api.aspose.cloud/v3.0/cells/watermark?text=CONFIDENTIAL&color=ff0000ff" \
-H "accept: application/json" \
-H "authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: multipart/form-data" \
-F "file1=@file1.xlsx" \
-F "file2=@file2.xlsx" \
-F "file3=@file3.xlsx"

Python Example

# Tutorial Code Example - Adding Watermarks to Multiple Files
import requests
import json
import base64

# Configure authentication (get your own bearer token using client credentials)
bearer_token = "YOUR_ACCESS_TOKEN"

# API endpoint
url = "https://api.aspose.cloud/v3.0/cells/watermark"

# Watermark text and color
watermark_text = "CONFIDENTIAL"
watermark_color = "ff0000ff"  # Red with 100% opacity

# Local file paths
file_paths = [
    "file1.xlsx",
    "file2.xlsx",
    "file3.xlsx"
]

# Prepare the request
headers = {
    "accept": "application/json",
    "authorization": f"Bearer {bearer_token}"
}

# Prepare the files
files = {}
for i, path in enumerate(file_paths, 1):
    files[f"file{i}"] = open(path, "rb")

# Submit the request
response = requests.post(
    f"{url}?text={watermark_text}&color={watermark_color}",
    headers=headers,
    files=files
)

# Remember to close the file handles
for file in files.values():
    file.close()

# Process the response
if response.status_code == 200:
    result = response.json()
    
    # The API returns all watermarked files in the response
    if "Files" in result and len(result["Files"]) > 0:
        print(f"Successfully watermarked {len(result['Files'])} files:")
        
        for file_info in result["Files"]:
            filename = file_info["Filename"]
            file_content_base64 = file_info["FileContent"]
            
            # Decode the file content
            file_content = base64.b64decode(file_content_base64)
            
            # Save the watermarked file
            watermarked_filename = f"watermarked_{filename}"
            with open(watermarked_filename, "wb") as f:
                f.write(file_content)
            
            print(f"  - Watermarked file saved as {watermarked_filename}")
    else:
        print("No watermarked files returned in the response.")
else:
    print(f"Error adding watermarks: {response.status_code}")
    print(response.text)

4. Practical Scenario: Document Classification System

Let’s walk through a real-world scenario where watermarking is essential - a document classification system that applies the appropriate watermarks based on document sensitivity:

# Tutorial Code Example - Document Classification System
import os
import requests
import json
import base64
import logging

# Configure logging
logging.basicConfig(level=logging.INFO, 
                    format='%(asctime)s - %(levelname)s - %(message)s')

# Configure authentication (get your own bearer token using client credentials)
bearer_token = "YOUR_ACCESS_TOKEN"

# API endpoint
url = "https://api.aspose.cloud/v3.0/cells/watermark"

# Document classification definitions
classifications = {
    "public": {
        "text": "PUBLIC INFORMATION",
        "color": "00800080"  # Green, 50% opacity
    },
    "internal": {
        "text": "INTERNAL USE ONLY",
        "color": "0000ff80"  # Blue, 50% opacity
    },
    "confidential": {
        "text": "CONFIDENTIAL",
        "color": "ff000080"  # Red, 50% opacity
    },
    "restricted": {
        "text": "RESTRICTED ACCESS",
        "color": "80008080"  # Purple, 50% opacity
    }
}

def apply_watermark(file_path, classification):
    """Apply the appropriate watermark based on document classification."""
    if classification not in classifications:
        logging.error(f"Unknown classification: {classification}")
        return None
    
    # Get watermark settings for this classification
    watermark_text = classifications[classification]["text"]
    watermark_color = classifications[classification]["color"]
    
    logging.info(f"Applying '{watermark_text}' watermark to {file_path}")
    
    try:
        # Prepare the request
        headers = {
            "accept": "application/json",
            "authorization": f"Bearer {bearer_token}"
        }
        
        # Prepare the file
        with open(file_path, "rb") as f:
            files = {"file": f}
            
            # Submit the request
            response = requests.post(
                f"{url}?text={watermark_text}&color={watermark_color}",
                headers=headers,
                files=files
            )
        
        # Process the response
        if response.status_code == 200:
            result = response.json()
            
            if "Files" in result and len(result["Files"]) > 0:
                file_info = result["Files"][0]
                filename = os.path.basename(file_path)
                file_content_base64 = file_info["FileContent"]
                
                # Decode the file content
                file_content = base64.b64decode(file_content_base64)
                
                # Create output filename with classification
                base_name, ext = os.path.splitext(filename)
                output_filename = f"{base_name}_{classification}{ext}"
                
                # Save the watermarked file
                with open(output_filename, "wb") as f:
                    f.write(file_content)
                
                logging.info(f"Watermarked file saved as {output_filename}")
                return output_filename
            else:
                logging.warning("No watermarked file returned in the response.")
                return None
        else:
            logging.error(f"API error ({response.status_code}): {response.text}")
            return None
    except Exception as e:
        logging.error(f"Error processing {file_path}: {str(e)}")
        return None

# Example usage
def process_documents():
    # Documents to process with their classifications
    documents = [
        {"path": "financial_report.xlsx", "classification": "confidential"},
        {"path": "company_overview.xlsx", "classification": "public"},
        {"path": "employee_handbook.xlsx", "classification": "internal"},
        {"path": "executive_strategy.xlsx", "classification": "restricted"}
    ]
    
    for doc in documents:
        result = apply_watermark(doc["path"], doc["classification"])
        if result:
            print(f"Successfully processed {doc['path']} as {doc['classification']}")
        else:
            print(f"Failed to process {doc['path']}")

# Run the process
process_documents()

This example demonstrates a document classification system that applies different watermarks based on document sensitivity levels. Each classification has its own text and color, making it easy to identify document types at a glance.

5. Best Practices for Excel Watermarks

When working with Excel watermarks, consider these best practices:

Text Clarity:
- Use short, clear text for watermarks (e.g., “CONFIDENTIAL” rather than “This document contains confidential information”)
- ALL CAPS text tends to be more visible as a watermark
Color and Opacity:
- Semi-transparent colors (opacity around 50%) provide the best balance between visibility and readability
- Choose colors that contrast with your typical spreadsheet content
- Red is commonly used for confidential documents, while blue or green may be used for drafts or internal documents
Placement:
- The Aspose.Cells Cloud API automatically positions the watermark diagonally across the sheet
- This ensures the watermark is visible regardless of which portion of the spreadsheet is being viewed
Document Workflow:
- Consider applying watermarks as part of your document generation or approval workflow
- You might use different watermarks for different stages (e.g., “DRAFT” during review, “FINAL” when approved)

Troubleshooting Tips

When working with Excel watermarks, you might encounter these common issues:

File size limitations:
- Very large Excel files might time out during API processing
- Consider breaking down very large workbooks into smaller files
Color specification:
- Remember to use the RRGGBBAA format for colors
- If your watermark is invisible, check that you’ve set an appropriate alpha (opacity) value
Text length:
- Very long watermark text may be difficult to read
- Shorter text (1-2 words) usually works best for watermarks
Network issues:
- Implement proper retry logic for network failures
- Use appropriate timeouts for large file uploads

What You’ve Learned

In this tutorial, you’ve learned how to:

Add text watermarks to Excel files using Aspose.Cells Cloud API
Customize watermark appearance by adjusting text and color
Process multiple files in a single API call for efficiency
Implement a practical document classification system using watermarks
Apply best practices for effective Excel watermarking

Further Practice

To reinforce your learning, try these exercises:

Create a script that watermarks all Excel files in a directory with different watermarks based on filename patterns
Implement a document approval system that changes watermarks from “DRAFT” to “APPROVED” when documents are finalized
Build a tool that watermarks financial reports with the appropriate fiscal period (e.g., “Q1 2023”)
Create a batch processing utility that applies different watermarks to files based on their content

Tutorial: Adding Watermarks to Excel Files with Aspose.Cells Cloud API

Prerequisites

Understanding Excel Watermarks

1. Adding a Text Watermark to Excel Files

Try It Yourself: Adding a Text Watermark

Using cURL

SDK Examples

Python

C#

2. Customizing Watermarks with Colors

Try It Yourself: Colored Watermarks

Color Examples

Python Example with Custom Color

3. Processing Multiple Files in One Request

Try It Yourself: Batch Watermarking

Using cURL

Python Example

4. Practical Scenario: Document Classification System

5. Best Practices for Excel Watermarks

Troubleshooting Tips

What You’ve Learned

Further Practice

Additional Resources