2.0.6 - Allows to implicitly link asset to device without specifying every measure names (#258)

Author: Aschen

features/Device/Controller/LinkAsset.feature

@@ -18,6 +18,7 @@ Feature: LinkAsset
       | linkedDevices[0].measureNames[0].asset  | "temperatureExt"      |
       | linkedDevices[0].measureNames[0].device | "temperature"         |
       | _kuzzle_info.updater                    | "-1"                  |
+    # Link second device
     When I successfully execute the action "device-manager/devices":"linkAsset" with args:
       | _id                         | "DummyTemp-unlinked2" |
       | assetId                     | "Container-unlinked1" |
@@ -31,6 +32,34 @@ Feature: LinkAsset
       | linkedDevices[1]._id                    | "DummyTemp-unlinked2" |
       | linkedDevices[1].measureNames[0].asset  | "temperatureInt"      |
 
+  Scenario: Link device with default measure names
+    Given I successfully execute the action "device-manager/devices":"linkAsset" with args:
+      | _id                         | "DummyTemp-unlinked1" |
+      | assetId                     | "Container-unlinked1" |
+      | engineId                    | "engine-ayse"         |
+      | body.measureNames[0].device | "temperature"         |
+      | body.measureNames[0].asset  | "temperatureExt"      |
+    When I successfully execute the action "device-manager/devices":"linkAsset" with args:
+      | _id                         | "DummyTempPosition-unlinked3" |
+      | assetId                     | "Container-unlinked1"         |
+      | engineId                    | "engine-ayse"                 |
+      | implicitMeasuresLinking     | true                          |
+      | body.measureNames[0].device | "temperature"                 |
+      | body.measureNames[0].asset  | "temperatureInt"              |
+    And The document "engine-ayse":"assets":"Container-unlinked1" content match:
+      # Keep the previously linked measure
+      | linkedDevices[0]._id                    | "DummyTemp-unlinked1"         |
+      | linkedDevices[0].measureNames[0].asset  | "temperatureExt"              |
+      | linkedDevices[0].measureNames[0].device | "temperature"                 |
+      # Explicitly linked measure
+      | linkedDevices[1]._id                    | "DummyTempPosition-unlinked3" |
+      | linkedDevices[1].measureNames.length    | 2                             |
+      | linkedDevices[1].measureNames[0].asset  | "temperatureInt"              |
+      | linkedDevices[1].measureNames[0].device | "temperature"                 |
+      # Implicitly linked measure
+      | linkedDevices[1].measureNames[1].asset  | "position"                    |
+      | linkedDevices[1].measureNames[1].device | "position"                    |
+
   Scenario: Error when device is already linked
     When I execute the action "device-manager/devices":"linkAsset" with args:
       | _id                         | "DummyTemp-linked1"   |

features/fixtures/fixtures.js

@@ -46,6 +46,16 @@ const deviceAyseUnlinked2 = {
 };
 const deviceAyseUnlinked2Id = `${deviceAyseUnlinked2.model}-${deviceAyseUnlinked2.reference}`;
 
+const deviceAyseUnlinked3 = {
+  model: "DummyTempPosition",
+  reference: "unlinked3",
+  metadata: {},
+  measures: {},
+  engineId: "engine-ayse",
+  assetId: null,
+};
+const deviceAyseUnlinked3Id = `${deviceAyseUnlinked3.model}-${deviceAyseUnlinked3.reference}`;
+
 const assetAyseLinked1 = {
   model: "Container",
   reference: "linked1",
@@ -97,14 +107,21 @@ module.exports = {
     devices: [
       { index: { _id: deviceAyseLinked1Id } },
       deviceAyseLinked1,
+
       { index: { _id: deviceAyseLinked2Id } },
       deviceAyseLinked2,
+
       { index: { _id: deviceDetached1Id } },
       deviceDetached1,
+
       { index: { _id: deviceAyseUnlinked1Id } },
       deviceAyseUnlinked1,
+
       { index: { _id: deviceAyseUnlinked2Id } },
       deviceAyseUnlinked2,
+
+      { index: { _id: deviceAyseUnlinked3Id } },
+      deviceAyseUnlinked3,
     ],
   },
 
@@ -113,18 +130,26 @@ module.exports = {
     devices: [
       { index: { _id: deviceAyseLinked1Id } },
       deviceAyseLinked1,
+
       { index: { _id: deviceAyseLinked2Id } },
       deviceAyseLinked2,
+
       { index: { _id: deviceAyseUnlinked1Id } },
       deviceAyseUnlinked1,
+
       { index: { _id: deviceAyseUnlinked2Id } },
       deviceAyseUnlinked2,
+
+      { index: { _id: deviceAyseUnlinked3Id } },
+      deviceAyseUnlinked3,
     ],
     assets: [
       { index: { _id: assetAyseLinked1Id } },
       assetAyseLinked1,
+
       { index: { _id: assetAyseLinked2Id } },
       assetAyseLinked2,
+
       { index: { _id: assetAyseUnlinkedId } },
       assetAyseUnlinked,
     ],

lib/modules/device/DeviceService.ts

@@ -18,7 +18,12 @@ import {
 } from "./../asset";
 import { InternalCollection, DeviceManagerConfiguration } from "../../core";
 import { Metadata, lock, ask, onAsk } from "../shared";
-import { AskModelDeviceGet } from "../model";
+import {
+  AskModelAssetGet,
+  AskModelDeviceGet,
+  AssetModelContent,
+  DeviceModelContent,
+} from "../model";
 import { MeasureContent } from "../measure";
 
 import { DeviceContent } from "./types/DeviceContent";
@@ -417,13 +422,17 @@ export class DeviceService {
     deviceId: string,
     assetId: string,
     measureNames: ApiDeviceLinkAssetRequest["body"]["measureNames"],
-    { refresh }: { refresh?: any } = {}
+    {
+      refresh,
+      implicitMeasuresLinking,
+    }: { refresh?: any; implicitMeasuresLinking?: boolean } = {}
   ): Promise<{
     asset: KDocument<AssetContent>;
     device: KDocument<DeviceContent>;
   }> {
     return lock(`device:linkAsset:${deviceId}`, async () => {
       const device = await this.get(this.config.adminIndex, deviceId);
+      const engine = await this.getEngine(engineId);
 
       this.checkAttachedToEngine(device);
 
@@ -445,7 +454,26 @@ export class DeviceService {
         assetId
       );
 
-      this.checkAssetMeasureNamesAvailability(asset, measureNames);
+      const [assetModel, deviceModel] = await Promise.all([
+        ask<AskModelAssetGet>("ask:device-manager:model:asset:get", {
+          engineGroup: engine.group,
+          model: asset._source.model,
+        }),
+        ask<AskModelDeviceGet>("ask:device-manager:model:device:get", {
+          model: device._source.model,
+        }),
+      ]);
+
+      this.checkAlreadyProvidedMeasures(asset, measureNames);
+
+      if (implicitMeasuresLinking) {
+        this.generateMissingAssetMeasureNames(
+          asset,
+          assetModel,
+          deviceModel,
+          measureNames
+        );
+      }
 
       device._source.assetId = assetId;
       asset._source.linkedDevices.push({
@@ -514,22 +542,68 @@ export class DeviceService {
    * Checks if the asset does not already have a linked device using one of the
    * requested measure names.
    */
-  private checkAssetMeasureNamesAvailability(
+  private checkAlreadyProvidedMeasures(
     asset: KDocument<AssetContent>,
-    measureNames: ApiDeviceLinkAssetRequest["body"]["measureNames"]
+    requestedMeasureNames: ApiDeviceLinkAssetRequest["body"]["measureNames"]
   ) {
-    const requestedMeasuresNames = measureNames.map((m) => m.asset);
+    const measureAlreadyProvided = (assetMeasureName: string): boolean => {
+      return asset._source.linkedDevices.some((link) =>
+        link.measureNames.some((names) => names.asset === assetMeasureName)
+      );
+    };
 
-    for (const link of asset._source.linkedDevices) {
-      const existingMeasureNames = link.measureNames.map((m) => m.asset);
+    for (const name of requestedMeasureNames) {
+      if (measureAlreadyProvided(name.asset)) {
+        throw new BadRequestError(
+          `Measure name "${name.asset}" is already used by another device on this asset.`
+        );
+      }
+    }
+  }
 
-      for (const requestedMeasuresName of requestedMeasuresNames) {
-        if (existingMeasureNames.includes(requestedMeasuresName)) {
-          throw new BadRequestError(
-            `Measure name "${requestedMeasuresName}" is already used by another device on this asset.`
-          );
-        }
+  /**
+   * Goes through the device available measures and add them into the link if:
+   *  - they are not already provided by another device
+   *  - they are not already present in the link request
+   *  - they are declared in the asset model
+   */
+  private generateMissingAssetMeasureNames(
+    asset: KDocument<AssetContent>,
+    assetModel: AssetModelContent,
+    deviceModel: DeviceModelContent,
+    requestedMeasureNames: ApiDeviceLinkAssetRequest["body"]["measureNames"]
+  ) {
+    const measureAlreadyProvided = (deviceMeasureName: string): boolean => {
+      return asset._source.linkedDevices.some((link) =>
+        link.measureNames.some((names) => names.device === deviceMeasureName)
+      );
+    };
+
+    const measureAlreadyRequested = (deviceMeasureName: string): boolean => {
+      return requestedMeasureNames.some(
+        (names) => names.device === deviceMeasureName
+      );
+    };
+
+    const measureUndeclared = (deviceMeasureName: string): boolean => {
+      return !assetModel.asset.measures.some(
+        (measure) => measure.name === deviceMeasureName
+      );
+    };
+
+    for (const deviceMeasure of deviceModel.device.measures) {
+      if (
+        measureAlreadyRequested(deviceMeasure.name) ||
+        measureAlreadyProvided(deviceMeasure.name) ||
+        measureUndeclared(deviceMeasure.name)
+      ) {
+        continue;
       }
+
+      requestedMeasureNames.push({
+        asset: deviceMeasure.name,
+        device: deviceMeasure.name,
+      });
     }
   }
 
@@ -703,4 +777,14 @@ export class DeviceService {
       );
     }
   }
+
+  private async getEngine(engineId: string): Promise<JSONObject> {
+    const engine = await this.sdk.document.get(
+      this.config.adminIndex,
+      InternalCollection.CONFIG,
+      `engine-device-manager--${engineId}`
+    );
+
+    return engine._source.engine;
+  }
 }

lib/modules/device/DevicesController.ts

@@ -237,6 +237,9 @@ export class DevicesController {
     const measureNames = request.getBodyArray(
       "measureNames"
     ) as ApiDeviceLinkAssetRequest["body"]["measureNames"];
+    const implicitMeasuresLinking = request.getBoolean(
+      "implicitMeasuresLinking"
+    );
     const refresh = request.getRefresh();
 
     const { asset, device } = await this.deviceService.linkAsset(
@@ -245,7 +248,7 @@ export class DevicesController {
       deviceId,
       assetId,
       measureNames,
-      { refresh }
+      { implicitMeasuresLinking, refresh }
     );
 
     return {

lib/modules/device/types/DeviceApi.ts

@@ -112,9 +112,27 @@ export interface ApiDeviceLinkAssetRequest extends DevicesControllerRequest {
 
   assetId: string;
 
+  /**
+   * This option allows to not specify the names of all the measures that should
+   * be linked to the asset.
+   *
+   * The algorithm will go through all the measures names provided by the device
+   * and add the one who are present with the same name in the asset.
+   *
+   * It will not add the measure if:
+   *   - it has been specified in the link request
+   *   - it was already present in the asset
+   *
+   * @example
+   *   if the device provide a measure of type "temperature" with the name "temp"
+   *   if the asset has declared a measure of type "temperature" with the name "temp"
+   *   then the measure will be automatically added in the link and will later be propagated to the asset
+   */
+  implicitMeasuresLinking?: boolean;
+
   body?: {
     /**
-     * Names of the linked measures
+     * Names of the linked measures.
      *
      * Array<{ asset: string, device: string }>
      *
@@ -124,7 +142,7 @@ export interface ApiDeviceLinkAssetRequest extends DevicesControllerRequest {
      *   { asset: "externalTemperature", device: "temperature" }
      * ]
      */
-    measureNames: Array<{ asset: string; device: string }>;
+    measureNames?: Array<{ asset: string; device: string }>;
   };
 }
 export type ApiDeviceLinkAssetResult = {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "kuzzle-device-manager",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Manage your IoT devices and assets. Choose a provisioning strategy, receive and decode payload, handle your IoT business logic.",
   "author": "The Kuzzle Team (support@kuzzle.io)",
   "repository": {