IMatch Documentation

Class: IMWS

IMWS

This class provided accessors and helper methods for IMatch Anywhere™ WebServices (IMWS).
With IMWS scripts and apps can access IMatch databases remotely in a controlled and secure fashion.

Embedded vs. Standalone IMWS

This class library can be used for both the standalone IMWS and the IMWS embedded in IMatch for Windows.
Some IMWS methods/endpoints work differently when used in the embedded version. If this is the case, the difference is explained and the Embedded badge is used to indicate this.

If you use it from apps running inside IMatch (in conjunction with the IMatch JavaScript library) you don't need to manually initialize this class.
Just make sure you include imwslib.js before you include imatchlib.js in your HTML document.
The IMatch class library detects IMWS and initializes it automatically.

If you use it stand-aline, call the IMWS#init function before you use any of the other methods.

Endpoint Documentation

For a full documentation of all available endpoints, please use the ##IMatch WebServices™ Documentation## app included in IMatch or call the IMWS /discover endpoint.

new IMWS()

Members

config

Contains the configuration data for this instance.
The members of this object are automatically filled during authenticate.

Properties:
Name Type Description
imwsUrl String

URL and port of IMatch WebServices. Set this before calling any endpoint
auth_token String

The session auth_token
user Object

User information retrieved during the authenticate call.

idlist :string

This enumeration defines the names of pre-defined idlists you can use in your code. These idlists are dynamic and automatically kept up-to-date by IMWS. You can use these names with the idlist parameter in all endpoints which accept an idlist, e.g., /files.

Type:
  • string
Properties:
Name Type Default Description
allFiles string @IMWS.allfiles

This idlist contains all files in the database.
Example
// Retrieve the id and file name of the first page of 500 files in the database:
 IMWS.get('v1/files' {
     idlist: IMWS.allFiles,
     pagesize: 500,
     page: 0,
     fields: 'id,filename'
}).then ...

COLLECTIONS :Number

This enumeration lists the ids of all IMatch collections with static ids. To determine the ids of dynamically created collections (e.g., labels) use the /collections endpoint.

Type:
  • Number
Properties:
Name Type Default Description
bookmarks Number 2
protectedFiles Number 4
pendingWriteBack Number 5
flagRoot Number 10
flagOn Number 11
flagOff Number 12
flagNone Number 13
dotRoot Number 30
dotRed Number 31
dotGreen Number 32
dotBlue Number 33
dotNone Number 34
pinRoot Number 50
pinRed Number 51
pinGreen Number 52
pinBlue Number 53
pinNone Number 54
addedRoot Number 70
addedToday Number 71
addedYesterday Number 72
addedThisWeek Number 73
addedLastWeek Number 74
addedThisMonth Number 75
addedLastMonth Number 76
addedThreeMonth Number 77
updatedRoot Number 90
updatedToday Number 91
updatedYesterday Number 92
updatedThisWeek Number 93
updatedLastWeek Number 94
updatedThisMonth Number 95
updatedLastMonth Number 96
updatedThreeMonth Number 97
viewedRoot Number 110
viewedToday Number 111
viewedYesterday Number 112
viewedThisWeek Number 113
viewedLastWeek Number 114
viewedThisMonth Number 115
viewedLastMonth Number 116
viewedThreeMonth Number 117
ratingRoot Number 10000
rating1 Number 10001
rating2 Number 10002
rating3 Number 10003
rating4 Number 10004
rating5 Number 10005
ratingNone Number 10006
ratingReject Number 10007
labelRoot Number 11000
labelNone Number 11001
labelItem Number 11002
relationRoot Number 100000
relationMaster Number 100001
relationVersion Number 100002
relationItem Number 100010
annoRoot Number 200000

ERROR_CODES :number

Enum for IMWS error messages. These error codes are returned in the JSON reponse as part of HTTP status codes <> 200 OK.
Note: Not all error responses contain additional JSON data. Always check for the existence of a JSON body via
error.responseJSON (if you use jQuery) or similar libraries.

Type:
  • number
Properties:
Name Type Default Description
PTWS_ERR_CODE_MAINTENANCEMODE number 1000

Maintenance Mode active.
In maintenance mode only Admin users can access IMWS (login disabled) and several endpoints are disabled.
PTWS_ERR_CODE_NOT_MAINTENANCEMODE number 1001

Maintenance Mode not active.
This endpoint can only be used in maintenance mode.
PTWS_ERR_CODE_MAINTENANCEMODE_NOLOGIN number 1002

Cannot log-in in maintenance mode.
PTWS_ERR_CODE_COM number 1003

Windows COM interface or method failed.
PTWS_ERR_CODE_CANCEL number 1005

The endpoint was prematurely aborted by user or app request. This is mostly used with long-running file System operations and the /cancel/* endpoint family.
PTWS_ERR_CODE_UNSUPPORTED number 1010

Unsupported endpoint / method.
PTWS_ERR_CODE_MISSING_PRIVILEGE number 1011

Insufficient privileges. The current user cannot use this function, e.g., deleting a file without the 'can delete files' permission.
Note: An app should check the privileges of the user before attempting to call an endpoint.
The /userinfo endpoint returns the privieleges for the current user.
PTWS_ERR_CODE_INTERNAL_ERROR number 1100

Snap :-/ Internal error. Check the IMWS log file for additional information.
PTWS_ERR_CODE_UNKNOWN_METHOD number 1101

Unknown or unsupported method.
PTWS_ERR_CODE_PARAM_INVALID number 1102

Invalid parameter.
PTWS_ERR_CODE_PARAM_RANGE number 1103

Parameter out of range.
PTWS_ERR_CODE_PARAM_INVALID_REGEXP number 1104

Invalid regular expression.
PTWS_ERR_CODE_PROTECTED_FILE number 1105

This file is protected.
PTWS_ERR_CODE_ACL_RESTRICTION number 1106

This file is not accessible because of ACL restrictions.
PTWS_ERR_CODE_NO_FILE_SPECIFIED number 1107

No file specified. Usually you need to specify an id, idlist or path parameter to match one or more filex.
PTWS_ERR_CODE_PARAM_SETTING_NOTFOUND number 1180

'data' endpoint. Setting not found.
PTWS_ERR_CODE_PARAM_SETTING_UPDATEFAILED number 1181

'data' endpoint. Update of setting failed. Check the IMWS log file for more information.
PTWS_ERR_CODE_PARAM_SETTING_DELETEFAILED number 1182

'data' endpoint. Deletion of setting failed. Check the IMWS log file for more information.
PTWS_ERR_CODE_SESSION number 1200

Too many sessions. Session limit exceeded. Depends on the edition. Install additional CALS or reduce the number of concurrent users.
PTWS_ERR_CODE_IM_FILE_READ number 1401

Error reading file. File does not exsit or is inaccessible.
PTWS_ERR_CODE_IM_FILE_WRITE number 1402

Error writing file. File does not exsit or is inaccessible.
PTWS_ERR_CODE_IM_FILE_EXISTS number 1403

A file already exists.
PTWS_ERR_CODE_IM_FOLDER_NOTFOUND number 1410

Folder not found
PTWS_ERR_CODE_IM_FOLDER_EXISTS number 1411

Folder already exists
PTWS_ERR_CODE_IM_FILESYS_OP_FAILED number 1450

Unspecified error during a file operation.
PTWS_ERR_CODE_DB_OP_FAILED number 1501
PTWS_ERR_CODE_DB_TRANSACTION number 1502

Database operation failed. Could not aquire a transaction within time-limit. Try again later.
PTWS_ERR_CODE_DB_COMMIT number 1503

Database operation failed. Could not commit a transaction. Changes to the database rolled back.
PTWS_ERR_CODE_DB_READONLY number 1504

Database is read-only. The attempted operation cannot be performed on read-only databases.
PTWS_ERR_CODE_LOCK_FAILED number 1600

One or more objects are currently locked by another session.
PTWS_ERR_CODE_LOCK_RELEASE_FAILED number 1601

One or more locks could not be released.
PTWS_ERR_CODE_SQLITE_FAILED number 1700

A SQLite operation failed
PTWS_ERR_CODE_UNAUTHORIZED number 2000

Unauthorized access or session expired. This request needs to be authenticated with a valid auth_token.
PTWS_ERR_CODE_INVALIDUSER number 2010

Unknown id or invalid password.
Example
IMWS.get('v1/method').then(function(response) {
    ...
},function(error) {
    if (error.responseJSON && (error.responseJSON.error.code == IMWS.ERROR_CODES.PTWS_ERR_CODE_NO_FILE_SPECIFIED)) {
    }
});

EVENT_CODES

This enum describes the major (ma) and minor (mi) codes used when IMWS sends messages over the websocket.
IMWS will send other events as well, but these are for internal purposes and should be ignored by apps.

Properties:
Name Type Default Description
evAttributeDB 5700

Attributes Database Events
All evSDB* event codes below are used as minor (mi) event codes.
evSDBDomainAdded 100

Attribute Set added
evSDBDomainUpdated 110

Attribute Set updated, Param1 : id or 0
evSDBDomainDeleted 120

Attribute Set removed, Param1 : Oid
evSDBDomainRenamed 130

Attribute Set renamed, d1 : id, s1: OldName, s2: new name
evSDBAttributeAdded 200

Attribute added, d1 : id
evSDBAttributeUpdated 210

Attribute updated, d1 : id
evSDBAttributeDeleted 220

Attribute removed, d1 : id
evSDBDataAdded 300

Data added, d1 : id, d2 : Attribute id
evSDBDataUpdated 310

Data updated, d1 : id, d2 : Attribute id
evSDBDataDeleted 320

Data removed, d1 : Oid, d2 : Attribute id
evUpdateQueue 500

Update Queue Events
All evUQ* event codes below are used as minor (mi) event codes
evUQBusy 1

Sent at intervals while the queue is processing.
evUQUpdated 2

Entries were added or removed. d1: Number of entries in the queue.
evUQEmpty 3

Queue is empty. Sent after the queue was processing something and is now empty again.
evUQImportComplete 4

Update and Metadata read completed. This is sent after the queue has finished processing folder/file imports. There may be other pending entries (write back, relation updates).
evUQNoWICCodec 5

No WIC codec installed for the given format (String 1 = Ext)
evUQDuplicateFilesFound 6

Duplicate files were found during a scan operation (only when the user has enabled duplicate checks)
evIMWSBroadcast 9000

IMWS Broadcast Event
This event is sent when an app uses the /messages/broadcast endpoint to send a broadcast message to all other apps.
s1 contains the message sent by the app. The format is undefined and completely under the control of the sending app.
evIMWSImageProcessor 9005

IMWS Image Processor Event
This event is sent when one of the /imageprocess endpoints is used. It provides info about the progress.
evIMWSIPProgress 1

Files are processed.
Fields:
appid: The id of the initiating app.
percentage: total percentage.
id: File id
evIMWSIPPackingProgress 2

Files are packed into an archive.
Fields:
appid: The id of the initiating app.
percentage: total percentage.
evEntityManager 9500

Entity Manager Events. This messages are sent when the IMatch entity graph is manipulated.
All evEM* event codes below are used as the minor (mi) event code.
evEMExportBegin 50

Export begins
evEMExportComplete 55

Export completed. d1: 1=success, 0=failure
evEMImportBegin 60

Import begins
evEMImportComplete 65

Import completed. d1: 1=success, 0=failure
evEMEntityAdded 100

Entity added. d1: id, s1: entity name, s2: tag
evEMEntityUpdated 101

Entity updated. d1: id, s1: entity name, s2: tag. Either id or tag is specified.
evEMEntityTagChanged 102

Entity tag changed. d1: id, s1: entity name, s2: tag|newtag
evEMEntityDeleted 103

Entity deleted. d1: id, s1: entity name, s2: tag
evEMEntityDeletedAll 104

All entities in a schema deleted. s1: entity name
evEMEntitySchemaAdded 200

Entity schema added. s1: entity name
evEMEntitySchemaUpdated 201

Entity schema updated. s1: entity name
evEMEntitySchemaDeleted 202

Entity schema deleted. s1: entity name. This also deletes all entity properties and entities and edges for this schema.
evEMEntityPropSchemaAdded 300

Entity property schema added. s1: entity name, s2: property name.
evEMEntityPropSchemaUpdated 301

Entity property schema updated. s1: entity name, s2: property name.
evEMEntityPropSchemaDeleted 302

Entity property schema deleted. s1: entity name, s2: property name.
evEMEdgeSchemaAdded 400

Edge schema added. s1: name.
evEMEdgeSchemaUpdated 401

Edge schema updated. s1: name.
evEMEdgeSchemaDeleted 402

Edge schema deleted. s1: name.
evEMEdgePropSchemaAdded 500

Edge property schema added. s1: edge schema name, s2: property name.
evEMEdgePropSchemaUpdated 501

Edge property schema updated. s1: edge schema name, s2: property name.
evEMEdgePropSchemaDeleted 502

Edge property schema deleted. s1: edge schema name, s2: property name.
evEMEdgeAdded 600

Edge added. d1: id.
evEMEdgeDeleted 601

Edge deleted. d1: id.
evEMEdgePropsUpdated 602

Edge properties updated. d1: id, s1: edge schema name.
evEMEdgePropsDeleted 603

Edge properties deleted. d1: id, s1: edge schema name.
evEventManager 9600

Event Manager Events. This messages are sent when event entities are manipulated.
All evEVM* event codes below are used as the minor (mi) event code.
evEVMEventUpdated 100
evPeopleManager 9700

People Manager Events. This messages are sent when people entities are manipulated.
All evPMM* event codes below are used as the minor (mi) event code.
evPMCoverFileChanged 100

The cover file of a person was changed. d1: person id.
evPMPersonLinkedToFace 110

A person was linked to a face. d1: person id, d2: face id.
evPMPersonUnlinkedFromFace 111

A person was unlinked from a face. d1: person id, d2: face id.
evPMPersonLinkedToFile 115

A person was linked to a face in a file. d1: person id, d2: file id
evPMPersonUnLinkedFromFile 116

A person was unlinked from a face in a file. d1: person id, d2: file id
evPMReject 120

A reject was set or reset. d1: person id, d2: face id. If d2 is 0, the reject was reset.
evPMSetFileData 125

Face data was set for a file. This can mean many things. It is
usually sent during undo operations, file background processing
or similar taks.
evPMPersonSortByChanged 130

The "sort by" property of a person was changed. d1: person id.
evPMReclusterBegin 150

Reclustering faces for a person in a background thread: begin. d1: Person id, d2: 1 if a file scope is used.
evPMReclusterEnd 151

Reclustering faces for a person in a background thread: completed. d1: Person id, d2: 1 if a file scope is used.
evPMReclusterComplete 155

All background recluster operations complete.
evPMAutoClusterP1Begin 160

Auto clustering phase 1. Loading faces from database
evPMAutoClusterP1End 161

Completed. d1: Number of faces to process
evPMAutoClusterP2Begin 165

Auto clustering phase 2. Creating graph. SLOWEST part. Massive processoor utilization for extended periods.
evPMAutoClusterP2Progress 166

Sent frequently while this phase runs
evPMAutoClusterP2End 167

Completed. d1: Number of edges
evPMAutoClusterP3Begin 170

Auto clustering phase 3. Analyzing graph and clustering faces.
evPMAutoClusterP3End 171

Completed. d1: Number of persons to create
evPMAutoClusterP4Begin 175

Auto clustering phase 4. Creating persons and assigning faces.
evPMAutoClusterP4End 176

Completed. d1: 0 = success, 1 = aborted.
evPMFaceAdded 500

A face was added. d1: face id
evPMFaceDeleted 510

A face was deleted. d1: face id. This message is not sent when an entire file (which may contain any number of faces) is deleted.
evPMFaceIgnored 520

A face was set to ignore. d1: face id.
evObjectUpdate 10000

Database Objects Updated Events.
All evOU* event codes below are used as the minor (mi) event code.
evOUFolderAdd 100

A folder was added d1 : id
evOUFolderUpdate 101

A folder was updated d1 : id, d2 : kind of update
evOUFolderRename 102

A folder was renamed (only the name was changed). d1: id, s1: name
evOUFolderMove 103

A folder was moved or relocated. d1: id, s1: name
evOUFolderRemove 105

A folder was deleted. d1 : id
evOUFolderAddOrUpdate 106

A folder was added or updated (e.g. during a Scan/Rescan). d1: id, d2: 0: existing folder, 1: new folder
evOULabelDefs 110

XMP Label definitions changed
evOUFileAdd 200

A file was added. d1: id, d2: folder id
evOUFileUpdate 201

A file was updated. d1 : id
evOUFileRename 202

A file was renamed. d1: id. s1: old name. s2: new name
evOUFileMove 203

A file was moved. d1 : id, d2: new folder id.
evOUFileRemove 205

A file was deleted. d1: id
evOUFileAttributeChange 230

A file attribute has changed, e.g. read-only flag. d1 : id
evOUFilePendingChange 235

The pending state of the file has changed. d1 : id, d2: 0:normal, 1: Metadata.
evOUTransformChange 240

The transformations for a file have changed. d1 : id.
evOUThumbUpdate 301

A thumbnail was updated. d1: id
evOUThumbDelete 302

A thumbnail was deleted. d1: id
evOUThumbSetUpdate 310

A thumbnail set was updated. d1: id
evOUThumbSetDelete 311

A thumbnail set (e.g., videos) was deleted. d1: id, d2: type.
evOUCollectionUpdate 400

A collection was updated. d1 : Collection id.
evOUCollectionLabelsChanged 401

A label was added or removed.
evOUTimelineAddNode 420

A timeline node was added. d1 : node id.
evOUTimelineUpdateNode 421

A timeline node was updated. d1 : node id.
evOUTimelineRemoveNode 422

A timeline node was removed. d1: node id.
evOUTimelineRebuildBegin 423

Timeline rebuild begins.
evOUTimelineRebuildFinish 424

Timeline rebuild completed. d1 : 0: Error, 1: OK.
evOUCategoryAdd 500

A category was added. d1 : id
evOUCategoryUpdate 501

A category was updated. d1 : id
evOUCategoryError 502

The InError() state of a category has changed. d1 : id of category, d2 : 1 or 0
evOUCategoryRemove 503

Sent after a category has been removed. d1: id
evOUCategoryMove 504

Sent after a category has been moved. d1 : id of category, d2 : id of new parent (may be 0 if the category was moved under @All.
evDataGrouperExecuteBegin 580

The data grouper starts to re-calculate a data-driven category. d1: category id
evDataGrouperExecuteFinish 581

The data grouper finished to re-calculate a data-driven category. d1: category id, d2: runtime in ms.
evDataGrouperUpdateBegin 585

A data-driven category is updated with new results. d1: category id
evDataGrouperUpdateFinish 586

A data-driven category has finished updating with new results. d1: category id, dw: runtime in ms.
evOUMBFileValueUpdate 600

Metadata* Values for a file were added or updated. d1 : id of file.
evOUMBFileValueDelete 601

Values for a file were removed. d1 : id of file.
evOUMBLabelUpdate 602

The label of a file was changed. Extra event because so frequent. d1: id of file.
evOUMBRatingUpdate 603

The rating of a file was changed. Extra event because so frequent. d1: id of file.
evOUMBFileWriteBack 650

The write-back for a file was completed. d1: file id.
evOUMBKeywordCategoryOpAdd 660

Files were added to @Keywords. d1 : id of category which caused the change.
evOUMBKeywordCategoryOpRemove 661

Files were removed from @Keywords. d1 : id of category which caused the change.
evOUMBKeywordCategoryOpUpdate 662

Files were updated in @Keywords. d1 : id of category which caused the change.
evOUMBKeywordRemove 665

A @Keyword category was removed, including all children and their associated keywords. d1 : id of category.
evOUSortArrayUpdate 700

A sort array (custom sort order) was updated. d1 : id of array, d2 storage id of array.
evOUSortArrayDelete 701

Sort array removed. d1 : id of the array. If 0, all entries were removed. d2 storage id.
evOUFavoriteSetAdd 750

A favorite set was added. d1 : id.
evOUFavoriteSetUpdate 751

A favorite set was updated. d1 : id, d2 : user data.
evOUFavoriteSetDelete 752

A favorite set was deleted. d1 : id.
evOURelationDefAdd 800

Relation Definition added. d1 : id of definition.
evOURelationDefUpdate 801

Relation Definition updated. d1 : id of definition.
evOURelationDefRemove 802

Relation Definition removed. d1 : id of definition.
evOURelationUpdate 820

Relation updated. d1 : id of file. If 0, multiple files were updated.
evOURelationStackCreate 830

A stack was created. d1 : id of file, d2 : relation type: 20: version, 30: regular stack.
evOURelationStackDelete 831

A stack was deleted. d1 : id of file, d2 : relation type.
evOURelationStackCreateElement 832

A stack elem was created. d1 : id of stack, d2 : id of file, d3 : relation type.
evOURelationStackDeleteElement 833

A stack elem was created. d1 : id of stack or 0 if multiple stacks were processed. d2 : id of file, d3 : relation type.
evOURelationStackStateUpdate 834

The stack state (expanded/contracted) changed, d1 : id of stack, d2 : relation type.
evOURelationStackTopUpdate 835

The stack top was changed (d1 : id of stack, d2 : id of new top).
evOUFileHistoryAdd 900

Added a history entry for a file (d1 : id of file, d2 : Type of event).
Event types:
1: File added
2: File updated
20: File moved
21: File copied
22: File renamed
50: Category assignment(s) changed
60: Metadata changed
70: Annotations changed

Tasks:
100: File viewed
101: File printed
102: File emailed
103: File edited

User Events:
1000: User-generated event
evOUFileHistoryUpdate 901

Updated a history entry for a file. d1 : id of file, d2 : Type of event.
evOUFileHistoryDelete 902

Deleted a history entry for a file. d1 : id of file, d2 : Type of event.
evOUFileHistoryPurge 903

Purged the history for a file. d1 : id of file. If 0, general purge for all files.
evOUMDTUpdate 950

Metadata Templates updated.
evOUGeoLocationsUpdate 1000

Geo Locations updated.
evOUAnnoUpdate 1100

Annotations for file updated. d1: id of file.
evOUAnnoRemove 1101

Annotations for file removed. d1: id of file.
evOUAnnoCopy 1102

Annotations copied. d1: source file id, d2: desitination file id.
evFileSystem 300

File System Events.
These events are sent when changes in the file system are detected.
evFSDeviceArrived 1
evFSDeviceRemoved 2
evFSCacheUpdated 10
evFSFolderModified 20
evFSFolderDeleted 21
evFSFolderCreated 22
evFSFolderRenamed 23
evFSFileModifed 30
evFSFileDeleted 31
evFSFileCreated 32
evFSFileRenamed 33
evFileOp 700

File System Operation Events
These events are sent during certain long-running batch operations like /folders/add, /folders/rescan, /folders/copy etc.
They are sent only to the app/session which triggered the operation (e.g. the app which used the folders/copy endpoint).
Note that these events are sent while the endpoint call is still running. This enables an app to provide user feedback during long-running batch operations.
evFOBatchBegin 1

Batch operation starts. d1: operation type
evFOBatchEnd 2

Batch operation completed. d1: operation type
evFOBatchError 5

Error during batch operation. This event includes an errorInfo object which tries to provide as much info about hte error as possible.
errorId: FileOpUIError code:
errUnknown : 0,
errDeleteFile : 1,
errCopyFile : 2,
errCopyFileBuddiesDuplicates : 3,
errMoveFile : 4,
errRenameFile : 5,
errRenameFileDuplicateFileName : 6,
errDeleteFolder : 7,
errCopyFolder : 8,
errMoveFolder : 9,
errRenameFolder : 10
lastOSError: Windows error code
id1, id2 : ids of involved objects
name1, name2: name of involved objects
evFOBatchAborted 6

Batch operation aborted by user / app
efFOBatchProgress 10

Progress feedback during batch operations. d1: operation type, d2: percentage of completion (0-100).

Methods

get(endpoint, parameters) → {Promise}

This method takes the name of an endpoint (without leading /) and an optional parameter object.
It perform a GET request on this endpoint with the given parameters and returns a promise.

The method automatically performs authentication using config.auth_token. You don't need to specify the auth_token parameter.

Parameters:
Name Type Description
endpoint string

The endpoint to call. Include the version number as needed.
parameters object

Optionel parameters to send to IMWS.
Returns:
  • A promise object that is resolved once the server has responded.
Type
Promise
Examples
// Calls the /info endpoint to retrieve information about IMWS and the database.
IMWS.get('/info').then(...
// Retrieves data for files using the /files endpoint. The files with the id 1,2,3 are queried
// and for each file the fields id, name and size are to be returned.
IMWS.get('v1/files',{
     id: "1,2,3", 
     fields: "id,name,size"
}).then(function(response) {
     response.files.forEach(...)
});

post(endpoint, parameters) → {Promise}

This method takes the name of an endpoint (without leading /) and an optional parameter object.
It perform a POST request on this endpoint with the given parameters and returns a promise.

The method automatically performs authentication using config.auth_token. You don't need to specify the auth_token parameter.

Parameters:
Name Type Description
endpoint String
parameters Object

Optional object with parameters to send to the server.
Returns:
  • A promise object that is resolved once the server has responded.
Type
Promise
Example
// Call an endpoint which requies the POST method:
IMatch.post('name of endpoint', ...)

delete(endpoint, parameters) → {Promise}

This method takes the name of an endpoint (without leading /) and an optional parameter object.
It perform a DELETE request on this endpoint with the given parameters and returns a promise.

The method automatically performs authentication using config.auth_token. You don't need to specify the auth_token parameter.

Parameters:
Name Type Description
endpoint String
parameters Object

Optional object with parameters to send to the server.
Returns:
  • A promise object that is resolved once the server has responded.
Type
Promise
Example
// Call an endpoint which requies the DELETE method:
IMatch.delete('name of endpoint', ...)

init(params)

Initialize this class.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
imwsUrl String

The URL of the IMatch WebServices instance to use.

authenticate(params) → {Promise}

Endpoint: /authenticate.
Authenticate the current session.
This is the first method to call. It logs into IMWS and stores the
session token in the config member.

Parameters:
Name Type Description
params Object

Login data

Properties
Name Type Description
id String

User name.
Use IMWS_DEFAULT_USER if the authentication in IMWS is disabled - unless a different default user name is configured on the server.
password String

password.
Use an empty password if authentication is disabled.
appid String

(Optional) The app id.
This is only needed when IMWS has been configured to accept only specific apps.
Returns:

If it resolves, the log-in was successful.

Type
Promise
Example
// Log in user 'Tom' with password 'secret'
IMWS.authenticate({
     id: "Tom", 
     password: "secret"
}).then(function(response) {
     // Successfully logged in. The IMWS instance now has the auth_token and other user
     // data in the IMWS.config object.
});

webSocket() → {WebSocket}

This function gives access to a web socket that allows your script to exchange messages with IMWS and to receive information about events or changes madeto the database.

The socket can been opened with IMWS#openWebSocket.

Returns:

The opened web socket or null if no web socket was opened.

Type
WebSocket

openWebSocket(url, authToken)

Open a web socket for the /imws url. The socket can then be used to send and receive messages from IMatch.
This method automatically authenticates the socket after creating it.

Embedded
If this is called from an app running in IMatch you don't need to specify {@param url} or {@param authToken}.
Otherwise specifiy the full URL and port, e.g., ws://127.0.0.1:50519 and the authentication token.

Parameters:
Name Type Description
url String

Optional. The web socket URL.
authToken String

Optional. The authentication token received from the /authenticate endpoint.

dataGet(params) → {Promise}

Endpoint: /v1/data

This method retrieves previously stored data.
The /data endpoints are basically a small 'cloud' storage facility managed by IMWS. You can store arbitrary text data (including stringified JSON data) using these endpoints. This is an easy way to store script settings or user preferences.

Each item is idenfied using a unique name (whatever you like).
Names starting with @ & or # are reserved for system usage.

IMWS associates the data with the current user and application id (if one was provided during /authenticate). Each user has its own isolated data store.
The maximum amount of data that can be stored per user is controlled via IMWS settings. By default, 1 MB of data can be stored per user, which is plenty.

Embedded
If this is used from an app using the embedded IMWS in IMatch, the data is not associated with a specific user.
This allows you to store global and per-user settings, depending on what you need. If you want to store settings per-user, include the user name in the name parameter.
The embedded IMWS in IMatch enforces no storage limit.

Parameters:
Name Type Description
params Object

Parameters to send to IMWS.

Properties
Name Type Argument Default Description
name String

name of the data item to retrieve.
target String <optional>
 'global'

Supported are 'global' (data stored in the settings database) and 'database' (data stored in the IMatch database).
encryption Boolean <optional>
 false

Set this to true if the data was saved with encryption.
password Boolean <optional>

The password used to encrypt the data.
Returns:
Type
Promise
Example
// Retrieves the data item named 'myapp.note'
IMWS.dataGet(
     {name: "myapp.note"
}).then(function(response) {
     console.log(response.value);
});

dataSet(params) → {Promise}

Endpoint: /v1/data

This method creates or updates a new data item.

Parameters:
Name Type Description
params Object

Parameters to send to IMWS.

Properties
Name Type Argument Default Description
name String

name of the data item to create or update
value String

the value to set. Only text is allowed. Use JSON.stringify to store arbitrary JSON data.
target String <optional>
 'global'

Where to store the data. Supported are 'global' (data is stored in the settings database) and 'database' (data is stored in the IMatch database).
encryption Boolean <optional>
 false

If this is true, the data is encrypted using password before storing it. This can be used as an extra safety measure (don't hard-code the password in yoru app!).
password Boolean <optional>

The password to use when encryption is used. You should specify a fairly long and complex password (or let the user choose one).
Returns:
Type
Promise
Example
// Add/update the data item named 'myapp.note'
IMWS.dataSet({
     name: "myapp.note",
     value: "This is the new note I want to store."
});

dataList(params) → {Promise}

Endpoint: /v1/data/list

This method allows to query existing data objects.

Parameters:
Name Type Description
params Object

Parameters to send to IMWS.

Properties
Name Type Argument Default Description
name String

PERL regular expression. Use .* to retireve a list of all stored items.
target String <optional>
 'global'

Supported are 'global' (data stored in the settings database) and 'database' (data stored in the IMatch database).
Returns:
Type
Promise

dataDelete(params) → {Promise}

Endpoint: /v1/data

Deletes a previously stored data item.

Parameters:
Name Type Description
params Object

Parameters to send to IMWS.

Properties
Name Type Argument Default Description
name String

name of the data item to delete.
target String <optional>
 'global'

Supported are 'global' (data stored in the settings database) and 'database' (data stored in the IMatch database).
Returns:
Type
Promise