Pular para o conteúdo principal

Updating Signer from 2.x to 3.x

Before updating your on-premises instance from version 2.x to a 3.x version, you must follow a few extra steps.

note

If your instance is still on version 1.x, follow the Updating to 2.x page first.

warning

Updating at a time of low usage is strongly recommended. After the update, background jobs can temporarily increase the load and consumption of the database, mainly on large tables.

Summary​

Part 1: How to update​

Follow the steps below in order.

1. Install the ASP.NET Core Runtime 10.0​

Version 3.0.0 moved the platform from .NET 8 to .NET 10. Install the ASP.NET Core Runtime 10.0 on the platform you use:

  • Windows: install the .NET 10.0 Hosting Bundle
  • Linux
    • Ubuntu Server: install the aspnetcore-runtime-10.0 package instead of aspnetcore-runtime-8.0
tip

It is not necessary to uninstall previous versions of ASP.NET Core Runtime, multiple versions can co-exist in the same system without issues.

note

On Docker this step is not necessary since the 3.x images already ship with the ASP.NET Core Runtime 10.0 embedded.

2. Back up and review the changes​

Back up the database before updating and read Part 2. If you integrate with Signer through the API or Webhooks, review your integrations before updating. To keep the previous document pause behavior, set General:EnableDocumentPause to false.

3. Update Signer​

After following the steps above, proceed with the normal update instructions.

Troubleshooting database timeout errors after the update​

If you face errors on the first start after the update and the log shows a timeout while applying the database migrations, run the command-line utility to start the migrations manually with a timeout larger than the default:

  1. Stop the application.

  2. Navigate to the folder where the application binaries are.

  3. Run the command:

    dotnet Lacuna.Signer.Site.dll -- update-db EventUserAgent --timeout 6000

  4. Restart the application.

Azure App Services​

If your instance is hosted on Azure App Services:

  1. In the Azure portal, open the App Service settings.
  2. Select Configuration, then the General settings tab.
  3. In the Stack settings section:
    1. Stack must be set to .NET
    2. .NET version must be set to .NET 10 (LTS)
tip

The Stack settings section above only appears for Windows-based App Service Plans. For Linux-based plans, no change is needed.

Part 2: Breaking changes and database changes​

The most important 3.0.0 changes for those updating from 2.x.

Database changes​

Version 3.0.0 applies the migrations AddDocumentsReportIndex, Spa8, SignerPositioningAndSignatureSheet, SignatureSheetBounds and EventUserAgent on its first start.

  • The Documents (SubscriptionId, CreationDateUtc) index, used by the documents reports, is built by a background job after the update, not during the migration. See Documents index: what it improves, how it is built and what to do if the automatic build fails.
  • If you are updating from a version earlier than 2.21.0, the update also applies the DocumentUser denormalization with an index (SIG-780), which can cause a period of slowness and higher database consumption on the instance. See DocumentUsers index: what it improves, how it is built and what to do if the automatic build fails. Instances already on 2.21.0 or later are not affected.
  • The Hangfire upgrade to version 1.8 does not change the schema of the Hangfire tables in the database: the schema stays at version 7 and no action is needed. Because of that, it is safe to go back to 2.x if you need to roll the update back.

API and Webhook integrations: document pause​

Document pause (SIG-1937) introduces changes that can break existing integrations. Review your integrations before updating, or set General:EnableDocumentPause to false to keep the previous behavior.

API

  • The document status (DocumentStatus) has a new value, Paused. A paused document is now returned with status Paused instead of Pending. Integrations that handle the status exhaustively (for example a switch without a default case) or that deserialize the enum strictly may fail. Treat Paused as an in-progress document, like Pending.
  • The Pending status filter on the document list still includes paused documents. Use the new Paused value to list only paused ones.
  • The document list returns the new IsPaused and CanResume fields, and the public endpoints return IsDocumentPaused. On paused documents the participant's pending action (PendingFlowAction) is not filled.
  • New endpoints: POST /api/documents/{id}/pause (with the optional Reason, up to 500 characters) and POST /api/documents/{id}/resume. Both require the PauseDocument permission.
  • While the document is paused, the operations below fail with new error codes (ErrorCodes) instead of running: sign, approve and refuse (CannotSignPausedDocument, CannotApprovePausedDocument, CannotRefusePausedDocument), edit the flow, edit the information, add a version, restart the flow, remove a signature, submit files, edit notified emails, send reminders and generate a share link. Canceling the document is still allowed. Integrations that sign, approve or edit documents in bulk must handle these errors.
  • Automatic reminders are not sent for paused documents.

Webhooks

  • Two new webhook types, DocumentPaused (10) and DocumentResumed (11), are sent to all already registered webhook endpoints, with no configuration needed. Endpoints that reject or fail on an unknown type must be adjusted before the update to ignore the new types.
  • The Data of DocumentPaused carries the document plus PausedBy and Reason. The one of DocumentResumed carries the document plus ResumedBy.
  • While the document is paused, the signature, approval or flow-conclusion webhooks are not fired, since none of those actions can happen.

Other API changes​

Comparison of the 2.22.2 Swagger with the 3.0.0 one. All are additive (no endpoint, field or schema was removed), with the caveats noted.

  • Signer signature positioning (SIG-1936):
    • New endpoint PUT /api/documents/{id}/signer-positioning, which sets signerPositioningEnabled and automaticSignaturePositioning (Disabled, Footnote or SignatureSheet) for the document. null takes the organization's current setting. It can only be changed until the first signature (SignerPositioningLockedAfterSignature).
    • CreateDocumentRequest accepts signerPositioningEnabled and automaticSignaturePositioning; DocumentModel returns those fields and signatureSheetFirstPage.
    • FlowActionModel returns visualRepresentationOnFootnote and DocumentMarkModel returns isAutoPositioned.
    • POST /api/documents/{id}/flow accepts the acceptFootnoteVisualRepresentation parameter. On an already signed document whose signature sheet has no free slot left, the edit is rejected with SignatureSheetFull unless the parameter is true.
    • New error codes: SignerPositioningNotAllowed, SignerPositioningIncompatibleWithAutomaticPositioningDisabled, SignatureSheetFull and SignerPositioningLockedAfterSignature.
    • Note: the default automatic positioning mode (VisualRepresentation:AutomaticSignaturePositioning) is Footnote. Signatures without a defined position are now placed on a free footer slot.
  • Document list: new ParticipantSituation parameter (Completed or Pending) on GET /api/documents, to filter by the situation of the searched participant (SIG-1951).
  • Evidences: EvidencesModel returns userAgent and consent (terms version, acceptance date and SHA-256 hash of the terms), following the signature evidences (SIG-1898) and the clickwrap consent (SIG-1899).
  • Identifiers: IdentifierTypes gained Ssn, Itin and Ein (SIG-1949). Integrations that deserialize the enum strictly must accept the new values.
  • Stricter validations. Requests that used to be accepted may now be rejected. Review integrations that send this data:
    • Email: addresses with consecutive dots (for example a..b@x.com) are rejected, since .NET 10 cannot send them. The validation applies to flow participants, the organization support email, template email fields and contacts (which is why the CreateContactRequest and UpdateContactRequest schemas no longer declare the email format). Addresses already stored are not changed.
    • Phone: number validation and normalization now share the same parsing. Numbers without the international prefix (+ and country code) are interpreted in the default region (Brazil); send numbers from other countries, such as Paraguay and Ecuador, with the + and country code. Numbers rejected by Grant ID now return a validation error instead of a 500 error (SIG-1923).
    • CNPJ: alphanumeric CNPJs are stored in uppercase (signers, signing rules, organizations, billing information and authentication profiles), and updating an organization now validates the identifier as creation does.
    • Paraguay and Ecuador identifiers: leading and trailing spaces are trimmed and the format is validated when creating users with multiple identifiers, returning a validation error instead of a 500 error (SIG-1942). The length of Ecuador identifiers (RUC and others) is now actually checked, and values with the wrong number of digits are rejected.
    • US identifiers (SSN, ITIN and EIN): only accept the bare 9 digits or the official dashed layout; spaces and misplaced dashes are rejected. The identifier add and update endpoints also validate the allowed types in AllowedIdentifierTypes.
    • Attachments and templates: document generation (GenerateDocumentsRequest) validates attachments against the attachment MIME type list, and template files are validated against the template list. Whitespace around the MIME type list entries is ignored (SIG-1948).
    • Public digital signature completion: the ticket sent must belong to the flow action and user being completed; otherwise the completion fails with InvalidTicket.
    • Email-matched account reuse (2.22.2 hotfix): not a break, but it changes the outcome of one scenario. On instances with a single identifier (CPF as claim) in NullableUnique mode, adding a participant whose email already belongs to a Grant ID account without a CPF claim used to return EmailAlreadyBeingUsed; the existing account is now reused. Reuse only happens when there is exactly one account with the email, its username is the email itself, it has no CPF in Grant and no different CPF is tied to it or to the CPF informed in Signer. Outside those conditions the EmailAlreadyBeingUsed error is still returned, and Unique mode was not changed. The CPF is not written to Grant ID on that reuse. Integrations that relied on that error to detect already registered emails must account for the new outcome.
    • Mark page numbers: negative page numbers resolve from the last page (-1) and pages beyond the end of the document are clamped to the last page. Page 0 is still accepted (SIG-453).
View as Markdown