@plusscommunities/pluss-maintenance-aws 2.1.21 → 2.1.23

package/getData.js

@@ -5,6 +5,7 @@ const generateJsonResponse = require("@plusscommunities/pluss-core-aws/helper/ge
 const getAssignees = require("./requests/getAssignees");
 const getRequests = require("./requests/getRequests");
 const getRequest = require("./requests/getRequest");
+const getExternalSync = require("./requests/getExternalSync");
 
 module.exports.getData = async (event, context, callback) => {
   init(config);
@@ -34,6 +35,12 @@ module.exports.getData = async (event, context, callback) => {
           log(action, "ResponseLength", response.data.Users.length, logId);
         }
         break;
+      case "externalsync":
+        response = await getExternalSync(event);
+        if (response.status === 200) {
+          log(action, "ExternalSystem", response.data.externalSystem, logId);
+        }
+        break;
       default:
         break;
     }

package/integration/archibus/ArchibusStrategy.js

@@ -139,7 +139,7 @@ class ArchibusStrategy extends IntegrationStrategy {
       if (!updatedJob.history) updatedJob.history = [];
       updatedJob.history.push({
         timestamp: moment.utc().valueOf(),
-        action: "ExternalIDSet",
+        EntryType: "ExternalIDSet",
         externalId: response.data.wrId,
         user: {
           displayName: "Archibus Integration",
@@ -176,7 +176,7 @@ class ArchibusStrategy extends IntegrationStrategy {
         if (!failedJob.history) failedJob.history = [];
         failedJob.history.push({
           timestamp: moment.utc().valueOf(),
-          action: "ExternalIDSetFailed",
+          EntryType: "ExternalIDSetFailed",
           user: {
             displayName: "Archibus Integration",
             id: "system",

package/integration/index.js

@@ -1,6 +1,7 @@
 const getString = require("@plusscommunities/pluss-core-aws/db/strings/getString");
 const { getRowId, log } = require("@plusscommunities/pluss-core-aws/helper");
 const ArchibusStrategy = require("./archibus/ArchibusStrategy");
+const SeeStuffStrategy = require("./seestuff/SeeStuffStrategy");
 const IntegrationStrategy = require("./IntegrationStrategy");
 const { values } = require("../values.config");
 
@@ -16,6 +17,8 @@ exports.getStrategy = async (site) => {
     switch (importConfig.Strategy) {
       case "Archibus":
         return new ArchibusStrategy(importConfig);
+      case "SeeStuff":
+        return new SeeStuffStrategy(importConfig);
       default:
         return new IntegrationStrategy();
     }

package/integration/seestuff/SeeStuffStrategy.js

@@ -0,0 +1,293 @@
+const axios = require("axios");
+const moment = require("moment");
+const _ = require("lodash");
+const IntegrationStrategy = require("../IntegrationStrategy");
+const { log, getRowId } = require("@plusscommunities/pluss-core-aws/helper");
+const editRef = require("@plusscommunities/pluss-core-aws/db/common/editRef");
+const updateRef = require("@plusscommunities/pluss-core-aws/db/common/updateRef");
+const getRef = require("@plusscommunities/pluss-core-aws/db/common/getRef");
+const indexQuery = require("@plusscommunities/pluss-core-aws/db/common/indexQuery");
+const { values } = require("../../values.config");
+
+class SeeStuffStrategy extends IntegrationStrategy {
+  constructor(config) {
+    super();
+    this.baseUrl = config.BaseUrl; // base URL for the API
+    this.apiKeyHeader = config.APIKeyHeader; // header to use for API key
+    this.apiKey = config.APIKey; // API key
+
+    const url = new URL(this.baseUrl);
+    this.host = url.host;
+
+    this.siteMap = config.SiteMap ?? {};
+  }
+
+  /**
+   * Gets the entity type for the integration
+   *
+   * @returns {String} The entity type for the integration
+   */
+  getEntityType = () => {
+    return `${values.serviceKey}_SeeStuff`;
+  };
+
+  /**
+   * Validates the integration
+   *
+   * @returns {Boolean} Whether the integration is valid
+   */
+  isValidIntegration = () => {
+    return true;
+  };
+
+  /**
+   * Gets the refresh interval for the SeeStuff system
+   *
+   * @returns {Number} The refresh interval in milliseconds
+   */
+  getRefreshInterval = () => {
+    return Number.MAX_SAFE_INTEGER; // should never refresh
+  };
+
+  /**
+   * Creates a request in the SeeStuff system
+   *
+   * @param {Object} request - Request definition on Pluss
+   * @param {Object} mockResponse - Mock response from SeeStuff to simulate response
+   * @returns {Boolean} Whether the request was created on SeeStuff
+   */
+  createRequest = async (request, mockResponse = null) => {
+    const logId = log("SeeStuff:CreateRequest", "Start", request);
+
+    try {
+      // Get user details for room/address and CRMID
+      let userRoom = request.room || "";
+      let crmResidentId = "";
+
+      // Map site to location code if available
+      const location = this.siteMap[request.site];
+      if (!location) {
+        log("SeeStuff:CreateRequest", "LocationNotFound", request.site, logId);
+        return false;
+      }
+
+      if (request.userID) {
+        try {
+          // Look up user from users table
+          const user = await getRef("users", "Id", request.userID);
+          log("SeeStuff:CreateRequest", "User", user, logId);
+
+          if (user) {
+            // Get user's address/room
+            if (user.unit) {
+              userRoom = user.unit;
+            }
+
+            // Get CRMID from user fields
+            try {
+              const crmIdField = await getRef(
+                "userfields",
+                "RowId",
+                getRowId(request.userID, "CRMID")
+              );
+              if (crmIdField && crmIdField.Value) {
+                crmResidentId = crmIdField.Value;
+              }
+              log("SeeStuff:CreateRequest", "CRMID", crmResidentId, logId);
+            } catch (fieldError) {
+              log(
+                "SeeStuff:CreateRequest",
+                "CRMIDLookupError",
+                fieldError,
+                logId
+              );
+            }
+          }
+        } catch (userError) {
+          log("SeeStuff:CreateRequest", "UserLookupError", userError, logId);
+        }
+      }
+
+      // Format description similar to Archibus
+      const description = `${request.title}${
+        _.isEmpty(request.description) ? "" : `\n\n${request.description}`
+      }${_.isEmpty(request.room) ? "" : `\n\nLocation: ${request.room}`}${
+        _.isEmpty(request.userName) ? "" : `\n\nName: ${request.userName}`
+      }${_.isEmpty(request.phone) ? "" : `\n\nPhone: ${request.phone}`}${
+        _.isEmpty(request.type) ? "" : `\n\nJob Type: ${request.type}`
+      }${
+        _.isEmpty(request.images)
+          ? ""
+          : `\n\nImages: ${request.images.join("\n")}`
+      }`;
+
+      // Format date_reported
+      const dateReported = moment().format("YYYY-MM-DD HH:mm:ss");
+
+      // Build payload
+      const data = {
+        externalId: request.id,
+        description: description,
+        priority: "P3",
+        location: location,
+        room: userRoom,
+        date_reported: dateReported,
+        crmResidentId: crmResidentId,
+      };
+
+      log("SeeStuff:CreateRequest", "Request", data, logId);
+
+      const response =
+        mockResponse ??
+        (await axios({
+          method: "POST",
+          url: `${this.baseUrl}/assetmgmt/servicerequests`,
+          timeout: 30000,
+          headers: {
+            [this.apiKeyHeader]: this.apiKey,
+            "Content-Type": "application/json",
+            Host: this.host,
+          },
+          data,
+        }));
+
+      log("SeeStuff:CreateRequest", "Response", response.data, logId);
+
+      return true;
+    } catch (e) {
+      log("SeeStuff:CreateRequest", "Error", e, logId);
+
+      // Add history entry for failed integration
+      try {
+        const failedJob = await getRef(
+          values.tableNameMaintenance,
+          "id",
+          request.id
+        );
+        if (!failedJob.history) failedJob.history = [];
+        failedJob.history.push({
+          timestamp: moment.utc().valueOf(),
+          EntryType: "ExternalIDSetFailed",
+          user: {
+            displayName: "SeeStuff Integration",
+            id: "system",
+          },
+        });
+
+        await editRef(values.tableNameMaintenance, "id", request.id, {
+          history: failedJob.history,
+        });
+      } catch (historyError) {
+        log("SeeStuff:CreateRequest", "HistoryError", historyError, logId);
+      }
+    }
+    return false;
+  };
+
+  /**
+   * Fetches a request from the SeeStuff system
+   * Not implemented yet
+   *
+   * @param {String} externalId - Id of the request on SeeStuff
+   * @returns {Object} The request as it exists on SeeStuff
+   */
+  getRequest = async (externalId) => {
+    return null;
+  };
+
+  /**
+   * Refreshes a request from the SeeStuff system
+   * Not implemented yet
+   *
+   * @param {String} requestId - Id of the request on Pluss
+   * @param {String} externalId - Id of the request on SeeStuff
+   * @param {Object} trackedData - The set of fields tracked
+   * @returns {Boolean} Whether the request had any changes on SeeStuff
+   */
+  refreshFromSource = async (requestId, externalId, trackedData) => {
+    return false;
+  };
+
+  /**
+   * Get SeeStuff Id of the request
+   * Queries externalentities table to find the external ID
+   *
+   * @param {Object} request - Request definition on Pluss
+   * @returns {String} Id of the request on SeeStuff
+   */
+  getExternalId = async (request) => {
+    const logId = log("SeeStuff:GetExternalId", "Start", { Id: request.id });
+
+    // get external id
+    const externalEntityQuery = await indexQuery("externalentities", {
+      IndexName: "InternalIdIndex",
+      KeyConditionExpression:
+        "EntityType = :entityType AND InternalId = :internalId",
+      ExpressionAttributeValues: {
+        ":entityType": this.getEntityType(),
+        ":internalId": request.id,
+      },
+    });
+
+    log(
+      "SeeStuff:GetExternalId",
+      "ExternalLength",
+      externalEntityQuery.Items.length,
+      logId
+    );
+    if (_.isEmpty(externalEntityQuery.Items)) {
+      return null;
+    }
+
+    const externalId = externalEntityQuery.Items[0].ExternalId;
+    log("SeeStuff:GetExternalId", "ExternalId", externalId, logId);
+
+    return externalId;
+  };
+
+  /**
+   * Perform actions when a task's status has changed
+   * Not implemented yet
+   *
+   * @param {Object} request - Request definition on Pluss
+   * @returns {Boolean} Represents whether the actions were successful
+   */
+  onStatusChanged = async (request) => {
+    return true;
+  };
+
+  /**
+   * Perform actions when a comment has been added to a task
+   * Not implemented yet
+   *
+   * @param {Object} request - Request definition on Pluss
+   * @returns {Boolean} Represents whether the actions were successful
+   */
+  onCommentAdded = async (request) => {
+    return true;
+  };
+
+  /**
+   * Perform actions when a note has been added to a task
+   * Not implemented yet
+   *
+   * @param {Object} request - Request definition on Pluss
+   * @returns {Boolean} Represents whether the actions were successful
+   */
+  onNotesAdded = async (request) => {
+    return true;
+  };
+
+  /**
+   * Perform completion actions when a task is completed
+   * Not implemented yet
+   *
+   * @param {Object} request - Request definition on Pluss
+   * @returns {Boolean} Represents whether the actions were successful
+   */
+  onCompleteRequest = async (request) => {
+    return true;
+  };
+}
+
+module.exports = SeeStuffStrategy;

package/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@plusscommunities/pluss-maintenance-aws",
-  "version": "2.1.21",
+  "version": "2.1.23",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plusscommunities/pluss-maintenance-aws",
-  "version": "2.1.21",
+  "version": "2.1.23",
   "description": "Extension package to enable maintenance on Pluss Communities Platform",
   "scripts": {
     "gc": "node ../../tools/gc ./",

package/requests/getExternalSync.js

@@ -0,0 +1,171 @@
+const getRef = require("@plusscommunities/pluss-core-aws/db/common/getRef");
+const indexQuery = require("@plusscommunities/pluss-core-aws/db/common/indexQuery");
+const validateMasterAuth = require("@plusscommunities/pluss-core-aws/helper/auth/validateMasterAuth");
+const isValidAssignee = require("./helper/isValidAssignee");
+const getSessionUserFromReqAuthKey = require("@plusscommunities/pluss-core-aws/helper/auth/getSessionUserFromReqAuthKey");
+const { log } = require("@plusscommunities/pluss-core-aws/helper");
+const { values } = require("../values.config");
+
+/**
+ * Retrieves external system sync information for a maintenance request
+ *
+ * Checks both SeeStuff and Archibus external entity tables to find
+ * if the request has been synced to an external system.
+ *
+ * @param {Object} event - Lambda event object
+ * @param {Object} params - Query parameters (optional, uses event.queryStringParameters if not provided)
+ * @returns {Object} Response object with status and data
+ *
+ * Response format (200):
+ * {
+ *   externalSystem: "SeeStuff" | "Archibus",
+ *   externalId: string,
+ *   syncedAt: number (Unix timestamp),
+ *   trackedData: object
+ * }
+ *
+ * Error responses:
+ * - 422: Missing required field (id)
+ * - 404: Request not found OR no external sync exists
+ * - 403: Not authorized (user doesn't have permission to view request)
+ * - 500: Internal server error
+ */
+module.exports = async (event, params) => {
+  const data = params || event.queryStringParameters || {};
+  const logId = log("getExternalSync", "Params", data);
+
+  // Validate input
+  if (!data.id) {
+    log("getExternalSync", "MissingId", true, logId);
+    return {
+      status: 422,
+      data: { error: "Missing required field: id" },
+    };
+  }
+
+  try {
+    // Get the request to verify it exists and get site for permission check
+    let request;
+    try {
+      request = await getRef(values.tableNameMaintenance, "id", data.id);
+    } catch (error) {
+      log("getExternalSync", "RequestNotFound", { id: data.id }, logId);
+      return {
+        status: 404,
+        data: { error: "Request not found" },
+      };
+    }
+
+    if (!request) {
+      log("getExternalSync", "RequestNotFound", { id: data.id }, logId);
+      return {
+        status: 404,
+        data: { error: "Request not found" },
+      };
+    }
+
+    // Check permissions (same pattern as getRequest.js)
+    // Three levels of access:
+    // 1. Full admin with maintenance tracking permission
+    // 2. User assigned to the request
+    // 3. User who created the request
+    const authorised = await validateMasterAuth(
+      event,
+      values.permissionMaintenanceTracking,
+      request.site
+    );
+
+    const assignAuthorised = await isValidAssignee(
+      event,
+      request.site,
+      request.AssigneeId
+    );
+
+    if (!authorised && !assignAuthorised) {
+      // Check if user is the request owner
+      const userId = await getSessionUserFromReqAuthKey(event);
+      if (userId !== request.userID) {
+        log(
+          "getExternalSync",
+          "NotAuthorised",
+          { userId, requestOwner: request.userID },
+          logId
+        );
+        return {
+          status: 403,
+          data: { error: "Not authorised" },
+        };
+      }
+    }
+
+    log("getExternalSync", "Authorised", true, logId);
+
+    // Query externalentities table for this request
+    // Check both SeeStuff and Archibus entity types
+    const entityTypes = [
+      `${values.serviceKey}_SeeStuff`,
+      `${values.serviceKey}_Archibus`,
+    ];
+
+    log("getExternalSync", "CheckingEntityTypes", entityTypes, logId);
+
+    let externalSync = null;
+
+    // Check each external system type
+    for (const entityType of entityTypes) {
+      const query = await indexQuery("externalentities", {
+        IndexName: "InternalIdIndex",
+        KeyConditionExpression:
+          "EntityType = :entityType AND InternalId = :internalId",
+        ExpressionAttributeValues: {
+          ":entityType": entityType,
+          ":internalId": request.id,
+        },
+      });
+
+      log(
+        "getExternalSync",
+        `${entityType}_Results`,
+        query.Items.length,
+        logId
+      );
+
+      if (query.Items && query.Items.length > 0) {
+        const item = query.Items[0];
+        // Extract system name from entity type (e.g., "maintenance_SeeStuff" -> "SeeStuff")
+        const systemName = entityType.split("_")[1];
+
+        externalSync = {
+          externalSystem: systemName,
+          externalId: item.ExternalId,
+          syncedAt: item.LastUpdated,
+          trackedData: item.TrackedData || {},
+        };
+
+        log("getExternalSync", "FoundSync", externalSync, logId);
+        break; // Stop after finding first match
+      }
+    }
+
+    // If no external sync found, return 404
+    if (!externalSync) {
+      log("getExternalSync", "NoSyncFound", { id: data.id }, logId);
+      return {
+        status: 404,
+        data: { error: "No external sync found" },
+      };
+    }
+
+    log("getExternalSync", "Success", externalSync, logId);
+    return {
+      status: 200,
+      data: externalSync,
+    };
+  } catch (error) {
+    log("getExternalSync", "InternalError", error.toString(), logId);
+    return {
+      status: 500,
+      data: { error: "Internal error", message: error.message },
+    };
+  }
+};

package/requests/setExternalJobId.js

@@ -75,7 +75,7 @@ module.exports = async (event, data) => {
     if (!job.history) job.history = [];
     job.history.push({
       timestamp: moment.utc().valueOf(),
-      action: "ExternalIDSet",
+      EntryType: "ExternalIDSet",
       externalId: data.externalId,
       user,
     });