All releases

Version c648191044: Word Templates, Page Designer and API v2

This is a big release: we’ve shipped a lot of new features, improvements and fixes since October. The major changes:

  • Word templates: upload a Word document with tags where the values go, and get filled-in Word documents or PDFs.
  • Page Designer: a new kind of template that you design in the template editor, with no document to start from.
  • API v2, with new 4.x API clients, a Rust client and the DocSpring CLI. API v1 keeps working.
  • Signature requests by email: DocSpring can email each signer a link to sign, send reminders, and have signers sign in order.
  • Email actions: email each submission’s PDF to fixed addresses or to addresses from the submission’s data.
  • Web forms have a new design with a dark mode, and can be split into sections that people fill in step by step.
  • A refreshed design for the app, with a sidebar and a dark mode.
  • Data retention settings that delete old data on a schedule. All of them are off until you turn them on.
  • One image with everything: LibreOffice and the AI field detection model are now in the DocSpring Enterprise image, so there’s no separate image variant.

In case you missed it in our last release: DocSpring can now detect the form fields on a PDF using AI. Upload a flat or scanned PDF, and AI field setup finds its fields, names them and sets their types. AI field detection explains how to turn it on.

Some of these changes need a setting or a change to your pages when you upgrade, so please read the upgrade notes first. The full list of changes follows.

Upgrade notes

  • Data retention: nothing new is deleted until you turn it on. This release can delete old data on a schedule: test submissions after 30 days, templates 30 days after they go to Trash, removed users after 30 days, account export files after 6 months, audit and sign-in history after 3 years, deleted accounts after 14 days, and a signed document’s signing data when it expires. Each has its own environment variable, all off by default: DOCSPRING_TEST_SUBMISSION_EXPIRY_ENABLED, DOCSPRING_TEMPLATE_TRASH_PURGE_ENABLED, DOCSPRING_REMOVED_USER_PURGE_ENABLED, DOCSPRING_EXPORT_ARCHIVE_EXPIRY_ENABLED, DOCSPRING_SECURITY_HISTORY_RETENTION_ENABLED, DOCSPRING_REQUESTED_ACCOUNT_PURGES_ENABLED, DOCSPRING_ACCOUNT_DELETION_NOTICES_ENABLED, DOCSPRING_ACCOUNT_PURGES_ENABLED, DOCSPRING_SIGNING_RECORD_BACKFILL_ENABLED and DOCSPRING_SIGNING_RECORD_PURGE_ENABLED. They also need a new scheduled job that runs rake timers:data_retention once a day. Without the job and the settings, your installation keeps all of this data as before. Data Retention has the job, each setting and the order to turn them on.
  • A submission that expires now also loses the details that expiry used to keep: its metadata, the submitter’s IP address and location, and the copies of its data in audit rows. Submissions that expired before the upgrade keep them until you run rake submissions:clear_expired_data (a count, then again with APPLY=true).
  • Signing events can no longer be changed or deleted, by a trigger on submission_data_request_events. A signed document that expires keeps its audit trail, signature images and signature requests, as before, until you turn on DOCSPRING_SIGNING_RECORD_PURGE_ENABLED.
  • A signed document now becomes processed a moment after its PDF is ready, once a background job has written the record of its hashes to your database. If that job is lost, your nightly scheduled job (the one that runs rake submissions:enqueue_expiry_jobs or rake submissions:expire_overdue_submissions) finishes the signing, so keep it scheduled.
  • Sidekiq’s dead job set now keeps jobs for 60 days.
  • One image with everything. The DocSpring Enterprise image now includes LibreOffice (PDFs from Word templates) and the AI field detection model, as well as Chromium (HTML templates). It’s about 0.8 GB larger on disk. The -ai-field-detection image tags are no longer published: if you use one, switch to the plain tag (<version> or latest) and set DOCSPRING_AI_FIELD_DETECTION_ENABLED=true.
  • AI field detection stays off until you set DOCSPRING_AI_FIELD_DETECTION_ENABLED=true, because it needs about 1 GB of free worker memory (AI field detection). It now detects one page at a time in each worker container, so that’s all it needs, whatever DOCSPRING_AI_FIELD_SETUP_CONCURRENCY is. When a worker’s container has less free under its memory limit, the page fails without starting detection, the template editor says the server ran short of memory, and the worker’s other jobs carry on.
  • The worker no longer needs to run privileged. Run every DocSpring container with all capabilities dropped and NET_ADMIN, SETUID and SETGID added back: the image uses NET_ADMIN to block the cloud metadata address before it starts the app as the deploy user. With Docker, that’s cap_drop: [ALL] and cap_add with those three; on Kubernetes, the same under the container’s securityContext.
  • Our API clients (SDKs) call API v2 from version 4.0.0, so keep the 3.x clients until you’ve upgraded to this release.
  • Every text and JSON value now has a maximum size: 512 characters for most names, 5,000 for descriptions and other text people write, 64 KB for most JSON, and 50 keys nested at most 5 levels deep for metadata. Saving a value over its limit returns a validation error (a 422 from the API) instead of storing it. The limits are listed in Size limits.
  • Error messages are now at most 2,000 characters, and webhook and API logs keep the first 10,000 characters of each request and response body (1,000 of a webhook’s response), with base64 data left out. When a submission or a combined PDF expires or is deleted, the bodies of its webhook and API logs are cleared too, and for a submission also those of its signature requests and its batch.
  • The database migration also adds a much higher limit to each column in the database itself. It reads each table once to check the rows you already have, which can take a while on a large database. If a row is already over a column’s limit, the migration cuts error messages, log bodies and other recorded text down to the limit; for other columns it leaves that column’s database limit out and prints the table, column and number of rows. Existing records keep saving either way.
  • Migrations add indexes to the submissions, templates and combined submissions tables. They build without locking the tables, but on a database with millions of submissions, expect rake db:migrate to take several minutes.
  • PDF passwords (the password a template encrypts its PDFs with, and the default for new templates on the Template defaults page) are now stored encrypted. The migration encrypts the existing ones; once every DocSpring process runs the new release, run rake plaintext_credentials:scrub once to remove the old unencrypted copies.
  • HTML templates’ margins and Custom page sizes need a unit (in, cm, mm or px, such as 20mm) when they’re set or changed. A value that’s already saved prints as before (a number without a unit is in pixels), and one with a unit the PDF engine didn’t read, such as pt, now prints the 1in default margin or the 8.5in x 11in page instead of failing the PDF.
  • HTML templates’ page settings are checked when they’re set or changed: the page format must be one the PDF engine knows, a Custom page’s width and height must be from 0.05in to 200in, and the left and right margins together must be less than the page’s width (the top and bottom ones less than its height). A template saved with other settings keeps them. If Chrome can’t print them, its PDFs fail with a message that says to check the page settings, and aren’t retried.
  • Two new optional settings for installs on AWS: DOCSPRING_DOCUMENT_TOOLS_LAMBDA_FUNCTION runs the PDF and image tools on a Lambda function, and DOCSPRING_OUTBOUND_HTTP_LAMBDA_FUNCTION sends webhooks, Slack messages and downloads from customer URLs from one. Without them, nothing changes: the workers run the tools and send the requests, as before.
  • When DOCSPRING_CSP_REPORT_URI is a URL, browsers now send Content Security Policy reports to your install’s own /csp_reports, and a background job forwards each one to that URL, leaving out reports caused by browser extensions. The reports now come from your servers’ IP addresses instead of the browsers’.
  • DocSpring now refuses a form or request whose Origin header names another host, even with a valid CSRF token. If forms, sign-in (including Google, GitHub and OpenID) or signing out fail behind a proxy that changes the Host header, and the log says “HTTP Origin header (…) didn’t match request.base_url (…)”, fix the proxy, or set the new DOCSPRING_DISABLE_CSRF_ORIGIN_CHECK=true to turn the check off.
  • An API token sent with HTTP Basic auth no longer signs in to the app’s web pages or the sign-in form. It still works for API requests and the permanent links to files (permanent_download_url, permanent_document_url and API v2’s links to PDFs and page images).
  • Check mark and shape conditions written as regular expressions now use RE2 syntax, which has no lookarounds or backreferences, and match in a time proportional to the value, so a pattern can no longer slow down or stop PDFs. The migration rewrites each regex condition that starts with a negative lookahead (^(?!...)) as one of the new condition types that say the same thing: Doesn’t equal, Doesn’t contain, Doesn’t start with, Doesn’t match regex or Isn’t blank. It logs the ID of any template with a lookaround it couldn’t rewrite; such a condition never matches until someone changes it. RE2 also refuses \Z, and a few features aren’t supported because visual forms would match them differently from the PDF: Unicode classes like \pL, \B, \C and very large repeats (Conditions lists them). A saved condition that uses one, or one sent in a submission’s API v1 field_overrides, also never matches, and the template editor shows what to change under it. The editor and the API refuse a new regex condition that breaks these rules.
  • A few regex conditions that RE2 accepts now match differently: \b and [[:alpha:]] only know ASCII letters (\bsí\b no longer matches “sí”), \s doesn’t match a vertical tab, (?i) doesn’t match ß with SS, (?m) no longer lets . match a line break (use (?s)), a{,3} matches its literal text, && in a class is two & characters, and ^$ matches a value that ends with a line break.
  • Invitations to join an account now expire after 7 days, so invitations sent more than a week before the upgrade stop working. Team > Pending invitations shows when each one expires and has a Resend invitation action that sends a new link. Someone with an expired invitation can still join with Forgot password on the sign-in page.
  • The Datadog request tracing is removed, with its settings DOCSPRING_ENABLE_DATADOG and DD_TRACE_AGENT_PORT. Remove them from your config: DocSpring logs a warning at startup for a DOCSPRING_ setting it doesn’t know.
  • A visual form embedded on your own site now loads only on the sites in its template’s Embed Domains setting, unless the setting is blank, and reads each entry the way the embedded template editor does. Pages that load /assets/embed/visual_form.js get the check with this upgrade, so before you upgrade, add those sites to any template whose Embed Domains lists only the sites where you embed the template editor or signature requests.
  • Embedded web forms use Web Forms JS 3.0. If your pages load /assets/embed/simple_form.js, load /assets/embed/web_form.js and /assets/embed/web_form.css instead, and call DocSpring.createWebForm where they called DocSpring.createSimpleForm. simple_form.js and simple_form.css are no longer in the image. The Web Forms JS changelog lists the other changes. The hosted web form needs no changes: it loads the new web form from your install, not from cdn.docspring.com.
  • With a container memory limit (cgroup v2) and WEB_CONCURRENCY of 2 or more, the web service restarts one worker process at a time when the container’s memory passes 80% of its limit or a worker has run for 12 to 14 hours (by default). The worker finishes its requests first while the others carry on.
  • New settings for those restarts: DOCSPRING_PUMA_WORKER_MEMORY_RESTART_PERCENT (default 80) and DOCSPRING_PUMA_WORKER_MAX_AGE_MINUTES (default 720), where 0 turns that restart off.
  • An idle web worker runs a full garbage collection once its memory has grown by DOCSPRING_PUMA_IDLE_GC_MIB (default 64), so it doesn’t keep the memory of large requests while it waits.
  • Web requests now stop after REQUEST_TIMEOUT seconds with a 503 error, and the web worker that ran the request restarts once its other requests are done (with two or more workers, one at a time). Earlier releases documented REQUEST_TIMEOUT but never applied it. Enterprise installs get at least 210 seconds, so the Admin API’s synchronous imports and exports, which wait up to 3 minutes, aren’t cut off, and with DOCSPRING_SYNCHRONOUS_API on, at least DOCSPRING_SYNCHRONOUS_TIMEOUT_LIMIT plus 30 seconds, so a request waiting for its PDF isn’t either. If people on your install use pages that take longer, raise REQUEST_TIMEOUT. With WEB_CONCURRENCY of 0, a timeout stops the web server, so run it with a restart policy.
  • A web worker that’s stopping gets the request timeout plus 5 seconds to finish its requests (at least 30 seconds), so a request waiting for its PDF is no longer cut off when a worker restarts.
  • New setting DOCSPRING_PUMA_READINESS_PORT: a second port on which the web server answers readiness checks while its workers are running, even when every request thread is busy. Point your load balancer’s or orchestrator’s readiness check at it, so a busy web server isn’t taken out of service. It needs worker processes (WEB_CONCURRENCY of 1 or more).
  • The dashboard’s charts and totals read hourly counts that older releases didn’t keep, so a period from before your install kept them can show too few PDFs, and the dashboard now says so. To fill in the history, run rake submissions:backfill_hourly_stats when it suits you (it never runs by itself): it covers 3 years, or set YEARS or START_DATE=YYYY-MM-DD, prints its progress, and can be stopped and carried on with START_ACCOUNT_ID.
  • Hourly counts now start on UTC hours. Older releases started them on the hour in the user’s or the server’s time zone, so if anyone on your install uses a time zone that isn’t a whole number of hours off UTC, such as India’s or Nepal’s, run rake submissions:backfill_hourly_stats at least two hours after upgrading to correct the counts.
  • A time zone the in_time_zone Liquid filter doesn’t recognize now fails the document with an error that names it, instead of showing the time in another time zone. A blank time zone keeps the template’s own, and the filter also takes the names on the account settings page, such as Eastern Time (US & Canada).
  • Visual forms and signing pages show Continue sooner, for every template. They show Continue next to Next as soon as every required field is filled in, and I Agree lists the optional fields the signer skipped, with a link back to them. Next still goes through every field. This is a new template setting, Show Continue once required fields are filled in (continue_before_optional_fields in the API), and it’s on for every template after the upgrade, whatever the template had before: the hosted visual form, the signing page and pages that load /assets/embed/visual_form.js from your install all get the new flow. To keep Continue in place of Next until every field has a value or has been visited, turn the setting off for a template (or in your account’s template defaults), or pass allowSkippingOptionalFields: false to Visual Forms JS or Signature Requests JS. The older setting that the editor showed as Allow skipping optional fields (allow_skipping_optional_fields) is no longer read by these forms or shown in the editor; only pages pinned to Visual Forms JS 2.16.0 to 2.23.0 on cdn.docspring.com read it.
  • Forms refuse some values they took before. A date typed into a web form needs all four digits of its year (02.28.20 is no longer read as 2020). Text too long for its box on the PDF can’t be submitted (below). A Number field printed in comb fields with a digit that no box prints fails the submission (Bug fixes).
  • Gravatar is now off by default, so people’s browsers no longer load avatars from secure.gravatar.com. People without a profile photo show their initials instead. To keep showing Gravatars, set DOCSPRING_GRAVATAR_ENABLED=true.
  • Templates saved long ago still hold an old copy of their compiled HTML in a column that nothing reads, as much as tens of megabytes on a large HTML template. rake templates:clear_compiled_html counts those rows, and with APPLY=true empties the column. It’s optional, and can run at any time. With very large HTML templates, give it a smaller BATCH_SIZE (the default is 500 rows).

New features and improvements

  • Deleted templates now go to Trash, on the Templates page, where they can be restored. They stay there until you turn on DOCSPRING_TEMPLATE_TRASH_PURGE_ENABLED, which removes them after 30 days and shows that date on the page.
  • Delete Account now suspends the account and rejects its API requests, and a sign-in by any of its users cancels the deletion. The account’s data stays until you delete the account from the admin dashboard, and the dialog and its email say so. With DOCSPRING_REQUESTED_ACCOUNT_PURGES_ENABLED and DOCSPRING_SIGNING_RECORD_PURGE_ENABLED on, the data is deleted 14 days later, and they give that date instead.
  • Emails with a download link now say how long the link works, using your retention settings.
  • The AWS S3 integration’s role-based authentication no longer needs an access key. When DOCSPRING_AWS_S3_ROLE_ACCESS_KEY_ID and DOCSPRING_AWS_ACCESS_KEY_ID (and their secrets) are all unset, DocSpring assumes each integration’s role with the AWS SDK’s default credentials: an instance role, an EKS Pod Identity or IAM Roles for Service Accounts. Give that identity sts:AssumeRole on the roles, and name it in their trust policies.
  • The submissions lists load faster on accounts with many submissions, and the API logs, webhook logs and combined PDFs lists show Previous and Next instead of a page count once they pass 1,000 rows.
  • A request cancelled by a database statement timeout now says it took too long, with a 503, instead of a 500 page. Each statement that takes a second or more is logged as a slow_query line, with its SQL but none of its values.
  • API v2, at /api/v2: strict request checks with one error format, consistent resources, and new endpoints to check a submission without creating it, make images of a template’s or a submission’s pages, create a template from a URL and see what changed in a template’s draft. API v1 keeps working, and Migrating to API v2 lists every difference.
  • The template editor warns when a template has a signature or initials field and its PDF is the official edition of a form whose agency won’t accept signature fields: nine USCIS forms (I-130, I-485, I-131, I-765, I-90, N-400, I-864, G-28 and I-751), the U.S. passport application (DS-11) and two of IRCC’s barcoded forms (IMM 1294 and IMM 5710). The warning says what the agency accepts instead and links to its rule.
  • Conditional logic now runs on one rule engine in web forms, visual forms, signature requests, PDFs and API validation, so a rule shows, hides and requires the same fields everywhere (Conditional logic).
  • Word templates: upload a Word document (.docx) with tags such as {{ customer.name }} where the values go, and each submission makes a filled-in Word document. Tags can show or hide text, repeat table rows and add pictures, signatures and barcodes, and the template editor edits the document and suggests tags from its fields. A template can make Word documents, PDFs and OpenDocument files, and takes .odt uploads too: the image includes LibreOffice, which converts them in your workers (Word templates).
  • The AWS S3, Google Drive, Dropbox and Box integrations have a File Formats setting: Word documents, OpenDocument files, PDFs, or all of them, with a new {{ extension }} variable for the file paths. New integrations upload all of them. Integrations you already have upload PDFs only, so their paths ending in .pdf stay right, until you add {{ extension }} to their paths and change the setting.
  • Page Designer: a new kind of template, designed in the template editor with no document to start from. Place text with your data’s values, tables and repeating sections, images, charts, QR codes, barcodes, form fields and HTML boxes on the page, with headers, footers and page numbers. API v2 creates and updates page designs from their layout, a JSON document with a published schema (Page Designer).
  • A refreshed design: a sidebar replaces the bar across the top of the app, with new type, colors and icons in light and dark mode. Every page keeps its address. See Design Refresh.
  • Email actions email each processed submission’s PDF, or a Word template’s Word document and OpenDocument file, attached or as a download link, to fixed addresses and to addresses from the submission’s fields or metadata, with your own subject, message and file name. Each one sends for every submission, or only for the submissions that meet its conditions. Add one for a template on the Emails tab of its settings, or for every template (or the templates and folders you choose) on the Email card of the Integrations page. A template can turn an account’s email action off for itself, or change its settings, on its Emails tab. On your install they go through the email service DocSpring already sends its emails with, from any address it accepts, so there’s nothing to set up and no Email domains page. API v2 has endpoints for them (Email Actions).
  • The dashboard starts with the live submissions that failed in the last 7 days, grouped by template and error, with the action that fixes each, then your three most recently edited templates.
  • The template editor has its own top bar with the template’s name, version and save state, and links to its submissions, versions, forms and settings. The template settings are in tabs, and so are the sections of the Account and Your profile pages. Template defaults uses the same tabs as the template settings.
  • Lists filter by several states at once, and the template and source filters search as you type.
  • Webhook delivery logs show each response as a status, such as “200 OK” or “Timed out”.
  • Data retention for the account. The Account page’s new Data retention tab has three expiry settings: one for submissions without signature requests, one for signed documents (submissions with signature requests) and one for PDFs combined with PDF tools. They replace the expiry settings on the Template defaults page: new templates follow the account’s settings, and a template sets its own expiry only when someone turns on Override the account’s expiry settings in its settings. Templates that already expire their submissions keep doing so. All three account settings start off, so nothing is deleted until you turn one on. An account whose Template defaults expired new templates’ submissions gets that length as its submissions and signed documents settings instead, so its new templates expire as they did. Changing an expiry setting, the account’s or a template’s, now applies to what’s already stored: turning it on or shortening it deletes the older submissions and combined PDFs 24 hours after we email the account’s owner and whoever made the change (Template Settings). In the admin interface and the admin API (POST /admin/accounts.json, PATCH /admin/accounts/<account_id>.json), set an account’s expiry with expire_submissions, expire_after and expiration_interval, expire_signed_submissions, signed_expire_after and signed_expiration_interval, and expire_pdf_tools, pdf_tools_expire_after and pdf_tools_expiration_interval. Expiry sent in default_template_settings, as before, sets the first two settings.
  • Update templates, on the Template defaults page, lets you choose which of your saved defaults to copy to existing templates, by tab or one setting at a time. It runs in the background and shows its progress, saves each template the same way the editor does (so template webhooks fire and the change is recorded as yours), and lists any template it couldn’t update, with the reason, instead of skipping the checks.
  • Connect apps with OAuth. Apps can ask your users to connect them to DocSpring, then call API v2 with an OAuth access token and only the access the user approved, instead of an API token. Users see and disconnect their connected apps on the Integrations page (OAuth guide).
  • Preview a template with data: POST /api/v2/templates/{template_id}/previews fills an HTML or PDF template’s draft (or a published version) with the data you send and returns PNG images of its pages, not a PDF, without a submission. Previews are watermarked like test PDFs.
  • The in_time_zone Liquid filter reads times in the account’s time zone in templates created after this release. Existing templates keep using the server’s (DOCSPRING_TIMEZONE), so their PDFs don’t change.
  • The Difference date formats count calendar years and months, so Difference: Years gives the right age on and around a birthday, and a PDF made near an anniversary can print a different number than before. They count today in the template’s time zone: the account’s, or the server’s (DOCSPRING_TIMEZONE) for templates that keep it.
  • Every API v2 request that changes something (each POST, PUT and DELETE) takes an Idempotency-Key header. Sending the same request again with the same key within 24 hours returns the first response instead of running it again, so an integration can safely retry a request that timed out. The task that deletes expired API logs, rake api_logs:delete_expired, also deletes expired keys.
  • HTML templates can escape the data they print. With the new Escape HTML in Data setting, {{ value }} prints a value as text and {{ value | raw }} prints it as HTML. New templates have it on. Existing templates, and those created with API v1 or imported from an older release, have it off and render as before (HTML escaping).
  • The PDF and image tools (PDFBox, qpdf, pdftk, ImageMagick and librsvg) now run in a separate worker process with a time limit, and each one uses a single CPU core, so one large document can’t slow down the rest of the server.
  • Password-protected PDFs are now encrypted with AES-256 instead of AES-128, with the same permissions.
  • A published template version now keeps only what decides its PDFs and forms: the PDF or HTML, the fields, the field defaults, the name and description, and a few settings such as merging the audit trail (Template versions). Its other settings (online form, privacy, redirect URL, expiry, PDF encryption, webhook and Slack URLs, embed domains, locking) come from the template’s draft, and the upgrade copies each draft’s settings to its published versions.
  • A Rust API client for API v2: the docspring crate on crates.io (Install an API client). The template editor’s Code button and the API’s model code endpoint also write Rust structs for a template’s data (Generate Model Code).
  • The DocSpring CLI: a docspring command for your users’ terminals, scripts and CI jobs, with a command for each API v2 operation. docspring login --host <your install's host> logs in with the browser (DocSpring CLI).
  • A signature request sent from a template’s draft now keeps the template as it was sent: editing the draft no longer changes what the signers see or their signed PDF. The submission page opens the template as sent, read-only (Template versions).
  • New condition types for check marks and shapes: Doesn’t equal, Doesn’t contain, Doesn’t start with, Doesn’t end with, Doesn’t match regex, Is blank and Isn’t blank. The Regex condition is now called Matches regex (Conditions).
  • Redesigned two-factor authentication pages: the sign-in step (with a code or a recovery code), enabling it, the recovery codes (now with Copy and Download) and the Two-factor authentication card on Your profile > Security.
  • The HTML template editor highlights Liquid tags, suggests field names after {{ and {%, and lists problems with the Liquid above the code with their line numbers. Click a {{ }} tag to change what it prints. Saving code that uses a new value adds a field for it, and renaming a field renames its tags in the code. The editor now uses CodeMirror instead of a 2017 build of Ace, so newer CSS no longer shows as errors.
  • New HTML templates start as an empty HTML document, without the example code and fields. So do templates created through the API without html, scss or fields.
  • Liquid works anywhere in an HTML template’s SCSS: it runs before the SCSS compiles, so a value can set a variable or a property, and an {% if %} can add rules. SCSS that compiled before still compiles.
  • DocSpring’s own emails (confirmations, password resets, invitations and failure alerts) have a new design, with the DocSpring logo attached to each email, so it shows without loading anything from your server. They now come with a plain text version written for each one, and the footer names your DocSpring server instead of DocSpring’s support address. The welcome email now goes out when someone who signed up confirms their email address, from your server’s sender address.
  • Signature requests can email their signers. With API v2, DocSpring emails each signer a link to sign, reminders if you ask for them, and the signed PDF once everyone has signed, through the email service your install already sends with. Signers can sign in order, and a template’s Emails tab sets the sender name, From and reply-to addresses, who hears about completed and declined documents, a signing page on your own site, and whether the signed PDF is attached. An email action that sends the signed PDF to one of those people replaces DocSpring’s email to them. Set send_email: false when your app sends the links itself, or when your install doesn’t send email. API v1 never emails signers (Emails from DocSpring).
  • The signing page, the signature request emails and the audit trail certificate show your account’s logo, and the signing page and emails use its brand color for their buttons. Set them on the Account page.
  • Web form sections: the template editor’s Sections button splits a template’s web form into steps, each with a title and a description, in the order you set. Visitors can open any step, and Next shows a step’s errors before they move on; the template’s Fill out sections in order setting keeps later steps locked until they reach them with Next. With AI field naming turned on (DOCSPRING_AI_FIELD_NAMING_PROVIDER), Suggest sections asks AI to group the fields. The web form has a new design, with a dark mode, and pages can restyle it with CSS custom properties (Web Forms JS). The embedded template editor’s showFormSections option hides the Sections button. Once it’s submitted, the web form shows a success screen with the title and message from the template’s Forms settings, a Download PDF button and a Fill out again button. The title, the message and the redirect URL can show what the person submitted, with variables such as {{ data.first_name }}. Image fields take a file (chosen, dropped or pasted, and resized in the browser) or a web address, and show the image.
  • AI field setup leaves out the fields that only the office, agency or court receiving a form fills in, such as a “For office use only” box or a received stamp. To keep them, turn on Include office-use fields on the Template defaults page, in Set Up Fields or on the upload page, or send include_office_use_fields: true when you create a template with the API.
  • The Preview button in the template editor’s toolbar shows a template’s preview beside the template while you edit it, and updates it after each save. Drag the divider between them to change the preview’s width; the browser remembers both.
  • PDF templates have a Preview tab in the template editor: the PDF filled with sample data, the way a submission would fill it, with no watermark and no submission. Your workers make it when someone opens the tab or shows the preview side by side after a change, not on every save.
  • Comb fields in visual forms: visual forms and the signing page show a comb field as one box per character. Typing moves from box to box across the comb fields that share a name, and every copy of the value updates as you type. A date split into month, day and year boxes is typed across them. Comb fields have three new options for the whole value: Print digits only (only the value’s digits print, so 123-45-6789 fills an SSN’s 9 boxes), Fill from the right (for amounts) and Pad with zeros. AI field setup sets them, and the template editor warns when the offsets of comb fields that share a name leave a gap or overlap.
  • Dollars and cents: a Number field can print only the part of its number before the decimal point, or only the part after it (the new Format option, number_part in API v2). An amount printed as $ ____ . __ is one number with a field for the dollars and a field for the cents, in comb boxes or ordinary ones, where it took two field names before. Forms show each field its part and save one number, and AI field setup sets amounts up this way (SSN and comb fields).
  • Text too long for its box: web forms, visual forms and the signing page say when what’s typed won’t fit in its box on the PDF, and how many characters to take out, measured in the font, size and box the PDF prints it in, and can’t be submitted until it fits. The browser fetches the fonts’ widths from your install (/text_fit_fonts/<font>.json). Text the form starts with (defaults, prefilled data, a signature request’s data from the API) isn’t checked, and submissions from the API shrink and cut off text that doesn’t fit, as before. Visual forms and the signing page also show a text field’s text at the size the PDF prints it, shrinking it to fit as it’s typed.
  • A hosted form that shows both forms in tabs (?mode=dual) follows the visitor’s light or dark theme, as hosted web forms do. It was always light. The PDF tab’s visual form stays light, on its own white card.
  • A date field’s calendar in visual forms and on the signing page opens where there’s room for it: above a field near the bottom of the form, and lined up with the field’s right edge near the form’s right edge, instead of running off the form.
  • Option labels: each of a text field’s options can have a label, which web forms, visual forms and the signing page show in place of the option (Married filing jointly for married_filing_jointly), while the submission’s data, the API and webhooks keep the option. The PDF prints the option, or the label with the new Print labels on the PDF setting. Set them under Option labels in the template editor, or with API v2’s option_labels; the template’s JSON schema lists them as x-option-labels. Options without labels that are all lowercase words joined by underscores show in sentence case (Head of household for head_of_household). AI field setup gives the options it sets up readable labels (Field Options).
  • People can upload their own profile photo from their profile page, and drag and zoom it to choose the part that shows. It appears beside their name across DocSpring, such as on the team page, API tokens and template versions. People who sign in with Google, GitHub or your OpenID Connect provider can import that account’s photo from the same page, and a new user who signs up with one gets its photo to start with. Your server downloads the photo once and serves its own copy, so browsers don’t load it from the provider. Microsoft Entra ID gives out its photos only with each person’s sign-in token, so people who sign in with it upload their photo instead.

Bug fixes

  • The template editor, the forms and the signing pages keep working while the browser translates the page (Chrome’s Translate, for example), and field names, templates’ contents and the values the forms show stay as written.
  • With a license that doesn’t load (missing, malformed or with an invalid signature), the worker now starts and reports the license error as the web server does. It used to crash at startup with an unrelated error.
  • Making a PDF from an HTML template no longer restarts the worker. Chromium leaves helper processes behind when it finishes, and foreman, which runs each service, stopped the service when one of them exited, so the worker’s container started again after a render. The image now starts its services under tini, which cleans those processes up. Your services’ commands don’t need to change: run_as_deploy does it.
  • A submission that had a PDF preview generated for it now sends its submission.processed webhook when its final PDF is ready. The webhook was skipped for those submissions.
  • A large request no longer takes gigabytes of memory for a moment when the account logs API request data, and a large webhook payload no longer does in the worker. An 11 MB base64 value took about 2 GB, which could get a web process killed and its requests answered with a 502.
  • A large report to /signature_request_error_logs no longer takes gigabytes of memory for a moment. Anyone can post to that path without signing in, so it could get a web process killed in the same way. Only its first 65,536 characters are read.
  • Combining PDFs (with or without a password) or extracting pages now removes digital signatures that came along from an input PDF, and draws them onto the page so they still show. Those files have been rewritten, so the signature no longer matches, and Acrobat showed the new PDF as invalid.
  • submission.expired and combined_submission.expired webhooks now arrive for records with a stored file. They weren’t being sent, so expect them from this release if you subscribe to them.
  • A combined PDF’s expires_in of zero or less now reads as null: it never meant anything.
  • A signing link with an unknown signature request ID now answers submission_expired with a 410, the same as a deleted document, instead of not_found.
  • API v1 no longer finds submissions deleted when an account was reset: getting, expiring, downloading or previewing one is a 404, and a combined PDF can’t include one. The submissions list’s next_cursor no longer names one, which made the next page list submissions again.
  • An HTML template’s scale must be between 0.1 and 2 when it’s set to a number, the scales Chrome prints at. A scale outside them was saved, and every PDF from the template then failed. A scale that isn’t a number still prints at 1, and a template that already has one outside them keeps saving.
  • The template editor’s single-key shortcuts now follow the embedded editor’s options, so in the embedded editor H and S can no longer hide a field or make it static with no way to undo it.
  • The two-factor sign-in form no longer submits the same code twice when automatic and manual submission overlap.
  • A template created or updated through the API from a presigned upload now records its own PDF’s MD5. It used to keep the md5_hash the request sent, and the API reference’s code samples sent the MD5 of one of our test files.
  • Template PDFs and custom files over 100 MB are refused before they’re stored: the presigned upload’s policy and the template upload endpoint now set the limit. A template’s PDF size is read from the uploaded file rather than from the request, and a presigned upload ID with no file behind it is a validation error (a 422 from the API) instead of a 500.
  • API validation now reads a field’s default when the request leaves the field out, as the PDF does, so it requires the fields that a rule shows.
  • A field that a rule hides is now blank in the PDF, even when it has a default, and combined fields that use it leave it out.
  • {% template_image_url %} now finds an image by the ID the Images tab shows, so images without a name work too.
  • A barcode field with no barcode type set in an HTML template prints Code 128 for values that aren’t 12 digits, instead of failing the PDF. 12-digit values still print EAN-13, as before.
  • Signing in for the first time with Google, GitHub or OpenID Connect no longer fails when the provider’s name for the person can’t be a DocSpring name, such as an email address or a URL: the user is created without a name and can add one later.
  • Rule edge cases now work the same in forms and PDFs. A rule whose condition field doesn’t exist is ignored. A rule with a target that doesn’t exist still applies to its other targets. Number conditions read only decimal numbers, so 0x10 isn’t 16.
  • The Preview tab of the HTML and Word template editors no longer flashes white every second while a preview renders. The last preview stays on screen, and the new one replaces it once it’s ready.
  • Reloading the embedded template editor opens the editor again, instead of saying the link isn’t valid.
  • The embedded template editor’s settings no longer offer Delete template, which it can’t do. In the app, Delete template asks in a dialog, then goes to the template’s folder.
  • Templates’ webhook, Slack and redirect URLs can’t point at your DocSpring install in the editor and the API either, as on the Template defaults page. Templates saved before keep their URLs until someone changes them.
  • Embedded signature requests, the embedded template editor, embedded visual forms and embedded web forms now work on a page whose Content-Security-Policy doesn’t allow inline styles (no 'unsafe-inline' in style-src) (Content Security Policy).
  • Flattening a template’s form now clears a field whose name has two spaces in a row. It used to keep the field’s default value, so a checkbox that was ticked by default stayed ticked.
  • A PDF now keeps its fields when it’s uploaded with a checkbox or radio button that has only an Off appearance. It used to upload with none of its fields. A PDF that stores a form field’s type or other values as separate objects can be uploaded now too: its upload used to fail.
  • Forget all trusted browsers now makes every trusted browser ask for a code again, not only the one you’re using.
  • Some malformed form fields no longer stop a PDF from uploading or cost it its other fields. A field with no usable position on the page is left out, a radio button its group doesn’t list is kept and imported with the others, and a name or value written as a PDF name with accented characters is kept as text.
  • A submission or combined PDF that an invalid license stopped now keeps its data when something saves it again, as its message says, where it used to get an expiry date. Once the license is valid, the submission’s menus offer Reprocess, which makes a new submission from that data, and once that has made its PDF, the stopped submission expires as its template’s settings say.
  • Web forms: a currency field shows its default value instead of NaN and takes negative amounts, fields whose names contain &, > or \ are no longer left out, and a group whose fields a rule hides no longer leaves an empty box with its title.
  • Embed Domains entries are saved without a path or a trailing slash (https://app.example.com/forms/ is saved as https://app.example.com), which nothing ever used, so a template’s embed domains can be sent back to API v2 as they came. The database migration rewrites the saved ones, for templates and the Template defaults page. The embedded template editor matches entries the way signature requests do: a wildcard like *.example.com:8443 with a port now works, and an entry like *.com no longer allows every site. A test signature request opened by Data Requests JS 2.x now loads on any site, as it does with Signature Requests JS 3.0.0.
  • An invitation that expired no longer keeps its email address from being invited to another account, or from signing up with Google or GitHub: the expired invitation is removed.
  • The embedded template editor’s welcome dialog no longer waits forever on an HTML template. It said “Processing PDF…” with Get started turned off, because an HTML template has no uploaded document to process.
  • API logs now include requests that end in an error, such as a failed save’s 422, a 404 or a 500, each with the response the client got.
  • Creating a template with API v1 now keeps a setting the request sends even when it equals the setting’s built-in default, such as public_submissions: false. The Template defaults page’s value used to replace it.
  • An account with signed download links turned off no longer gets them in API v1’s preview_download_url for a submission or download_url for a combined submission, in API responses and webhooks. Authenticated downloads still work.
  • On a phone, a visual form’s header no longer covers the page above the form: it’s fixed to the top of the screen only when the form starts at the top of the page, and otherwise stays with the form as the page scrolls.
  • A Number field split across comb fields prints each field’s own digits, where every field printed the whole number, and the comb fields of a static value print their own characters instead of the whole value. A number with a digit that no comb box prints (more digits than the boxes, or a gap in the fields’ offsets) fails the submission with a message that names the field, where the PDF printed only the digits that fit. API v2 and forms refuse it when the submission is created, and an API v1 submission fails when its PDF is generated.
  • Visual form fixes that changed what a form saved: a Number field saved 25.00 as 250 and 1.05 as 15; a required yes/no question printed as two check marks answered yes when its “no” box was clicked; a date edited in place in a day-first template was read month first; and required Country and Address fields had no box to fill in. Number fields in both forms now read a $, the commas between thousands and a comma as the decimal mark (25,50 is 25.5), where the web form read $25.00 as $2500. The Visual Forms JS and Web Forms JS changelogs list the rest.

Security and updates

  • A template image’s link (/templates/TEMPLATE_ID/images/IMAGE_ID) now needs someone signed in to the template’s account, unless it’s a demo template: on an install that stores files on its own filesystem, it used to open for anyone who had it. Forms, signature requests and PDFs don’t use this link, and on S3, GCS and MinIO, where it returned an error for everyone, it now works for the account.
  • Rails 8.1.4.1, with its security fixes.
  • Puma 8.0.3, with its security fixes: a client that stops reading, or sends data slowly, can no longer hold a web worker’s connections open, and a graceful restart reads an incomplete request for at most 25 seconds.
  • Fixed client IP spoofing: a request could set the IP address that rate limits, sign-in history and signature audit trails record. DocSpring now trusts CF-Connecting-IP only from Cloudflare’s addresses, or, as before, when your load balancer hides client addresses.
  • Closed gaps in the sign-in and password reset rate limits, and added rate limits to confirmation and unlock emails.
  • The embedded template editor no longer sends the people using it other users’ email addresses and IDs, the template’s permanent download link or its Embed Domains, and it sends version history only when the embed’s token allows versioning.
  • The PDF and image tools (PDFBox, qpdf, pdftk, ImageMagick, librsvg) now run under a seccomp filter, so a tool reading a crafted file can’t open network connections, trace another process, or read or write another process’s memory. On an older Linux kernel that can’t install a seccomp filter, the worker logs a warning and runs the tool as before, so nothing stops working. Confining which files those tools can reach follows in a later release.
  • PDF passwords are stored encrypted in the database.
  • Error reports to Sentry (when SENTRY_DSN or DOCSPRING_SENTRY_JS_DSN is set) no longer include a job’s arguments other than IDs, the tokens in email, sign-in and signing page links, a download’s custom filename or the embedded template editor’s token: a request’s report now sends only the request headers that help with debugging. The request logs mask those tokens and filenames too.
  • The admin pages’ Content Security Policy no longer allows inline scripts, so a script injected into an admin page can’t run.
  • Content Security Policy reports no longer send the tokens in a page’s URL (password reset, two-factor, invitation and email links) to DOCSPRING_CSP_REPORT_URI, and the two-factor sign-in challenge is filtered from request logs and error reports.
  • A failed internal type check no longer sends the value it checked to Sentry or the logs, where it could be form data.
  • Chromium 156.
  • PDFBox 3.0.8 and the TwelveMonkeys image libraries 3.15.3, which fixes an XML external entity (XXE) vulnerability in reading images’ XMP metadata (CVE-2021-23792).
  • Updated dependencies with security fixes, including Devise 5.0.4, ransack 4.4.4, sanitize 7.0.1, rails-html-sanitizer 1.7.2, Loofah 2.25.3, Nokogiri 1.19.7, axios 1.21.0, fast-json-patch 3.1.1, Pillow 13.0.0 (field detection), and the document worker’s rustls 0.23.46, rustls-webpki 0.103.16 and hickory-resolver 0.26.3.
  • Visual forms log a warning in the browser console when the page passes the apiTokenId and apiTokenSecret options, which put an API token where anyone can read it. They still work. Remove them, replace the token, and get private submissions’ PDFs on your server (Private submissions and API tokens).
  • API requests made with a signed-in browser session now need the page’s CSRF token, so another site’s page can’t use a signed-in user’s session to call the API. A request without it gets a 401, and the template editor fetches a new token and tries again. API clients that use an API token or OAuth aren’t affected.
  • Signing out takes a request with the page’s CSRF token, so other sites can’t sign people out. A link to /sign_out shows a page with a Sign out button.
  • Removed two-factor authentication pages the app didn’t use, including one that showed a signed-in user’s two-factor secret and one that turned two-factor authentication off without asking.
  • Wrong two-factor codes lock an account more firmly: waiting out the one-hour lock no longer resets the count, and after 10 wrong codes in a row only the unlock email’s link or a password reset unlocks it. The lock doesn’t stop the user’s API tokens and OAuth connections. Codes are accepted for 30 seconds either side of the current one instead of 90.
  • A wrong current password, when changing it or when DocSpring asks for it again before a security setting changes, counts toward the account’s lock like a wrong sign-in, and profile changes are rate limited.
  • Removing a linked Google, GitHub or OpenID sign-in asks for the password again, then for REMOVE to be typed.
  • Field detection no longer runs ONNX Runtime’s usage telemetry, which recorded a device ID in the container and could send usage events to Microsoft.
  • API request logs (for accounts with Log API requests and responses on) keep a request’s Referer without its query string, which can hold a signer’s token on requests from a signing page.

Other

  • Webhooks and Slack notifications keep the first 1 MB of each response, and combining PDFs can take up to 14 minutes in all.
  • Commands run with bin/rails runner no longer send errors to Sentry when SENTRY_DSN is set: their errors show in the command’s output. The web server, the workers and rake tasks still report to Sentry.

Upgrade to this version

Pull its image from AWS ECR or Docker Hub (multi-arch manifests for amd64 and arm64):

691950705664.dkr.ecr.us-east-1.amazonaws.com/docspring/enterprise:c648191044
docspringcom/docspring-enterprise:c648191044

If its database version is newer than the one in your admin pages' footer, run rake db:migrate when you upgrade. Upgrading from an older version? Read the notes of every release in between.

Product news by email

New features and changes, once a month.