Electronic records (21 CFR Part 11)

E-Signature `<smart-esignature>`

ESignature provides the electronic signature dialog described in 21 CFR Part 11.

JavaScript TypeScript Angular React Vue Blazor

<smart-esignature> · 16 properties, 9 methods, 6 events · source/modules/smart.esignature.js

Usage in Angular

The Angular wrapper is ESignatureComponent from ESignatureModule: every property is an input, every event an output named on<Event>, and the methods are called on the component reference from @ViewChild. A method that returns a value returns a Promise of it, resolved once the component has rendered; its ...Sync() twin returns the value at once, or null before the component has rendered. Unknown bindings are rejected at compile time.

import { ESignatureModule, ESignatureComponent } from 'smart-industrial/angular/esignature';

<smart-esignature #esignature [meaning]="'approved'"
    (onSignRequest)="onSignRequest($event)"></smart-esignature>

@ViewChild('esignature', { read: ESignatureComponent }) esignature!: ESignatureComponent;
// methods are called on the component reference; this one returns a Promise
const result = await this.esignature.sign({}, {});

Properties

Input	Type, default	Description
`[record]` record	object	Sets or retrieves the record being signed, as { id, title, fields: [{ label, value }] } or any object. The record is shown in the panel and the whole object is hashed into the signature. The panel takes a copy and its hash together, so what is signed is what was shown: a record assigned while the application is verifying a submitted signature does not change that signature (its recordId and recordHash stay those of the record submitted) and is shown once the request is answered.
`[meaning]` meaning	string	Sets or retrieves the meaning of the signature. Empty asks the signer to choose.
`[meanings]` meanings	array	Sets or retrieves the meanings offered, as ids or { id, label }. Empty offers approved, reviewed, authored, responsible, verified and witnessed.
`[lockMeaning]` lockMeaning	boolean false	Determines whether the meaning is shown as fixed text instead of a selection, for a step whose meaning is always the same, such as a release that is always an approval.
`[requireReason]` requireReason	boolean false	Determines whether a reason must be given before the request is raised.
`[reasons]` reasons	array	Sets or retrieves preset reasons, shown as a list. Empty gives a free text field.
`[sessionUserId]` sessionUserId	string	Sets or retrieves the signed-in user, when the application knows one. Pre-fills the user ID and, with continuousSession, is the user whose repeat signings need the password only.
`[sessionUserName]` sessionUserName	string	Sets or retrieves the printed name of the session user, used in the continuous-session hint and as the signer's name when the signer is the session user and the application's accept() gives no name.
`[continuousSession]` continuousSession	boolean false	Determines whether a repeat signing by the session user within sessionTimeout of the last asks for the password only. The first signing always uses both components.
`[sessionTimeout]` sessionTimeout	number 900000	Sets or retrieves how long after a signing the next one by the same user counts as the same session, in milliseconds.
`[maxAttempts]` maxAttempts	number 3	Sets or retrieves the number of rejections after which the panel is locked. 0 disables the lock. reset() unlocks the panel.
`[autoClose]` autoClose	number 2500	Sets or retrieves how long the manifestation stays after a signing before the panel closes, in milliseconds. 0 keeps it open until Close.
`[opened]` opened	boolean false	Determines whether the panel is shown. sign() opens it; cancel(), Escape and the close button close it. After a signing the manifestation stays for autoClose milliseconds, or until Close is pressed when autoClose is 0.
`[modal]` modal	boolean true	Determines whether the open panel is a modal dialog: aria-modal is true, Tab and Shift+Tab stay inside the panel, and when it closes - by Cancel, Escape, Close or after autoClose - the keyboard returns to the element that had it when the panel opened. Set to false for a panel that is part of the page.
`[label]` label	string	Sets or retrieves the panel's title. Empty shows 'Electronic signature'.
`[density]` density	ESignatureDensity normal	Sets or retrieves the target size. touch makes the fields and buttons 48px high.

Methods

Method	Description
`sign(record?: any, options?: any): Promise<any>` and `signSync(record?: any, options?: any): any`	Opens the panel for a record and returns a promise of the signature. The promise resolves when the application calls accept(), and rejects with { reason: 'cancel' \| 'lockout' \| 'superseded' } otherwise. `record` object Replaces the record property when given. `options` object { meaning, reason } for this ceremony.
`accept(verification?: any): Promise<any>` and `acceptSync(verification?: any): any`	Called by the application after it has verified the credentials. Builds the signature as { id, userId, userName, meaning, meaningLabel, reason, at, recordId, recordHash }, where recordId and recordHash are those of the record that was submitted, shows the manifestation, raises the signed event and resolves the promise. Returns the signature, or null when no signing was pending. `verification` object { userName, userId, at, id } - the printed name, and the application's values where they are to replace the panel's.
`reject(reason?: string): void`	Called by the application when the credentials could not be verified or the signer is not authorised. Counts the attempt, shows the rejection and locks the panel after maxAttempts. `reason` string Shown to the signer after 'Signature refused:'.
`cancel(): void`	Closes the panel without signing, raises the cancel event and rejects the promise. Does nothing while the panel is closed.
`reset(): void`	Clears the failed attempt count and the lock. Intended to be called by the application, not by the signer.
`resetSession(): void`	Clears the last signing, so that the next signing asks for both signature components again.
`attempts(): Promise<any>` and `attemptsSync(): number`	Returns the failed attempts since the last successful signing or reset().
`isLocked(): Promise<any>` and `isLockedSync(): boolean`	Returns whether the panel is locked.
`isContinuous(): Promise<any>` and `isContinuousSync(): boolean`	Returns whether the next signing needs the password only.

Events

The data of an event is in event.detail. signRequest is a request: the e-signature panel shows the signing as pending and waits, with no timeout, until the application calls accept() or reject(). signed, rejected, lockout, open and cancel report what the panel has already done.

Output	Description and detail
`(onSignRequest)` signRequest	This event is triggered when the signer submits. The application verifies the credentials and calls accept() or reject(). The password is in this event and nowhere else. record is the copy that was shown and recordHash its hash - the signature accept() builds carries the same. `userId` string The user ID entered, or the session user's. `password` string The password entered. `meaning` string The meaning chosen. `reason` string The reason given, or ''. `record` object The record being signed. `recordHash` string SHA-256 of the record, computed when the panel opened or the record property last changed. `continuous` boolean Whether this was a password-only signing. `at` string When it was submitted, ISO 8601 with offset.
`(onSigned)` signed	This event is triggered when the application accepts. `signature` object { id, userId, userName, meaning, meaningLabel, reason, at, recordId, recordHash }.
`(onRejected)` rejected	This event is triggered when the application rejects. `reason` string The reason given, or ''. `attempt` number How many refusals so far. `remaining` number Attempts left before the lock, or -1 when maxAttempts is 0.
`(onLockout)` lockout	This event is triggered when the refusals reach maxAttempts. The application enforces the same on the server. `userId` string The user ID in the field at the time. `attempts` number The refusals counted.
`(onOpen)` open	This event is triggered when the panel opens.
`(onCancel)` cancel	This event is triggered when the panel is closed without signing.

Types

`type ESignatureDensity`

'normal' | 'touch'

CSS variables

The component declares 9 CSS variables; the CSS page shows how to set them.

--smart-esign-size --smart-esign-background --smart-esign-header-background --smart-esign-border --smart-esign-primary --smart-esign-primary-text --smart-esign-error-text --smart-esign-ok-text --smart-esign-readout-font