Tutorial: Learn to Create or Update Templates in GroupDocs.Parser Cloud

Learning Objectives

In this tutorial, you’ll learn how to create and update document parsing templates using the GroupDocs.Parser Cloud API. By the end, you’ll be able to:

Define custom templates for extracting data from documents
Create templates with fields for specific data points
Add tables to your templates for structured data extraction
Save templates for future use in parsing operations
Update existing templates with new fields or parameters

Estimated completion time: 20-25 minutes

Prerequisites

Before starting this tutorial, make sure you have:

A GroupDocs.Parser Cloud account (if not, register for a free trial)
Your Client ID and Client Secret from the dashboard
Basic understanding of REST API concepts
Familiarity with your preferred programming language (C#, Java, or cURL)
Development environment set up for your chosen SDK

Understanding Templates in Document Parsing

Templates are powerful tools that define patterns for extracting specific data from documents. They’re especially useful when you need to extract data from similarly structured documents like invoices, contracts, or forms.

Why Use Templates?

Templates allow you to:

Extract data from fixed positions in a document
Find data linked to other elements in the document
Define tables for structured data extraction
Process batches of similarly structured documents consistently

Creating Your First Template

Let’s start by creating a simple template that extracts an address and company name from a document.

Step 1: Plan Your Template Structure

First, identify what data you need to extract:

Address - located at a fixed position
Company Name - positioned below the address
Totals Table - containing financial summary data

Step 2: Obtain Authentication Token

Before making any API calls, you need to authenticate with the GroupDocs.Parser Cloud API:

# First get JSON Web Token
curl -v "https://api.groupdocs.cloud/connect/token" \
-X POST \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

Save the JWT token from the response for use in subsequent API calls.

Step 3: Define Template Fields

Now, let’s create a template with fields for the address and company name:

Try it yourself:

Use the following cURL command to create a new template:

curl -v "https://api.groupdocs.cloud/v1.0/parser/template" \
-X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d "{
    \"Template\": {
        \"Fields\": [
            {
                \"FieldName\": \"Address\",
                \"FieldPosition\": {
                    \"FieldPositionType\": \"Fixed\",
                    \"Rectangle\": {
                        \"Position\": {
                            \"X\": 13.0,
                            \"Y\": 35.0
                        },
                        \"Size\": {
                            \"Height\": 10.0,
                            \"Width\": 100.0
                        }
                    },
                    \"MatchCase\": false,
                    \"IsLeftLinked\": false,
                    \"IsRightLinked\": false,
                    \"IsTopLinked\": false,
                    \"IsBottomLinked\": false,
                    \"AutoScale\": false
                }
            },
            {
                \"FieldName\": \"Company\",
                \"FieldPosition\": {
                    \"FieldPositionType\": \"Linked\",
                    \"MatchCase\": false,
                    \"LinkedFieldName\": \"Address\",
                    \"IsLeftLinked\": false,
                    \"IsRightLinked\": false,
                    \"IsTopLinked\": false,
                    \"IsBottomLinked\": true,
                    \"SearchArea\": {
                        \"Height\": 15.0,
                        \"Width\": 100.0
                    },
                    \"AutoScale\": true
                }
            }
        ],
        \"Tables\": [
            {
                \"TableName\": \"Totals\",
                \"DetectorParameters\": {
                    \"Rectangle\": {
                        \"Position\": {
                            \"X\": 300.0,
                            \"Y\": 385.0
                        },
                        \"Size\": {
                            \"Height\": 220.0,
                            \"Width\": 65.0
                        }
                    }
                }
            }
        ]
    },
    \"TemplatePath\": \"templates/my_first_template.json\"
}"

Step 4: Understanding the Template Structure

Let’s break down what each part of the template does:

Fixed Position Field (Address):
- Positioned at coordinates X:13, Y:35
- Covers an area of width 100 and height 10
- Uses absolute positioning on the page
Linked Field (Company):
- Linked to the “Address” field
- Positioned below the address (IsBottomLinked: true)
- Search area of width 100 and height 15
- Will automatically scale based on the size of the linked field
Table (Totals):
- Located within a rectangle at position X:300, Y:385
- Covers an area with width 65 and height 220

SDK Implementation

Let’s implement the same template creation using the SDK of your choice.

C# Example

Java Example

Updating an Existing Template

Now let’s learn how to update an existing template by adding a new field.

Step 5: Add a New Field to Your Template

To update a template, use the same API endpoint but specify the path of the existing template:

curl -v "https://api.groupdocs.cloud/v1.0/parser/template" \
-X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d "{
    \"Template\": {
        \"Fields\": [
            {
                \"FieldName\": \"Address\",
                \"FieldPosition\": {
                    \"FieldPositionType\": \"Fixed\",
                    \"Rectangle\": {
                        \"Position\": {
                            \"X\": 13.0,
                            \"Y\": 35.0
                        },
                        \"Size\": {
                            \"Height\": 10.0,
                            \"Width\": 100.0
                        }
                    },
                    \"MatchCase\": false
                }
            },
            {
                \"FieldName\": \"Company\",
                \"FieldPosition\": {
                    \"FieldPositionType\": \"Linked\",
                    \"MatchCase\": false,
                    \"LinkedFieldName\": \"Address\",
                    \"IsBottomLinked\": true,
                    \"SearchArea\": {
                        \"Height\": 15.0,
                        \"Width\": 100.0
                    },
                    \"AutoScale\": true
                }
            },
            {
                \"FieldName\": \"InvoiceNumber\",
                \"FieldPosition\": {
                    \"FieldPositionType\": \"Regex\",
                    \"Regex\": \"Invoice #(\\\\d+)\",
                    \"MatchCase\": false
                }
            }
        ],
        \"Tables\": [
            {
                \"TableName\": \"Totals\",
                \"DetectorParameters\": {
                    \"Rectangle\": {
                        \"Position\": {
                            \"X\": 300.0,
                            \"Y\": 385.0
                        },
                        \"Size\": {
                            \"Height\": 220.0,
                            \"Width\": 65.0
                        }
                    }
                }
            }
        ]
    },
    \"TemplatePath\": \"templates/my_first_template.json\"
}"

Notice we’ve added an “InvoiceNumber” field that uses a regular expression to find the invoice number.

Troubleshooting Tips

Common Issues and Solutions

Authentication Errors:
- Ensure your Client ID and Client Secret are correct
- Check that your JWT token hasn’t expired
Template Not Saving:
- Verify that the storage path exists
- Ensure all required fields have valid values
Field Not Found During Parsing:
- Double-check coordinates and dimensions
- Try expanding the search area for linked fields
- Test regex patterns separately before using them in templates

What You’ve Learned

In this tutorial, you’ve learned how to:

Create a new document parsing template
Define fixed-position fields for specific data extraction
Create linked fields that relate to other elements
Add tables to your templates
Update existing templates with new fields
Implement template operations using cURL, C#, and Java

Further Practice

To reinforce your learning, try these exercises:

Create a template that extracts data from an invoice PDF
Add a regex field to find dates in various formats
Create a template with multiple tables on different pages
Update an existing template to add search capabilities for email addresses

Next Steps

Now that you know how to create and update templates, continue your learning journey with our next tutorial: How to Retrieve Templates.

Helpful Resources

Have questions about this tutorial? Feel free to ask in our support forum.