## agile ⇒ Object Welcome to the Agile SDK documentation. This document aims to describe all the functions supported by the SDK, as well as showing examples of their expected usage. If you feel something is missing, not clear or could be improved, please don't hesitate to open an [issue in GitHub](https://github.com/agile-iot/agile-sdk/issues/new), we'll be happy to help. **Kind**: global namespace | Type | Description | | --- | --- | | Object | including the api base url, idm base url (if not provided defaults to the same api host but default idm port), and a token. | **Example** ```js var agile = require('agile-sdk')({ api:'http://agile-core:8080', idm: 'http://agile-core:3000', data: 'http://agile-data:1338', token: 'zIOycOqbEQh4ayw7lGAm9ILBIr' }) ``` * [agile](#agile) ⇒ Object * [.protocolManager](#agile.protocolManager) : object * [.discovery](#agile.protocolManager.discovery) : object * [.start([protocolId])](#agile.protocolManager.discovery.start) ⇒ Promise * [.stop([protocolId])](#agile.protocolManager.discovery.stop) ⇒ Promise * [.status([protocolId])](#agile.protocolManager.discovery.status) ⇒ Promise * [.get()](#agile.protocolManager.get) ⇒ Promise * [.delete(protocolId)](#agile.protocolManager.delete) ⇒ Promise * [.create(protocolId)](#agile.protocolManager.create) ⇒ Promise * [.devices()](#agile.protocolManager.devices) ⇒ Promise * [.deviceManager](#agile.deviceManager) : object * [.get([deviceId])](#agile.deviceManager.get) ⇒ Promise * [.delete(deviceId)](#agile.deviceManager.delete) ⇒ Promise * [.create(deviceOverview, type)](#agile.deviceManager.create) ⇒ Promise * [.typeof(deviceOverview)](#agile.deviceManager.typeof) ⇒ Promise * [.device](#agile.device) : object * [.status(deviceId)](#agile.device.status) ⇒ Promise * [.get(deviceId, [componentId])](#agile.device.get) ⇒ Promise * [.connect(deviceId)](#agile.device.connect) ⇒ Promise * [.disconnect(deviceId)](#agile.device.disconnect) ⇒ Promise * [.execute(deviceId, command)](#agile.device.execute) ⇒ Promise * [.lastUpdate(deviceId, [componentId])](#agile.device.lastUpdate) ⇒ Promise * [.subscribe(deviceId, componentId)](#agile.device.subscribe) ⇒ Promise * [.unsubscribe(deviceId, componentId)](#agile.device.unsubscribe) ⇒ Promise * [.protocol](#agile.protocol) : object * [.disconnect(protocolId, deviceId)](#agile.protocol.disconnect) ⇒ Promise * [.connect(protocolId, deviceId)](#agile.protocol.connect) ⇒ Promise * [.read(protocolId, deviceId)](#agile.protocol.read) ⇒ Promise * [.write(protocolId, deviceId, data)](#agile.protocol.write) ⇒ Promise * [.idm](#agile.idm) : object * [.group](#agile.idm.group) : object * [.get([owner], [groupName])](#agile.idm.group.get) ⇒ Promise * [.create(groupName)](#agile.idm.group.create) ⇒ Promise * [.delete(owner, groupName)](#agile.idm.group.delete) ⇒ Promise * [.addEntity(containing)](#agile.idm.group.addEntity) ⇒ Promise * [.removeEntity(containing)](#agile.idm.group.removeEntity) ⇒ Promise * [.user](#agile.idm.user) : object * [.getCurrentUserInfo()](#agile.idm.user.getCurrentUserInfo) ⇒ Promise * [.get(userName, authType)](#agile.idm.user.get) ⇒ Promise * [.create(including, authType, [options])](#agile.idm.user.create) ⇒ Promise * [.delete(userName, authType)](#agile.idm.user.delete) ⇒ Promise * [.resetPassword(userName, authType, newPassword)](#agile.idm.user.resetPassword) ⇒ Promise * [.updatePassword(oldPassword, newPassword)](#agile.idm.user.updatePassword) ⇒ Promise * [.entity](#agile.idm.entity) : object * [.getByType(entityType)](#agile.idm.entity.getByType) ⇒ Promise * [.getByAttributeValue(constraints)](#agile.idm.entity.getByAttributeValue) ⇒ Promise * [.get(entityId, entityType)](#agile.idm.entity.get) ⇒ Promise * [.create(entityId, entityType, entity)](#agile.idm.entity.create) ⇒ Promise * [.delete(entityId, entityType)](#agile.idm.entity.delete) ⇒ Promise * [.setAttribute(with)](#agile.idm.entity.setAttribute) ⇒ Promise * [.deleteAttribute(entityId, entityType, attributeName-)](#agile.idm.entity.deleteAttribute) ⇒ Promise * [.getEntitiesSchema()](#agile.idm.entity.getEntitiesSchema) ⇒ Promise * [.authentication](#agile.idm.authentication) : object * [.authenticateClient(client, secret)](#agile.idm.authentication.authenticateClient) ⇒ Promise * [.data](#agile.data) : object * [.subscription](#agile.data.subscription) : object * [.create([subscription])](#agile.data.subscription.create) ⇒ Promise * [.delete([subscriptionID])](#agile.data.subscription.delete) ⇒ Promise * [.update([subscriptionID], [subscription])](#agile.data.subscription.update) ⇒ Promise * [.get([subscriptionID])](#agile.data.subscription.get) ⇒ Promise * [.record](#agile.data.record) : object * [.get([query])](#agile.data.record.get) ⇒ Promise * [.settings](#agile.data.settings) : object * [.get()](#agile.data.settings.get) ⇒ Promise * [.update(settings)](#agile.data.settings.update) ⇒ Promise * [.policies](#agile.policies) : object * [.pdp](#agile.policies.pdp) : object * [.evaluate(PDP)](#agile.policies.pdp.evaluate) ⇒ Promise * [.pap](#agile.policies.pap) : object * [.get(including)](#agile.policies.pap.get) ⇒ Promise * [.set(including)](#agile.policies.pap.set) ⇒ Promise * [.delete(including)](#agile.policies.pap.delete) ⇒ Promise * [.audit](#agile.audit) : object * [.getUserActions()](#agile.audit.getUserActions) ⇒ Promise * [.getActionsOnUsersEntities()](#agile.audit.getActionsOnUsersEntities) ⇒ Promise * [.cleanActionsOnUsersEntities()](#agile.audit.cleanActionsOnUsersEntities) ⇒ Promise * [.tokenSet(token)](#agile.tokenSet) ⇒ String * [.tokenGet()](#agile.tokenGet) ⇒ String * [.tokenDelete()](#agile.tokenDelete) ⇒ String ### agile.protocolManager : object **Kind**: static namespace of [agile](#agile) * [.protocolManager](#agile.protocolManager) : object * [.discovery](#agile.protocolManager.discovery) : object * [.start([protocolId])](#agile.protocolManager.discovery.start) ⇒ Promise * [.stop([protocolId])](#agile.protocolManager.discovery.stop) ⇒ Promise * [.status([protocolId])](#agile.protocolManager.discovery.status) ⇒ Promise * [.get()](#agile.protocolManager.get) ⇒ Promise * [.delete(protocolId)](#agile.protocolManager.delete) ⇒ Promise * [.create(protocolId)](#agile.protocolManager.create) ⇒ Promise * [.devices()](#agile.protocolManager.devices) ⇒ Promise #### protocolManager.discovery : object **Kind**: static namespace of [protocolManager](#agile.protocolManager) * [.discovery](#agile.protocolManager.discovery) : object * [.start([protocolId])](#agile.protocolManager.discovery.start) ⇒ Promise * [.stop([protocolId])](#agile.protocolManager.discovery.stop) ⇒ Promise * [.status([protocolId])](#agile.protocolManager.discovery.status) ⇒ Promise ##### discovery.start([protocolId]) ⇒ Promise **Kind**: static method of [discovery](#agile.protocolManager.discovery) **Summary**: Start device discovery on all or single protocol **Access:** public **Fulfil**: null | Param | Description | | --- | --- | | [protocolId] | Agile protocol Id | **Example** ```js agile.protocolManager.discovery.start().then(function() { console.log('All protocols discovery is on'); }); agile.protocolManager.discovery.start('Bluetooth LE').then(function() { console.log('Bluetooth LE protocols discovery is on'); }); ``` ##### discovery.stop([protocolId]) ⇒ Promise **Kind**: static method of [discovery](#agile.protocolManager.discovery) **Summary**: Stop device discovery on all or single protocol **Access:** public **Fulfil**: null | Param | Description | | --- | --- | | [protocolId] | Agile protocol Id | **Example** ```js agile.protocolManager.discovery.stop().then(function() { console.log('All protocols discovery is off'); }); agile.protocolManager.discovery.stop('Bluetooth LE').then(function() { console.log('Bluetooth LE discovery is off'); }); ``` ##### discovery.status([protocolId]) ⇒ Promise **Kind**: static method of [discovery](#agile.protocolManager.discovery) **Summary**: Return the status object of discovery on the all or single protocol **Access:** public **Fulfil**: Array\|Object | Param | Description | | --- | --- | | [protocolId] | Agile protocol Id | **Example** ```js agile.protocolManager.discovery.status().then(function(protocols) { console.log(protocols); }); agile.protocolManager.discovery.status('Bluetooth LE').then(function(protocol) { console.log(protocol.status); }); ``` #### protocolManager.get() ⇒ Promise **Kind**: static method of [protocolManager](#agile.protocolManager) **Summary**: Get the list of registered protocols **Access:** public **Fulfil**: Array - protocols **Example** ```js agile.protocolManager.protocols.get().then(function(protocols) { console.log(protocols); }); ``` #### protocolManager.delete(protocolId) ⇒ Promise **Kind**: static method of [protocolManager](#agile.protocolManager) **Summary**: Unregister a Dbus Protocol object reference **Access:** public **Fulfil**: null | Param | Type | Description | | --- | --- | --- | | protocolId | String | Agile protocol Id | **Example** ```js agile.protocolManager.protocols.delete(protocolId).then(function() { console.log('protocol has been unregistered'); }); ``` #### protocolManager.create(protocolId) ⇒ Promise **Kind**: static method of [protocolManager](#agile.protocolManager) **Summary**: Register a new Dbus object implementing the protocol API **Access:** public **Fulfil**: null | Param | Type | Description | | --- | --- | --- | | protocolId | String | Agile protocol Id | **Example** ```js agile.protocolManager.protocols.create(protocolId).then(function() { console.log('protocol has been registered'); }); ``` #### protocolManager.devices() ⇒ Promise **Kind**: static method of [protocolManager](#agile.protocolManager) **Summary**: List all discovered devices on all available protocols **Access:** public **Fulfil**: Array - devices **Example** ```js agile.protocolManager.devices().then(function(devices) { console.log(devices); }); ``` ### agile.deviceManager : object **Kind**: static namespace of [agile](#agile) * [.deviceManager](#agile.deviceManager) : object * [.get([deviceId])](#agile.deviceManager.get) ⇒ Promise * [.delete(deviceId)](#agile.deviceManager.delete) ⇒ Promise * [.create(deviceOverview, type)](#agile.deviceManager.create) ⇒ Promise * [.typeof(deviceOverview)](#agile.deviceManager.typeof) ⇒ Promise #### deviceManager.get([deviceId]) ⇒ Promise **Kind**: static method of [deviceManager](#agile.deviceManager) **Summary**: Get all or single device definition **Access:** public **Fulfil**: Array - devices | Param | Type | Description | | --- | --- | --- | | [deviceId] | String | Agile device Id | **Example** ```js agile.deviceManager.get('bleB0B448BE5084').then(function(device) { console.log(device); }); ``` #### deviceManager.delete(deviceId) ⇒ Promise **Kind**: static method of [deviceManager](#agile.deviceManager) **Summary**: Delete a device definition and unregister it **Access:** public **Fulfil**: undefined | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | **Example** ```js agile.deviceManager.delete('bleB0B448BE5084').then(function() { console.log('Device bleB0B448BD1085 deleted'); }); ``` #### deviceManager.create(deviceOverview, type) ⇒ Promise **Kind**: static method of [deviceManager](#agile.deviceManager) **Summary**: Register a new device based on information from ProtocolManager and device type **Access:** public **Fulfil**: Object - device | Param | Type | | --- | --- | | deviceOverview | Object | | type | string | **Example** ```js const deviceOverview = { "name": "CC2650 SensorTag", "protocol": "iot.agile.protocol.BLE", "id": "B0:B4:48:BD:10:85", "status": "CONNECTED" }; const type = "TI SensorTag"; agile.deviceManager.create(deviceOverview, type).then(function(newDevice) { console.log(newDevice); }); ``` #### deviceManager.typeof(deviceOverview) ⇒ Promise **Kind**: static method of [deviceManager](#agile.deviceManager) **Summary**: Get matching types for a device overview **Access:** public **Fulfil**: Array - deviceTypes | Param | Type | | --- | --- | | deviceOverview | Object | **Example** ```js const deviceOverview = { "name": "CC2650 SensorTag", "protocol": "iot.agile.protocol.BLE", "id": "B0:B4:48:BD:10:85", "status": "CONNECTED" }; agile.deviceManager.typeof(deviceOverview).then(function(deviceTypes) { console.log(deviceTypes); }); ``` ### agile.device : object **Kind**: static namespace of [agile](#agile) * [.device](#agile.device) : object * [.status(deviceId)](#agile.device.status) ⇒ Promise * [.get(deviceId, [componentId])](#agile.device.get) ⇒ Promise * [.connect(deviceId)](#agile.device.connect) ⇒ Promise * [.disconnect(deviceId)](#agile.device.disconnect) ⇒ Promise * [.execute(deviceId, command)](#agile.device.execute) ⇒ Promise * [.lastUpdate(deviceId, [componentId])](#agile.device.lastUpdate) ⇒ Promise * [.subscribe(deviceId, componentId)](#agile.device.subscribe) ⇒ Promise * [.unsubscribe(deviceId, componentId)](#agile.device.unsubscribe) ⇒ Promise #### device.status(deviceId) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Get the device status **Access:** public **Fulfil**: String - status | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | **Example** ```js agile.device.status('bleB0B448BE5084').then(function(status) { console.log(status); }); ``` #### device.get(deviceId, [componentId]) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Read values of all components from the device **Access:** public **Fulfil**: Object\|Array Single Component readings returned as object, Device readings returned as Array of Objects. | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | | [componentId] | String | Agile component name, like a sensor | **Example** ```js agile.device.get('bleB0B448BE5084').then(function(deviceComponents) { console.log(deviceComponents); }); ``` **Example** ```js agile.device.get('bleB0B448BE5084', 'Temperature').then(function(deviceComponent) { console.log(deviceComponent); }); ``` #### device.connect(deviceId) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Connect the device at protocol level **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | **Example** ```js agile.device.connect('bleB0B448BE5084').then(function() { console.log('Connected!'); }); ``` #### device.disconnect(deviceId) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Disconnect device at protocol level **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | **Example** ```js agile.device.disconnect('bleB0B448BE5084').then(function() { console.log('Disconnected!'); }); ``` #### device.execute(deviceId, command) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Perform an action on the device **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | | command | String | Operation name to be performed | **Example** ```js agile.device.execute('bleB0B448BE5084', command).then(function() { console.log(`executed ${command}!``); }); ``` #### device.lastUpdate(deviceId, [componentId]) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Get the last record fetched from the device or component **Access:** public **Fulfil**: Object\|Array Single Component readings returned as object, Device readings returned as Array of Objects. | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | | [componentId] | String | Agile component name, like a sensor | **Example** ```js agile.device.lastUpdate('bleB0B448BE5084', 'Temperature').then(function(temperatureReading) { console.log(temperatureReading); }); ``` **Example** ```js agile.device.lastUpdate('bleB0B448BE5084').then(function(componentsReading) { console.log(componentsReading); }); ``` #### device.subscribe(deviceId, componentId) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Enable a subscription to a data stream. Asynchronous data updates will be delivered via websocket. **Access:** public **Fulfil**: Object - websocket instance - https://www.w3.org/TR/websockets/ | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | | componentId | String | Operation name to be performed | **Example** ```js agile.device.subscribe('bleB0B448BE5084', 'Temperature').then(function(stream) { stream.onerror = () => { console.log('Connection Error'); }; stream.onopen = () => { console.log('WebSocket Client Connected'); }; stream.onclose = () => { console.log('echo-protocol Client Closed'); }; stream.onmessage = (e) => { if (typeof e.data === 'string') { console.log("Received: '" + e.data + "'"); } }; }); ``` #### device.unsubscribe(deviceId, componentId) ⇒ Promise **Kind**: static method of [device](#agile.device) **Summary**: Unsubscribe from a data stream **Access:** public **Fulfil**: undefined | Param | Type | Description | | --- | --- | --- | | deviceId | String | Agile device Id | | componentId | String | Agile component name, like a sensor | **Example** ```js agile.device.unsubscribe('bleB0B448BE5084', 'Temperature').then(function() { console.log('Unsubscribed!'); }); ``` ### agile.protocol : object **Kind**: static namespace of [agile](#agile) * [.protocol](#agile.protocol) : object * [.disconnect(protocolId, deviceId)](#agile.protocol.disconnect) ⇒ Promise * [.connect(protocolId, deviceId)](#agile.protocol.connect) ⇒ Promise * [.read(protocolId, deviceId)](#agile.protocol.read) ⇒ Promise * [.write(protocolId, deviceId, data)](#agile.protocol.write) ⇒ Promise #### protocol.disconnect(protocolId, deviceId) ⇒ Promise **Kind**: static method of [protocol](#agile.protocol) **Summary**: Disconnect from the device **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | protocolId | String | Agile Id of the protocol | | deviceId | String | Agile internal Id of the protocol | **Example** ```js agile.protocol.disconnect('Bluetooth LE', 'bleB0B448BE5084').then(function() { console.log('Disconnected!'); }); ``` #### protocol.connect(protocolId, deviceId) ⇒ Promise **Kind**: static method of [protocol](#agile.protocol) **Summary**: Connect to the device **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | protocolId | String | Agile Id of the protocol | | deviceId | String | Agile internal Id of the protocol | **Example** ```js agile.protocol.connect('Bluetooth LE', 'bleB0B448BE5084').then(function() { console.log('Connected!'); }); ``` #### protocol.read(protocolId, deviceId) ⇒ Promise **Kind**: static method of [protocol](#agile.protocol) **Summary**: Call a read via protocol **Access:** public **Fulfil**: Object | Param | Type | Description | | --- | --- | --- | | protocolId | String | Agile Id of the protocol | | deviceId | String | Agile internal Id of the protocol | **Example** ```js agile.protocol.read('Bluetooth LE', 'bleB0B448BE5084').then(function(data) { console.log(data); }); ``` #### protocol.write(protocolId, deviceId, data) ⇒ Promise **Kind**: static method of [protocol](#agile.protocol) **Summary**: Call a write via protocol **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | protocolId | String | Agile Id of the protocol | | deviceId | String | Agile internal Id of the protocol | | data | object | An object containing the content to write | **Example** ```js agile.protocol.write('Bluetooth LE', 'bleB0B448BE5084', data).then(function() { console.log('wrote data!'); }); ``` ### agile.idm : object **Kind**: static namespace of [agile](#agile) * [.idm](#agile.idm) : object * [.group](#agile.idm.group) : object * [.get([owner], [groupName])](#agile.idm.group.get) ⇒ Promise * [.create(groupName)](#agile.idm.group.create) ⇒ Promise * [.delete(owner, groupName)](#agile.idm.group.delete) ⇒ Promise * [.addEntity(containing)](#agile.idm.group.addEntity) ⇒ Promise * [.removeEntity(containing)](#agile.idm.group.removeEntity) ⇒ Promise * [.user](#agile.idm.user) : object * [.getCurrentUserInfo()](#agile.idm.user.getCurrentUserInfo) ⇒ Promise * [.get(userName, authType)](#agile.idm.user.get) ⇒ Promise * [.create(including, authType, [options])](#agile.idm.user.create) ⇒ Promise * [.delete(userName, authType)](#agile.idm.user.delete) ⇒ Promise * [.resetPassword(userName, authType, newPassword)](#agile.idm.user.resetPassword) ⇒ Promise * [.updatePassword(oldPassword, newPassword)](#agile.idm.user.updatePassword) ⇒ Promise * [.entity](#agile.idm.entity) : object * [.getByType(entityType)](#agile.idm.entity.getByType) ⇒ Promise * [.getByAttributeValue(constraints)](#agile.idm.entity.getByAttributeValue) ⇒ Promise * [.get(entityId, entityType)](#agile.idm.entity.get) ⇒ Promise * [.create(entityId, entityType, entity)](#agile.idm.entity.create) ⇒ Promise * [.delete(entityId, entityType)](#agile.idm.entity.delete) ⇒ Promise * [.setAttribute(with)](#agile.idm.entity.setAttribute) ⇒ Promise * [.deleteAttribute(entityId, entityType, attributeName-)](#agile.idm.entity.deleteAttribute) ⇒ Promise * [.getEntitiesSchema()](#agile.idm.entity.getEntitiesSchema) ⇒ Promise * [.authentication](#agile.idm.authentication) : object * [.authenticateClient(client, secret)](#agile.idm.authentication.authenticateClient) ⇒ Promise #### idm.group : object **Kind**: static namespace of [idm](#agile.idm) * [.group](#agile.idm.group) : object * [.get([owner], [groupName])](#agile.idm.group.get) ⇒ Promise * [.create(groupName)](#agile.idm.group.create) ⇒ Promise * [.delete(owner, groupName)](#agile.idm.group.delete) ⇒ Promise * [.addEntity(containing)](#agile.idm.group.addEntity) ⇒ Promise * [.removeEntity(containing)](#agile.idm.group.removeEntity) ⇒ Promise ##### group.get([owner], [groupName]) ⇒ Promise **Kind**: static method of [group](#agile.idm.group) **Summary**: Get a particular group by name and owner **Access:** public **Fulfil**: Array all groups if no arguments are provided, otherwise the group with given name and owner. | Param | Type | Description | | --- | --- | --- | | [owner] | String | Owner of the group | | [groupName] | String | Name of the group | **Example** ```js agile.idm.group.get('agile!@!agile-local','my-group').then(function(group) { console.log('this is my group '+JSON.stringify(group)); }); agile.idm.group.get().then(function(groups) { console.log('these are all groups '+JSON.stringify(groups)); }); ``` ##### group.create(groupName) ⇒ Promise **Kind**: static method of [group](#agile.idm.group) **Summary**: Create a group onwned by the authenticated user **Access:** public **Fulfil**: Object group created | Param | Type | Description | | --- | --- | --- | | groupName | String | Name of the group | **Example** ```js agile.idm.group.create('ble-devices').then(function(group) { console.log('group created!'+group); }); ``` ##### group.delete(owner, groupName) ⇒ Promise **Kind**: static method of [group](#agile.idm.group) **Summary**: Delete a group **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | owner | String | Owner of the group | | groupName | String | Name of the group | **Example** ```js agile.idm.group.delete('agile!@!agile-local','my-group').then(function() { console.log('group removed!'); }); ``` ##### group.addEntity(containing) ⇒ Promise **Kind**: static method of [group](#agile.idm.group) **Summary**: Add entity to a group **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | containing | Object | the owner of the group, the name of the group, the id of the entity to be added to the group, and the Type of the entity | **Example** ```js agile.idm.group.addEntity({ owner: 'agile!@!agile-local', name: 'my-group', entityId: '1', entityType: 'device' }).then(function(updated) { console.log('entity updated !'+updated); }); ``` ##### group.removeEntity(containing) ⇒ Promise **Kind**: static method of [group](#agile.idm.group) **Summary**: Remove entity from a group **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | containing | Object | the owner of the group, the name of the group, the id of the entity to be removed to the group, and the Type of the entity | **Example** ```js agile.idm.group.removeEntity({ owner: 'agile!@!agile-local', name: 'my-group', entityId: '1', entityType: 'device' }).then(function(updated) { console.log('entity updated !'+updated); }); ``` #### idm.user : object **Kind**: static namespace of [idm](#agile.idm) * [.user](#agile.idm.user) : object * [.getCurrentUserInfo()](#agile.idm.user.getCurrentUserInfo) ⇒ Promise * [.get(userName, authType)](#agile.idm.user.get) ⇒ Promise * [.create(including, authType, [options])](#agile.idm.user.create) ⇒ Promise * [.delete(userName, authType)](#agile.idm.user.delete) ⇒ Promise * [.resetPassword(userName, authType, newPassword)](#agile.idm.user.resetPassword) ⇒ Promise * [.updatePassword(oldPassword, newPassword)](#agile.idm.user.updatePassword) ⇒ Promise ##### user.getCurrentUserInfo() ⇒ Promise **Kind**: static method of [user](#agile.idm.user) **Summary**: Get the user information for the user currently logged in, i.e. token provided when agileSDK was created **Access:** public **Fulfil**: Object userInfo - object with user information **Example** ```js agile.idm.user.getCurrentUserInfo().then(function(info) { console.log(info); }); ``` ##### user.get(userName, authType) ⇒ Promise **Kind**: static method of [user](#agile.idm.user) **Summary**: Show information for a particular user by username and authentication type **Access:** public **Fulfil**: Object user found | Param | Type | Description | | --- | --- | --- | | userName | String | user name | | authType | String | authentication type | **Example** ```js agile.idm.user.get('alice','agile-local').then(function(user) { console.log(user); }); ``` ##### user.create(including, authType, [options]) ⇒ Promise **Kind**: static method of [user](#agile.idm.user) **Summary**: Create user **Access:** public **Fulfil**: Object user created | Param | Type | Description | | --- | --- | --- | | including | object | userName user name | | authType | String | authentication type | | [options] | Object | continaing role of the user as 'role' and password as 'password' | **Example** ```js agile.idm.user.create('bob','agile-local',{'role':'admin', 'password':'secret'}).then(function(user) { console.log('user created!'+user); }); ``` ##### user.delete(userName, authType) ⇒ Promise **Kind**: static method of [user](#agile.idm.user) **Summary**: Delete a user **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | userName | String | user name | | authType | String | authentication type | **Example** ```js agile.idm.user.delete('bob','agile-local').then(function() { console.log('user removed!'); }); ``` ##### user.resetPassword(userName, authType, newPassword) ⇒ Promise **Kind**: static method of [user](#agile.idm.user) **Summary**: Reset password for any user. The user executing this action needs to be allowed to do this, e.g. admin. **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | userName | String | user name | | authType | String | authentication type | | newPassword | String | new password | **Example** ```js agile.idm.user.resetPassword('bob','agile-local',"myNewPassword").then(function() { console.log('password updated!'); }); ``` ##### user.updatePassword(oldPassword, newPassword) ⇒ Promise **Kind**: static method of [user](#agile.idm.user) **Summary**: update password for himself **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | oldPassword | String | old password | | newPassword | String | new password | **Example** ```js agile.idm.user.updatePassword("myOldPassword","myNewPassword").then(function() { console.log('password updated!'); }); ``` #### idm.entity : object **Kind**: static namespace of [idm](#agile.idm) * [.entity](#agile.idm.entity) : object * [.getByType(entityType)](#agile.idm.entity.getByType) ⇒ Promise * [.getByAttributeValue(constraints)](#agile.idm.entity.getByAttributeValue) ⇒ Promise * [.get(entityId, entityType)](#agile.idm.entity.get) ⇒ Promise * [.create(entityId, entityType, entity)](#agile.idm.entity.create) ⇒ Promise * [.delete(entityId, entityType)](#agile.idm.entity.delete) ⇒ Promise * [.setAttribute(with)](#agile.idm.entity.setAttribute) ⇒ Promise * [.deleteAttribute(entityId, entityType, attributeName-)](#agile.idm.entity.deleteAttribute) ⇒ Promise * [.getEntitiesSchema()](#agile.idm.entity.getEntitiesSchema) ⇒ Promise ##### entity.getByType(entityType) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: List all entities by type **Access:** public **Fulfil**: Array all entities with a given type | Param | Type | Description | | --- | --- | --- | | entityType | String | type of entity | **Example** ```js agile.idm.entity.getByType('device').then(function(entities) { console.log(entities); }); ``` ##### entity.getByAttributeValue(constraints) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: List all entities which have a particular attribute value **Access:** public **Fulfil**: Array all entities with a given type | Param | Type | Description | | --- | --- | --- | | constraints | Array | contains objects containing objects with the property 'attributeType' to specify the attribute type and with the property 'attributeValue' to specify the expected attribute value | **Example** ```js agile.idm.entity.getByAttributeValue([{attributeType:'credentials.dropbox','attributeValue':'expected attribute value for dropbox credentials'}]).then(function(entities) { console.log(entities); }); ``` ##### entity.get(entityId, entityType) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: get Entity by entity id and type **Access:** public **Fulfil**: Object entity entity | Param | Type | Description | | --- | --- | --- | | entityId | String | id of entity | | entityType | String | type of entity | **Example** ```js agile.idm.entity.get('1','device').then(function(result) { console.log('entity created!'+result); }); ``` ##### entity.create(entityId, entityType, entity) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: Create a group onwned by the authenticated user **Access:** public **Fulfil**: Object entity created | Param | Type | Description | | --- | --- | --- | | entityId | String | id of entity | | entityType | String | type of entity | | entity | object | An object containing the entity | **Example** ```js agile.idm.entity.create('1','device',{'name':'entity name'}).then(function(result) { console.log('entity created!'+result); }); ``` ##### entity.delete(entityId, entityType) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: Delete entity **Access:** public **Fulfil**: Undefined | Param | Type | Description | | --- | --- | --- | | entityId | String | id of entity | | entityType | String | type of entity | **Example** ```js agile.idm.entity.delete('1','device').then(function() { console.log('group removed!'); }); ``` ##### entity.setAttribute(with) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: Set Entity's attribute **Access:** public **Fulfil**: Object entity updated | Param | Type | Description | | --- | --- | --- | | with | Object | entityId - id of entity, entityType - type of entity, attributeName- name of the attribute, attribute - An object or a String containing the entity's attribute value | **Example** ```js agile.idm.entity.setAttribute({ entityId: '1', entityType: 'device', attributeType: 'credentials', attributeValue: {'dropbox':'entity credentials for drop'} }).then(function(result) { console.log('entity created!'+result); }); ``` ##### entity.deleteAttribute(entityId, entityType, attributeName-) ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: Delete Entity's attribute **Access:** public **Fulfil**: Object entity updated entity | Param | Type | Description | | --- | --- | --- | | entityId | String | id of entity | | entityType | String | type of entity | | attributeName- | String | name of the attribute | **Example** ```js agile.idm.entity.deleteAttribute('1','device','credentials').then(function(result) { console.log('entity updated!'+result); }); ``` ##### entity.getEntitiesSchema() ⇒ Promise **Kind**: static method of [entity](#agile.idm.entity) **Summary**: Get Entities schema **Access:** public **Fulfil**: Object JSON Schema with the configuration for the entity format **Example** ```js agile.idm.entity.getEntitiesSchema().then(function(jsonschema) { console.log('schema for the entities'+jsonschema); }); ``` #### idm.authentication : object **Kind**: static namespace of [idm](#agile.idm) ##### authentication.authenticateClient(client, secret) ⇒ Promise **Kind**: static method of [authentication](#agile.idm.authentication) **Summary**: Authenticate a client with client secret and client name. **Access:** public **Fulfil**: Object Authentication information including token_type and access_token | Param | Type | Description | | --- | --- | --- | | client | String | client name. This is the client name provided to the create Entity when you register an Oauth2 client in AGILE-IDM. For more info: https://github.com/Agile-IoT/agile-idm-oauth2-client-example | | secret | String | client secret. This is the client name provided to the create Entity when you register an Oauth2 client in AGILE-IDM. For more info: https://github.com/Agile-IoT/agile-idm-oauth2-client-example | **Example** ```js agile.idm.authentication.authenticateClient('MyAgileClient2','WLnhhc3LnesbYj0GspNA13zgJEroN8V').then(function(result) { console.log(credentials.access_token); console.log(credentials.token_type); }); ``` ### agile.data : object **Kind**: static namespace of [agile](#agile) * [.data](#agile.data) : object * [.subscription](#agile.data.subscription) : object * [.create([subscription])](#agile.data.subscription.create) ⇒ Promise * [.delete([subscriptionID])](#agile.data.subscription.delete) ⇒ Promise * [.update([subscriptionID], [subscription])](#agile.data.subscription.update) ⇒ Promise * [.get([subscriptionID])](#agile.data.subscription.get) ⇒ Promise * [.record](#agile.data.record) : object * [.get([query])](#agile.data.record.get) ⇒ Promise * [.settings](#agile.data.settings) : object * [.get()](#agile.data.settings.get) ⇒ Promise * [.update(settings)](#agile.data.settings.update) ⇒ Promise #### data.subscription : object **Kind**: static namespace of [data](#agile.data) * [.subscription](#agile.data.subscription) : object * [.create([subscription])](#agile.data.subscription.create) ⇒ Promise * [.delete([subscriptionID])](#agile.data.subscription.delete) ⇒ Promise * [.update([subscriptionID], [subscription])](#agile.data.subscription.update) ⇒ Promise * [.get([subscriptionID])](#agile.data.subscription.get) ⇒ Promise ##### subscription.create([subscription]) ⇒ Promise **Kind**: static method of [subscription](#agile.data.subscription) **Summary**: Create subscription for device component **Access:** public **Fulfil**: Object | Param | Type | Description | | --- | --- | --- | | [subscription] | Object | New Subscription configuration | **Example** ```js agile.data.subscription.create({ deviceID: 'myDevice', componentID: 'temperature', interval: 3000, retention: '7d' }) .then(function(subscription) { console.log(subscription); }); ``` ##### subscription.delete([subscriptionID]) ⇒ Promise **Kind**: static method of [subscription](#agile.data.subscription) **Summary**: Delete subscription for device component **Access:** public **Fulfil**: null | Param | Type | Description | | --- | --- | --- | | [subscriptionID] | String | Agile data subscriptionID | **Example** ```js agile.data.subscription.delete('128484893938') .then(function(subscription) { console.log('Subscription deleted!'); }); ``` ##### subscription.update([subscriptionID], [subscription]) ⇒ Promise **Kind**: static method of [subscription](#agile.data.subscription) **Summary**: Update subscription **Access:** public **Fulfil**: Object | Param | Type | Description | | --- | --- | --- | | [subscriptionID] | String | Agile data subscriptionID | | [subscription] | Object | Updated Subscription configuration | **Example** ```js agile.data.subscription.update('5991b583553d6897bd14f87d', { interval : 25000 }) .then(function(subscription) { console.log(subscription); }); ``` ##### subscription.get([subscriptionID]) ⇒ Promise **Kind**: static method of [subscription](#agile.data.subscription) **Summary**: Get single or all subscriptions on gateway **Access:** public **Fulfil**: Object\|Array | Param | Type | Description | | --- | --- | --- | | [subscriptionID] | String | Agile data subscriptionID | **Example** ```js agile.data.subscription.get('5991b583553d6897bd14f87d') .then(function(subscription) { console.log(subscription); }); agile.data.subscription.get() .then(function(subscriptions) { console.log(subscriptions); }); ``` #### data.record : object **Kind**: static namespace of [data](#agile.data) ##### record.get([query]) ⇒ Promise **Kind**: static method of [record](#agile.data.record) **Summary**: Get records from gateway **Access:** public **Fulfil**: Array | Param | Type | Description | | --- | --- | --- | | [query] | String | Basic query that is transformed to influx sql | **Example** ```js agile.data.record.get() .then(function(subscription) { console.log(subscription); }); // you can use any valid mongo-querystring // https://www.npmjs.com/package/mongo-querystring const query = 'deviceID=mySensor' agile.data.record.get(query) .then(function(records) { console.log(records); }); ``` #### data.settings : object **Kind**: static namespace of [data](#agile.data) * [.settings](#agile.data.settings) : object * [.get()](#agile.data.settings.get) ⇒ Promise * [.update(settings)](#agile.data.settings.update) ⇒ Promise ##### settings.get() ⇒ Promise **Kind**: static method of [settings](#agile.data.settings) **Summary**: Get settings for agile data **Access:** public **Fulfil**: Array **Example** ```js agile.data.settings.get() .then(function(settings) { console.log(settings); }); ``` ##### settings.update(settings) ⇒ Promise **Kind**: static method of [settings](#agile.data.settings) **Summary**: Update settings for agile data **Access:** public **Fulfil**: Array | Param | Type | Description | | --- | --- | --- | | settings | Object | Updated settings values | **Example** ```js agile.data.settings.update({ retention: '4d' }) .then(function(newSettings) { console.log(newSettings); }); ``` ### agile.policies : object **Kind**: static namespace of [agile](#agile) * [.policies](#agile.policies) : object * [.pdp](#agile.policies.pdp) : object * [.evaluate(PDP)](#agile.policies.pdp.evaluate) ⇒ Promise * [.pap](#agile.policies.pap) : object * [.get(including)](#agile.policies.pap.get) ⇒ Promise * [.set(including)](#agile.policies.pap.set) ⇒ Promise * [.delete(including)](#agile.policies.pap.delete) ⇒ Promise #### policies.pdp : object **Kind**: static namespace of [policies](#agile.policies) ##### pdp.evaluate(PDP) ⇒ Promise **Kind**: static method of [pdp](#agile.policies.pdp) **Summary**: Evaluate policies for a particular entity and action or attribute **Access:** public **Fulfil**: Array boolean - each elemtn in the array is a boolean value mapeed one-to-one to the PDP requests objects. Each boolean shows whether the policy evaluated in the same potition of the array was allowed or not. | Param | Type | Description | | --- | --- | --- | | PDP | Array | request - each element in the array includes entityId, entityType, field indicating the attribute or action to be executed. Finally the method can be read or write depending on the action to be performed. For instance the example shows the evaluation of a policy showing whether the user logged in can read the attribute password for the user with id sam!@!agile-local | **Example** ```js agile.policies.pdp.evaluate([{ entityId : 'sam!@!agile-local', entityType: 'user', field : 'password', method : 'read' }]).then(function(results) { console.log(results); }); ``` #### policies.pap : object **Kind**: static namespace of [policies](#agile.policies) * [.pap](#agile.policies.pap) : object * [.get(including)](#agile.policies.pap.get) ⇒ Promise * [.set(including)](#agile.policies.pap.set) ⇒ Promise * [.delete(including)](#agile.policies.pap.delete) ⇒ Promise ##### pap.get(including) ⇒ Promise **Kind**: static method of [pap](#agile.policies.pap) **Summary**: Get policies for a particular entity and action or attribute **Access:** public **Fulfil**: Object Policy for the query, in case it is there | Param | Type | Description | | --- | --- | --- | | including | Object | entityType, entityId, and field optionally. If provided, field represents the attribute or action for which the policy is being queried. The example shows how to obtain the (read and write) policy for the user with id sam!@!agile-local. | **Example** ```js agile.policies.pap.get({ entityId : 'sam!@!agile-local', entityType: 'user', field : 'password' }).then(function(results) { console.log(results); }); ``` ##### pap.set(including) ⇒ Promise **Kind**: static method of [pap](#agile.policies.pap) **Summary**: Set policies for a particular entity and action or attribute **Access:** public **Fulfil**: Object Policy for the entity resulting after the update | Param | Type | Description | | --- | --- | --- | | including | Object | entityType, entityId, policy, and field optionally. If provided, field represents the attribute or action for which the policy is being queried. The example shows how to make the password of sam!@!agile-local readable and writable to anyone (do not do this in production!). | **Example** ```js agile.policies.pap.set({ entityId : 'sam!@!agile-local', entityType: 'user', field : 'password', policy : [ { op: "write" }, { op: "read" } ] }).then(function(results) { console.log(results); }); ``` ##### pap.delete(including) ⇒ Promise **Kind**: static method of [pap](#agile.policies.pap) **Summary**: Delete policies for a particular entity and action or attribute **Access:** public **Fulfil**: Object Policy for the entity resulting after the update | Param | Type | Description | | --- | --- | --- | | including | Object | entityType, entityId, and field optionally. If provided, field represents the attribute or action for which the policy is to be deleted. The example shows how to delete the (read and write) policy for the user with id sam!@!agile-local. | **Example** ```js agile.policies.pap.delete({ entityId : 'sam!@!agile-local', entityType: 'user', field : 'password' }).then(function(results) { console.log(results); }); ``` ### agile.audit : object **Kind**: static namespace of [agile](#agile) * [.audit](#agile.audit) : object * [.getUserActions()](#agile.audit.getUserActions) ⇒ Promise * [.getActionsOnUsersEntities()](#agile.audit.getActionsOnUsersEntities) ⇒ Promise * [.cleanActionsOnUsersEntities()](#agile.audit.cleanActionsOnUsersEntities) ⇒ Promise #### audit.getUserActions() ⇒ Promise **Kind**: static method of [audit](#agile.audit) **Summary**: Get actions performed by currently logged in user **Access:** public **Fulfil**: Array Actions actions performed by the user authenticated with the token used by the SDK. Each action has a user, entity and time field to show who executed where action when on which entity. **Example** ```js agile.policies.audit.getUserActions( ).then(function(results) { console.log(results); }); ``` #### audit.getActionsOnUsersEntities() ⇒ Promise **Kind**: static method of [audit](#agile.audit) **Summary**: Get actions performed on entities owned by the user currently logged in **Access:** public **Fulfil**: Array Actions actions performed by the user authenticated with the token used by the SDK. Each action has a user, entity and time field to show who executed where action when on which entity. **Example** ```js agile.policies.audit.getActionsOnUsersEntities( ).then(function(results) { console.log(results); }); ``` #### audit.cleanActionsOnUsersEntities() ⇒ Promise **Kind**: static method of [audit](#agile.audit) **Summary**: Removes actions performed on entities owned by the user currently logged in **Access:** public **Example** ```js agile.policies.audit.cleanActionsOnUsersEntities( ).then(function(results) { console.log(results); }); ``` ### agile.tokenSet(token) ⇒ String **Kind**: static method of [agile](#agile) **Summary**: Set/Update Idm Authentication token **Returns**: String - token - Newly set Idm Authentication token **Access:** public | Param | Type | Description | | --- | --- | --- | | token | String | Idm Authentication token | **Example** ```js agile.tokenSet('1234'); ``` ### agile.tokenGet() ⇒ String **Kind**: static method of [agile](#agile) **Summary**: Get Idm Authentication token **Access:** public **Example** ```js agile.tokenGet(); ``` ### agile.tokenDelete() ⇒ String **Kind**: static method of [agile](#agile) **Summary**: Unset/delete Idm Authentication token **Access:** public **Example** ```js agile.tokenDelete(); ```