Events
The library emits a number of events that can be used to integrate the library with your existing website and analytics solutions. A Node.js style event emitter interface is used.
Listeners are added and removed using the datawollet.on, datawollet.off, datawollet.addListener, and datawollet.removeListener methods.
datawollet.addListener('initialise', e => {
console.debug("The interface has been initialised - that means it's now visisble!")
})
Event replay
The web library may initialise at a different time to your own application, particularly if embedded using a script tag. This creates the possibility of some events occuring before your application has registered a handler.
Any events that occur when there are no handlers registered are cached in memory and replayed when the first event handler is attached. This should ensure no events are missed, though delivery is only guaranteed to the first listener registered for an event.
A maximum of 125 events per event type are stored in the cache. The oldest event will be purged if the limit is reached.
Event descriptions
The event payloads are specified below and can be used with TypeScript. The sessionID and type are present in all payloads.
Where HTML elements are the source or target associated with an event, they may be referred to using a string in the same format as a CSS selector, e.g. #element-id if the element has a unique identifier. We recommend setting a unique ID on any elements used to trigger actions in your custom HTML.
The web library automatically assigns a random ID to monitored input elements if they did not already have one, to ensure elements can be referenced without retaining the actual elements in memory.
reset
This event is emitted when a session is reset. A reset session closes it for any further use and prevents the data from being accessed from DataWollet's servers. It is the equivalent of signing out.
type EventSessionReset = {
sessionId?: string;
type: 'reset';
}
restore
A restore event is emitted when a session is restored with DataWollet's servers. This happens when the page is refreshed or the user navigates, to provide continuity to the user. Sources added previously within a session are made available again.
type EventSessionRestore = {
sessionId?: string;
type: 'restore';
}
initialise
An initialise event is emitted after the user interface is made visible. This event may not be emitted at all if the conditions have not been met or an error occurs that would prevent the library from functioning correctly.
type EventInterfaceInitialise = {
sessionId?: string;
type: 'initialise';
target: HTMLElement;
}
expand
An expand event is emitted when the controller for the library is expanded, or any expandable detail sections in the HTML configuration are expanded. Use the target property to determine which element was expanded.
type EventInterfaceExpand = {
sessionId?: string;
type: 'expand';
target?: HTMLElement;
cause: {
type: 'userInteraction' | 'system'
element?: HTMLElement;
}
}
collapse
A collapse event is emitted when the controller for the library is collapsed, or any expandable detail sections in the HTML configuration are collapsed. Use the target property to determine which element was collapsed.
type EventInterfaceCollapse = {
sessionId?: string;
type: 'collapse';
target?: HTMLElement;
cause: {
type: 'userInteraction' | 'system'
element?: HTMLElement;
}
}
sourceFileDialogOpen
A source file dialog open event is triggered if the user invokes the interface to select one or more files to use as a source. The exact behaviour of the interface is platform and operating system dependent. The user may cancel the interface without selecting a file.
A source may be added without this event being emitted, by dragging and dropping a source instead.
type EventSourceFileDialogOpen = {
sessionId?: string;
type: 'sourceFileDialogOpen';
}
sourceFileDialogCancel
A source file dialog cancel event is triggered if the user closes the file selection window using the cancel or close buttons, without selecting a valid source.
type EventSourceFileDialogCancel = {
sessionId?: string;
type: 'sourceFileDialogCancel';
}
sourceFileDragEnter
A file drag enter event is triggered if the user drags a file over the top of the designated drop area. The user might not actually drop the file, so there is no guarantee the file will be received and processed nor that it is a valid source.
type EventSourceFileDragEnter = {
sessionId?: string;
type: 'sourceFileDragEnter';
}
sourceUploadStart
A source upload started event is emitted after a source has been provisionally accepted, meaning it has the correct MIME type, but it does not guarantee the source will be added.
type EventSourceUploadStart = {
sessionId?: string;
type: 'sourceUploadStart';
source: {
type: 'file' | 'scan';
name: string;
file?: File;
}
}
sourceUploadFailed
A source upload failed event is emitted after a source upload was attempted but could not be completed. The reasons returned are a subset of the errors that can be returned when adding a source.
The response from the server is included to provide additional information and assist with debugging.
type EventSourceUploadFailed = {
sessionId?: string;
type: 'sourceUploadFailed';
source: {
type: EventSourceType;
name: string;
file?: File;
error:
'file-type'
| 'file-parse'
| 'file-size'
| 'source-unexpected'
| 'source-unmatched'
| 'source-lacking'
| 'source-expectations'
| 'server-error'
| 'server-timeout'
| 'server-forbidden'
| 'scan-capability'
| 'scan-permission'
| 'scan-quality'
| null;
response: any;
}
}
sourceUploadFinish
A source upload finished event is emitted after a source has been analysed by DataWollet's servers, meaning additional metadata is available such as the document classification and its text content. It does not guarantee the source will be added.
type EventSourceUploadFinish = {
sessionId?: string;
type: 'sourceUploadFinish';
source: {
requestId: string;
type: 'file' | 'scan';
name: string;
file?: File;
content: {
classification: string;
nodes: any[];
text: string;
} | null;
}
}
sourceAdded
A source added event is emitted when a source has been accepted and will be used to auto-fill fields.
A source may be added but still have an error, for example it could have an unexpected classification depending on the configuration used.
When a session is restored, such as when the page is refreshed or the user navigates causing a new page load, then sources will be re-added to the client using data held on the server. The source status will be new the first time a source is added, and restored for all subsequent times the same source is added.
type EventSourceAdded = {
sessionId?: string;
type: 'sourceAdded';
sourceStatus: 'new' | 'restored';
source: {
requestId: string;
type: 'file' | 'scan';
name: string;
error:
'file-type'
| 'file-parse'
| 'file-size'
| 'source-unexpected'
| 'source-unmatched'
| 'source-lacking'
| 'source-expectations'
| 'server-error'
| 'server-timeout'
| 'server-forbidden'
| 'scan-capability'
| 'scan-permission'
| 'scan-quality'
| null;
content: {
classification: string;
nodes: any[];
} | null;
}
}
sourceRejected
A source rejected event is emitted when a source has been rejected after it was analysed by the server, likely because it was not readable or does not have the expected document classification.
type EventSourceRejected = {
sessionId?: string;
type: 'sourceRejected';
source: {
requestId: string;
type: 'file' | 'scan';
name: string;
error:
'file-type'
| 'file-parse'
| 'source-unexpected'
| 'source-unmatched'
| 'source-lacking'
| 'source-expectations'
| 'server-error'
| 'server-timeout'
| 'server-forbidden'
| 'scan-capability'
| 'scan-permission'
| 'scan-quality'
| null;
content: {
classification: string;
nodes: any[];
} | null;
}
}
sourceRemoved
A source removed event is emitted after a source is removed by the user. This occurs after the removal is confirmed, if confirmation is enabled in the configuration.
type EventSourceRemoved = {
sessionId?: string;
type: 'sourceRemoved';
source: {
requestId: string;
type: 'file' | 'scan';
name: string;
}
}
fillsPrecomputed
A fills precomputed event is emitted after a source is added as a result of precomputation to determine which inputs might be filled. It is not possible to know all of the inputs that could be filled in advance, so only an estimated number of fills is provided. Fills that depend on the options made available (e.g. address lookups) cannot be precomputed and are only determined when the field is visible.
type EventFillsPrecomputed = {
sessionId?: string;
type: 'fillsPrecomputed';
expected: {
fills: number;
}
}
fillsCompleted
A fills completed event is emitted after the library believes it has successfully made a change to an input field. It does not gurantee that the input has validated or that other code on the page wont modify the value further.
The noops array contains changes that resulted in no operation. This may be because the default value matched the requested value, for example.
Reasons are supplied for the changes made or no operations. A value will ordinarily only be changed once, unless a fill activitiy and its parent step is explicitly marked as repeatable, which may be necessary when other client-side scripts are manipulating an input.
type EventFillsCompleted = {
sessionId?: string;
type: 'fillsCompleted';
fills: {
name?: string;
id: string;
value: string | number | Date | boolean;
reason?: 'CHANGE_FROM_CURRENT_VALUE' | 'REPEATABLE_CHANGE_FROM_CURRENT_VALUE';
}[]
noops: {
name?: string;
id: string;
value: string | number | Date | boolean;
reason?: 'ELEMENT_NOT_FOUND' | 'OPTION_NOT_FOUND' | 'NO_CHANGE_FROM_CURRENT_VALUE' | 'OTHER' | 'MODIFIED_BY_USER' | 'MODIFIED_ALREADY';
}[]
}
inputFocus
An input focus event is emitted after an input being monitored by the library is focused, either by the user or by the library.
type EventInputFocus = {
sessionId?: string;
type: 'inputFocus';
target: HTMLElement;
}
inputBlur
An input blur event is emitted after an input being monitored by the library has lost focus. This is often when validation checks are carried out and an input is considered 'touched'.
type EventInputBlur = {
sessionId?: string;
type: 'inputBlur';
target: HTMLElement;
}
inputChange
An input change event is emitted after an input being monitored by the library has changed. This may be a result of the library, the other scripts on the page, actions by the browser, or actions by the user. The library attempts to determine the cause of the change and its new value.
type EventInputChange = {
sessionId?: string;
type: 'inputChange';
target: HTMLElement;
cause: {
type: 'userInteraction' | 'unknown';
}
value: string | number | Date | boolean | null;
}