Electronic records (21 CFR Part 11)
E-Signature <smart-esignature>
ESignature provides the electronic signature dialog described in 21 CFR Part 11.
<smart-esignature> · 16 properties, 9 methods, 6 events · source/modules/smart.esignature.js
Usage in React
The React wrapper is the ESignature component: every property is a prop, every event a prop named on<Event> that receives the CustomEvent, and the methods are called on the element through a ref.
import { ESignature } from 'smart-industrial/react/esignature';
const ref = useRef<ESignature>(null);
<ESignature ref={ref} meaning={'approved'}
onSignRequest={(event: CustomEvent) => console.log(event.detail)} />
// methods are called on the wrapper the ref holds, which calls the element
ref.current?.sign({}, {});
Properties
| Prop | Type, default | Description |
|---|---|---|
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 | string | Sets or retrieves the meaning of the signature. Empty asks the signer to choose. |
meanings | array | Sets or retrieves the meanings offered, as ids or { id, label }. Empty offers approved, reviewed, authored, responsible, verified and witnessed. |
lockMeaning | boolean | 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 | boolean | Determines whether a reason must be given before the request is raised. |
reasons | array | Sets or retrieves preset reasons, shown as a list. Empty gives a free text field. |
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 | 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 | boolean | 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 | number | Sets or retrieves how long after a signing the next one by the same user counts as the same session, in milliseconds. |
maxAttempts | number | Sets or retrieves the number of rejections after which the panel is locked. 0 disables the lock. reset() unlocks the panel. |
autoClose | number | Sets or retrieves how long the manifestation stays after a signing before the panel closes, in milliseconds. 0 keeps it open until Close. |
opened | boolean | 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 | boolean | 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 | string | Sets or retrieves the panel's title. Empty shows 'Electronic signature'. |
density | ESignatureDensity | Sets or retrieves the target size. touch makes the fields and buttons 48px high. |
Methods
| Method | Description |
|---|---|
sign(record?: object, options?: object): 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?: object): object | 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(): number | Returns the failed attempts since the last successful signing or reset(). |
isLocked(): boolean | Returns whether the panel is locked. |
isContinuous(): 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.
| Event | Description and detail |
|---|---|
onSignRequest | 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 | This event is triggered when the application accepts.signature object { id, userId, userName, meaning, meaningLabel, reason, at, recordId, recordHash }. |
onRejected | 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 | 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 | This event is triggered when the panel opens. |
onCancel | 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