@plusscommunities/pluss-maintenance-aws-a 2.1.31 → 2.1.34-beta.0

package/feature.config.js

@@ -155,6 +155,14 @@ exports.serverless = {
       timeout: 300,
       table: values.tableKeyMaintenance,
     },
+    {
+      name: "jobTypesChanged",
+      file: "jobTypesChanged",
+      function: "jobTypesChanged",
+      memorySize: 512,
+      timeout: 60,
+      table: values.tableKeyJobTypes,
+    },
   ],
   schedules: [
     {

package/integration/IntegrationStrategy.js

@@ -45,6 +45,12 @@ class IntegrationStrategy {
   onCompleteRequest = async (request) => {
     return null;
   };
+
+  // TODO: Remove once all existing records have ActiveEntityType (PC-1382)
+  // backfills ActiveEntityType on existing externalentities records for the sparse GSI migration
+  backfillActiveEntityType = async (timeout) => {
+    return { backfillCount: 0, complete: true };
+  };
 }
 
 module.exports = IntegrationStrategy;

package/integration/archibus/ArchibusStrategy.js

@@ -23,6 +23,7 @@ class ArchibusStrategy extends IntegrationStrategy {
     this.host = url.host;
 
     this.statusMap = config.StatusMap;
+    this.completedStatuses = config.CompletedStatuses ?? [];
     this.siteMap = config.SiteMap ?? {};
     this.buildingCodes = [];
   }
@@ -51,7 +52,7 @@ class ArchibusStrategy extends IntegrationStrategy {
    * @returns {Number} The refresh interval in milliseconds
    */
   getRefreshInterval = () => {
-    return 15 * 60 * 1000; // 15 minutes
+    return 60 * 60 * 1000; // 60 minutes
   };
 
   /**
@@ -125,6 +126,7 @@ class ArchibusStrategy extends IntegrationStrategy {
         RowId: `${this.getEntityType()}_${response.data.wrId}`,
         LastUpdated: moment().valueOf(),
         EntityType: this.getEntityType(),
+        ActiveEntityType: this.getEntityType(),
         InternalId: request.id,
         ExternalId: response.data.wrId,
         TrackedData: {},
@@ -304,6 +306,17 @@ class ArchibusStrategy extends IntegrationStrategy {
       }
     );
 
+    // If the external status is terminal, remove ActiveEntityType to exclude from sparse GSI
+    if (this.completedStatuses.includes(request.status)) {
+      log("Archibus:RefreshFromSource", "TerminalStatus", request.status, logId);
+      const entityRowId = `${this.getEntityType()}_${externalId}`;
+      const entity = await getRef("externalentities", "RowId", entityRowId);
+      if (entity && entity.ActiveEntityType) {
+        delete entity.ActiveEntityType;
+        await updateRef("externalentities", entity);
+      }
+    }
+
     log("Archibus:RefreshFromSource", "Result", true, logId);
     return true;
   };
@@ -630,6 +643,48 @@ class ArchibusStrategy extends IntegrationStrategy {
   onCompleteRequest = async (request) => {
     return true;
   };
+
+  // TODO: Remove once all existing records have ActiveEntityType (PC-1382)
+  // Backfills ActiveEntityType on existing externalentities records for the sparse GSI migration.
+  // Runs as part of the cron job after normal processing, respecting the given timeout.
+  backfillActiveEntityType = async (timeout) => {
+    const logId = log("Archibus:Backfill", "Start", true);
+    const startTime = moment().valueOf();
+    let backfillCount = 0;
+    let lastEvaluatedKey = null;
+
+    do {
+      const query = {
+        IndexName: "EntityTypeIndex",
+        KeyConditionExpression: "EntityType = :entityType",
+        ExpressionAttributeValues: {
+          ":entityType": this.getEntityType(),
+        },
+        Limit: 25,
+      };
+      if (lastEvaluatedKey) query.ExclusiveStartKey = lastEvaluatedKey;
+
+      const result = await indexQuery("externalentities", query);
+      lastEvaluatedKey = result.LastEvaluatedKey;
+
+      for (const item of result.Items) {
+        if (!item.ActiveEntityType) {
+          // Skip records already in a terminal status — they should stay out of the sparse GSI
+          const trackedStatus = item.TrackedData && item.TrackedData.status;
+          if (trackedStatus && this.completedStatuses.includes(trackedStatus)) {
+            continue;
+          }
+          item.ActiveEntityType = item.EntityType;
+          await updateRef("externalentities", item);
+          backfillCount++;
+        }
+      }
+    } while (lastEvaluatedKey && moment().valueOf() < startTime + timeout);
+
+    const complete = !lastEvaluatedKey;
+    log("Archibus:Backfill", "End", { backfillCount, complete }, logId);
+    return { backfillCount, complete };
+  };
 }
 
 module.exports = ArchibusStrategy;

package/jobChanged.js

@@ -43,7 +43,7 @@ const onNotesAdded = async (request) => {
 const checkIntegrationActions = async (request, prevRequest) => {
   if (
     request.ExtCreateRetry &&
-    request.ExtCreateRetry !== prevRequest.ExtCreateRetry
+    request.ExtCreateRetry > prevRequest.ExtCreateRetry
   ) {
     log("checkIntegrationActions", "Retrying", true);
     await pushRequestToIntegration(request);

package/jobTypesChanged.js

@@ -0,0 +1,55 @@
+/**
+ * DynamoDB Stream Handler for JobTypes changes
+ *
+ * Republishes any templates using this site as source.
+ * Only notifies siteConfigs for variants with enableSiteConfigsPropagation: true
+ * (maintenance and maintenanceForms). Other variants (feedback, enquiry) are excluded.
+ */
+
+const { Marshaller } = require("@aws/dynamodb-auto-marshaller");
+const marshaller = new Marshaller();
+const { log } = require("@plusscommunities/pluss-core-aws/helper");
+const notifySiteConfigs = require("@plusscommunities/pluss-core-aws/helper/notifySiteConfigs");
+const { values } = require("./values.config");
+
+module.exports.jobTypesChanged = async (event, context, callback) => {
+  const logId = log("jobTypesChanged", "Start", { recordCount: event.Records.length, serviceKey: values.serviceKey });
+
+  // Check if this variant supports siteConfigs propagation
+  if (!values.enableSiteConfigsPropagation) {
+    log("jobTypesChanged", "SkipPropagation", { serviceKey: values.serviceKey }, logId);
+    return;
+  }
+
+  const promises = [];
+
+  event.Records.forEach((record) => {
+    log("jobTypesChanged", "Record", { eventName: record.eventName }, logId);
+
+    if (record.eventName === "INSERT") {
+      const data = marshaller.unmarshallItem(record.dynamodb.NewImage);
+      log("jobTypesChanged", "Insert", { id: data.id, site: data.site }, logId);
+
+      if (data.site) {
+        promises.push(notifySiteConfigs(data.site, logId));
+      }
+    } else if (record.eventName === "MODIFY") {
+      const data = marshaller.unmarshallItem(record.dynamodb.NewImage);
+      log("jobTypesChanged", "Modify", { id: data.id, site: data.site }, logId);
+
+      if (data.site) {
+        promises.push(notifySiteConfigs(data.site, logId));
+      }
+    } else if (record.eventName === "REMOVE") {
+      const previousData = marshaller.unmarshallItem(record.dynamodb.OldImage);
+      log("jobTypesChanged", "Remove", { id: previousData.id, site: previousData.site }, logId);
+
+      if (previousData.site) {
+        promises.push(notifySiteConfigs(previousData.site, logId));
+      }
+    }
+  });
+
+  await Promise.all(promises);
+  log("jobTypesChanged", "Complete", { promiseCount: promises.length }, logId);
+};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@plusscommunities/pluss-maintenance-aws-a",
-  "version": "2.1.31",
+  "version": "2.1.34-beta.0",
   "description": "Extension package to enable maintenance on Pluss Communities Platform",
   "scripts": {
     "gc": "node ../../tools/gc ./",
-    "gs": "node ../../tools/gs ./ ../../activity/serverless.yml",
+    "gs": "node ../../tools/gs ./ ../../strings/serverless.yml",
     "betapatch": "npm version prepatch --preid=beta",
     "patch": "npm version patch",
     "deploy": "npm run gc && npm run gs && serverless deploy",
@@ -24,7 +24,7 @@
   "license": "ISC",
   "dependencies": {
     "@aws/dynamodb-auto-marshaller": "^0.7.1",
-    "@plusscommunities/pluss-core-aws": "2.0.23",
+    "@plusscommunities/pluss-core-aws": "2.0.24-beta.0",
     "amazon-cognito-identity-js": "^2.0.19",
     "aws-sdk": "^2.1591.0",
     "axios": "^1.6.8",

package/requests/retrySync.js

@@ -0,0 +1,161 @@
+const moment = require("moment");
+const getRef = require("@plusscommunities/pluss-core-aws/db/common/getRef");
+const editRef = require("@plusscommunities/pluss-core-aws/db/common/editRef");
+const validateMasterAuth = require("@plusscommunities/pluss-core-aws/helper/auth/validateMasterAuth");
+const { log } = require("@plusscommunities/pluss-core-aws/helper");
+const { values } = require("../values.config");
+const { getStrategy } = require("../integration");
+
+/**
+ * Checks if a job has already been successfully synced to an external system.
+ * Uses two methods to determine sync status:
+ * 1. Checks job history for an "ExternalIDSet" entry
+ * 2. Queries the integration strategy's getExternalId method if available
+ *
+ * @param {Object} job - The maintenance job record
+ * @param {string} job.id - The job's internal ID
+ * @param {string} job.site - The site the job belongs to
+ * @param {Array} [job.history] - The job's history entries
+ * @param {string} logId - The log ID for tracing
+ * @returns {Promise<boolean>} True if the job has already been synced
+ */
+const isAlreadySynced = async (job, logId) => {
+  const history = job.history || [];
+  const hasSuccessfulSync = history.some(
+    (entry) => entry.EntryType === "ExternalIDSet"
+  );
+
+  if (hasSuccessfulSync) {
+    log("isAlreadySynced", "FoundInHistory", true, logId);
+    return true;
+  }
+
+  try {
+    const integrationStrategy = await getStrategy(job.site);
+    if (integrationStrategy.getExternalId) {
+      const externalId = await integrationStrategy.getExternalId(job);
+      if (externalId) {
+        log("isAlreadySynced", "FoundViaStrategy", externalId, logId);
+        return true;
+      }
+    }
+  } catch (error) {
+    log("isAlreadySynced", "StrategyCheckError", error.message, logId);
+  }
+
+  return false;
+};
+
+/**
+ * Initiates a retry of the external system sync for a maintenance job.
+ * This endpoint sets the ExtCreateRetry field on the job, which triggers
+ * the jobChanged stream handler to attempt pushing the request to the
+ * external integration system again.
+ *
+ * @param {Object} event - The Lambda event object
+ * @param {Object} event.headers - Request headers containing auth credentials
+ * @param {Object} data - The request body
+ * @param {string} data.id - The ID of the job to retry sync for
+ * @returns {Promise<Object>} Response object with status and data
+ * @returns {number} returns.status - HTTP status code
+ * @returns {Object} returns.data - Response payload
+ *
+ * @example
+ * // Request
+ * POST /maintenance/update/retrysync
+ * { "id": "job-uuid-here" }
+ *
+ * // Success Response (200)
+ * {
+ *   "success": true,
+ *   "message": "Sync retry initiated. Check back shortly for results.",
+ *   "job": { ... }
+ * }
+ *
+ * // Error Responses
+ * // 400 - Job already synced to external system
+ * // 403 - Not authorised
+ * // 404 - Job not found
+ * // 422 - Missing required field: id
+ * // 500 - Internal error
+ */
+module.exports = async (event, data) => {
+  const action = "retrySync";
+  const logId = log(action, "Input", data);
+
+  try {
+    // Validate required fields
+    if (!data.id) {
+      return {
+        status: 422,
+        data: { error: "Missing required field: id" },
+      };
+    }
+
+    // Fetch the job record
+    let job;
+    try {
+      job = await getRef(values.tableNameMaintenance, "id", data.id);
+    } catch (error) {
+      log(action, "Error:JobNotFound", { error: error.message }, logId);
+      return { status: 404, data: { error: "Job not found" } };
+    }
+
+    if (!job) {
+      log(action, "JobNotFound", { id: data.id }, logId);
+      return { status: 404, data: { error: "Job not found" } };
+    }
+
+    // Validate user has permission to manage maintenance for this site
+    const authorised = await validateMasterAuth(
+      event,
+      values.permissionMaintenanceTracking,
+      job.site
+    );
+
+    if (!authorised) {
+      log(action, "NotAuthorised", { site: job.site }, logId);
+      return { status: 403, data: { error: "Not authorised" } };
+    }
+
+    // Prevent duplicate syncs - check if already synced via history or external entity
+    const alreadySynced = await isAlreadySynced(job, logId);
+    if (alreadySynced) {
+      log(action, "AlreadySynced", { id: job.id }, logId);
+      return {
+        status: 400,
+        data: { error: "Job already synced to external system" },
+      };
+    }
+
+    // Set ExtCreateRetry to a new timestamp value.
+    // The jobChanged stream handler detects this field change and
+    // triggers pushRequestToIntegration() to retry the external sync.
+    const retryTimestamp = moment.utc().valueOf();
+    const updatedJob = await editRef(
+      values.tableNameMaintenance,
+      "id",
+      job.id,
+      {
+        ExtCreateRetry: retryTimestamp,
+      }
+    );
+
+    log(action, "RetryTriggered", { ExtCreateRetry: retryTimestamp }, logId);
+
+    return {
+      status: 200,
+      data: {
+        success: true,
+        message: "Sync retry initiated. Check back shortly for results.",
+        job: updatedJob,
+      },
+    };
+  } catch (error) {
+    log(action, "InternalError", error, logId);
+    return {
+      status: 500,
+      data: { error: "Internal error", message: error.message },
+    };
+  }
+};

package/requests/setExternalJobId.js

@@ -62,6 +62,7 @@ module.exports = async (event, data) => {
     const externalEntity = await updateRef("externalentities", {
       RowId: rowId,
       EntityType: entityType,
+      ActiveEntityType: entityType,
       InternalId: job.id,
       ExternalId: data.externalId,
       LastUpdated: moment().valueOf(),

package/scheduleJobImport.js

@@ -29,11 +29,11 @@ const processBatch = async (strategy, startTime) => {
 
   // use index query to fetch IDs of requests
   const query = {
-    IndexName: "EntityTypeIndex",
+    IndexName: "ActiveEntityTypeIndex",
     KeyConditionExpression:
-      "EntityType = :entityType AND LastUpdated < :lastUpdate", // only fetch items that haven't been updated in this scan
+      "ActiveEntityType = :activeEntityType AND LastUpdated < :lastUpdate", // only fetch items that haven't been updated in this scan
     ExpressionAttributeValues: {
-      ":entityType": strategy.getEntityType(),
+      ":activeEntityType": strategy.getEntityType(),
       ":lastUpdate": startTime - strategy.getRefreshInterval(),
     },
     Limit: 10,
@@ -77,5 +77,11 @@ module.exports.scheduleJobImport = async (event, context, callback) => {
     }
     log("scheduleJobImport", "EndLoop", moment().valueOf(), logId);
   }
+  // TODO: Remove this call once all existing records have ActiveEntityType (PC-1382)
+  const remainingTime = (startTime + timeout) - moment().valueOf();
+  if (remainingTime > 0) {
+    await integrationStrategy.backfillActiveEntityType(remainingTime);
+  }
+
   log("scheduleJobImport", "End", moment().valueOf(), logId);
 };

package/updateData.js

@@ -5,6 +5,7 @@ const config = require("./config.json");
 const assignRequest = require("./requests/assignRequest");
 const updatePriority = require("./requests/updatePriority");
 const setExternalJobId = require("./requests/setExternalJobId");
+const retrySync = require("./requests/retrySync");
 
 module.exports.updateData = async (event, context, callback) => {
   init(config);
@@ -25,6 +26,9 @@ module.exports.updateData = async (event, context, callback) => {
       case "externalid":
         response = await setExternalJobId(event, data);
         break;
+      case "retrysync":
+        response = await retrySync(event, data);
+        break;
       default:
         response = { status: 404, data: { error: "Action not found" } };
         break;

package/values.config.a.js

@@ -23,5 +23,6 @@ const values = {
   activityEditMaintenanceNote: "EditMaintenanceNoteA",
   textJobEmailTitle: "Service Request",
   triggerMaintenanceStatusChanged: "MaintenanceStatusChangedA",
+  enableSiteConfigsPropagation: false,
 };
 exports.values = values;

package/values.config.default.js

@@ -26,5 +26,6 @@ const values = {
   allowGeneralType: true,
   defaultJobTypes: [],
   triggerMaintenanceStatusChanged: "MaintenanceStatusChanged",
+  enableSiteConfigsPropagation: true,
 };
 exports.values = values;

package/values.config.enquiry.js

@@ -219,5 +219,6 @@ const values = {
     },
   ],
   triggerMaintenanceStatusChanged: "MaintenanceStatusChangedEnquiry",
+  enableSiteConfigsPropagation: false,
 };
 exports.values = values;

package/values.config.feedback.js

@@ -191,5 +191,6 @@ const values = {
     },
   ],
   triggerMaintenanceStatusChanged: "MaintenanceStatusChangedFeedback",
+  enableSiteConfigsPropagation: false,
 };
 exports.values = values;

package/values.config.food.js

@@ -26,5 +26,6 @@ const values = {
   allowGeneralType: false,
   defaultJobTypes: [],
   triggerMaintenanceStatusChanged: "MaintenanceStatusChangedFood",
+  enableSiteConfigsPropagation: false,
 };
 exports.values = values;

package/values.config.forms.js

@@ -26,5 +26,6 @@ const values = {
   allowGeneralType: false,
   defaultJobTypes: [],
   triggerMaintenanceStatusChanged: "MaintenanceStatusChangedForms",
+  enableSiteConfigsPropagation: true,
 };
 exports.values = values;

package/values.config.js

@@ -23,5 +23,6 @@ const values = {
   activityEditMaintenanceNote: "EditMaintenanceNoteA",
   textJobEmailTitle: "Service Request",
   triggerMaintenanceStatusChanged: "MaintenanceStatusChangedA",
+  enableSiteConfigsPropagation: false,
 };
 exports.values = values;