@docbrasil/api-systemmanager 1.2.4 → 1.2.6

package/api/admin/user.js

@@ -298,6 +298,90 @@ class AdminUser {
     }
   }
 
+  /**
+   * @author Myndware <augusto.pissarra@myndware.com>
+   * @description Batch-create users from an uploaded Excel (.xlsx) or CSV file.
+   *
+   * Uploads the file as multipart/form-data. The server parses it, validates
+   * headers, de-duplicates emails, admits rows FIFO against the organization's
+   * user cap, and delegates the actual creation to the existing registration
+   * chain. Response is a per-row result array (created / existing / skipped).
+   *
+   * Status codes:
+   *   - 200 when at least one row was created or matched an existing user.
+   *   - 422 (same JSON body shape) when EVERY row was skipped — callers
+   *     should promote the 422 response body to a completed result, not an
+   *     error. Axios throws on 422 by default, so catch and inspect
+   *     `ex.response.data.results`.
+   *   - 400 for structural failures (invalid_file, missing_columns, empty_file,
+   *     too_many_rows) — `response.data.code` carries the machine-readable code.
+   *   - 403 when the caller does not belong to the target organization or lacks
+   *     user-admin role (code: 'forbidden').
+   *   - 413 when the uploaded file exceeds 2 MB.
+   *
+   * @param {FormData} formData A browser FormData instance with a single field
+   *   named `file` whose value is the .xlsx or .csv File/Blob. Must be
+   *   FormData so the browser/axios can set the multipart boundary.
+   * @param {string} session JWT session token
+   * @return {Promise<object>} Batch result:
+   *   {
+   *     total: number,
+   *     created: number,
+   *     existing: number,
+   *     skipped: number,
+   *     results: Array<{
+   *       row: number,                      // spreadsheet row (1-based, header = 1)
+   *       email: string,
+   *       status: 'created' | 'existing' | 'skipped',
+   *       userId: string | null,
+   *       message: string | null            // snake_case code, optionally `code:detail`
+   *     }>
+   *   }
+   * @public
+   * @async
+   * @example
+   *
+   * const API = require('@docbrasil/api-systemmanager');
+   * const api = new API();
+   * const fd = new FormData();
+   * fd.append('file', fileInput.files[0]);   // .xlsx or .csv
+   * const session = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
+   * // Ensure the client is scoped to the caller's org:
+   * api.admin.user.setOrgId(myOrgId);
+   * try {
+   *   const result = await api.admin.user.batchCreate(fd, session);
+   *   console.log(`${result.created} created, ${result.skipped} skipped`);
+   * } catch (ex) {
+   *   if (ex?.response?.status === 422 && ex.response.data?.results) {
+   *     // All-skipped batch — still a valid result to render.
+   *     console.warn('All rows skipped:', ex.response.data.results);
+   *   } else {
+   *     throw ex;
+   *   }
+   * }
+   */
+  async batchCreate(formData, session) {
+    const self = this;
+
+    try {
+      Joi.assert(formData, Joi.any().required(), 'Multipart FormData with a `file` field');
+      Joi.assert(session, Joi.string().required(), 'Session token');
+
+      // Do NOT force Content-Type — let the browser/axios set it with the
+      // correct multipart boundary. Raise the axios body-size caps to 5 MB
+      // (server enforces its own 2 MB cap via Hapi `maxBytes`).
+      const cfg = {
+        ...self._setHeader(session),
+        maxContentLength: 5 * 1024 * 1024,
+        maxBodyLength:    5 * 1024 * 1024
+      };
+      const apiCall = self.client.put(`${self._basePath()}/batch`, formData, cfg);
+      return self._returnData(await apiCall);
+    } catch (ex) {
+      throw ex;
+    }
+  }
+
   /**
    * @author Myndware <augusto.pissarra@myndware.com>
    * @description Remove a user

package/api/user/task.js

@@ -256,6 +256,7 @@ class Task {
    * @param {string=} params.title - Task title
    * @param {array=} params.tags - Task tags
    * @param {string=} params.dueDate - Due date ISO string
+ * @param {object=} params.processProperties - Keys merged into the process's processProperties bag (search, task cards, BI); omitted when empty
    * @param {string} session - Session, token JWT
    * @return {Promise}
    * @public
@@ -279,7 +280,8 @@ class Task {
    *   order: 0,
    *   title: 'My Task',
    *   tags: [],
-   *   dueDate: '2024-01-15T00:00:00Z'
+   *   dueDate: '2024-01-15T00:00:00Z',
+ *   processProperties: { surgicalPatientName: 'Maria' } // optional, merged into the process bag
    * };
    * const session = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
    * await api.user.task.saveTask(params, session);
@@ -304,6 +306,7 @@ class Task {
       Joi.assert(params.title, Joi.string().allow(''), 'Task title');
       Joi.assert(params.tags, Joi.array(), 'Task tags');
       Joi.assert(params.dueDate, Joi.string(), 'Due date ISO string');
+      Joi.assert(params.processProperties, Joi.object(), 'Process properties to merge into the process bag');
       Joi.assert(session, Joi.string().required(), 'Session token JWT');
 
       const {
@@ -321,7 +324,8 @@ class Task {
         order = 0,
         title = '',
         tags = [],
-        dueDate
+        dueDate,
+        processProperties
       } = params;
 
       const body = {
@@ -337,6 +341,13 @@ class Task {
         tags
       };
       if (dueDate) body.dueDate = dueDate;
+      // Forwarded verbatim; the server MERGES each key into the process's own
+      // `processProperties` bag (site setStepData). Omitted when empty so a save
+      // that has nothing to publish carries no key at all. Only a plain object
+      // travels: an array or scalar would be folded into the bag index by index.
+      if (_.isPlainObject(processProperties) && !_.isEmpty(processProperties)) {
+        body.processProperties = processProperties;
+      }
 
       const url = `organizations/${orgId}/adhoc/${processId}/save/${taskId}/${flowName}`;
       const apiCall = self._client.put(url, body, self._setHeader(session));
@@ -366,6 +377,7 @@ class Task {
    * @param {string=} params.title - Task title
    * @param {array=} params.tags - Task tags
    * @param {string=} params.dueDate - Due date ISO string
+ * @param {object=} params.processProperties - Keys merged into the process's processProperties bag (search, task cards, BI); omitted when empty
    * @param {string} session - Session, token JWT
    * @return {Promise}
    * @public
@@ -389,7 +401,8 @@ class Task {
    *   order: 0,
    *   title: 'My Task',
    *   tags: [],
-   *   dueDate: '2024-01-15T00:00:00Z'
+   *   dueDate: '2024-01-15T00:00:00Z',
+ *   processProperties: { surgicalPatientName: 'Maria' } // optional, merged into the process bag
    * };
    * const session = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
    * await api.user.task.endTask(params, session);
@@ -414,6 +427,7 @@ class Task {
       Joi.assert(params.title, Joi.string().allow(''), 'Task title');
       Joi.assert(params.tags, Joi.array(), 'Task tags');
       Joi.assert(params.dueDate, Joi.string(), 'Due date ISO string');
+      Joi.assert(params.processProperties, Joi.object(), 'Process properties to merge into the process bag');
       Joi.assert(session, Joi.string().required(), 'Session token JWT');
 
       const {
@@ -431,7 +445,8 @@ class Task {
         order = 0,
         title = '',
         tags = [],
-        dueDate
+        dueDate,
+        processProperties
       } = params;
 
       const body = {
@@ -447,6 +462,13 @@ class Task {
         tags
       };
       if (dueDate) body.dueDate = dueDate;
+      // Forwarded verbatim; the server MERGES each key into the process's own
+      // `processProperties` bag (site setStepData). Omitted when empty so a save
+      // that has nothing to publish carries no key at all. Only a plain object
+      // travels: an array or scalar would be folded into the bag index by index.
+      if (_.isPlainObject(processProperties) && !_.isEmpty(processProperties)) {
+        body.processProperties = processProperties;
+      }
 
       const url = `organizations/${orgId}/adhoc/${processId}/endprocess/${taskId}/${flowName}`;
       const apiCall = self._client.put(url, body, self._setHeader(session));

package/dist/bundle.cjs

@@ -3660,6 +3660,7 @@ class Task {
    * @param {string=} params.title - Task title
    * @param {array=} params.tags - Task tags
    * @param {string=} params.dueDate - Due date ISO string
+ * @param {object=} params.processProperties - Keys merged into the process's processProperties bag (search, task cards, BI); omitted when empty
    * @param {string} session - Session, token JWT
    * @return {Promise}
    * @public
@@ -3683,7 +3684,8 @@ class Task {
    *   order: 0,
    *   title: 'My Task',
    *   tags: [],
-   *   dueDate: '2024-01-15T00:00:00Z'
+   *   dueDate: '2024-01-15T00:00:00Z',
+ *   processProperties: { surgicalPatientName: 'Maria' } // optional, merged into the process bag
    * };
    * const session = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
    * await api.user.task.saveTask(params, session);
@@ -3708,6 +3710,7 @@ class Task {
       Joi__default["default"].assert(params.title, Joi__default["default"].string().allow(''), 'Task title');
       Joi__default["default"].assert(params.tags, Joi__default["default"].array(), 'Task tags');
       Joi__default["default"].assert(params.dueDate, Joi__default["default"].string(), 'Due date ISO string');
+      Joi__default["default"].assert(params.processProperties, Joi__default["default"].object(), 'Process properties to merge into the process bag');
       Joi__default["default"].assert(session, Joi__default["default"].string().required(), 'Session token JWT');
 
       const {
@@ -3725,7 +3728,8 @@ class Task {
         order = 0,
         title = '',
         tags = [],
-        dueDate
+        dueDate,
+        processProperties
       } = params;
 
       const body = {
@@ -3741,6 +3745,13 @@ class Task {
         tags
       };
       if (dueDate) body.dueDate = dueDate;
+      // Forwarded verbatim; the server MERGES each key into the process's own
+      // `processProperties` bag (site setStepData). Omitted when empty so a save
+      // that has nothing to publish carries no key at all. Only a plain object
+      // travels: an array or scalar would be folded into the bag index by index.
+      if (___default["default"].isPlainObject(processProperties) && !___default["default"].isEmpty(processProperties)) {
+        body.processProperties = processProperties;
+      }
 
       const url = `organizations/${orgId}/adhoc/${processId}/save/${taskId}/${flowName}`;
       const apiCall = self._client.put(url, body, self._setHeader(session));
@@ -3770,6 +3781,7 @@ class Task {
    * @param {string=} params.title - Task title
    * @param {array=} params.tags - Task tags
    * @param {string=} params.dueDate - Due date ISO string
+ * @param {object=} params.processProperties - Keys merged into the process's processProperties bag (search, task cards, BI); omitted when empty
    * @param {string} session - Session, token JWT
    * @return {Promise}
    * @public
@@ -3793,7 +3805,8 @@ class Task {
    *   order: 0,
    *   title: 'My Task',
    *   tags: [],
-   *   dueDate: '2024-01-15T00:00:00Z'
+   *   dueDate: '2024-01-15T00:00:00Z',
+ *   processProperties: { surgicalPatientName: 'Maria' } // optional, merged into the process bag
    * };
    * const session = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
    * await api.user.task.endTask(params, session);
@@ -3818,6 +3831,7 @@ class Task {
       Joi__default["default"].assert(params.title, Joi__default["default"].string().allow(''), 'Task title');
       Joi__default["default"].assert(params.tags, Joi__default["default"].array(), 'Task tags');
       Joi__default["default"].assert(params.dueDate, Joi__default["default"].string(), 'Due date ISO string');
+      Joi__default["default"].assert(params.processProperties, Joi__default["default"].object(), 'Process properties to merge into the process bag');
       Joi__default["default"].assert(session, Joi__default["default"].string().required(), 'Session token JWT');
 
       const {
@@ -3835,7 +3849,8 @@ class Task {
         order = 0,
         title = '',
         tags = [],
-        dueDate
+        dueDate,
+        processProperties
       } = params;
 
       const body = {
@@ -3851,6 +3866,13 @@ class Task {
         tags
       };
       if (dueDate) body.dueDate = dueDate;
+      // Forwarded verbatim; the server MERGES each key into the process's own
+      // `processProperties` bag (site setStepData). Omitted when empty so a save
+      // that has nothing to publish carries no key at all. Only a plain object
+      // travels: an array or scalar would be folded into the bag index by index.
+      if (___default["default"].isPlainObject(processProperties) && !___default["default"].isEmpty(processProperties)) {
+        body.processProperties = processProperties;
+      }
 
       const url = `organizations/${orgId}/adhoc/${processId}/endprocess/${taskId}/${flowName}`;
       const apiCall = self._client.put(url, body, self._setHeader(session));
@@ -14903,6 +14925,90 @@ class AdminUser {
     }
   }
 
+  /**
+   * @author Myndware <augusto.pissarra@myndware.com>
+   * @description Batch-create users from an uploaded Excel (.xlsx) or CSV file.
+   *
+   * Uploads the file as multipart/form-data. The server parses it, validates
+   * headers, de-duplicates emails, admits rows FIFO against the organization's
+   * user cap, and delegates the actual creation to the existing registration
+   * chain. Response is a per-row result array (created / existing / skipped).
+   *
+   * Status codes:
+   *   - 200 when at least one row was created or matched an existing user.
+   *   - 422 (same JSON body shape) when EVERY row was skipped — callers
+   *     should promote the 422 response body to a completed result, not an
+   *     error. Axios throws on 422 by default, so catch and inspect
+   *     `ex.response.data.results`.
+   *   - 400 for structural failures (invalid_file, missing_columns, empty_file,
+   *     too_many_rows) — `response.data.code` carries the machine-readable code.
+   *   - 403 when the caller does not belong to the target organization or lacks
+   *     user-admin role (code: 'forbidden').
+   *   - 413 when the uploaded file exceeds 2 MB.
+   *
+   * @param {FormData} formData A browser FormData instance with a single field
+   *   named `file` whose value is the .xlsx or .csv File/Blob. Must be
+   *   FormData so the browser/axios can set the multipart boundary.
+   * @param {string} session JWT session token
+   * @return {Promise<object>} Batch result:
+   *   {
+   *     total: number,
+   *     created: number,
+   *     existing: number,
+   *     skipped: number,
+   *     results: Array<{
+   *       row: number,                      // spreadsheet row (1-based, header = 1)
+   *       email: string,
+   *       status: 'created' | 'existing' | 'skipped',
+   *       userId: string | null,
+   *       message: string | null            // snake_case code, optionally `code:detail`
+   *     }>
+   *   }
+   * @public
+   * @async
+   * @example
+   *
+   * const API = require('@docbrasil/api-systemmanager');
+   * const api = new API();
+   * const fd = new FormData();
+   * fd.append('file', fileInput.files[0]);   // .xlsx or .csv
+   * const session = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
+   * // Ensure the client is scoped to the caller's org:
+   * api.admin.user.setOrgId(myOrgId);
+   * try {
+   *   const result = await api.admin.user.batchCreate(fd, session);
+   *   console.log(`${result.created} created, ${result.skipped} skipped`);
+   * } catch (ex) {
+   *   if (ex?.response?.status === 422 && ex.response.data?.results) {
+   *     // All-skipped batch — still a valid result to render.
+   *     console.warn('All rows skipped:', ex.response.data.results);
+   *   } else {
+   *     throw ex;
+   *   }
+   * }
+   */
+  async batchCreate(formData, session) {
+    const self = this;
+
+    try {
+      Joi__default["default"].assert(formData, Joi__default["default"].any().required(), 'Multipart FormData with a `file` field');
+      Joi__default["default"].assert(session, Joi__default["default"].string().required(), 'Session token');
+
+      // Do NOT force Content-Type — let the browser/axios set it with the
+      // correct multipart boundary. Raise the axios body-size caps to 5 MB
+      // (server enforces its own 2 MB cap via Hapi `maxBytes`).
+      const cfg = {
+        ...self._setHeader(session),
+        maxContentLength: 5 * 1024 * 1024,
+        maxBodyLength:    5 * 1024 * 1024
+      };
+      const apiCall = self.client.put(`${self._basePath()}/batch`, formData, cfg);
+      return self._returnData(await apiCall);
+    } catch (ex) {
+      throw ex;
+    }
+  }
+
   /**
    * @author Myndware <augusto.pissarra@myndware.com>
    * @description Remove a user