Tutorial: How to Work with Conversion Settings in GroupDocs.Conversion Cloud API

Learning Objectives

In this tutorial, you’ll learn:

What ConversionSettings are and their role in document conversion
How to structure conversion settings for different scenarios
Best practices for configuring document conversion parameters
Techniques for troubleshooting common settings issues

Prerequisites

Before starting this tutorial, you should have:

A GroupDocs.Conversion Cloud account
Your Client ID and Client Secret credentials
Basic understanding of REST API concepts
Familiarity with JSON data structures
A development environment set up for your preferred language (examples provided in cURL, Python, Java, and C#)

What are ConversionSettings?

ConversionSettings are critical data structures that control how the GroupDocs.Conversion Cloud API processes your documents. They define:

The source document to convert
The target format for conversion
How to load the document (LoadOptions)
Format-specific conversion parameters (ConvertOptions)
Where to store the conversion results

Think of ConversionSettings as a comprehensive instruction set for the API to follow when converting your documents.

Understanding the ConversionSettings Structure

Let’s examine the basic structure of ConversionSettings:

{
  "Format": "string",
  "FilePath": "string",
  "Storage": "string",
  "LoadOptions": {
    "Password": "string"
  },
  "ConvertOptions": {
    "FromPage": "integer",
    "PagesCount": "integer"
  },
  "OutputPath": "string"
}

Each field serves a specific purpose:

Field	Description	Required?
Format	Target conversion format (e.g., “pdf”, “docx”)	Yes
FilePath	Path to the source document in storage	Yes
Storage	Storage name where document is located	No
LoadOptions	Format-specific options for loading the document	No
ConvertOptions	Format-specific options for the conversion process	No
OutputPath	Path where conversion results will be stored	No

Step 1: Creating Basic ConversionSettings

Let’s start with a simple example of converting a Word document to PDF:

# Tutorial Code Example: Basic Conversion Settings
conversion_settings = {
    "Format": "pdf",  # Target format is PDF
    "FilePath": "documents/sample.docx",  # Source document path
    "OutputPath": "converted/"  # Where to save the result
}

# This minimal setup instructs the API to:
# 1. Find a file named "sample.docx" in the "documents" folder
# 2. Convert it to PDF format
# 3. Save the result in the "converted" folder

Try it yourself

Create conversion settings for converting an Excel file to HTML:

# Exercise: Create ConversionSettings for Excel to HTML conversion
# Your code here:
conversion_settings = {
    "Format": "html",
    "FilePath": "spreadsheets/data.xlsx",
    "OutputPath": "converted/web/"
}

Step 2: Adding LoadOptions for Protected Documents

Many documents are password-protected. Let’s see how to handle this:

# Tutorial Code Example: Conversion Settings with LoadOptions
conversion_settings = {
    "Format": "pdf",
    "FilePath": "documents/protected.docx",
    "LoadOptions": {
        "Password": "your-password-here"  # Password to open the document
    },
    "OutputPath": "converted/"
}

# Now the API will:
# 1. Use the provided password to open the protected document
# 2. Proceed with conversion as instructed

Different document formats support different LoadOptions. For example, spreadsheet documents have additional options:

# Tutorial Code Example: Excel-specific LoadOptions
conversion_settings = {
    "Format": "pdf",
    "FilePath": "spreadsheets/quarterly_report.xlsx",
    "LoadOptions": {
        "Password": "your-password-here",
        "ShowGridLines": True,
        "OnePagePerSheet": True,
        "SkipEmptyRowsAndColumns": True
    },
    "OutputPath": "converted/"
}

Try it yourself

Create conversion settings for a password-protected PowerPoint file with specific loading options:

# Exercise: Create ConversionSettings with LoadOptions for PowerPoint
# Your code here:
conversion_settings = {
    "Format": "pdf",
    "FilePath": "presentations/company_deck.pptx",
    "LoadOptions": {
        "Password": "secure123",
        "ShowHiddenSlides": False
    },
    "OutputPath": "converted/presentations/"
}

Step 3: Customizing Conversion with ConvertOptions

ConvertOptions allow you to fine-tune how the conversion process works:

# Tutorial Code Example: Conversion Settings with ConvertOptions
conversion_settings = {
    "Format": "pdf",
    "FilePath": "documents/large_report.docx",
    "ConvertOptions": {
        "FromPage": 5,     # Start conversion from page 5
        "PagesCount": 10,  # Convert only 10 pages
        "Zoom": 100,       # Zoom level for the output
        "Grayscale": True  # Convert to grayscale PDF
    },
    "OutputPath": "converted/"
}

# This configuration tells the API to:
# 1. Convert only pages 5-14 of the document
# 2. Use 100% zoom level
# 3. Create a grayscale PDF instead of color

Different target formats support different ConvertOptions. For image conversions, you might specify:

# Tutorial Code Example: Image-specific ConvertOptions
conversion_settings = {
    "Format": "jpeg",
    "FilePath": "documents/brochure.pdf",
    "ConvertOptions": {
        "Width": 1920,
        "Height": 1080,
        "Quality": 95,
        "RotateAngle": 0
    },
    "OutputPath": "converted/images/"
}

Try it yourself

Create conversion settings for converting specific pages of a PDF to PNG images with custom dimensions:

# Exercise: Create ConversionSettings with ConvertOptions for PDF to PNG
# Your code here:
conversion_settings = {
    "Format": "png",
    "FilePath": "documents/annual_report.pdf",
    "ConvertOptions": {
        "Width": 800,
        "Height": 600,
        "FromPage": 10,
        "PagesCount": 5
    },
    "OutputPath": "converted/report_images/"
}

Step 4: Putting It All Together

Now, let’s create a complete example with all components:

# Tutorial Code Example: Complete ConversionSettings
conversion_settings = {
    "Format": "pdf",
    "FilePath": "documents/quarterly_report.xlsx",
    "Storage": "WorkDocuments",
    "LoadOptions": {
        "Password": "report2023",
        "ShowGridLines": False,
        "ShowHiddenSheets": False
    },
    "ConvertOptions": {
        "FromPage": 1,
        "PagesCount": 5,
        "Zoom": 100,
        "Grayscale": False,
        "MarginTop": 0.5,
        "MarginBottom": 0.5,
        "MarginLeft": 0.5,
        "MarginRight": 0.5
    },
    "OutputPath": "converted/reports/q3_2023/"
}

Implementation Examples

Let’s see how to use ConversionSettings with the API:

cURL Example

# Tutorial Code Example: Using ConversionSettings with cURL
curl -X POST "https://api.groupdocs.cloud/v2.0/conversion" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Format": "pdf",
    "FilePath": "documents/sample.docx",
    "LoadOptions": {
      "Password": "docx-password"
    },
    "ConvertOptions": {
      "FromPage": 1,
      "PagesCount": 10
    },
    "OutputPath": "converted/"
  }'

Python Example

# Tutorial Code Example: Using ConversionSettings with Python SDK
import groupdocs_conversion_cloud

# Configure the API client
configuration = groupdocs_conversion_cloud.Configuration(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
api_client = groupdocs_conversion_cloud.ApiClient(configuration)
api = groupdocs_conversion_cloud.ConvertApi(api_client)

# Create conversion settings
settings = groupdocs_conversion_cloud.ConvertSettings()
settings.file_path = "documents/sample.docx"
settings.format = "pdf"

# Add load options if needed
load_options = groupdocs_conversion_cloud.DocxLoadOptions()
load_options.password = "docx-password"
settings.load_options = load_options

# Add convert options if needed
convert_options = groupdocs_conversion_cloud.PdfConvertOptions()
convert_options.from_page = 1
convert_options.pages_count = 10
settings.convert_options = convert_options

settings.output_path = "converted/"

# Execute conversion
result = api.convert(settings)
print(f"Document converted successfully! Results: {result}")

C# Example

// Tutorial Code Example: Using ConversionSettings with C# SDK
using GroupDocs.Conversion.Cloud.Sdk;
using GroupDocs.Conversion.Cloud.Sdk.Model;
using GroupDocs.Conversion.Cloud.Sdk.Model.Requests;

// Configure the API client
var configuration = new Configuration 
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET"
};
var apiInstance = new ConvertApi(configuration);

// Create conversion settings
var settings = new ConvertSettings 
{
    FilePath = "documents/sample.docx",
    Format = "pdf",
    LoadOptions = new DocxLoadOptions 
    {
        Password = "docx-password"
    },
    ConvertOptions = new PdfConvertOptions 
    {
        FromPage = 1,
        PagesCount = 10
    },
    OutputPath = "converted/"
};

// Execute conversion
var result = apiInstance.Convert(new ConvertRequest(settings));
Console.WriteLine($"Document converted successfully! Results: {result.Count} files");

Java Example

// Tutorial Code Example: Using ConversionSettings with Java SDK
import com.groupdocs.conversion.cloud.api.ConvertApi;
import com.groupdocs.conversion.cloud.api.model.*;
import com.groupdocs.conversion.cloud.api.model.requests.ConvertRequest;

// Configure the API client
Configuration configuration = new Configuration();
configuration.setClientId("YOUR_CLIENT_ID");
configuration.setClientSecret("YOUR_CLIENT_SECRET");
ConvertApi apiInstance = new ConvertApi(configuration);

// Create conversion settings
ConvertSettings settings = new ConvertSettings();
settings.setFilePath("documents/sample.docx");
settings.setFormat("pdf");

// Add load options if needed
DocxLoadOptions loadOptions = new DocxLoadOptions();
loadOptions.setPassword("docx-password");
settings.setLoadOptions(loadOptions);

// Add convert options if needed
PdfConvertOptions convertOptions = new PdfConvertOptions();
convertOptions.setFromPage(1);
convertOptions.setPagesCount(10);
settings.setConvertOptions(convertOptions);

settings.setOutputPath("converted/");

// Execute conversion
List<StoredConvertedResult> result = apiInstance.convert(new ConvertRequest(settings));
System.out.println("Document converted successfully! Results: " + result.size() + " files");

Troubleshooting Common Issues

Issue 1: File Not Found Errors

If you encounter “File not found” errors, ensure:

The FilePath is correct and the file exists in your storage
You have the correct Storage name if using a non-default storage
The file path follows the correct format (e.g., “folder/file.ext”)

Issue 2: Conversion Fails with Protected Documents

If conversion fails with password-protected documents:

Verify the password is correct
Ensure you’re using the right type of LoadOptions for your document format
Check that the password is provided as a string

Issue 3: Unexpected Conversion Results

If the conversion output is not as expected:

Review the ConvertOptions to ensure they’re appropriate for your target format
Check format-specific documentation for special requirements
Try converting without ConvertOptions first, then add them incrementally

What You’ve Learned

In this tutorial, you’ve learned:

The structure and purpose of ConversionSettings in the GroupDocs.Conversion Cloud API
How to configure basic conversion parameters
Techniques for handling protected documents with LoadOptions
Methods for customizing conversion output with ConvertOptions
Practical implementation in multiple programming languages
Troubleshooting common conversion issues

Further Practice

To reinforce your understanding:

Try converting different document types (PDF, Excel, PowerPoint) with custom settings
Experiment with different target formats and observe how ConvertOptions affect the output
Create a simple application that allows users to specify their own conversion settings
Implement error handling for common conversion issues

Next Steps

Ready to advance your skills? Move on to our next tutorial: Tutorial: Understanding Load Options in Document Conversion to learn more about optimizing the document loading process for different formats.

Helpful Resources

Feedback

Have questions about working with ConversionSettings? Need clarification on any part of this tutorial? We’d love to hear from you! Please visit our support forum with any questions or feedback.