Skip to Content
File integrationsGoogle Docs and Drive

Google Docs and Drive

Choose Import from Google Drive in Documents or Templates. Connect Google if prompted, then select a Google Doc, Word file, or PDF. The page you started from determines whether the import creates a document or template. Manage connected accounts in Settings → Integrations → Google Docs and Drive. Korala prepares a PDF for review before creating the resource. Creating a document leaves it in draft; add signers and fields before sending it.

Choose optional destination collections before preparing the preview. Starting from a collection’s Import from Google Drive action preselects that collection; you can change or clear the selection. Test collections create test resources. Korala checks destinations again when you create the reviewed resource. If a collection was archived during preparation, restore it before retrying publication, or start a new import with another destination.

A Google connection belongs to the user who connected it. Korala requests drive.file access to files selected for or created by the application. Connecting Google does not grant access to your entire Drive or give every API key access to your files.

Documents and templates

For a native Google Doc without variables, a document import uses Google’s PDF export. A template import retains the content of the exported Word file and renders its preview using Korala’s converter. Documents with variables use that same Word conversion after values are supplied. PDF and Word files stored in Drive can also be imported.

Google and Korala can paginate the same source differently. For native Google Docs, Korala suppresses blank parity pages automatically inserted by the Word converter. Tab-title pages and explicit page breaks in Google’s export are preserved. This policy is saved as googleSource.skipEmptyPages (or provenance.skipEmptyPages on an import); existing imports without it retain their original pagination so placed fields do not shift. Reconfirming a template or replacing its Word file retains this saved rendering policy for both the preview and generated documents. Review every page, including tables, images, headers, footers, and content from other tabs. Place signing fields on the final PDF after values have been filled.

Use simple variables such as {{client_name}}. You can include spaces around the name, as in {{ client_name }}. Repeated variables use the same value. Expressions, loops, and literal double braces are not supported in this import workflow. Resolve suggested edits in Google Docs before importing.

Supply a string value for each detected variable when importing a document. An empty string is an explicit blank; omitting a value is an error. Template imports retain variables for later use. Generating from a Google-derived Word template uses the same explicit-value validation and expansion limits; choose Leave blank for intentional blanks. Duplicating a template preserves its Google source history and these validation rules.

This version creates a copy. Editing Google Docs later does not update that copy. Template refresh, automatic synchronization, a Google Docs add-on, and writing signed files back to Drive are separate follow-up work.

API workflow

The connection owner must first connect Google, choose the source file, select the key under Optional partner API access, and click Allow access. The page shows the connection and file IDs needed by the client. Remove access revokes that grant. OAuth connection and grant management require an interactive user session; API keys cannot create connections or grant themselves access.

The TypeScript client exposes the import workflow through client.googleWorkspace:

const operation = await client.googleWorkspace.createImport({
  connectionId,
  fileId,
  target: 'document', // or 'template'
  name: 'Services agreement',
  idempotencyKey: crypto.randomUUID(),
});
 
let current = await client.googleWorkspace.getImport(operation.id);
 
if (current.status === 'awaiting_values') {
  current = await client.googleWorkspace.supplyValues(current.id, {
    values: { client_name: 'Example Company', reference: '' },
  });
}

Poll getImport while the status is queued or processing, using a delay between requests. When it becomes ready, display previewUrl for review. After the user confirms that exact PDF, pass its reviewHash:

const completed = await client.googleWorkspace.publishImport(current.id, {
  reviewHash: current.reviewHash!,
});
// completed.documentId or completed.templateId identifies the created resource.

Wait for the user to review the PDF before publishing an import. The hash binds confirmation to the prepared artifact; a stale hash returns 409. Repeating publication with the same hash returns the existing resource.

Reuse the creation idempotency key only when retrying the same request. Changing the file, target, name, API key, or sandbox mode with that key returns 409.

The public import response includes source provenance, detected variables, status, and the created resource ID. Provenance records the source file and version, fetch time, variable dialect, and SHA-256 hashes of the original Google download, stored source, and reviewed PDF. Word imports rebuild the ZIP container from validated entries; the stored Word file can have different bytes while preserving its XML and media content. Document and template detail responses also expose this metadata as googleSource. These responses omit Google credentials and storage keys.

The import request accepts optional collectionIds (up to 100 distinct collection UUIDs). Omission or [] leaves the resource unassigned. The operation response retains the requested destinations; the created resource’s details show its current memberships. Dashboard requests can supply sandbox; API keys always use their authenticated mode. Destinations must be active and belong to the same organization and mode. Collection assignment and resource creation commit together. Reusing an idempotency key with different destinations returns 409; destination ordering and UUID letter casing do not matter.

Source history and local replacement

Document and template details show the original Google Drive file and import date, with a link to open the source. This is a saved copy: Google edits do not update it automatically, and the source link does not indicate that the Google connection is still authorized.

Replacing an imported template through Replace Template File or client.templates.confirmReplaceFile makes the uploaded file the current source. Existing generated documents stay unchanged. Review the preserved field positions against the new PDF before creating another document.

The template’s googleSource retains the original import metadata and gains an optional locallyReplacedAt timestamp. Its hashes, source name and Google revision describe the original import, not the replacement. Further local replacements retain the first replacement date. Replacement Word files use the regular Word-template variable rules; the import’s saved pagination setting is retained. Duplicated templates preserve this history. The TypeScript client exposes this field on template detail responses.

Retrying confirmation of the current upload returns the same published result. Korala retains the first replacement date and removes abandoned or superseded previews after 24 hours. The current file remains available.

Updating a template from Google under the same template ID is not available yet. Import the revised Google file as a new template until reviewed refresh is released.

Limits and failure handling

Imports accept at most 10 MiB per downloaded artifact, subject to the plan’s lower upload limit. PDFs must be readable, unencrypted, and no longer than 500 pages. Word archives are limited to 5,000 entries and 64 MiB expanded content, with at most 200,000 XML markup tokens before parsing. Sources may contain up to 500 distinct variables, and supplied values may total up to 100,000 characters. Values multiplied by their occurrence counts must stay within 8 MiB of text. Complex source trees and text matching also have memory bounds.

If Google changes the source during export, the import fails with source_changed. Wait for editing to finish and create a new import. export_content_mismatch means the exported Word content did not pass the source-content checks. Neither an unchanged Google version nor a successful content check guarantees visual fidelity.

Disconnecting Google prevents further import work through that connection. Revoking a partner grant prevents that API key from importing the source or publishing pending imports. Copies already created in Korala remain available. Removing the connection owner from the organization removes their Google credentials and stops pending imports; published copies retain their source history.

Last updated on
Adverse mediaOverview and API