From 0f5595c16878abc3eb46e5d743db657f46737e07 Mon Sep 17 00:00:00 2001 From: Lucas Date: Tue, 3 Oct 2023 07:29:01 +0200 Subject: [PATCH 01/13] update bpmn moddle to current version --- .../bpmn-helper/__tests__/getters.test.js | 29 +++++++++---------- .../bpmn-helper/__tests__/setters.test.js | 11 +++---- .../bpmn-helper/__tests__/util.test.js | 11 +++---- src/helper-modules/bpmn-helper/package.json | 2 +- src/helper-modules/bpmn-helper/src/util.js | 25 ++++------------ yarn.lock | 2 +- 6 files changed, 29 insertions(+), 51 deletions(-) diff --git a/src/helper-modules/bpmn-helper/__tests__/getters.test.js b/src/helper-modules/bpmn-helper/__tests__/getters.test.js index 3f8245e33..83531d0ce 100644 --- a/src/helper-modules/bpmn-helper/__tests__/getters.test.js +++ b/src/helper-modules/bpmn-helper/__tests__/getters.test.js @@ -18,14 +18,11 @@ jest.doMock('bpmn-moddle', () => { }; }); -mockToXML.mockImplementation((_, a, callback) => { - callback(undefined, ''); -}); +mockToXML.mockImplementation((_, a) => ({ xml: '' })); mockCreate.mockImplementation((name) => ({ $type: name })); - -mockFromXML.mockImplementation((_, a, callback) => { - callback(undefined, JSON.parse(JSON.stringify(baseJSON))); -}); +mockFromXML.mockImplementation((_, a) => ({ + rootElement: JSON.parse(JSON.stringify(baseJSON)), +})); const getters = require('../src/getters.js'); const { get } = require('http'); @@ -67,17 +64,17 @@ describe('Tests for getter functions of this library', () => { describe('getDeploymentMethod', () => { it('returns the deploymentMethod for the given process', async () => { - mockFromXML.mockImplementationOnce((_a, _b, callback) => - callback(undefined, JSON.parse(JSON.stringify(deploymentObj))), - ); + mockFromXML.mockImplementationOnce((_a, _b) => ({ + rootElement: JSON.parse(JSON.stringify(deploymentObj)), + })); expect(await getters.getDeploymentMethod(deploymentXML)).toBe('static'); }); }); describe('getElementMachineMapping', () => { it('returns a mapping from task ids to assigned machineIds or addresses', async () => { - mockFromXML.mockImplementationOnce((_a, _b, callback) => - callback(undefined, JSON.parse(JSON.stringify(deploymentObj))), - ); + mockFromXML.mockImplementationOnce((_a, _b) => ({ + rootElement: JSON.parse(JSON.stringify(deploymentObj)), + })); expect(await getters.getElementMachineMapping(deploymentXML)).toStrictEqual({ StartEvent_1: { machineId: '1234', machineAddress: undefined }, EndEvent_1d3ier5: { machineId: undefined, machineAddress: '192.168.1.1:1234' }, @@ -87,9 +84,9 @@ describe('Tests for getter functions of this library', () => { }); describe('getProcessIds', () => { it('returns the ids of all processes in the process definition', async () => { - mockFromXML.mockImplementationOnce((_a, _b, callback) => - callback(undefined, JSON.parse(JSON.stringify(twoProcessObj))), - ); + mockFromXML.mockImplementationOnce((_a, _b) => ({ + rootElement: JSON.parse(JSON.stringify(twoProcessObj)), + })); expect(await getters.getProcessIds(twoProcessXML)).toStrictEqual([ 'Process_02x86ax', 'Process_0xqodb2', diff --git a/src/helper-modules/bpmn-helper/__tests__/setters.test.js b/src/helper-modules/bpmn-helper/__tests__/setters.test.js index 12e9f2261..913b59ea3 100644 --- a/src/helper-modules/bpmn-helper/__tests__/setters.test.js +++ b/src/helper-modules/bpmn-helper/__tests__/setters.test.js @@ -17,14 +17,11 @@ jest.doMock('bpmn-moddle', () => { }; }); -mockToXML.mockImplementation((_, a, callback) => { - callback(undefined, ''); -}); +mockToXML.mockImplementation((_, a) => ({ xml: '' })); mockCreate.mockImplementation((name) => ({ $type: name })); - -mockFromXML.mockImplementation((_, a, callback) => { - callback(undefined, JSON.parse(JSON.stringify(baseJSON))); -}); +mockFromXML.mockImplementation((_, a) => ({ + rootElement: JSON.parse(JSON.stringify(baseJSON)), +})); const setters = require('../src/setters.js'); diff --git a/src/helper-modules/bpmn-helper/__tests__/util.test.js b/src/helper-modules/bpmn-helper/__tests__/util.test.js index b5a8ded9a..015dc5a84 100644 --- a/src/helper-modules/bpmn-helper/__tests__/util.test.js +++ b/src/helper-modules/bpmn-helper/__tests__/util.test.js @@ -17,14 +17,11 @@ jest.doMock('bpmn-moddle', () => { }; }); -mockToXML.mockImplementation((_, a, callback) => { - callback(undefined, ''); -}); +mockToXML.mockImplementation((_, a) => ({ xml: '' })); mockCreate.mockImplementation((name) => ({ $type: name })); - -mockFromXML.mockImplementation((_, a, callback) => { - callback(undefined, JSON.parse(JSON.stringify(baseJSON))); -}); +mockFromXML.mockImplementation((_, a) => ({ + rootElement: JSON.parse(JSON.stringify(baseJSON)), +})); const util = require('../src/util.js'); diff --git a/src/helper-modules/bpmn-helper/package.json b/src/helper-modules/bpmn-helper/package.json index 5c0db2e9e..4fb6c53d9 100644 --- a/src/helper-modules/bpmn-helper/package.json +++ b/src/helper-modules/bpmn-helper/package.json @@ -11,7 +11,7 @@ "lint": "eslint ." }, "dependencies": { - "bpmn-moddle": "^6.0.0", + "bpmn-moddle": "^8.0.1", "ids": "^1.0.0", "uuid": "^9.0.0" } diff --git a/src/helper-modules/bpmn-helper/src/util.js b/src/helper-modules/bpmn-helper/src/util.js index 95f510d7e..a8b33dcc9 100644 --- a/src/helper-modules/bpmn-helper/src/util.js +++ b/src/helper-modules/bpmn-helper/src/util.js @@ -28,16 +28,9 @@ function ensureCorrectProceedNamespace(xml) { * @throws {Error} if the given string is not an XML * @throws {Error} if the given XML can not be converted to a bpmn-moddle object (multiple possible reasons) */ -function toBpmnObject(xml, typename) { - return new Promise((resolve, reject) => { - moddle.fromXML(xml, typename, (err, obj) => { - if (err) { - reject(err); - } else { - resolve(obj); - } - }); - }); +async function toBpmnObject(xml, typename) { + const { rootElement } = await moddle.fromXML(xml, typename); + return rootElement; } /** @@ -46,15 +39,9 @@ function toBpmnObject(xml, typename) { * @param {Object} bpmn traversable object representation * @returns {Promise} a xml representation of the given object */ -function toBpmnXml(obj) { - return new Promise((resolve, reject) => { - moddle.toXML(obj, { format: true }, (saveErr, xml) => { - if (saveErr) { - reject(saveErr); - } - resolve(xml); - }); - }); +async function toBpmnXml(obj) { + const { xml } = await moddle.toXML(obj, { format: true }); + return xml; } /** diff --git a/yarn.lock b/yarn.lock index ca7ad17b8..c6ba309b8 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5268,7 +5268,7 @@ bpmn-moddle@^6.0.0: moddle "^5.0.1" moddle-xml "^8.0.8" -bpmn-moddle@^8.0.0: +bpmn-moddle@^8.0.0, bpmn-moddle@^8.0.1: version "8.0.1" resolved "https://registry.yarnpkg.com/bpmn-moddle/-/bpmn-moddle-8.0.1.tgz#ba8a009fbd354fb521a11a1dd1417655a9d2ec02" integrity sha512-mwZcrWhi52+JH5Oq58WwKYcUxQ1ZMiDQuzt1bpqiqEEFFnQLqCgtLwEXQuDXFmAuQPdMAghyPzqdOZQqIQVesw== From ee59a5ca0fd11fc005f1088faa36871f1fe26993 Mon Sep 17 00:00:00 2001 From: Lucas Date: Tue, 3 Oct 2023 07:32:32 +0200 Subject: [PATCH 02/13] correct jsdoc in constraint parser --- src/helper-modules/constraint-parser-xml-json/parser.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/helper-modules/constraint-parser-xml-json/parser.js b/src/helper-modules/constraint-parser-xml-json/parser.js index 1e2d61e89..2aac026b1 100644 --- a/src/helper-modules/constraint-parser-xml-json/parser.js +++ b/src/helper-modules/constraint-parser-xml-json/parser.js @@ -56,7 +56,7 @@ class ConstraintParser { /** * A logger that shall be used by the parser * - * @param {object} logger + * @param {object} [logger] */ constructor(logger) { this.setLogger(logger); From ecfe73525cab375e05c068647cb55a5776d2563b Mon Sep 17 00:00:00 2001 From: Lucas Date: Tue, 3 Oct 2023 14:31:16 +0200 Subject: [PATCH 03/13] added declaration files for bpmn helper module --- src/helper-modules/bpmn-helper/index.d.ts | 130 ++++++ .../bpmn-helper/src/PROCEED-CONSTANTS.d.ts | 50 +++ .../bpmn-helper/src/PROCEED-CONSTANTS.js | 6 +- .../bpmn-helper/src/getters.d.ts | 384 ++++++++++++++++++ src/helper-modules/bpmn-helper/src/getters.js | 70 ++-- .../bpmn-helper/src/proceedExtensions.d.ts | 40 ++ .../bpmn-helper/src/proceedExtensions.js | 16 +- .../bpmn-helper/src/setters.d.ts | 194 +++++++++ src/helper-modules/bpmn-helper/src/setters.js | 40 +- src/helper-modules/bpmn-helper/src/util.d.ts | 98 +++++ src/helper-modules/bpmn-helper/src/util.js | 16 +- .../bpmn-helper/src/validators.d.ts | 11 + .../bpmn-helper/src/validators.js | 5 +- src/management-system-v2/lib/helpers.ts | 66 +-- 14 files changed, 1029 insertions(+), 97 deletions(-) create mode 100644 src/helper-modules/bpmn-helper/index.d.ts create mode 100644 src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.d.ts create mode 100644 src/helper-modules/bpmn-helper/src/getters.d.ts create mode 100644 src/helper-modules/bpmn-helper/src/proceedExtensions.d.ts create mode 100644 src/helper-modules/bpmn-helper/src/setters.d.ts create mode 100644 src/helper-modules/bpmn-helper/src/util.d.ts create mode 100644 src/helper-modules/bpmn-helper/src/validators.d.ts diff --git a/src/helper-modules/bpmn-helper/index.d.ts b/src/helper-modules/bpmn-helper/index.d.ts new file mode 100644 index 000000000..1da9a609d --- /dev/null +++ b/src/helper-modules/bpmn-helper/index.d.ts @@ -0,0 +1,130 @@ +declare const _exports: { + ensureExtensionElements(element: object): object; + removeEmptyExtensionElements(element: any): void; + ensureContainerElement(element: object, containerType: string): object; + removeEmptyContainerElement(element: any, containerType: any, containerElement: any): void; + setMetaData(bpmn: string | object, elId: string, metaValues: object): Promise; + setProceedElement(element: any, proceedElementType: any, value: any, attributes?: {}): {}; + getExporterName(): string; + getExporterVersion(): string; + generateBpmnId(prefix?: string): string; + generateDefinitionsId(): string; + generateProcessId(): string; + generateUserTaskFileName(): string; + getUserTaskImplementationString(): string; + generateTargetNamespace(id: any): string; + initXml(processId?: any, startEventId?: string): string; + validateCalledProcess(xml: string, processId: string): boolean; + setDefinitionsId(bpmn: string | object, id: string): Promise; + setDefinitionsName(bpmn: string | object, name: string): Promise; + setDefinitionsVersionInformation( + bpmn: string | object, + { + version, + versionName, + versionDescription, + versionBasedOn, + }: { + version: string | number; + versionName?: string; + versionDescription?: string; + versionBasedOn?: string | number; + }, + ): Promise; + setProcessId(bpmn: string, id: string): string; + setTemplateId(bpmn: any, id: any): Promise; + setTargetNamespace(bpmn: string | object, id: string): Promise; + setStandardDefinitions( + bpmn: string | object, + exporterName: string, + exporterVersion: string, + ): Promise; + setDeploymentMethod(bpmn: string | object, method: string): Promise; + setMachineInfo(bpmn: string | object, machineInfo: object[]): string | object; + setUserTaskData( + bpmn: string | object, + userTaskId: string, + newFileName: string, + newImplementation?: string, + ): string | object; + addConstraintsToElementById( + bpmn: string | object, + elementId: string, + constraints: object, + ): string | object; + addCallActivityReference( + bpmn: string | object, + callActivityId: string, + calledBpmn: string, + calledProcessLocation: string, + ): string | object; + removeCallActivityReference(bpmn: string | object, callActivityId: string): string | object; + removeUnusedCallActivityReferences(bpmn: string | object): string | object; + removeColorFromAllElements(bpmn: any): Promise; + addDocumentation(bpmn: string | object, description: string): string | object; + addDocumentationToProcessObject(processObj: object, description: string): Promise; + updatePerformersOnElement(element: object, performers: any[]): Promise; + updatePerformersOnElementById( + bpmn: string | object, + elementId: string, + performers: any[], + ): Promise; + getDefinitionsId: typeof getters.getDefinitionsId; + getOriginalDefinitionsId: typeof getters.getOriginalDefinitionsId; + getDefinitionsName: typeof getters.getDefinitionsName; + getDefinitionsInfos: typeof getters.getDefinitionsInfos; + getImports: typeof getters.getImports; + getDefinitionsVersionInformation: typeof getters.getDefinitionsVersionInformation; + getProcessIds: typeof getters.getProcessIds; + getDeploymentMethod: typeof getters.getDeploymentMethod; + getProcessConstraints: typeof getters.getProcessConstraints; + getProcessDocumentation: typeof getters.getProcessDocumentation; + getProcessDocumentationByObject: typeof getters.getProcessDocumentationByObject; + getUserTaskFileNameMapping: typeof getters.getUserTaskFileNameMapping; + getAllUserTaskFileNamesAndUserTaskIdsMapping: typeof getters.getAllUserTaskFileNamesAndUserTaskIdsMapping; + getSubprocess: typeof getters.getSubprocess; + getSubprocessContent: typeof getters.getSubprocessContent; + getTargetDefinitionsAndProcessIdForCallActivityByObject: typeof getters.getTargetDefinitionsAndProcessIdForCallActivityByObject; + getDefinitionsAndProcessIdForEveryCallActivity: typeof getters.getDefinitionsAndProcessIdForEveryCallActivity; + getStartEvents: typeof getters.getStartEvents; + getAllBpmnFlowElements: typeof getters.getAllBpmnFlowElements; + getAllBpmnFlowNodeIds: typeof getters.getAllBpmnFlowNodeIds; + getAllBpmnFlowElementIds: typeof getters.getAllBpmnFlowElementIds; + getChildrenFlowElements: typeof getters.getChildrenFlowElements; + getElementMachineMapping: typeof getters.getElementMachineMapping; + getTaskConstraintMapping: typeof getters.getTaskConstraintMapping; + getIdentifyingInfos: typeof getters.getIdentifyingInfos; + getRootFromElement: typeof getters.getRootFromElement; + getMetaDataFromElement: typeof getters.getMetaDataFromElement; + getMetaData: typeof getters.getMetaData; + getMilestonesFromElement: typeof getters.getMilestonesFromElement; + getMilestonesFromElementById: typeof getters.getMilestonesFromElementById; + getResourcesFromElement: typeof getters.getResourcesFromElement; + getLocationsFromElement: typeof getters.getLocationsFromElement; + getPerformersFromElement: typeof getters.getPerformersFromElement; + getPerformersFromElementById: typeof getters.getPerformersFromElementById; + parseISODuration: typeof getters.parseISODuration; + convertISODurationToMiliseconds: typeof getters.convertISODurationToMiliseconds; + ensureCorrectProceedNamespace(xml: string): string; + toBpmnObject(xml: string, typename?: string): Promise; + toBpmnXml(obj: any): Promise; + getChildren(travObj: object): any[]; + getElementsByTagName(travObj: object, tagname: string): any[]; + getAllElements(travObj: object): any[]; + getElementById(travObj: object, id: string): object; + getElementDI(element: object, definitions?: object): any; + manipulateElementById( + bpmn: string | object, + id: string, + manipFunc: util.manipulationFunction, + ): Promise; + manipulateElementsByTagName( + bpmn: string | object, + tagName: string, + manipFunc: util.manipulationFunction, + ): Promise; + moddle: any; +}; +export = _exports; +import getters = require('./src/getters.js'); +import util = require('./src/util.js'); diff --git a/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.d.ts b/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.d.ts new file mode 100644 index 000000000..a1961f8dd --- /dev/null +++ b/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.d.ts @@ -0,0 +1,50 @@ +/** + * @module @proceed/bpmn-helper + */ +/** + * Exporter name is used in the bpmn definitions parts + * + * @returns {string} static exporter name + */ +export function getExporterName(): string; +/** + * Exporter version is used in the bpmn definitions parts + * + * This version should be adjusted when this module (bpmn-helper) + * changes or any changes in the management-system occur regarding the export + * + * @returns {string} static exporter version + */ +export function getExporterVersion(): string; +/** + * Generate a new ID for PROCEED BPMN elements + * + * @param {string} [prefix] optional prefix for the id + * @returns {string} short id in the form '0bkz1kb' + */ +export function generateBpmnId(prefix?: string): string; +/** + * Generate a new ID for the 'definitions' element in a PROCEED process + * @returns {string} a new PROCEED definitions 'id' + */ +export function generateDefinitionsId(): string; +export function generateProcessId(): string; +/** + * Generates the 'fileName' attribute string of a PROCEED UserTask + * @returns A new 'filename' value + */ +export function generateUserTaskFileName(): string; +/** + * Return the string for the 'implementation' attribute in a UserTask + * @returns {String} URL of the HTML spec + */ +export function getUserTaskImplementationString(): string; +export function generateTargetNamespace(id: any): string; +/** + * Creates a minimal valid proceed bpmn + * + * @param {*} processId the id to use for the contained process + * @param {string} startEventId the id to use for the start event + * @returns {string} a minimal valid proceed bpmn + */ +export function initXml(processId?: any, startEventId?: string): string; diff --git a/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.js b/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.js index 3bb2fb56f..c4d91d3b0 100644 --- a/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.js +++ b/src/helper-modules/bpmn-helper/src/PROCEED-CONSTANTS.js @@ -51,7 +51,7 @@ const idGenerator = new Ids([32, 36, 1]); /** * Generate a new ID for PROCEED BPMN elements * - * @param {String} [prefix] optional prefix for the id + * @param {string} [prefix] optional prefix for the id * @returns {string} short id in the form '0bkz1kb' */ function generateBpmnId(prefix) { @@ -90,8 +90,8 @@ function generateTargetNamespace(id) { * Creates a minimal valid proceed bpmn * * @param {*} processId the id to use for the contained process - * @param {String} startEventId the id to use for the start event - * @returns {String} a minimal valid proceed bpmn + * @param {string} startEventId the id to use for the start event + * @returns {string} a minimal valid proceed bpmn */ function initXml( processId = `Process_${generateBpmnId()}`, diff --git a/src/helper-modules/bpmn-helper/src/getters.d.ts b/src/helper-modules/bpmn-helper/src/getters.d.ts new file mode 100644 index 000000000..da37e3e91 --- /dev/null +++ b/src/helper-modules/bpmn-helper/src/getters.d.ts @@ -0,0 +1,384 @@ +/** + * An object containing properties from the + * definitions element in a BPMN file. + */ +export type DefinitionsInfos = { + /** + * - definitions id + */ + id: string; + /** + * - definitions name + */ + name: string; + /** + * - definitions exporter + */ + exporter: string; + /** + * - definitions exporterVersion + */ + exporterVersion: string; + /** + * - definitions targetNamespace + */ + targetNamespace: string; +}; +/** + * Returns id of the given process definition + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} The id stored in the definitions field of the given bpmn process + */ +export function getDefinitionsId(bpmn: string | object): Promise; +/** + * Returns the value of the originalId attribute in the given process definition + * the originalId is the id the process had before it was imported + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {(Promise.)} The originalId stored in the definitions field of the given bpmn process + */ +export function getOriginalDefinitionsId(bpmn: string | object): Promise; +/** + * Returns the name of the given bpmn process definition + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} - The name stored in the definitions field of the given bpmn process + */ +export function getDefinitionsName(bpmn: string | object): Promise; +/** + * An object containing properties from the + * definitions element in a BPMN file. + * + * @typedef DefinitionsInfos + * @type {object} + * @property {string} id - definitions id + * @property {string} name - definitions name + * @property {string} exporter - definitions exporter + * @property {string} exporterVersion - definitions exporterVersion + * @property {string} targetNamespace - definitions targetNamespace + */ +/** + * Gets the 'definitions' root element from the given BPMN XML + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} The 'definitions' root element with some selected attributes + */ +export function getDefinitionsInfos(bpmn: string | object): Promise; +/** + * Returns an array of import elements for a given bpmn xml + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} - Arry of of import elements inside the given xml + */ +export function getImports(bpmn: string | object): Promise; +/** + * Returns the version information of the given bpmn process definition + * + * @param {string|object} bpmn - the process definition as XML string or BPMN-moddle Object + * @returns {(Promise.<{version?: number, name?: string, description?: string, versionBasedOn?: number}>)} - The version information if it exists + * @throws {Error} will throw if the definition contains a version that is not a number + */ +export function getDefinitionsVersionInformation(bpmn: string | object): Promise<{ + version?: number; + name?: string; + description?: string; + versionBasedOn?: number; +}>; +/** + * Get all process ids from a BPMN definitions/object. + * (A BPMN file can contain multiple 'process' elements inside its 'definitions' element.) + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} An Array with Strings containing all IDs from every 'process' element + */ +export function getProcessIds(bpmn: string | object): Promise; +/** + * Gets deployment method of the given process + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} the deployment method used for the given process + */ +export function getDeploymentMethod(bpmn: string | object): Promise; +/** + * Get the Constraints of the BPMN process. + * (The Constraint XML elements are defined in the PROCEED XML Schema + * and are not standardized in BPMN.) + * + * @see {@link https://docs.proceed-labs.org/concepts/bpmn/bpmn-constraints/} + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns { Promise.<{ hardConstraints: Array, softConstraints: Array }> } An Object (a map) where all keys are the BPMN element ids and the value is an object with the hard and soft Constraint Arrays + */ +export function getProcessConstraints(bpmn: string | object): Promise<{ + hardConstraints: any[]; + softConstraints: any[]; +}>; +/** + * Get the content of the 'documentation' element of the first process inside a BPMN file. + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} the documentation content + */ +export function getProcessDocumentation(bpmn: string | object): Promise; +/** + * Get the content of the 'documentation' element of the given process object. + * + * @param {object} processObject - a process element as BPMN-Moddle Object + * @returns {string} the documentation content + */ +export function getProcessDocumentationByObject(processObject: object): string; +/** + * Get all fileName for all userTasks, + * (The attribute 'filename' is defined in the PROCEED XML Schema and not a standard BPMN attribute.) + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns { Promise.<{ [userTaskId: string]: { fileName: string, implementation: string }}> } an object (a map) with all userTaskIds as keys + */ +export function getUserTaskFileNameMapping(bpmn: string | object): Promise<{ + [userTaskId: string]: { + fileName: string; + implementation: string; + }; +}>; +/** + * Creates a map (object) that contains the 'fileName' (key) and UserTask-IDs (value) + * for every UserTask in a BPMN process. + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns { Promise.<{ '': '' }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) + */ +export function getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn: string | object): Promise<{ + '': ''; +}>; +/** + * Returns a xml with Diagram Elements just from the given subprocess and their nested Processes + * + * Structure of XMl: + * Defintions + * - Process + * - FlowElements of the Process (BPMN Part) + * - Process End + * - Diagram (How to visualize the XML in the viewer) + * Definitions End + * + * This function only remove all Diagram Parts that are not part of the subprocess - the flowElements are still part of the xml + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} subprocessId - id of subprocess you want to show + * @return {Promise.} BPMN xml with only diagram parts for the subprocess + */ +export function getSubprocess(bpmn: string | object, subprocessId: string): Promise; +/** + * Returns a xml with elements inside given subprocess + * + * Structure of XMl: + * Defintions + * - Process + * -FlowElements of the Process (BPMN Part) + * - Process End + * - Diagram (How to visualize the XML in the viewer) + * Definitions End + * + * This function removes all Diagram Parts and flowElements that are not part of the subprocess + * + * @param {string} bpmn - the process definition of the main process as XML string or BPMN-Moddle Object + * @param {string} subprocessId - id of subprocess you want to show + * @return {Promise.} - xml with only flowElements and diagram parts inside the subprocess + */ +export function getSubprocessContent(bpmn: string, subprocessId: string): Promise; +/** + * Get the definitionId and processId of a target called process (callActivity) + * + * @see {@link https://docs.proceed-labs.org/concepts/bpmn/bpmn-subprocesses/} + * + * @param {object} bpmnObj - The BPMN XML as converted bpmn-moddle object with toBpmnObject + * @param {string} callActivityId - The id of the callActivity + * @returns { { definitionId: string, processId: string, version: number } } An Object with the definition, process id and version + * @throws An Error if the callActivity id does not exist + * @throws If the callActivity has no 'calledElement' attribute + * @throws If the targetNamespace for a callActivity could not be found + * @throws If no import element could be found for a targetNamespace + */ +export function getTargetDefinitionsAndProcessIdForCallActivityByObject( + bpmnObj: object, + callActivityId: string, +): { + definitionId: string; + processId: string; + version: number; +}; +/** + * Get all definitionIds for all imported Processes used in callActivities + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {boolean} [dontThrow] - whether to throw errors or not in retrieving process ids in call activities + * @returns { Promise.<{ '': { definitionId: string, processId: string, version: number }}> } an object (a map) with all callActivityIds as keys + * @throws see function: {@link getTargetDefinitionsAndProcessIdForCallActivityByObject} + */ +export function getDefinitionsAndProcessIdForEveryCallActivity( + bpmn: string | object, + dontThrow?: boolean, +): Promise<{ + '': { + definitionId: string; + processId: string; + version: number; + }; +}>; +/** + * @module @proceed/bpmn-helper + */ +/** + * Function that returns ids of all start events in a bpmn process model + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} the ids of all startEvents + */ +export function getStartEvents(bpmn: string | object): Promise; +/** + * Gets every Task|Event|Gateway|CallActivity|SubProcess|SequenceFlow inside a BPMN process + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} every element inside a BPMN process + */ +export function getAllBpmnFlowElements(bpmn: string | object): Promise; +/** + * Gets the Id of every Task|Event|Gateway|CallActivity|SubProcess inside a BPMN process + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} Ids of every element inside a BPMN process + */ +export function getAllBpmnFlowNodeIds(bpmn: string | object): Promise; +/** + * Gets the Id of every Task|Event|Gateway|CallActivity|SubProcess|SequenceFlow inside a BPMN process + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} Ids of every element inside a BPMN process + */ +export function getAllBpmnFlowElementIds(bpmn: string | object): Promise; +/** + * Gets first-level child flow Elements Task|Event|Gateway|CallActivity|SubProcess|SequenceFlow of a process/subprocess + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} every child element inside a process/subprocess + */ +export function getChildrenFlowElements(bpmn: string | object, elementId: any): Promise; +/** + * Returns a mapping of the ids of the process nodes to the machines they are mapped to + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {Promise.} the mapping from a node id to information about the machine it is mapped to + */ +export function getElementMachineMapping(bpmn: string | object): Promise; +/** + * Get all Constraints for every BPMN Element. + * (The Constraint XML elements are defined in the PROCEED XML Schema + * and are not standardized in BPMN.) + * + * @see {@link https://docs.proceed-labs.org/concepts/bpmn/bpmn-constraints/} + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns { Promise.<{ '': { hardConstraints: Array, softConstraints: Array} }> } An Object (a map) where all keys are the BPMN element ids and the value is an object with the hard and soft Constraint Arrays + */ +export function getTaskConstraintMapping(bpmn: string | object): Promise<{ + '': { + hardConstraints: any[]; + softConstraints: any[]; + }; +}>; +/** + * Returns information about the process that can be used to identify it + * + * e.g. its unique id, original id and processIds for automatic identification + * and its name and description for human identification + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns { Promise.<{ id: string, originalId: string, processIds: string[], name: string, description: string }> } object containing the identifying information + */ +export function getIdentifyingInfos(bpmn: string | object): Promise<{ + id: string; + originalId: string; + processIds: string[]; + name: string; + description: string; +}>; +/** + * Returns the definitions object of the process + * + * @param {object} businessObject the businessObject of a process element + * @returns {object} definitions object of the process + */ +export function getRootFromElement(businessObject: object): object; +/** + * Parses the meta data from a bpmn-moddle element + * + * @param {object} element + * @returns {object} key value list of meta values + */ +export function getMetaDataFromElement(element: object): object; +/** + * Get the meta information of an element + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} elId the id of the element to update + * @returns {Promise.} the meta information + */ +export function getMetaData(bpmn: string | object, elId: string): Promise; +/** + * Parses the milestones from a bpmn-moddle element + * + * @param {object} element + * @returns {Array} array with all milestones + */ +export function getMilestonesFromElement(element: object): any[]; +/** + * Get the milestones for given element id + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} elementId the id of the element + * @returns {Array} array with all milestones + */ +export function getMilestonesFromElementById(bpmn: string | object, elementId: string): any[]; +/** + * Parses the resources from a bpmn-moddle element + * + * @param {object} element + * @returns {object} object with all resources + */ +export function getResourcesFromElement(element: object): object; +/** + * Parses the locations from a bpmn-moddle element + * + * @param {object} element + * @returns {object} object with all locations + */ +export function getLocationsFromElement(element: object): object; +/** + * Get the performers for given element + * + * @param {object} element + * @returns {Array} performers given for element + */ +export function getPerformersFromElement(element: object): any[]; +/** + * Get the performers for given element id + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} elementId the id of the element + * @returns {Array} array with all performers + */ +export function getPerformersFromElementById(bpmn: string | object, elementId: string): any[]; +/** + * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds + * @param {string} isoDuration + * @returns {object} Object with number of years, months, days, hours, minutes and seconds + */ +export function parseISODuration(isoDuration: string): object; +/** + * Convert given ISO Duration in number of miliseconds + * + * @param {string} isoDuration duration in iso standard + * @returns {number} number of miliseconds for duration + */ +export function convertISODurationToMiliseconds(isoDuration: string): number; diff --git a/src/helper-modules/bpmn-helper/src/getters.js b/src/helper-modules/bpmn-helper/src/getters.js index 72bba7ad6..a43f9e4ab 100644 --- a/src/helper-modules/bpmn-helper/src/getters.js +++ b/src/helper-modules/bpmn-helper/src/getters.js @@ -19,7 +19,7 @@ const constraintParser = new ConstraintParser(); * Function that returns ids of all start events in a bpmn process model * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} the ids of all startEvents + * @returns {Promise.} the ids of all startEvents */ async function getStartEvents(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -42,7 +42,7 @@ async function getDefinitionsId(bpmn) { * the originalId is the id the process had before it was imported * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {(Promise.|Promise.)} The originalId stored in the definitions field of the given bpmn process + * @returns {(Promise.)} The originalId stored in the definitions field of the given bpmn process */ async function getOriginalDefinitionsId(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -63,8 +63,8 @@ async function getDefinitionsName(bpmn) { /** * Returns the version information of the given bpmn process definition * - * @param {(string|object)} bpmn - the process definition as XML string or BPMN-moddle Object - * @returns {Promise.<{version: number, name: (string|undefined), description: (string|undefined), versionBasedOn: (number|undefined)}|undefined>} - The version information if it exists + * @param {string|object} bpmn - the process definition as XML string or BPMN-moddle Object + * @returns {(Promise.<{version?: number, name?: string, description?: string, versionBasedOn?: number}>)} - The version information if it exists * @throws {Error} will throw if the definition contains a version that is not a number */ async function getDefinitionsVersionInformation(bpmn) { @@ -92,7 +92,7 @@ async function getDefinitionsVersionInformation(bpmn) { * Get the content of the 'documentation' element of the first process inside a BPMN file. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} the documentation content + * @returns {Promise.} the documentation content */ async function getProcessDocumentation(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -107,8 +107,8 @@ async function getProcessDocumentation(bpmn) { /** * Get the content of the 'documentation' element of the given process object. * - * @param {Object} processObject - a process element as BPMN-Moddle Object - * @returns {String} the documentation content + * @param {object} processObject - a process element as BPMN-Moddle Object + * @returns {string} the documentation content */ function getProcessDocumentationByObject(processObject) { const docs = processObject.get('documentation'); @@ -187,7 +187,7 @@ async function getElementMachineMapping(bpmn) { * (The attribute 'filename' is defined in the PROCEED XML Schema and not a standard BPMN attribute.) * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ '': { fileName: string, implementation: string }}> } an object (a map) with all userTaskIds as keys + * @returns { Promise.<{ [userTaskId: string]: { fileName: string, implementation: string }}> } an object (a map) with all userTaskIds as keys */ async function getUserTaskFileNameMapping(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -276,7 +276,7 @@ async function getSubprocess(bpmn, subprocessId) { * * @param {string} bpmn - the process definition of the main process as XML string or BPMN-Moddle Object * @param {string} subprocessId - id of subprocess you want to show - * @return {string} - xml with only flowElements and diagram parts inside the subprocess + * @return {Promise.} - xml with only flowElements and diagram parts inside the subprocess */ async function getSubprocessContent(bpmn, subprocessId) { const bpmnObject = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -314,7 +314,7 @@ async function getSubprocessContent(bpmn, subprocessId) { * (A BPMN file can contain multiple 'process' elements inside its 'definitions' element.) * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} An Array with Strings containing all IDs from every 'process' element + * @returns {Promise.} An Array with Strings containing all IDs from every 'process' element */ async function getProcessIds(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -361,7 +361,7 @@ async function getAllBpmnFlowElementIds(bpmn) { * Gets the Id of every Task|Event|Gateway|CallActivity|SubProcess inside a BPMN process * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} Ids of every element inside a BPMN process + * @returns {Promise.} Ids of every element inside a BPMN process */ async function getAllBpmnFlowNodeIds(bpmn) { const allBpmnElements = await getAllBpmnFlowElements(bpmn); @@ -393,7 +393,7 @@ async function getChildrenFlowElements(bpmn, elementId) { * * @see {@link https://docs.proceed-labs.org/concepts/bpmn/bpmn-subprocesses/} * - * @param {Object} bpmnObj - The BPMN XML as converted bpmn-moddle object with toBpmnObject + * @param {object} bpmnObj - The BPMN XML as converted bpmn-moddle object with toBpmnObject * @param {string} callActivityId - The id of the callActivity * @returns { { definitionId: string, processId: string, version: number } } An Object with the definition, process id and version * @throws An Error if the callActivity id does not exist @@ -443,6 +443,7 @@ function getTargetDefinitionsAndProcessIdForCallActivityByObject(bpmnObj, callAc * Get all definitionIds for all imported Processes used in callActivities * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {boolean} [dontThrow] - whether to throw errors or not in retrieving process ids in call activities * @returns { Promise.<{ '': { definitionId: string, processId: string, version: number }}> } an object (a map) with all callActivityIds as keys * @throws see function: {@link getTargetDefinitionsAndProcessIdForCallActivityByObject} */ @@ -472,7 +473,7 @@ async function getDefinitionsAndProcessIdForEveryCallActivity(bpmn, dontThrow = * Returns an array of import elements for a given bpmn xml * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} - Arry of of import elements inside the given xml + * @returns {Promise.} - Arry of of import elements inside the given xml */ async function getImports(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -566,7 +567,7 @@ async function getProcessConstraints(bpmn) { * and its name and description for human identification * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ id: String, originalId: String, processIds: String[], name: String, description: String }> } object containing the identifying information + * @returns { Promise.<{ id: string, originalId: string, processIds: string[], name: string, description: string }> } object containing the identifying information */ async function getIdentifyingInfos(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -590,7 +591,8 @@ async function getIdentifyingInfos(bpmn) { /** * Returns the definitions object of the process * - * @param {Object} businessObject the businessObject of a process element + * @param {object} businessObject the businessObject of a process element + * @returns {object} definitions object of the process */ function getRootFromElement(businessObject) { let el = businessObject; @@ -605,8 +607,8 @@ function getRootFromElement(businessObject) { /** * Parses the meta data from a bpmn-moddle element * - * @param {Object} element - * @returns {Object} key value list of meta values + * @param {object} element + * @returns {object} key value list of meta values */ function getMetaDataFromElement(element) { const properties = {}; @@ -647,8 +649,8 @@ function getMetaDataFromElement(element) { * Get the meta information of an element * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} elId the id of the element to update - * @returns {object} the meta information + * @param {string} elId the id of the element to update + * @returns {Promise.} the meta information */ async function getMetaData(bpmn, elId) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -660,7 +662,7 @@ async function getMetaData(bpmn, elId) { /** * Parses the milestones from a bpmn-moddle element * - * @param {Object} element + * @param {object} element * @returns {Array} array with all milestones */ function getMilestonesFromElement(element) { @@ -686,7 +688,7 @@ function getMilestonesFromElement(element) { * Get the milestones for given element id * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} elementId the id of the element + * @param {string} elementId the id of the element * @returns {Array} array with all milestones */ async function getMilestonesFromElementById(bpmn, elementId) { @@ -700,7 +702,7 @@ async function getMilestonesFromElementById(bpmn, elementId) { * Get the performers for given element id * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} elementId the id of the element + * @param {string} elementId the id of the element * @returns {Array} array with all performers */ async function getPerformersFromElementById(bpmn, elementId) { @@ -713,8 +715,8 @@ async function getPerformersFromElementById(bpmn, elementId) { /** * Parses the locations from a bpmn-moddle element * - * @param {Object} element - * @returns {Object} object with all locations + * @param {object} element + * @returns {object} object with all locations */ function getLocationsFromElement(element) { let company = []; @@ -791,8 +793,8 @@ function getLocationsFromElement(element) { /** * Parses the resources from a bpmn-moddle element * - * @param {Object} element - * @returns {Object} object with all resources + * @param {object} element + * @returns {object} object with all resources */ function getResourcesFromElement(element) { let consumableMaterial = []; @@ -879,6 +881,12 @@ function getResourcesFromElement(element) { return { consumableMaterial, tool, inspectionInstrument }; } +/** + * Get the performers for given element + * + * @param {object} element + * @returns {Array} performers given for element + */ function getPerformersFromElement(element) { if (element.resources) { const potentialOwner = element.resources.find( @@ -899,8 +907,8 @@ function getPerformersFromElement(element) { /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds - * @param {String} isoDuration - * @returns {Object} Object with number of years, months, days, hours, minutes and seconds + * @param {string} isoDuration + * @returns {object} Object with number of years, months, days, hours, minutes and seconds */ function parseISODuration(isoDuration) { let years = null; @@ -948,6 +956,12 @@ function parseISODuration(isoDuration) { return { years, months, days, hours, minutes, seconds }; } +/** + * Convert given ISO Duration in number of miliseconds + * + * @param {string} isoDuration duration in iso standard + * @returns {number} number of miliseconds for duration + */ function convertISODurationToMiliseconds(isoDuration) { const { years, months, days, hours, minutes, seconds } = parseISODuration(isoDuration); diff --git a/src/helper-modules/bpmn-helper/src/proceedExtensions.d.ts b/src/helper-modules/bpmn-helper/src/proceedExtensions.d.ts new file mode 100644 index 000000000..31437e602 --- /dev/null +++ b/src/helper-modules/bpmn-helper/src/proceedExtensions.d.ts @@ -0,0 +1,40 @@ +/** + * Returns the extensionElements entry inside the given element (creates one if there isn't one already) + * + * @param {object} element the element we want the extensionElements entry of + * @returns {object} the extensionElements entry + */ +export function ensureExtensionElements(element: object): object; +export function removeEmptyExtensionElements(element: any): void; +/** + * Returns a container element entry inside a given element (creates it if there isn't already one) + * + * @param {object} element the element that should contain the container element + * @param {string} containerType the type of container that is expected + * @returns {object} the container element + */ +export function ensureContainerElement(element: object, containerType: string): object; +export function removeEmptyContainerElement( + element: any, + containerType: any, + containerElement: any, +): void; +/** + * Updates the Meta Information of an element + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} elId the id of the element to update + * @param {object} metaValues the meta data values to set + * @returns {Promise.} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function setMetaData( + bpmn: string | object, + elId: string, + metaValues: object, +): Promise; +export function setProceedElement( + element: any, + proceedElementType: any, + value: any, + attributes?: {}, +): {}; diff --git a/src/helper-modules/bpmn-helper/src/proceedExtensions.js b/src/helper-modules/bpmn-helper/src/proceedExtensions.js index a2b2f6dba..3c2ce47f8 100644 --- a/src/helper-modules/bpmn-helper/src/proceedExtensions.js +++ b/src/helper-modules/bpmn-helper/src/proceedExtensions.js @@ -43,8 +43,8 @@ const proceedExtensionElements = { /** * Returns the extensionElements entry inside the given element (creates one if there isn't one already) * - * @param {Object} element the element we want the extensionElements entry of - * @returns {Object} the extensionElements entry + * @param {object} element the element we want the extensionElements entry of + * @returns {object} the extensionElements entry */ function ensureExtensionElements(element) { let { extensionElements } = element; @@ -70,9 +70,9 @@ function removeEmptyExtensionElements(element) { /** * Returns a container element entry inside a given element (creates it if there isn't already one) * - * @param {Object} element the element that should contain the container element - * @param {String} containerType the type of container that is expected - * @returns {Object} the container element + * @param {object} element the element that should contain the container element + * @param {string} containerType the type of container that is expected + * @returns {object} the container element */ function ensureContainerElement(element, containerType) { let container; @@ -194,9 +194,9 @@ function setProceedElement(element, proceedElementType, value, attributes = {}) * Updates the Meta Information of an element * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} elId the id of the element to update - * @param {Object} metaValues the meta data values to set - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @param {string} elId the id of the element to update + * @param {object} metaValues the meta data values to set + * @returns {Promise.} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function setMetaData(bpmn, elId, metaValues) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; diff --git a/src/helper-modules/bpmn-helper/src/setters.d.ts b/src/helper-modules/bpmn-helper/src/setters.d.ts new file mode 100644 index 000000000..4399610a0 --- /dev/null +++ b/src/helper-modules/bpmn-helper/src/setters.d.ts @@ -0,0 +1,194 @@ +/** + * @module @proceed/bpmn-helper + */ +/** + * Sets id in definitions element to given id, if an id already exists and differs from the new one the old id will be saved in the originalId field + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} id - the id we want to set the definitions element to + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setDefinitionsId(bpmn: string | object, id: string): Promise; +/** + * Sets name in definitions element to given name + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} name - the id we want to set the definitions element to + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setDefinitionsName(bpmn: string | object, name: string): Promise; +/** + * Will set a version in the definitions element + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {object} versionInformation - the version information to set in the definitions object + * @param {(string|number)} versionInformation.version - the version number (a time since epoch string or number) + * @param {string} [versionInformation.versionName] - a human readable name for the version + * @param {string} [versionInformation.versionDescription] - a longer description of the version + * @param {(string|number)} [versionInformation.versionBasedOn] - a reference to the version this one is based on + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setDefinitionsVersionInformation( + bpmn: string | object, + { + version, + versionName, + versionDescription, + versionBasedOn, + }: { + version: string | number; + versionName?: string; + versionDescription?: string; + versionBasedOn?: string | number; + }, +): Promise; +/** + * Sets name in definitions element to given name + * + * @param {string} bpmn the xml we want to update + * @param {string} id the id we want to set for the process inside the bpmn + * @returns {string} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setProcessId(bpmn: string, id: string): string; +export function setTemplateId(bpmn: any, id: any): Promise; +/** + * Sets targetNamespace in definitions element to https://docs.proceed-labs.org/${id}, keeps existing namespace as originalTargetNamespace + * + * @param {(string|object)} bpmn the process definition as XML string or BPMN-Moddle Object + * @param {string} id the id to be used for the targetNamespace + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setTargetNamespace(bpmn: string | object, id: string): Promise; +/** + * Sets exporter, exporterVersion, expressionLanguage, typeLanguage and needed namespaces on defintions element + * stores the previous values of exporter and exporterVersion if there are any + * + * @param {(string|object)} bpmn the process definition as XML string or BPMN-Moddle Object + * @param {string} exporterName - the exporter name + * @param {string} exporterVersion - the exporter version + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setStandardDefinitions( + bpmn: string | object, + exporterName: string, + exporterVersion: string, +): Promise; +/** + * Sets deployment method of a process + * + * @param {(string|object)} bpmn the process definition as XML string or BPMN-Moddle Object + * @param {string} method the method we want to set (dynamic/static) + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setDeploymentMethod( + bpmn: string | object, + method: string, +): Promise; +/** + * Function that sets the machineInfo of all elements in the given xml with the given machineIds + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function setMachineInfo(bpmn: string | object, machineInfo: object[]): string | object; +/** + * Sets the 'fileName' and 'implementation' attributes of a UserTask with new values. + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} userTaskId - the userTaskId to look for + * @param {string} newFileName - the new value of 'fileName' attribute + * @param {string} [newImplementation] - the new value of 'implementation' attribute; will default to html implementation + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function setUserTaskData( + bpmn: string | object, + userTaskId: string, + newFileName: string, + newImplementation?: string, +): string | object; +/** + * Adds the given constraints to the bpmn element with the given id + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} elementId + * @param {object} constraints object containing the hardConstraints and softConstraints + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function addConstraintsToElementById( + bpmn: string | object, + elementId: string, + constraints: object, +): string | object; +/** + * Add meta information of the called bpmn process to the bpmn file where it's getting called from. This includes a custom namespace in the definitions part, + * an import element as first child of definitions and the calledElement attribute of the call activity bpmn element + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} callActivityId The ID of the call activity bpmn element + * @param {string} calledBpmn The bpmn file of the called process + * @param {string} calledProcessLocation The DefinitionId of the calledBpmn. Combination of process name and process id + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function addCallActivityReference( + bpmn: string | object, + callActivityId: string, + calledBpmn: string, + calledProcessLocation: string, +): string | object; +/** + * Remove the reference to the called process added in {@link addCallActivityReference} but remains the actual bpmn element + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} callActivityId The ID of the bpmn element for which the meta information should be removed + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function removeCallActivityReference( + bpmn: string | object, + callActivityId: string, +): string | object; +/** + * Look up the given bpmn document for unused imports/custom namespaces which don't get referenced by a call activity inside this bpmn document. + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function removeUnusedCallActivityReferences(bpmn: string | object): string | object; +export function removeColorFromAllElements(bpmn: any): Promise; +/** + * Adds a documentation element to the first process in the process definition + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} description the content for the documentation element + * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + */ +export function addDocumentation(bpmn: string | object, description: string): string | object; +/** + * Adds documentation to a given process object + * + * @param {object} processObj + * @param {string} description + */ +export function addDocumentationToProcessObject( + processObj: object, + description: string, +): Promise; +/** + * Update the performer info of an element + * + * @param {object} element the element to update + * @param {Array} performers the performer data to emplace in the element + */ +export function updatePerformersOnElement(element: object, performers: any[]): Promise; +/** + * Update the performer info of an element in a bpmn file/object + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} elementId + * @param {Array} performers the performer data to emplace in the element + */ +export function updatePerformersOnElementById( + bpmn: string | object, + elementId: string, + performers: any[], +): Promise; diff --git a/src/helper-modules/bpmn-helper/src/setters.js b/src/helper-modules/bpmn-helper/src/setters.js index 23cb6bd3e..f5f7f01dc 100644 --- a/src/helper-modules/bpmn-helper/src/setters.js +++ b/src/helper-modules/bpmn-helper/src/setters.js @@ -28,7 +28,7 @@ const constraintParser = new ConstraintParser(); * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} id - the id we want to set the definitions element to - * @returns {(object|Promise)} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setDefinitionsId(bpmn, id) { return await manipulateElementsByTagName(bpmn, 'bpmn:Definitions', (definitions) => { @@ -46,7 +46,7 @@ async function setDefinitionsId(bpmn, id) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} name - the id we want to set the definitions element to - * @returns {(object|Promise)} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setDefinitionsName(bpmn, name) { return await manipulateElementsByTagName(bpmn, 'bpmn:Definitions', (definitions) => { @@ -63,7 +63,7 @@ async function setDefinitionsName(bpmn, name) { * @param {string} [versionInformation.versionName] - a human readable name for the version * @param {string} [versionInformation.versionDescription] - a longer description of the version * @param {(string|number)} [versionInformation.versionBasedOn] - a reference to the version this one is based on - * @returns {(object|Promise)} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setDefinitionsVersionInformation( bpmn, @@ -109,7 +109,7 @@ async function setTemplateId(bpmn, id) { * * @param {(string|object)} bpmn the process definition as XML string or BPMN-Moddle Object * @param {string} id the id to be used for the targetNamespace - * @returns {(object|Promise)} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setTargetNamespace(bpmn, id) { return await manipulateElementsByTagName(bpmn, 'bpmn:Definitions', (definitions) => { @@ -132,9 +132,9 @@ async function setTargetNamespace(bpmn, id) { * stores the previous values of exporter and exporterVersion if there are any * * @param {(string|object)} bpmn the process definition as XML string or BPMN-Moddle Object - * @param {String} exporterName - the exporter name - * @param {String} exporterVersion - the exporter version - * @returns {(object|Promise)} the modified BPMN process as bpmn-moddle object or XML string based on input + * @param {string} exporterName - the exporter name + * @param {string} exporterVersion - the exporter version + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setStandardDefinitions(bpmn, exporterName, exporterVersion) { return await manipulateElementsByTagName(bpmn, 'bpmn:Definitions', (definitions) => { @@ -193,7 +193,7 @@ async function setStandardDefinitions(bpmn, exporterName, exporterVersion) { * * @param {(string|object)} bpmn the process definition as XML string or BPMN-Moddle Object * @param {string} method the method we want to set (dynamic/static) - * @returns {(object|Promise)} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setDeploymentMethod(bpmn, method) { return await manipulateElementsByTagName(bpmn, 'bpmn:Process', (process) => { @@ -226,7 +226,7 @@ async function setUserTaskData( * Function that sets the machineInfo of all elements in the given xml with the given machineIds * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {Object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set + * @param {object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function setMachineInfo(bpmn, machineInfo) { @@ -245,8 +245,8 @@ async function setMachineInfo(bpmn, machineInfo) { /** * Adds the given constraint to the given bpmn element * - * @param {Object} element the bpmn BPMN-Moddle element - * @param {Object} cons object containing the hardConstraints and softConstraints + * @param {object} element the bpmn BPMN-Moddle element + * @param {object} cons object containing the hardConstraints and softConstraints */ async function addConstraintsToElement(element, cons) { if (element) { @@ -283,7 +283,7 @@ async function addConstraintsToElement(element, cons) { /** * Update the performer info of an element * - * @param {Object} element the element to update + * @param {object} element the element to update * @param {Array} performers the performer data to emplace in the element */ async function updatePerformersOnElement(element, performers) { @@ -320,7 +320,7 @@ async function updatePerformersOnElement(element, performers) { * Update the performer info of an element in a bpmn file/object * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} elementId + * @param {string} elementId * @param {Array} performers the performer data to emplace in the element */ async function updatePerformersOnElementById(bpmn, elementId, performers) { @@ -334,7 +334,7 @@ async function updatePerformersOnElementById(bpmn, elementId, performers) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId - * @param {Object} constraints object containing the hardConstraints and softConstraints + * @param {object} constraints object containing the hardConstraints and softConstraints * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function addConstraintsToElementById(bpmn, elementId, constraints) { @@ -348,9 +348,9 @@ async function addConstraintsToElementById(bpmn, elementId, constraints) { * an import element as first child of definitions and the calledElement attribute of the call activity bpmn element * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} callActivityId The ID of the call activity bpmn element - * @param {String} calledBpmn The bpmn file of the called process - * @param {String} calledProcessLocation The DefinitionId of the calledBpmn. Combination of process name and process id + * @param {string} callActivityId The ID of the call activity bpmn element + * @param {string} calledBpmn The bpmn file of the called process + * @param {string} calledProcessLocation The DefinitionId of the calledBpmn. Combination of process name and process id * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function addCallActivityReference(bpmn, callActivityId, calledBpmn, calledProcessLocation) { @@ -413,7 +413,7 @@ async function addCallActivityReference(bpmn, callActivityId, calledBpmn, called * Remove the reference to the called process added in {@link addCallActivityReference} but remains the actual bpmn element * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {String} callActivityId The ID of the bpmn element for which the meta information should be removed + * @param {string} callActivityId The ID of the bpmn element for which the meta information should be removed * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function removeCallActivityReference(bpmn, callActivityId) { @@ -523,8 +523,8 @@ async function addDocumentation(bpmn, description) { /** * Adds documentation to a given process object * - * @param {Object} processObj - * @param {String} description + * @param {object} processObj + * @param {string} description */ async function addDocumentationToProcessObject(processObj, description) { const docs = processObj.get('documentation'); diff --git a/src/helper-modules/bpmn-helper/src/util.d.ts b/src/helper-modules/bpmn-helper/src/util.d.ts new file mode 100644 index 000000000..f59dfdf39 --- /dev/null +++ b/src/helper-modules/bpmn-helper/src/util.d.ts @@ -0,0 +1,98 @@ +export type manipulationFunction = (bpmnModdleElement: object) => any; +export const moddle: any; +/** + * @module @proceed/bpmn-helper + */ +/** + * Sets the xmlns:proceed attribute in the definitions element of the bpmn to the one expected in our custom schema + * + * This is to make sure that importing the xml with bpmn-moddle will not lead to every proceed element being prefixed with ns0 + * + * @param {string} xml + */ +export function ensureCorrectProceedNamespace(xml: string): string; +/** + * Function that converts the given XML to a traversable object representation + * + * @param {string} xml - the BPMN XML that should be converted + * @param {string} [typename] - name of the root element, optional + * @returns {Promise} a traversable object representation of the given XML + * @throws {Error} if the given string is not an XML + * @throws {Error} if the given XML can not be converted to a bpmn-moddle object (multiple possible reasons) + */ +export function toBpmnObject(xml: string, typename?: string): Promise; +/** + * Function that converts the given bpmn object to xml + * + * @param {object} bpmn traversable object representation + * @returns {Promise} a xml representation of the given object + */ +export function toBpmnXml(obj: any): Promise; +/** + * Finds all kinds of childnodes in a given node + * + * @param {object} travObj object of which we want to know the childnodes + * @returns {array} all childnodes of the given node + */ +export function getChildren(travObj: object): any[]; +/** + * A function that given a traversable object returns all occurences of a given tagName + * + * @param {object} travObj the object we want to search in + * @param {string} tagname the name we are searching for + * @returns {array} - all nodes with the given tagName + */ +export function getElementsByTagName(travObj: object, tagname: string): any[]; +/** + * A function that given a traversable object returns all occurences + * + * @param {object} travObj the object we want to search in + * @returns {array} - all nodes within the object + */ +export function getAllElements(travObj: object): any[]; +/** + * A function that given a traversable object returns the nested object with the given id + * + * @param {object} travObj the object we want to search in + * @param {string} id the id of the object we want to find + * @returns {object|undefined} - returns the found object or undefined when no matching object was found + */ +export function getElementById(travObj: object, id: string): object | undefined; +/** + * Gets the diagram element for the given model element + * + * @param {object} element the model element + * @param {object} [definitions] the definitions object to search in + */ +export function getElementDI(element: object, definitions?: object): any; +/** + * @callback manipulationFunction + * @param {object} bpmnModdleElement - the element return by searching the bpmn-moddle process + */ +/** + * Function that changes an element in the given xml using the given manipulation function + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} id - the id of the element that should be changed + * @param {manipulationFunction} manipFunc - the function that will be used to change the element + * @returns {Promise} the BPMN process as bpmn-moddle object or XML string based on input + */ +export function manipulateElementById( + bpmn: string | object, + id: string, + manipFunc: manipulationFunction, +): Promise; +/** + * Function that changes all elements in the given xml with the given tagname + * using the given function + * + * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object + * @param {string} tagName - the tagname of the elements we want to change, starts with 'bpmn:', e.g. 'bpmn:Definitions' + * @param {manipulationFunction} manipFunc - the function that gets called on each element with a forEach-Loop + * @returns {Promise} the BPMN process as bpmn-moddle object or XML string based on input + */ +export function manipulateElementsByTagName( + bpmn: string | object, + tagName: string, + manipFunc: manipulationFunction, +): Promise; diff --git a/src/helper-modules/bpmn-helper/src/util.js b/src/helper-modules/bpmn-helper/src/util.js index a8b33dcc9..7be220236 100644 --- a/src/helper-modules/bpmn-helper/src/util.js +++ b/src/helper-modules/bpmn-helper/src/util.js @@ -13,7 +13,7 @@ const moddle = new BPMNModdle({ proceed: bpmnSchema }); * * This is to make sure that importing the xml with bpmn-moddle will not lead to every proceed element being prefixed with ns0 * - * @param {String} xml + * @param {string} xml */ function ensureCorrectProceedNamespace(xml) { return xml.replace(/(xmlns:proceed=\")([^\"]*)(\")/g, `$1${bpmnSchema.uri}$3`); @@ -24,7 +24,7 @@ function ensureCorrectProceedNamespace(xml) { * * @param {string} xml - the BPMN XML that should be converted * @param {string} [typename] - name of the root element, optional - * @returns {Promise} a traversable object representation of the given XML + * @returns {Promise} a traversable object representation of the given XML * @throws {Error} if the given string is not an XML * @throws {Error} if the given XML can not be converted to a bpmn-moddle object (multiple possible reasons) */ @@ -36,7 +36,7 @@ async function toBpmnObject(xml, typename) { /** * Function that converts the given bpmn object to xml * - * @param {Object} bpmn traversable object representation + * @param {object} bpmn traversable object representation * @returns {Promise} a xml representation of the given object */ async function toBpmnXml(obj) { @@ -106,8 +106,8 @@ function getElementsByTagName(travObj, tagname) { /** * Gets the diagram element for the given model element * - * @param {Object} element the model element - * @param {Object} [definitions] the definitions object to search in + * @param {object} element the model element + * @param {object} [definitions] the definitions object to search in */ function getElementDI(element, definitions) { if (!definitions) { @@ -150,7 +150,7 @@ function getElementById(travObj, id) { /** * @callback manipulationFunction - * @param {object} bpmn-moddle-element - the element return by searching the bpmn-moddle process + * @param {object} bpmnModdleElement - the element return by searching the bpmn-moddle process */ /** @@ -159,7 +159,7 @@ function getElementById(travObj, id) { * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} id - the id of the element that should be changed * @param {manipulationFunction} manipFunc - the function that will be used to change the element - * @returns {(object|Promise)} the BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the BPMN process as bpmn-moddle object or XML string based on input */ async function manipulateElementById(bpmn, id, manipFunc) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -176,7 +176,7 @@ async function manipulateElementById(bpmn, id, manipFunc) { * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} tagName - the tagname of the elements we want to change, starts with 'bpmn:', e.g. 'bpmn:Definitions' * @param {manipulationFunction} manipFunc - the function that gets called on each element with a forEach-Loop - * @returns {(object|Promise)} the BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the BPMN process as bpmn-moddle object or XML string based on input */ async function manipulateElementsByTagName(bpmn, tagName, manipFunc) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; diff --git a/src/helper-modules/bpmn-helper/src/validators.d.ts b/src/helper-modules/bpmn-helper/src/validators.d.ts new file mode 100644 index 000000000..761f35dfd --- /dev/null +++ b/src/helper-modules/bpmn-helper/src/validators.d.ts @@ -0,0 +1,11 @@ +/** + * @module @proceed/bpmn-helper + */ +/** + * Checks if a process referenced in a call activity contains only a single non-typed start event + * + * @param {string} xml + * @param {string} processId + * @returns {boolean} true if called process is valid + */ +export function validateCalledProcess(xml: string, processId: string): boolean; diff --git a/src/helper-modules/bpmn-helper/src/validators.js b/src/helper-modules/bpmn-helper/src/validators.js index f8a8ba4a2..0499f8a7e 100644 --- a/src/helper-modules/bpmn-helper/src/validators.js +++ b/src/helper-modules/bpmn-helper/src/validators.js @@ -7,8 +7,9 @@ const { toBpmnObject, getElementsByTagName, getElementById } = require('./util.j /** * Checks if a process referenced in a call activity contains only a single non-typed start event * - * @param {String} xml - * @param {String} processId + * @param {string} xml + * @param {string} processId + * @returns {boolean} true if called process is valid */ async function validateCalledProcess(xml, processId) { const definitions = await toBpmnObject(xml); diff --git a/src/management-system-v2/lib/helpers.ts b/src/management-system-v2/lib/helpers.ts index d8dee8097..971a5e834 100644 --- a/src/management-system-v2/lib/helpers.ts +++ b/src/management-system-v2/lib/helpers.ts @@ -1,6 +1,6 @@ import { ApiData, get, put, post } from './fetch-data'; -const { +import { toBpmnObject, toBpmnXml, getDefinitionsId, @@ -9,7 +9,7 @@ const { getUserTaskImplementationString, getUserTaskFileNameMapping, setUserTaskData, -} = require('@proceed/bpmn-helper'); +} from '@proceed/bpmn-helper'; const { diff } = require('bpmn-js-differ'); @@ -31,23 +31,27 @@ async function areVersionsEqual(bpmn: string, otherBpmn: string) { versionBasedOn, } = await getDefinitionsVersionInformation(otherBpmnObj); - // check if the two bpmns were the same if they had the same version information - await setDefinitionsVersionInformation(bpmnObj, { - version, - versionName, - versionDescription, - versionBasedOn, - }); + if (version) { + // check if the two bpmns were the same if they had the same version information + await setDefinitionsVersionInformation(bpmnObj, { + version, + versionName, + versionDescription, + versionBasedOn, + }); - // compare the two bpmns - const changes = diff(otherBpmnObj, bpmnObj); - const hasChanges = - Object.keys(changes._changed).length || - Object.keys(changes._removed).length || - Object.keys(changes._added).length || - Object.keys(changes._layoutChanged).length; + // compare the two bpmns + const changes = diff(otherBpmnObj, bpmnObj); + const hasChanges = + Object.keys(changes._changed).length || + Object.keys(changes._removed).length || + Object.keys(changes._added).length || + Object.keys(changes._layoutChanged).length; - return !hasChanges; + return !hasChanges; + } + + return false; } async function getLocalVersionBpmn( @@ -93,7 +97,8 @@ async function versionUserTasks( let fileName = `${htmlMapping[userTaskId].fileName}-${newVersion}`; // get the html of the user task in the based on version (if there is one and it is locally known) - const basedOnBPMN = await getLocalVersionBpmn(processInfo, versionBasedOn); + const basedOnBPMN = + versionBasedOn && (await getLocalVersionBpmn(processInfo, versionBasedOn)); // check if there is a preceding version and if the html of the user task actually changed from that version let userTaskHtmlAlreadyExisting = false; @@ -170,7 +175,7 @@ export async function createNewProcessVersion( const versionedBpmn = await toBpmnXml(bpmnObj); // if the new version has no changes to the version it is based on don't create a new version and return the previous version - const basedOnBPMN = await getLocalVersionBpmn(processInfo, versionBasedOn); + const basedOnBPMN = versionBasedOn && (await getLocalVersionBpmn(processInfo, versionBasedOn)); if (basedOnBPMN && (await areVersionsEqual(versionedBpmn, basedOnBPMN))) { return versionBasedOn; } @@ -194,14 +199,19 @@ async function updateProcessVersionBasedOn(processDefinitionsId: string, version }); if (processInfo?.bpmn) { - const versionInformation = await getDefinitionsVersionInformation(processInfo.bpmn); - const bpmn = await setDefinitionsVersionInformation(processInfo.bpmn, { - ...versionInformation, - versionBasedOn, - }); - await put('/process/{definitionId}', { - params: { path: { definitionId: processDefinitionsId } }, - body: { bpmn }, - }); + const { version, description, name } = await getDefinitionsVersionInformation(processInfo.bpmn); + + if (version) { + const bpmn = (await setDefinitionsVersionInformation(processInfo.bpmn, { + version, + versionDescription: description, + versionName: name, + versionBasedOn, + })) as string; + await put('/process/{definitionId}', { + params: { path: { definitionId: processDefinitionsId } }, + body: { bpmn }, + }); + } } } From a56cee5a5d9dd7ab86b3053945d9365fe3e08f9c Mon Sep 17 00:00:00 2001 From: Lucas Date: Thu, 5 Oct 2023 14:01:45 +0200 Subject: [PATCH 04/13] improved jsdoc comments in bpmn helper files --- src/helper-modules/bpmn-helper/index.d.ts | 179 +++++++--- .../bpmn-helper/src/getters.d.ts | 321 ++++++++++++++++-- src/helper-modules/bpmn-helper/src/getters.js | 99 +++++- .../bpmn-helper/src/setters.d.ts | 57 ++-- src/helper-modules/bpmn-helper/src/setters.js | 31 +- .../bpmn-helper/src/validators.d.ts | 4 +- .../bpmn-helper/src/validators.js | 2 +- 7 files changed, 578 insertions(+), 115 deletions(-) diff --git a/src/helper-modules/bpmn-helper/index.d.ts b/src/helper-modules/bpmn-helper/index.d.ts index 1da9a609d..982d6d802 100644 --- a/src/helper-modules/bpmn-helper/index.d.ts +++ b/src/helper-modules/bpmn-helper/index.d.ts @@ -14,7 +14,7 @@ declare const _exports: { getUserTaskImplementationString(): string; generateTargetNamespace(id: any): string; initXml(processId?: any, startEventId?: string): string; - validateCalledProcess(xml: string, processId: string): boolean; + validateCalledProcess(xml: string, processId: string): Promise; setDefinitionsId(bpmn: string | object, id: string): Promise; setDefinitionsName(bpmn: string | object, name: string): Promise; setDefinitionsVersionInformation( @@ -31,8 +31,8 @@ declare const _exports: { versionBasedOn?: string | number; }, ): Promise; - setProcessId(bpmn: string, id: string): string; - setTemplateId(bpmn: any, id: any): Promise; + setProcessId(bpmn: string, id: string): Promise; + setTemplateId(bpmn: string, id: string): Promise; setTargetNamespace(bpmn: string | object, id: string): Promise; setStandardDefinitions( bpmn: string | object, @@ -40,28 +40,31 @@ declare const _exports: { exporterVersion: string, ): Promise; setDeploymentMethod(bpmn: string | object, method: string): Promise; - setMachineInfo(bpmn: string | object, machineInfo: object[]): string | object; + setMachineInfo(bpmn: string | object, machineInfo: object[]): Promise; setUserTaskData( bpmn: string | object, userTaskId: string, newFileName: string, newImplementation?: string, - ): string | object; + ): Promise; addConstraintsToElementById( bpmn: string | object, elementId: string, constraints: object, - ): string | object; + ): Promise; addCallActivityReference( bpmn: string | object, callActivityId: string, calledBpmn: string, calledProcessLocation: string, - ): string | object; - removeCallActivityReference(bpmn: string | object, callActivityId: string): string | object; - removeUnusedCallActivityReferences(bpmn: string | object): string | object; - removeColorFromAllElements(bpmn: any): Promise; - addDocumentation(bpmn: string | object, description: string): string | object; + ): Promise; + removeCallActivityReference( + bpmn: string | object, + callActivityId: string, + ): Promise; + removeUnusedCallActivityReferences(bpmn: string | object): Promise; + removeColorFromAllElements(bpmn: string | object): Promise; + addDocumentation(bpmn: string | object, description: string): Promise; addDocumentationToProcessObject(processObj: object, description: string): Promise; updatePerformersOnElement(element: object, performers: any[]): Promise; updatePerformersOnElementById( @@ -69,42 +72,124 @@ declare const _exports: { elementId: string, performers: any[], ): Promise; - getDefinitionsId: typeof getters.getDefinitionsId; - getOriginalDefinitionsId: typeof getters.getOriginalDefinitionsId; - getDefinitionsName: typeof getters.getDefinitionsName; - getDefinitionsInfos: typeof getters.getDefinitionsInfos; - getImports: typeof getters.getImports; - getDefinitionsVersionInformation: typeof getters.getDefinitionsVersionInformation; - getProcessIds: typeof getters.getProcessIds; - getDeploymentMethod: typeof getters.getDeploymentMethod; - getProcessConstraints: typeof getters.getProcessConstraints; - getProcessDocumentation: typeof getters.getProcessDocumentation; - getProcessDocumentationByObject: typeof getters.getProcessDocumentationByObject; - getUserTaskFileNameMapping: typeof getters.getUserTaskFileNameMapping; - getAllUserTaskFileNamesAndUserTaskIdsMapping: typeof getters.getAllUserTaskFileNamesAndUserTaskIdsMapping; - getSubprocess: typeof getters.getSubprocess; - getSubprocessContent: typeof getters.getSubprocessContent; - getTargetDefinitionsAndProcessIdForCallActivityByObject: typeof getters.getTargetDefinitionsAndProcessIdForCallActivityByObject; - getDefinitionsAndProcessIdForEveryCallActivity: typeof getters.getDefinitionsAndProcessIdForEveryCallActivity; - getStartEvents: typeof getters.getStartEvents; - getAllBpmnFlowElements: typeof getters.getAllBpmnFlowElements; - getAllBpmnFlowNodeIds: typeof getters.getAllBpmnFlowNodeIds; - getAllBpmnFlowElementIds: typeof getters.getAllBpmnFlowElementIds; - getChildrenFlowElements: typeof getters.getChildrenFlowElements; - getElementMachineMapping: typeof getters.getElementMachineMapping; - getTaskConstraintMapping: typeof getters.getTaskConstraintMapping; - getIdentifyingInfos: typeof getters.getIdentifyingInfos; - getRootFromElement: typeof getters.getRootFromElement; - getMetaDataFromElement: typeof getters.getMetaDataFromElement; - getMetaData: typeof getters.getMetaData; - getMilestonesFromElement: typeof getters.getMilestonesFromElement; - getMilestonesFromElementById: typeof getters.getMilestonesFromElementById; - getResourcesFromElement: typeof getters.getResourcesFromElement; - getLocationsFromElement: typeof getters.getLocationsFromElement; - getPerformersFromElement: typeof getters.getPerformersFromElement; - getPerformersFromElementById: typeof getters.getPerformersFromElementById; - parseISODuration: typeof getters.parseISODuration; - convertISODurationToMiliseconds: typeof getters.convertISODurationToMiliseconds; + getDefinitionsId(bpmn: string | object): Promise; + getOriginalDefinitionsId(bpmn: string | object): Promise; + getDefinitionsName(bpmn: string | object): Promise; + getDefinitionsInfos(bpmn: string | object): Promise; + getImports(bpmn: string | object): Promise; + getDefinitionsVersionInformation(bpmn: string | object): Promise<{ + version?: number; + name?: string; + description?: string; + versionBasedOn?: number; + }>; + getProcessIds(bpmn: string | object): Promise; + getDeploymentMethod(bpmn: string | object): Promise; + getProcessConstraints(bpmn: string | object): Promise<{ + hardConstraints: any[]; + softConstraints: any[]; + }>; + getProcessDocumentation(bpmn: string | object): Promise; + getProcessDocumentationByObject(processObject: object): string; + getUserTaskFileNameMapping(bpmn: string | object): Promise<{ + [userTaskId: string]: { + fileName: string; + implementation: string; + }; + }>; + getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn: string | object): Promise<{ + [userTaskFileName: string]: string; + }>; + getSubprocess(bpmn: string | object, subprocessId: string): Promise; + getSubprocessContent(bpmn: string, subprocessId: string): Promise; + getTargetDefinitionsAndProcessIdForCallActivityByObject( + bpmnObj: object, + callActivityId: string, + ): { + definitionId: string; + processId: string; + version: number; + }; + getDefinitionsAndProcessIdForEveryCallActivity( + bpmn: string | object, + dontThrow?: boolean, + ): Promise<{ + [callActivityId: string]: { + definitionId: string; + processId: string; + version: number; + }; + }>; + getStartEvents(bpmn: string | object): Promise; + getAllBpmnFlowElements(bpmn: string | object): Promise; + getAllBpmnFlowNodeIds(bpmn: string | object): Promise; + getAllBpmnFlowElementIds(bpmn: string | object): Promise; + getChildrenFlowElements(bpmn: string | object, elementId: any): Promise; + getElementMachineMapping(bpmn: string | object): Promise<{ + [flowNodeId: string]: { + machineAddress: string; + machineId: string; + }; + }>; + getTaskConstraintMapping(bpmn: string | object): Promise<{ + [bpmnElementIds: string]: { + hardConstraints: any[]; + softConstraints: any[]; + }; + }>; + getIdentifyingInfos(bpmn: string | object): Promise<{ + id: string; + originalId: string; + processIds: string[]; + name: string; + description: string; + }>; + getRootFromElement(businessObject: object): object; + getMetaDataFromElement(element: object): { + [key: string]: any; + }; + getMetaData( + bpmn: string | object, + elId: string, + ): Promise<{ + [key: string]: any; + }>; + getMilestonesFromElement(element: object): { + id: string; + name: string; + description: string; + }[]; + getMilestonesFromElementById( + bpmn: string | object, + elementId: string, + ): { + id: string; + name: string; + description: string; + }[]; + getResourcesFromElement(element: object): { + consumableMaterial: getters.ResourceInfos[]; + tool: getters.ResourceInfos[]; + inspectionInstrument: getters.ResourceInfos[]; + }; + getLocationsFromElement(element: object): { + company: getters.CompanyInfos[]; + factory: getters.FactoryInfos[]; + building: getters.BuildingInfos[]; + area: getters.AreaInfos[]; + workingPlace: getters.WorkingPlaceInfos[]; + }; + getPerformersFromElement(element: object): any[]; + getPerformersFromElementById(bpmn: string | object, elementId: string): any[]; + parseISODuration(isoDuration: string): { + years: number; + months: number; + days: number; + hours: number; + minutes: number; + seconds: number; + }; + convertISODurationToMiliseconds(isoDuration: string): number; ensureCorrectProceedNamespace(xml: string): string; toBpmnObject(xml: string, typename?: string): Promise; toBpmnXml(obj: any): Promise; diff --git a/src/helper-modules/bpmn-helper/src/getters.d.ts b/src/helper-modules/bpmn-helper/src/getters.d.ts index da37e3e91..2129224c7 100644 --- a/src/helper-modules/bpmn-helper/src/getters.d.ts +++ b/src/helper-modules/bpmn-helper/src/getters.d.ts @@ -24,6 +24,168 @@ export type DefinitionsInfos = { */ targetNamespace: string; }; +/** + * An object containing properties from defined companies + */ +export type CompanyInfos = { + /** + * - company id + */ + id: string; + /** + * - company short name + */ + shortName: string; + /** + * - company long name + */ + longName: string; + /** + * - company description + */ + description: string; +}; +/** + * An object containing properties from defined factories + */ +export type FactoryInfos = { + /** + * - factory id + */ + id: string; + /** + * - factory short name + */ + shortName: string; + /** + * - factory long name + */ + longName: string; + /** + * - factory description + */ + description: string; + /** + * - reference to company linked to factory + */ + companyRef: string; +}; +/** + * An object containing properties from defined buildings + */ +export type BuildingInfos = { + /** + * - building id + */ + id: string; + /** + * - building short name + */ + shortName: string; + /** + * - building long name + */ + longName: string; + /** + * - building description + */ + description: string; + /** + * - building to factory linked to building + */ + factoryRef: string; +}; +/** + * An object containing properties from defined areas + */ +export type AreaInfos = { + /** + * - area id + */ + id: string; + /** + * - area short name + */ + shortName: string; + /** + * - area long name + */ + longName: string; + /** + * - area description + */ + description: string; + /** + * - reference to building linked to area + */ + buildingRef: string; +}; +/** + * An object containing properties from defined working places + */ +export type WorkingPlaceInfos = { + /** + * - workingPlace id + */ + id: string; + /** + * - workingPlace short name + */ + shortName: string; + /** + * - workingPlace long name + */ + longName: string; + /** + * - workingPlace description + */ + description: string; + /** + * - reference to building linked to workingPlace + */ + buildingRef: string; + /** + * - reference to area linked to workingPlace + */ + areaRef: string; +}; +/** + * An object containing properties from defined resources + */ +export type ResourceInfos = { + /** + * - consumableMaterial id + */ + id: string; + /** + * - consumableMaterial short name + */ + shortName: string; + /** + * - consumableMaterial long name + */ + longName: string; + /** + * - consumableMaterial manufacturer + */ + manufacturer: string; + /** + * - consumableMaterial manufacturerSerialNumber + */ + manufacturerSerialNumber: string; + /** + * - consumableMaterial unit + */ + unit: string; + /** + * - consumableMaterial quantity + */ + quantity: string; + /** + * - consumableMaterial description + */ + description: string; +}; /** * Returns id of the given process definition * @@ -146,10 +308,10 @@ export function getUserTaskFileNameMapping(bpmn: string | object): Promise<{ * for every UserTask in a BPMN process. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ '': '' }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) + * @returns { Promise.<{ [userTaskFileName: string] : string }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) */ export function getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn: string | object): Promise<{ - '': ''; + [userTaskFileName: string]: string; }>; /** * Returns a xml with Diagram Elements just from the given subprocess and their nested Processes @@ -213,14 +375,14 @@ export function getTargetDefinitionsAndProcessIdForCallActivityByObject( * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {boolean} [dontThrow] - whether to throw errors or not in retrieving process ids in call activities - * @returns { Promise.<{ '': { definitionId: string, processId: string, version: number }}> } an object (a map) with all callActivityIds as keys + * @returns { Promise.<{ [callActivityId: string]: { definitionId: string, processId: string, version: number }}> } an object (a map) with all callActivityIds as keys * @throws see function: {@link getTargetDefinitionsAndProcessIdForCallActivityByObject} */ export function getDefinitionsAndProcessIdForEveryCallActivity( bpmn: string | object, dontThrow?: boolean, ): Promise<{ - '': { + [callActivityId: string]: { definitionId: string; processId: string; version: number; @@ -254,7 +416,7 @@ export function getAllBpmnFlowNodeIds(bpmn: string | object): Promise; * Gets the Id of every Task|Event|Gateway|CallActivity|SubProcess|SequenceFlow inside a BPMN process * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} Ids of every element inside a BPMN process + * @returns {Promise.} Ids of every element inside a BPMN process */ export function getAllBpmnFlowElementIds(bpmn: string | object): Promise; /** @@ -268,9 +430,14 @@ export function getChildrenFlowElements(bpmn: string | object, elementId: any): * Returns a mapping of the ids of the process nodes to the machines they are mapped to * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} the mapping from a node id to information about the machine it is mapped to + * @returns {Promise.<{[flowNodeId: string]: {machineAddress: string, machineId: string}}>} the mapping from a node id to information about the machine it is mapped to */ -export function getElementMachineMapping(bpmn: string | object): Promise; +export function getElementMachineMapping(bpmn: string | object): Promise<{ + [flowNodeId: string]: { + machineAddress: string; + machineId: string; + }; +}>; /** * Get all Constraints for every BPMN Element. * (The Constraint XML elements are defined in the PROCEED XML Schema @@ -279,10 +446,10 @@ export function getElementMachineMapping(bpmn: string | object): Promise; * @see {@link https://docs.proceed-labs.org/concepts/bpmn/bpmn-constraints/} * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ '': { hardConstraints: Array, softConstraints: Array} }> } An Object (a map) where all keys are the BPMN element ids and the value is an object with the hard and soft Constraint Arrays + * @returns { Promise.<{ [bpmnElementIds: string]: { hardConstraints: Array, softConstraints: Array} }> } An Object (a map) where all keys are the BPMN element ids and the value is an object with the hard and soft Constraint Arrays */ export function getTaskConstraintMapping(bpmn: string | object): Promise<{ - '': { + [bpmnElementIds: string]: { hardConstraints: any[]; softConstraints: any[]; }; @@ -314,46 +481,143 @@ export function getRootFromElement(businessObject: object): object; * Parses the meta data from a bpmn-moddle element * * @param {object} element - * @returns {object} key value list of meta values + * @returns {{[key: string]: any}} key value list of meta values */ -export function getMetaDataFromElement(element: object): object; +export function getMetaDataFromElement(element: object): { + [key: string]: any; +}; /** * Get the meta information of an element * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elId the id of the element to update - * @returns {Promise.} the meta information + * @returns {Promise.<{[key: string]: any}>} the meta information */ -export function getMetaData(bpmn: string | object, elId: string): Promise; +export function getMetaData( + bpmn: string | object, + elId: string, +): Promise<{ + [key: string]: any; +}>; /** * Parses the milestones from a bpmn-moddle element * * @param {object} element - * @returns {Array} array with all milestones + * @returns {{id: string, name: string, description: string}[]} array with all milestones */ -export function getMilestonesFromElement(element: object): any[]; +export function getMilestonesFromElement(element: object): { + id: string; + name: string; + description: string; +}[]; /** * Get the milestones for given element id * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId the id of the element - * @returns {Array} array with all milestones + * @returns {{id: string, name: string, description: string}[]} array with all milestones + */ +export function getMilestonesFromElementById( + bpmn: string | object, + elementId: string, +): { + id: string; + name: string; + description: string; +}[]; +/** + * An object containing properties from defined resources + * + * @typedef ResourceInfos + * @type {object} + * @property {string} id - consumableMaterial id + * @property {string} shortName - consumableMaterial short name + * @property {string} longName - consumableMaterial long name + * @property {string} manufacturer - consumableMaterial manufacturer + * @property {string} manufacturerSerialNumber - consumableMaterial manufacturerSerialNumber + * @property {string} unit - consumableMaterial unit + * @property {string} quantity - consumableMaterial quantity + * @property {string} description - consumableMaterial description */ -export function getMilestonesFromElementById(bpmn: string | object, elementId: string): any[]; /** * Parses the resources from a bpmn-moddle element * * @param {object} element - * @returns {object} object with all resources + * @returns {{consumableMaterial: ResourceInfos[], tool: ResourceInfos[], inspectionInstrument: ResourceInfos[]}} object with all resources + */ +export function getResourcesFromElement(element: object): { + consumableMaterial: ResourceInfos[]; + tool: ResourceInfos[]; + inspectionInstrument: ResourceInfos[]; +}; +/** + * An object containing properties from defined companies + * + * @typedef CompanyInfos + * @type {object} + * @property {string} id - company id + * @property {string} shortName - company short name + * @property {string} longName - company long name + * @property {string} description - company description + */ +/** + * An object containing properties from defined factories + * + * @typedef FactoryInfos + * @type {object} + * @property {string} id - factory id + * @property {string} shortName - factory short name + * @property {string} longName - factory long name + * @property {string} description - factory description + * @property {string} companyRef - reference to company linked to factory + */ +/** + * An object containing properties from defined buildings + * + * @typedef BuildingInfos + * @type {object} + * @property {string} id - building id + * @property {string} shortName - building short name + * @property {string} longName - building long name + * @property {string} description - building description + * @property {string} factoryRef - building to factory linked to building + */ +/** + * An object containing properties from defined areas + * + * @typedef AreaInfos + * @type {object} + * @property {string} id - area id + * @property {string} shortName - area short name + * @property {string} longName - area long name + * @property {string} description - area description + * @property {string} buildingRef - reference to building linked to area + */ +/** + * An object containing properties from defined working places + * + * @typedef WorkingPlaceInfos + * @type {object} + * @property {string} id - workingPlace id + * @property {string} shortName - workingPlace short name + * @property {string} longName - workingPlace long name + * @property {string} description - workingPlace description + * @property {string} buildingRef - reference to building linked to workingPlace + * @property {string} areaRef - reference to area linked to workingPlace */ -export function getResourcesFromElement(element: object): object; /** * Parses the locations from a bpmn-moddle element * * @param {object} element - * @returns {object} object with all locations - */ -export function getLocationsFromElement(element: object): object; + * @returns {{company: CompanyInfos[], factory: FactoryInfos[], building: BuildingInfos[], area: AreaInfos[], workingPlace: WorkingPlaceInfos[]}} object with all locations + */ +export function getLocationsFromElement(element: object): { + company: CompanyInfos[]; + factory: FactoryInfos[]; + building: BuildingInfos[]; + area: AreaInfos[]; + workingPlace: WorkingPlaceInfos[]; +}; /** * Get the performers for given element * @@ -372,9 +636,16 @@ export function getPerformersFromElementById(bpmn: string | object, elementId: s /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds * @param {string} isoDuration - * @returns {object} Object with number of years, months, days, hours, minutes and seconds - */ -export function parseISODuration(isoDuration: string): object; + * @returns {{years: number, months: number, days: number, hours: number, minutes: number, seconds: number}} Object with number of years, months, days, hours, minutes and seconds + */ +export function parseISODuration(isoDuration: string): { + years: number; + months: number; + days: number; + hours: number; + minutes: number; + seconds: number; +}; /** * Convert given ISO Duration in number of miliseconds * diff --git a/src/helper-modules/bpmn-helper/src/getters.js b/src/helper-modules/bpmn-helper/src/getters.js index a43f9e4ab..820792454 100644 --- a/src/helper-modules/bpmn-helper/src/getters.js +++ b/src/helper-modules/bpmn-helper/src/getters.js @@ -167,7 +167,7 @@ async function getDeploymentMethod(bpmn) { * Returns a mapping of the ids of the process nodes to the machines they are mapped to * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} the mapping from a node id to information about the machine it is mapped to + * @returns {Promise.<{[flowNodeId: string]: {machineAddress: string, machineId: string}}>} the mapping from a node id to information about the machine it is mapped to */ async function getElementMachineMapping(bpmn) { const elementMachineMapping = {}; @@ -207,7 +207,7 @@ async function getUserTaskFileNameMapping(bpmn) { * for every UserTask in a BPMN process. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ '': '' }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) + * @returns { Promise.<{ [userTaskFileName: string] : string }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) */ async function getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -350,7 +350,7 @@ async function getAllBpmnFlowElements(bpmn) { * Gets the Id of every Task|Event|Gateway|CallActivity|SubProcess|SequenceFlow inside a BPMN process * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} Ids of every element inside a BPMN process + * @returns {Promise.} Ids of every element inside a BPMN process */ async function getAllBpmnFlowElementIds(bpmn) { const allBpmnElements = await getAllBpmnFlowElements(bpmn); @@ -444,7 +444,7 @@ function getTargetDefinitionsAndProcessIdForCallActivityByObject(bpmnObj, callAc * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {boolean} [dontThrow] - whether to throw errors or not in retrieving process ids in call activities - * @returns { Promise.<{ '': { definitionId: string, processId: string, version: number }}> } an object (a map) with all callActivityIds as keys + * @returns { Promise.<{ [callActivityId: string]: { definitionId: string, processId: string, version: number }}> } an object (a map) with all callActivityIds as keys * @throws see function: {@link getTargetDefinitionsAndProcessIdForCallActivityByObject} */ async function getDefinitionsAndProcessIdForEveryCallActivity(bpmn, dontThrow = false) { @@ -489,7 +489,7 @@ async function getImports(bpmn) { * @see {@link https://docs.proceed-labs.org/concepts/bpmn/bpmn-constraints/} * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ '': { hardConstraints: Array, softConstraints: Array} }> } An Object (a map) where all keys are the BPMN element ids and the value is an object with the hard and soft Constraint Arrays + * @returns { Promise.<{ [bpmnElementIds: string]: { hardConstraints: Array, softConstraints: Array} }> } An Object (a map) where all keys are the BPMN element ids and the value is an object with the hard and soft Constraint Arrays */ async function getTaskConstraintMapping(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -608,7 +608,7 @@ function getRootFromElement(businessObject) { * Parses the meta data from a bpmn-moddle element * * @param {object} element - * @returns {object} key value list of meta values + * @returns {{[key: string]: any}} key value list of meta values */ function getMetaDataFromElement(element) { const properties = {}; @@ -650,7 +650,7 @@ function getMetaDataFromElement(element) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elId the id of the element to update - * @returns {Promise.} the meta information + * @returns {Promise.<{[key: string]: any}>} the meta information */ async function getMetaData(bpmn, elId) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -663,7 +663,7 @@ async function getMetaData(bpmn, elId) { * Parses the milestones from a bpmn-moddle element * * @param {object} element - * @returns {Array} array with all milestones + * @returns {{id: string, name: string, description: string}[]} array with all milestones */ function getMilestonesFromElement(element) { let milestones = []; @@ -689,7 +689,7 @@ function getMilestonesFromElement(element) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId the id of the element - * @returns {Array} array with all milestones + * @returns {{id: string, name: string, description: string}[]} array with all milestones */ async function getMilestonesFromElementById(bpmn, elementId) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -712,11 +712,71 @@ async function getPerformersFromElementById(bpmn, elementId) { return getPerformersFromElement(element); } +/** + * An object containing properties from defined companies + * + * @typedef CompanyInfos + * @type {object} + * @property {string} id - company id + * @property {string} shortName - company short name + * @property {string} longName - company long name + * @property {string} description - company description + */ + +/** + * An object containing properties from defined factories + * + * @typedef FactoryInfos + * @type {object} + * @property {string} id - factory id + * @property {string} shortName - factory short name + * @property {string} longName - factory long name + * @property {string} description - factory description + * @property {string} companyRef - reference to company linked to factory + */ + +/** + * An object containing properties from defined buildings + * + * @typedef BuildingInfos + * @type {object} + * @property {string} id - building id + * @property {string} shortName - building short name + * @property {string} longName - building long name + * @property {string} description - building description + * @property {string} factoryRef - building to factory linked to building + */ + +/** + * An object containing properties from defined areas + * + * @typedef AreaInfos + * @type {object} + * @property {string} id - area id + * @property {string} shortName - area short name + * @property {string} longName - area long name + * @property {string} description - area description + * @property {string} buildingRef - reference to building linked to area + */ + +/** + * An object containing properties from defined working places + * + * @typedef WorkingPlaceInfos + * @type {object} + * @property {string} id - workingPlace id + * @property {string} shortName - workingPlace short name + * @property {string} longName - workingPlace long name + * @property {string} description - workingPlace description + * @property {string} buildingRef - reference to building linked to workingPlace + * @property {string} areaRef - reference to area linked to workingPlace + */ + /** * Parses the locations from a bpmn-moddle element * * @param {object} element - * @returns {object} object with all locations + * @returns {{company: CompanyInfos[], factory: FactoryInfos[], building: BuildingInfos[], area: AreaInfos[], workingPlace: WorkingPlaceInfos[]}} object with all locations */ function getLocationsFromElement(element) { let company = []; @@ -790,11 +850,26 @@ function getLocationsFromElement(element) { return { company, factory, building, area, workingPlace }; } +/** + * An object containing properties from defined resources + * + * @typedef ResourceInfos + * @type {object} + * @property {string} id - consumableMaterial id + * @property {string} shortName - consumableMaterial short name + * @property {string} longName - consumableMaterial long name + * @property {string} manufacturer - consumableMaterial manufacturer + * @property {string} manufacturerSerialNumber - consumableMaterial manufacturerSerialNumber + * @property {string} unit - consumableMaterial unit + * @property {string} quantity - consumableMaterial quantity + * @property {string} description - consumableMaterial description + */ + /** * Parses the resources from a bpmn-moddle element * * @param {object} element - * @returns {object} object with all resources + * @returns {{consumableMaterial: ResourceInfos[], tool: ResourceInfos[], inspectionInstrument: ResourceInfos[]}} object with all resources */ function getResourcesFromElement(element) { let consumableMaterial = []; @@ -908,7 +983,7 @@ function getPerformersFromElement(element) { /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds * @param {string} isoDuration - * @returns {object} Object with number of years, months, days, hours, minutes and seconds + * @returns {{years: number, months: number, days: number, hours: number, minutes: number, seconds: number}} Object with number of years, months, days, hours, minutes and seconds */ function parseISODuration(isoDuration) { let years = null; diff --git a/src/helper-modules/bpmn-helper/src/setters.d.ts b/src/helper-modules/bpmn-helper/src/setters.d.ts index 4399610a0..ef8ed69ec 100644 --- a/src/helper-modules/bpmn-helper/src/setters.d.ts +++ b/src/helper-modules/bpmn-helper/src/setters.d.ts @@ -43,14 +43,21 @@ export function setDefinitionsVersionInformation( }, ): Promise; /** - * Sets name in definitions element to given name + * Sets process Id in definitions element * * @param {string} bpmn the xml we want to update * @param {string} id the id we want to set for the process inside the bpmn - * @returns {string} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ +export function setProcessId(bpmn: string, id: string): Promise; +/** + * Sets templaseId in definitions element + * + * @param {string} bpmn the xml we want to update + * @param {string} id the id we want to set for the template inside the bpmn + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ -export function setProcessId(bpmn: string, id: string): string; -export function setTemplateId(bpmn: any, id: any): Promise; +export function setTemplateId(bpmn: string, id: string): Promise; /** * Sets targetNamespace in definitions element to https://docs.proceed-labs.org/${id}, keeps existing namespace as originalTargetNamespace * @@ -89,9 +96,12 @@ export function setDeploymentMethod( * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ -export function setMachineInfo(bpmn: string | object, machineInfo: object[]): string | object; +export function setMachineInfo( + bpmn: string | object, + machineInfo: object[], +): Promise; /** * Sets the 'fileName' and 'implementation' attributes of a UserTask with new values. * @@ -99,27 +109,27 @@ export function setMachineInfo(bpmn: string | object, machineInfo: object[]): st * @param {string} userTaskId - the userTaskId to look for * @param {string} newFileName - the new value of 'fileName' attribute * @param {string} [newImplementation] - the new value of 'implementation' attribute; will default to html implementation - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ export function setUserTaskData( bpmn: string | object, userTaskId: string, newFileName: string, newImplementation?: string, -): string | object; +): Promise; /** * Adds the given constraints to the bpmn element with the given id * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId * @param {object} constraints object containing the hardConstraints and softConstraints - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ export function addConstraintsToElementById( bpmn: string | object, elementId: string, constraints: object, -): string | object; +): Promise; /** * Add meta information of the called bpmn process to the bpmn file where it's getting called from. This includes a custom namespace in the definitions part, * an import element as first child of definitions and the calledElement attribute of the call activity bpmn element @@ -128,41 +138,50 @@ export function addConstraintsToElementById( * @param {string} callActivityId The ID of the call activity bpmn element * @param {string} calledBpmn The bpmn file of the called process * @param {string} calledProcessLocation The DefinitionId of the calledBpmn. Combination of process name and process id - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ export function addCallActivityReference( bpmn: string | object, callActivityId: string, calledBpmn: string, calledProcessLocation: string, -): string | object; +): Promise; /** * Remove the reference to the called process added in {@link addCallActivityReference} but remains the actual bpmn element * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} callActivityId The ID of the bpmn element for which the meta information should be removed - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ export function removeCallActivityReference( bpmn: string | object, callActivityId: string, -): string | object; +): Promise; /** * Look up the given bpmn document for unused imports/custom namespaces which don't get referenced by a call activity inside this bpmn document. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ -export function removeUnusedCallActivityReferences(bpmn: string | object): string | object; -export function removeColorFromAllElements(bpmn: any): Promise; +export function removeUnusedCallActivityReferences(bpmn: string | object): Promise; +/** + * Remove color from all elements of given process + * + * @param {string|object} bpmn + * @returns {Promise} + */ +export function removeColorFromAllElements(bpmn: string | object): Promise; /** * Adds a documentation element to the first process in the process definition * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} description the content for the documentation element - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ -export function addDocumentation(bpmn: string | object, description: string): string | object; +export function addDocumentation( + bpmn: string | object, + description: string, +): Promise; /** * Adds documentation to a given process object * diff --git a/src/helper-modules/bpmn-helper/src/setters.js b/src/helper-modules/bpmn-helper/src/setters.js index f5f7f01dc..5b4a381d7 100644 --- a/src/helper-modules/bpmn-helper/src/setters.js +++ b/src/helper-modules/bpmn-helper/src/setters.js @@ -86,11 +86,11 @@ async function setDefinitionsVersionInformation( } /** - * Sets name in definitions element to given name + * Sets process Id in definitions element * * @param {string} bpmn the xml we want to update * @param {string} id the id we want to set for the process inside the bpmn - * @returns {string} the modified BPMN process as bpmn-moddle object or XML string based on input + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input */ async function setProcessId(bpmn, id) { return await manipulateElementsByTagName(bpmn, 'bpmn:Process', (process) => { @@ -98,6 +98,13 @@ async function setProcessId(bpmn, id) { }); } +/** + * Sets templaseId in definitions element + * + * @param {string} bpmn the xml we want to update + * @param {string} id the id we want to set for the template inside the bpmn + * @returns {Promise} the modified BPMN process as bpmn-moddle object or XML string based on input + */ async function setTemplateId(bpmn, id) { return await manipulateElementsByTagName(bpmn, 'bpmn:Definitions', (definitions) => { definitions.templateId = `${id}`; @@ -208,7 +215,7 @@ async function setDeploymentMethod(bpmn, method) { * @param {string} userTaskId - the userTaskId to look for * @param {string} newFileName - the new value of 'fileName' attribute * @param {string} [newImplementation] - the new value of 'implementation' attribute; will default to html implementation - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function setUserTaskData( bpmn, @@ -227,7 +234,7 @@ async function setUserTaskData( * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function setMachineInfo(bpmn, machineInfo) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -335,7 +342,7 @@ async function updatePerformersOnElementById(bpmn, elementId, performers) { * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId * @param {object} constraints object containing the hardConstraints and softConstraints - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function addConstraintsToElementById(bpmn, elementId, constraints) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -351,7 +358,7 @@ async function addConstraintsToElementById(bpmn, elementId, constraints) { * @param {string} callActivityId The ID of the call activity bpmn element * @param {string} calledBpmn The bpmn file of the called process * @param {string} calledProcessLocation The DefinitionId of the calledBpmn. Combination of process name and process id - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function addCallActivityReference(bpmn, callActivityId, calledBpmn, calledProcessLocation) { // checks if there is already a reference for this call activity and remove it with all related informations (namespace definitions/imports) @@ -414,7 +421,7 @@ async function addCallActivityReference(bpmn, callActivityId, calledBpmn, called * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} callActivityId The ID of the bpmn element for which the meta information should be removed - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function removeCallActivityReference(bpmn, callActivityId) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -457,7 +464,7 @@ async function removeCallActivityReference(bpmn, callActivityId) { * Look up the given bpmn document for unused imports/custom namespaces which don't get referenced by a call activity inside this bpmn document. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function removeUnusedCallActivityReferences(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -506,7 +513,7 @@ async function removeUnusedCallActivityReferences(bpmn) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} description the content for the documentation element - * @returns {(string|object)} the BPMN process as XML string or BPMN-Moddle Object based on input + * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function addDocumentation(bpmn, description) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -536,6 +543,12 @@ async function addDocumentationToProcessObject(processObj, description) { } } +/** + * Remove color from all elements of given process + * + * @param {string|object} bpmn + * @returns {Promise} + */ async function removeColorFromAllElements(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; diff --git a/src/helper-modules/bpmn-helper/src/validators.d.ts b/src/helper-modules/bpmn-helper/src/validators.d.ts index 761f35dfd..93ab29347 100644 --- a/src/helper-modules/bpmn-helper/src/validators.d.ts +++ b/src/helper-modules/bpmn-helper/src/validators.d.ts @@ -6,6 +6,6 @@ * * @param {string} xml * @param {string} processId - * @returns {boolean} true if called process is valid + * @returns {Promise} true if called process is valid */ -export function validateCalledProcess(xml: string, processId: string): boolean; +export function validateCalledProcess(xml: string, processId: string): Promise; diff --git a/src/helper-modules/bpmn-helper/src/validators.js b/src/helper-modules/bpmn-helper/src/validators.js index 0499f8a7e..c13e7a9d3 100644 --- a/src/helper-modules/bpmn-helper/src/validators.js +++ b/src/helper-modules/bpmn-helper/src/validators.js @@ -9,7 +9,7 @@ const { toBpmnObject, getElementsByTagName, getElementById } = require('./util.j * * @param {string} xml * @param {string} processId - * @returns {boolean} true if called process is valid + * @returns {Promise} true if called process is valid */ async function validateCalledProcess(xml, processId) { const definitions = await toBpmnObject(xml); From f2bcd03aec925558ab1618a68da339af1adae394 Mon Sep 17 00:00:00 2001 From: Lucas Date: Mon, 9 Oct 2023 22:01:43 +0200 Subject: [PATCH 05/13] corrected jdoc comments in bpmn helper files --- src/helper-modules/bpmn-helper/src/getters.js | 58 ++++++++++--------- src/helper-modules/bpmn-helper/src/setters.js | 8 +-- 2 files changed, 35 insertions(+), 31 deletions(-) diff --git a/src/helper-modules/bpmn-helper/src/getters.js b/src/helper-modules/bpmn-helper/src/getters.js index 820792454..d95ddf093 100644 --- a/src/helper-modules/bpmn-helper/src/getters.js +++ b/src/helper-modules/bpmn-helper/src/getters.js @@ -167,7 +167,7 @@ async function getDeploymentMethod(bpmn) { * Returns a mapping of the ids of the process nodes to the machines they are mapped to * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.<{[flowNodeId: string]: {machineAddress: string, machineId: string}}>} the mapping from a node id to information about the machine it is mapped to + * @returns {Promise.<{[flowNodeId: string]: {machineAddress?: string, machineId?: string}}>} the mapping from a node id to information about the machine it is mapped to */ async function getElementMachineMapping(bpmn) { const elementMachineMapping = {}; @@ -187,7 +187,7 @@ async function getElementMachineMapping(bpmn) { * (The attribute 'filename' is defined in the PROCEED XML Schema and not a standard BPMN attribute.) * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ [userTaskId: string]: { fileName: string, implementation: string }}> } an object (a map) with all userTaskIds as keys + * @returns { Promise.<{ [userTaskId: string]: { fileName?: string, implementation?: string }}> } an object (a map) with all userTaskIds as keys */ async function getUserTaskFileNameMapping(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -207,7 +207,7 @@ async function getUserTaskFileNameMapping(bpmn) { * for every UserTask in a BPMN process. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ [userTaskFileName: string] : string }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) + * @returns { Promise.<{ [userTaskFileName: string] : string[] }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) */ async function getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -567,7 +567,7 @@ async function getProcessConstraints(bpmn) { * and its name and description for human identification * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ id: string, originalId: string, processIds: string[], name: string, description: string }> } object containing the identifying information + * @returns { Promise.<{ id: string, originalId?: string, processIds: string[], name: string, description: string }> } object containing the identifying information */ async function getIdentifyingInfos(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -663,7 +663,7 @@ async function getMetaData(bpmn, elId) { * Parses the milestones from a bpmn-moddle element * * @param {object} element - * @returns {{id: string, name: string, description: string}[]} array with all milestones + * @returns {{id: string, name: string, description?: string}[]} array with all milestones */ function getMilestonesFromElement(element) { let milestones = []; @@ -689,7 +689,7 @@ function getMilestonesFromElement(element) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId the id of the element - * @returns {{id: string, name: string, description: string}[]} array with all milestones + * @returns {{id: string, name: string, description?: string}[]} array with all milestones */ async function getMilestonesFromElementById(bpmn, elementId) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -720,7 +720,8 @@ async function getPerformersFromElementById(bpmn, elementId) { * @property {string} id - company id * @property {string} shortName - company short name * @property {string} longName - company long name - * @property {string} description - company description + * @property {string} [description] - company description + * @property {string} [factoryIds] */ /** @@ -731,8 +732,8 @@ async function getPerformersFromElementById(bpmn, elementId) { * @property {string} id - factory id * @property {string} shortName - factory short name * @property {string} longName - factory long name - * @property {string} description - factory description - * @property {string} companyRef - reference to company linked to factory + * @property {string} [description] - factory description + * @property {string} [companyRef] - reference to company linked to factory */ /** @@ -743,8 +744,8 @@ async function getPerformersFromElementById(bpmn, elementId) { * @property {string} id - building id * @property {string} shortName - building short name * @property {string} longName - building long name - * @property {string} description - building description - * @property {string} factoryRef - building to factory linked to building + * @property {string} [description] - building description + * @property {string} [factoryRef] - building to factory linked to building */ /** @@ -755,8 +756,8 @@ async function getPerformersFromElementById(bpmn, elementId) { * @property {string} id - area id * @property {string} shortName - area short name * @property {string} longName - area long name - * @property {string} description - area description - * @property {string} buildingRef - reference to building linked to area + * @property {string} [description] - area description + * @property {string} [buildingRef] - reference to building linked to area */ /** @@ -767,9 +768,9 @@ async function getPerformersFromElementById(bpmn, elementId) { * @property {string} id - workingPlace id * @property {string} shortName - workingPlace short name * @property {string} longName - workingPlace long name - * @property {string} description - workingPlace description - * @property {string} buildingRef - reference to building linked to workingPlace - * @property {string} areaRef - reference to area linked to workingPlace + * @property {string} [description] - workingPlace description + * @property {string} [buildingRef] - reference to building linked to workingPlace + * @property {string} [areaRef] - reference to area linked to workingPlace */ /** @@ -791,12 +792,15 @@ function getLocationsFromElement(element) { (child) => child.$type == 'proceed:Locations', ); if (locationsElement && locationsElement.company) { - company = locationsElement.company.map(({ id, shortName, longName, description }) => ({ - id, - shortName, - longName, - description, - })); + company = locationsElement.company.map( + ({ id, shortName, longName, description, factoryIds }) => ({ + id, + shortName, + longName, + description, + factoryIds, + }), + ); } if (locationsElement && locationsElement.factory) { @@ -858,11 +862,11 @@ function getLocationsFromElement(element) { * @property {string} id - consumableMaterial id * @property {string} shortName - consumableMaterial short name * @property {string} longName - consumableMaterial long name - * @property {string} manufacturer - consumableMaterial manufacturer - * @property {string} manufacturerSerialNumber - consumableMaterial manufacturerSerialNumber - * @property {string} unit - consumableMaterial unit + * @property {string} [manufacturer] - consumableMaterial manufacturer + * @property {string} [manufacturerSerialNumber] - consumableMaterial manufacturerSerialNumber + * @property {string} [unit] - consumableMaterial unit * @property {string} quantity - consumableMaterial quantity - * @property {string} description - consumableMaterial description + * @property {string} [description] - consumableMaterial description */ /** @@ -983,7 +987,7 @@ function getPerformersFromElement(element) { /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds * @param {string} isoDuration - * @returns {{years: number, months: number, days: number, hours: number, minutes: number, seconds: number}} Object with number of years, months, days, hours, minutes and seconds + * @returns {{years?: number, months?: number, days?: number, hours?: number, minutes?: number, seconds?: number}} Object with number of years, months, days, hours, minutes and seconds */ function parseISODuration(isoDuration) { let years = null; diff --git a/src/helper-modules/bpmn-helper/src/setters.js b/src/helper-modules/bpmn-helper/src/setters.js index 5b4a381d7..82aed0005 100644 --- a/src/helper-modules/bpmn-helper/src/setters.js +++ b/src/helper-modules/bpmn-helper/src/setters.js @@ -59,7 +59,7 @@ async function setDefinitionsName(bpmn, name) { * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {object} versionInformation - the version information to set in the definitions object - * @param {(string|number)} versionInformation.version - the version number (a time since epoch string or number) + * @param {(string|number)} [versionInformation.version] - the version number (a time since epoch string or number) * @param {string} [versionInformation.versionName] - a human readable name for the version * @param {string} [versionInformation.versionDescription] - a longer description of the version * @param {(string|number)} [versionInformation.versionBasedOn] - a reference to the version this one is based on @@ -233,7 +233,7 @@ async function setUserTaskData( * Function that sets the machineInfo of all elements in the given xml with the given machineIds * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set + * @param {{[elementId: string]: {machineAddress?: string, machineId?: string}}} machineInfo the machineAddresses and machineIps of all the elements we want to set * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function setMachineInfo(bpmn, machineInfo) { @@ -363,7 +363,7 @@ async function addConstraintsToElementById(bpmn, elementId, constraints) { async function addCallActivityReference(bpmn, callActivityId, calledBpmn, calledProcessLocation) { // checks if there is already a reference for this call activity and remove it with all related informations (namespace definitions/imports) const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; - const callActivity = await getElementById(bpmnObj, callActivityId); + const callActivity = getElementById(bpmnObj, callActivityId); if (callActivity.calledElement) { await removeCallActivityReference(bpmnObj, callActivityId); } @@ -533,7 +533,7 @@ async function addDocumentation(bpmn, description) { * @param {object} processObj * @param {string} description */ -async function addDocumentationToProcessObject(processObj, description) { +function addDocumentationToProcessObject(processObj, description) { const docs = processObj.get('documentation'); const documentation = moddle.create('bpmn:Documentation', { text: description || '' }); if (docs.length > 0) { From ef6e5bb05940ffd42c544502227e97c7d45489d7 Mon Sep 17 00:00:00 2001 From: Lucas Date: Mon, 9 Oct 2023 22:04:13 +0200 Subject: [PATCH 06/13] updated typescript declaration files for bpmn helper module --- src/helper-modules/bpmn-helper/index.d.ts | 294 +++++------------- .../bpmn-helper/src/getters.d.ts | 100 +++--- .../bpmn-helper/src/setters.d.ts | 18 +- 3 files changed, 146 insertions(+), 266 deletions(-) diff --git a/src/helper-modules/bpmn-helper/index.d.ts b/src/helper-modules/bpmn-helper/index.d.ts index 982d6d802..45eb29d8c 100644 --- a/src/helper-modules/bpmn-helper/index.d.ts +++ b/src/helper-modules/bpmn-helper/index.d.ts @@ -1,215 +1,91 @@ declare const _exports: { - ensureExtensionElements(element: object): object; - removeEmptyExtensionElements(element: any): void; - ensureContainerElement(element: object, containerType: string): object; - removeEmptyContainerElement(element: any, containerType: any, containerElement: any): void; - setMetaData(bpmn: string | object, elId: string, metaValues: object): Promise; - setProceedElement(element: any, proceedElementType: any, value: any, attributes?: {}): {}; - getExporterName(): string; - getExporterVersion(): string; - generateBpmnId(prefix?: string): string; - generateDefinitionsId(): string; - generateProcessId(): string; - generateUserTaskFileName(): string; - getUserTaskImplementationString(): string; - generateTargetNamespace(id: any): string; - initXml(processId?: any, startEventId?: string): string; - validateCalledProcess(xml: string, processId: string): Promise; - setDefinitionsId(bpmn: string | object, id: string): Promise; - setDefinitionsName(bpmn: string | object, name: string): Promise; - setDefinitionsVersionInformation( - bpmn: string | object, - { - version, - versionName, - versionDescription, - versionBasedOn, - }: { - version: string | number; - versionName?: string; - versionDescription?: string; - versionBasedOn?: string | number; - }, - ): Promise; - setProcessId(bpmn: string, id: string): Promise; - setTemplateId(bpmn: string, id: string): Promise; - setTargetNamespace(bpmn: string | object, id: string): Promise; - setStandardDefinitions( - bpmn: string | object, - exporterName: string, - exporterVersion: string, - ): Promise; - setDeploymentMethod(bpmn: string | object, method: string): Promise; - setMachineInfo(bpmn: string | object, machineInfo: object[]): Promise; - setUserTaskData( - bpmn: string | object, - userTaskId: string, - newFileName: string, - newImplementation?: string, - ): Promise; - addConstraintsToElementById( - bpmn: string | object, - elementId: string, - constraints: object, - ): Promise; - addCallActivityReference( - bpmn: string | object, - callActivityId: string, - calledBpmn: string, - calledProcessLocation: string, - ): Promise; - removeCallActivityReference( - bpmn: string | object, - callActivityId: string, - ): Promise; - removeUnusedCallActivityReferences(bpmn: string | object): Promise; - removeColorFromAllElements(bpmn: string | object): Promise; - addDocumentation(bpmn: string | object, description: string): Promise; - addDocumentationToProcessObject(processObj: object, description: string): Promise; - updatePerformersOnElement(element: object, performers: any[]): Promise; - updatePerformersOnElementById( - bpmn: string | object, - elementId: string, - performers: any[], - ): Promise; - getDefinitionsId(bpmn: string | object): Promise; - getOriginalDefinitionsId(bpmn: string | object): Promise; - getDefinitionsName(bpmn: string | object): Promise; - getDefinitionsInfos(bpmn: string | object): Promise; - getImports(bpmn: string | object): Promise; - getDefinitionsVersionInformation(bpmn: string | object): Promise<{ - version?: number; - name?: string; - description?: string; - versionBasedOn?: number; - }>; - getProcessIds(bpmn: string | object): Promise; - getDeploymentMethod(bpmn: string | object): Promise; - getProcessConstraints(bpmn: string | object): Promise<{ - hardConstraints: any[]; - softConstraints: any[]; - }>; - getProcessDocumentation(bpmn: string | object): Promise; - getProcessDocumentationByObject(processObject: object): string; - getUserTaskFileNameMapping(bpmn: string | object): Promise<{ - [userTaskId: string]: { - fileName: string; - implementation: string; - }; - }>; - getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn: string | object): Promise<{ - [userTaskFileName: string]: string; - }>; - getSubprocess(bpmn: string | object, subprocessId: string): Promise; - getSubprocessContent(bpmn: string, subprocessId: string): Promise; - getTargetDefinitionsAndProcessIdForCallActivityByObject( - bpmnObj: object, - callActivityId: string, - ): { - definitionId: string; - processId: string; - version: number; - }; - getDefinitionsAndProcessIdForEveryCallActivity( - bpmn: string | object, - dontThrow?: boolean, - ): Promise<{ - [callActivityId: string]: { - definitionId: string; - processId: string; - version: number; - }; - }>; - getStartEvents(bpmn: string | object): Promise; - getAllBpmnFlowElements(bpmn: string | object): Promise; - getAllBpmnFlowNodeIds(bpmn: string | object): Promise; - getAllBpmnFlowElementIds(bpmn: string | object): Promise; - getChildrenFlowElements(bpmn: string | object, elementId: any): Promise; - getElementMachineMapping(bpmn: string | object): Promise<{ - [flowNodeId: string]: { - machineAddress: string; - machineId: string; - }; - }>; - getTaskConstraintMapping(bpmn: string | object): Promise<{ - [bpmnElementIds: string]: { - hardConstraints: any[]; - softConstraints: any[]; - }; - }>; - getIdentifyingInfos(bpmn: string | object): Promise<{ - id: string; - originalId: string; - processIds: string[]; - name: string; - description: string; - }>; - getRootFromElement(businessObject: object): object; - getMetaDataFromElement(element: object): { - [key: string]: any; - }; - getMetaData( - bpmn: string | object, - elId: string, - ): Promise<{ - [key: string]: any; - }>; - getMilestonesFromElement(element: object): { - id: string; - name: string; - description: string; - }[]; - getMilestonesFromElementById( - bpmn: string | object, - elementId: string, - ): { - id: string; - name: string; - description: string; - }[]; - getResourcesFromElement(element: object): { - consumableMaterial: getters.ResourceInfos[]; - tool: getters.ResourceInfos[]; - inspectionInstrument: getters.ResourceInfos[]; - }; - getLocationsFromElement(element: object): { - company: getters.CompanyInfos[]; - factory: getters.FactoryInfos[]; - building: getters.BuildingInfos[]; - area: getters.AreaInfos[]; - workingPlace: getters.WorkingPlaceInfos[]; - }; - getPerformersFromElement(element: object): any[]; - getPerformersFromElementById(bpmn: string | object, elementId: string): any[]; - parseISODuration(isoDuration: string): { - years: number; - months: number; - days: number; - hours: number; - minutes: number; - seconds: number; - }; - convertISODurationToMiliseconds(isoDuration: string): number; - ensureCorrectProceedNamespace(xml: string): string; - toBpmnObject(xml: string, typename?: string): Promise; - toBpmnXml(obj: any): Promise; - getChildren(travObj: object): any[]; - getElementsByTagName(travObj: object, tagname: string): any[]; - getAllElements(travObj: object): any[]; - getElementById(travObj: object, id: string): object; - getElementDI(element: object, definitions?: object): any; - manipulateElementById( - bpmn: string | object, - id: string, - manipFunc: util.manipulationFunction, - ): Promise; - manipulateElementsByTagName( - bpmn: string | object, - tagName: string, - manipFunc: util.manipulationFunction, - ): Promise; + ensureExtensionElements: typeof proceedExtensions.ensureExtensionElements; + removeEmptyExtensionElements: typeof proceedExtensions.removeEmptyExtensionElements; + ensureContainerElement: typeof proceedExtensions.ensureContainerElement; + removeEmptyContainerElement: typeof proceedExtensions.removeEmptyContainerElement; + setMetaData: typeof proceedExtensions.setMetaData; + setProceedElement: typeof proceedExtensions.setProceedElement; + getExporterName: typeof proceedConstants.getExporterName; + getExporterVersion: typeof proceedConstants.getExporterVersion; + generateBpmnId: typeof proceedConstants.generateBpmnId; + generateDefinitionsId: typeof proceedConstants.generateDefinitionsId; + generateProcessId: typeof proceedConstants.generateProcessId; + generateUserTaskFileName: typeof proceedConstants.generateUserTaskFileName; + getUserTaskImplementationString: typeof proceedConstants.getUserTaskImplementationString; + generateTargetNamespace: typeof proceedConstants.generateTargetNamespace; + initXml: typeof proceedConstants.initXml; + validateCalledProcess: typeof validators.validateCalledProcess; + setDefinitionsId: typeof setters.setDefinitionsId; + setDefinitionsName: typeof setters.setDefinitionsName; + setDefinitionsVersionInformation: typeof setters.setDefinitionsVersionInformation; + setProcessId: typeof setters.setProcessId; + setTemplateId: typeof setters.setTemplateId; + setTargetNamespace: typeof setters.setTargetNamespace; + setStandardDefinitions: typeof setters.setStandardDefinitions; + setDeploymentMethod: typeof setters.setDeploymentMethod; + setMachineInfo: typeof setters.setMachineInfo; + setUserTaskData: typeof setters.setUserTaskData; + addConstraintsToElementById: typeof setters.addConstraintsToElementById; + addCallActivityReference: typeof setters.addCallActivityReference; + removeCallActivityReference: typeof setters.removeCallActivityReference; + removeUnusedCallActivityReferences: typeof setters.removeUnusedCallActivityReferences; + removeColorFromAllElements: typeof setters.removeColorFromAllElements; + addDocumentation: typeof setters.addDocumentation; + addDocumentationToProcessObject: typeof setters.addDocumentationToProcessObject; + updatePerformersOnElement: typeof setters.updatePerformersOnElement; + updatePerformersOnElementById: typeof setters.updatePerformersOnElementById; + getDefinitionsId: typeof getters.getDefinitionsId; + getOriginalDefinitionsId: typeof getters.getOriginalDefinitionsId; + getDefinitionsName: typeof getters.getDefinitionsName; + getDefinitionsInfos: typeof getters.getDefinitionsInfos; + getImports: typeof getters.getImports; + getDefinitionsVersionInformation: typeof getters.getDefinitionsVersionInformation; + getProcessIds: typeof getters.getProcessIds; + getDeploymentMethod: typeof getters.getDeploymentMethod; + getProcessConstraints: typeof getters.getProcessConstraints; + getProcessDocumentation: typeof getters.getProcessDocumentation; + getProcessDocumentationByObject: typeof getters.getProcessDocumentationByObject; + getUserTaskFileNameMapping: typeof getters.getUserTaskFileNameMapping; + getAllUserTaskFileNamesAndUserTaskIdsMapping: typeof getters.getAllUserTaskFileNamesAndUserTaskIdsMapping; + getSubprocess: typeof getters.getSubprocess; + getSubprocessContent: typeof getters.getSubprocessContent; + getTargetDefinitionsAndProcessIdForCallActivityByObject: typeof getters.getTargetDefinitionsAndProcessIdForCallActivityByObject; + getDefinitionsAndProcessIdForEveryCallActivity: typeof getters.getDefinitionsAndProcessIdForEveryCallActivity; + getStartEvents: typeof getters.getStartEvents; + getAllBpmnFlowElements: typeof getters.getAllBpmnFlowElements; + getAllBpmnFlowNodeIds: typeof getters.getAllBpmnFlowNodeIds; + getAllBpmnFlowElementIds: typeof getters.getAllBpmnFlowElementIds; + getChildrenFlowElements: typeof getters.getChildrenFlowElements; + getElementMachineMapping: typeof getters.getElementMachineMapping; + getTaskConstraintMapping: typeof getters.getTaskConstraintMapping; + getIdentifyingInfos: typeof getters.getIdentifyingInfos; + getRootFromElement: typeof getters.getRootFromElement; + getMetaDataFromElement: typeof getters.getMetaDataFromElement; + getMetaData: typeof getters.getMetaData; + getMilestonesFromElement: typeof getters.getMilestonesFromElement; + getMilestonesFromElementById: typeof getters.getMilestonesFromElementById; + getResourcesFromElement: typeof getters.getResourcesFromElement; + getLocationsFromElement: typeof getters.getLocationsFromElement; + getPerformersFromElement: typeof getters.getPerformersFromElement; + getPerformersFromElementById: typeof getters.getPerformersFromElementById; + parseISODuration: typeof getters.parseISODuration; + convertISODurationToMiliseconds: typeof getters.convertISODurationToMiliseconds; moddle: any; + ensureCorrectProceedNamespace: typeof util.ensureCorrectProceedNamespace; + toBpmnObject: typeof util.toBpmnObject; + toBpmnXml: typeof util.toBpmnXml; + getChildren: typeof util.getChildren; + getElementsByTagName: typeof util.getElementsByTagName; + getAllElements: typeof util.getAllElements; + getElementById: typeof util.getElementById; + getElementDI: typeof util.getElementDI; + manipulateElementById: typeof util.manipulateElementById; + manipulateElementsByTagName: typeof util.manipulateElementsByTagName; }; export = _exports; +import proceedExtensions = require('./src/proceedExtensions'); +import proceedConstants = require('./src/PROCEED-CONSTANTS.js'); +import validators = require('./src/validators.js'); +import setters = require('./src/setters.js'); import getters = require('./src/getters.js'); import util = require('./src/util.js'); diff --git a/src/helper-modules/bpmn-helper/src/getters.d.ts b/src/helper-modules/bpmn-helper/src/getters.d.ts index 2129224c7..ea8ff3c15 100644 --- a/src/helper-modules/bpmn-helper/src/getters.d.ts +++ b/src/helper-modules/bpmn-helper/src/getters.d.ts @@ -43,7 +43,8 @@ export type CompanyInfos = { /** * - company description */ - description: string; + description?: string; + factoryIds?: string; }; /** * An object containing properties from defined factories @@ -64,11 +65,11 @@ export type FactoryInfos = { /** * - factory description */ - description: string; + description?: string; /** * - reference to company linked to factory */ - companyRef: string; + companyRef?: string; }; /** * An object containing properties from defined buildings @@ -89,11 +90,11 @@ export type BuildingInfos = { /** * - building description */ - description: string; + description?: string; /** * - building to factory linked to building */ - factoryRef: string; + factoryRef?: string; }; /** * An object containing properties from defined areas @@ -114,11 +115,11 @@ export type AreaInfos = { /** * - area description */ - description: string; + description?: string; /** * - reference to building linked to area */ - buildingRef: string; + buildingRef?: string; }; /** * An object containing properties from defined working places @@ -139,15 +140,15 @@ export type WorkingPlaceInfos = { /** * - workingPlace description */ - description: string; + description?: string; /** * - reference to building linked to workingPlace */ - buildingRef: string; + buildingRef?: string; /** * - reference to area linked to workingPlace */ - areaRef: string; + areaRef?: string; }; /** * An object containing properties from defined resources @@ -168,15 +169,15 @@ export type ResourceInfos = { /** * - consumableMaterial manufacturer */ - manufacturer: string; + manufacturer?: string; /** * - consumableMaterial manufacturerSerialNumber */ - manufacturerSerialNumber: string; + manufacturerSerialNumber?: string; /** * - consumableMaterial unit */ - unit: string; + unit?: string; /** * - consumableMaterial quantity */ @@ -184,7 +185,7 @@ export type ResourceInfos = { /** * - consumableMaterial description */ - description: string; + description?: string; }; /** * Returns id of the given process definition @@ -295,12 +296,12 @@ export function getProcessDocumentationByObject(processObject: object): string; * (The attribute 'filename' is defined in the PROCEED XML Schema and not a standard BPMN attribute.) * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ [userTaskId: string]: { fileName: string, implementation: string }}> } an object (a map) with all userTaskIds as keys + * @returns { Promise.<{ [userTaskId: string]: { fileName?: string, implementation?: string }}> } an object (a map) with all userTaskIds as keys */ export function getUserTaskFileNameMapping(bpmn: string | object): Promise<{ [userTaskId: string]: { - fileName: string; - implementation: string; + fileName?: string; + implementation?: string; }; }>; /** @@ -308,10 +309,10 @@ export function getUserTaskFileNameMapping(bpmn: string | object): Promise<{ * for every UserTask in a BPMN process. * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ [userTaskFileName: string] : string }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) + * @returns { Promise.<{ [userTaskFileName: string] : string[] }>} A map (object) that returns for every UserTask the 'fileName' (key) and UserTask-IDs (value) */ export function getAllUserTaskFileNamesAndUserTaskIdsMapping(bpmn: string | object): Promise<{ - [userTaskFileName: string]: string; + [userTaskFileName: string]: string[]; }>; /** * Returns a xml with Diagram Elements just from the given subprocess and their nested Processes @@ -430,12 +431,12 @@ export function getChildrenFlowElements(bpmn: string | object, elementId: any): * Returns a mapping of the ids of the process nodes to the machines they are mapped to * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.<{[flowNodeId: string]: {machineAddress: string, machineId: string}}>} the mapping from a node id to information about the machine it is mapped to + * @returns {Promise.<{[flowNodeId: string]: {machineAddress?: string, machineId?: string}}>} the mapping from a node id to information about the machine it is mapped to */ export function getElementMachineMapping(bpmn: string | object): Promise<{ [flowNodeId: string]: { - machineAddress: string; - machineId: string; + machineAddress?: string; + machineId?: string; }; }>; /** @@ -461,11 +462,11 @@ export function getTaskConstraintMapping(bpmn: string | object): Promise<{ * and its name and description for human identification * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns { Promise.<{ id: string, originalId: string, processIds: string[], name: string, description: string }> } object containing the identifying information + * @returns { Promise.<{ id: string, originalId?: string, processIds: string[], name: string, description: string }> } object containing the identifying information */ export function getIdentifyingInfos(bpmn: string | object): Promise<{ id: string; - originalId: string; + originalId?: string; processIds: string[]; name: string; description: string; @@ -503,19 +504,19 @@ export function getMetaData( * Parses the milestones from a bpmn-moddle element * * @param {object} element - * @returns {{id: string, name: string, description: string}[]} array with all milestones + * @returns {{id: string, name: string, description?: string}[]} array with all milestones */ export function getMilestonesFromElement(element: object): { id: string; name: string; - description: string; + description?: string; }[]; /** * Get the milestones for given element id * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {string} elementId the id of the element - * @returns {{id: string, name: string, description: string}[]} array with all milestones + * @returns {{id: string, name: string, description?: string}[]} array with all milestones */ export function getMilestonesFromElementById( bpmn: string | object, @@ -523,7 +524,7 @@ export function getMilestonesFromElementById( ): { id: string; name: string; - description: string; + description?: string; }[]; /** * An object containing properties from defined resources @@ -533,11 +534,11 @@ export function getMilestonesFromElementById( * @property {string} id - consumableMaterial id * @property {string} shortName - consumableMaterial short name * @property {string} longName - consumableMaterial long name - * @property {string} manufacturer - consumableMaterial manufacturer - * @property {string} manufacturerSerialNumber - consumableMaterial manufacturerSerialNumber - * @property {string} unit - consumableMaterial unit + * @property {string} [manufacturer] - consumableMaterial manufacturer + * @property {string} [manufacturerSerialNumber] - consumableMaterial manufacturerSerialNumber + * @property {string} [unit] - consumableMaterial unit * @property {string} quantity - consumableMaterial quantity - * @property {string} description - consumableMaterial description + * @property {string} [description] - consumableMaterial description */ /** * Parses the resources from a bpmn-moddle element @@ -558,7 +559,8 @@ export function getResourcesFromElement(element: object): { * @property {string} id - company id * @property {string} shortName - company short name * @property {string} longName - company long name - * @property {string} description - company description + * @property {string} [description] - company description + * @property {string} [factoryIds] */ /** * An object containing properties from defined factories @@ -568,8 +570,8 @@ export function getResourcesFromElement(element: object): { * @property {string} id - factory id * @property {string} shortName - factory short name * @property {string} longName - factory long name - * @property {string} description - factory description - * @property {string} companyRef - reference to company linked to factory + * @property {string} [description] - factory description + * @property {string} [companyRef] - reference to company linked to factory */ /** * An object containing properties from defined buildings @@ -579,8 +581,8 @@ export function getResourcesFromElement(element: object): { * @property {string} id - building id * @property {string} shortName - building short name * @property {string} longName - building long name - * @property {string} description - building description - * @property {string} factoryRef - building to factory linked to building + * @property {string} [description] - building description + * @property {string} [factoryRef] - building to factory linked to building */ /** * An object containing properties from defined areas @@ -590,8 +592,8 @@ export function getResourcesFromElement(element: object): { * @property {string} id - area id * @property {string} shortName - area short name * @property {string} longName - area long name - * @property {string} description - area description - * @property {string} buildingRef - reference to building linked to area + * @property {string} [description] - area description + * @property {string} [buildingRef] - reference to building linked to area */ /** * An object containing properties from defined working places @@ -601,9 +603,9 @@ export function getResourcesFromElement(element: object): { * @property {string} id - workingPlace id * @property {string} shortName - workingPlace short name * @property {string} longName - workingPlace long name - * @property {string} description - workingPlace description - * @property {string} buildingRef - reference to building linked to workingPlace - * @property {string} areaRef - reference to area linked to workingPlace + * @property {string} [description] - workingPlace description + * @property {string} [buildingRef] - reference to building linked to workingPlace + * @property {string} [areaRef] - reference to area linked to workingPlace */ /** * Parses the locations from a bpmn-moddle element @@ -636,15 +638,15 @@ export function getPerformersFromElementById(bpmn: string | object, elementId: s /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds * @param {string} isoDuration - * @returns {{years: number, months: number, days: number, hours: number, minutes: number, seconds: number}} Object with number of years, months, days, hours, minutes and seconds + * @returns {{years?: number, months?: number, days?: number, hours?: number, minutes?: number, seconds?: number}} Object with number of years, months, days, hours, minutes and seconds */ export function parseISODuration(isoDuration: string): { - years: number; - months: number; - days: number; - hours: number; - minutes: number; - seconds: number; + years?: number; + months?: number; + days?: number; + hours?: number; + minutes?: number; + seconds?: number; }; /** * Convert given ISO Duration in number of miliseconds diff --git a/src/helper-modules/bpmn-helper/src/setters.d.ts b/src/helper-modules/bpmn-helper/src/setters.d.ts index ef8ed69ec..02bbefd51 100644 --- a/src/helper-modules/bpmn-helper/src/setters.d.ts +++ b/src/helper-modules/bpmn-helper/src/setters.d.ts @@ -22,7 +22,7 @@ export function setDefinitionsName(bpmn: string | object, name: string): Promise * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object * @param {object} versionInformation - the version information to set in the definitions object - * @param {(string|number)} versionInformation.version - the version number (a time since epoch string or number) + * @param {(string|number)} [versionInformation.version] - the version number (a time since epoch string or number) * @param {string} [versionInformation.versionName] - a human readable name for the version * @param {string} [versionInformation.versionDescription] - a longer description of the version * @param {(string|number)} [versionInformation.versionBasedOn] - a reference to the version this one is based on @@ -36,7 +36,7 @@ export function setDefinitionsVersionInformation( versionDescription, versionBasedOn, }: { - version: string | number; + version?: string | number; versionName?: string; versionDescription?: string; versionBasedOn?: string | number; @@ -95,12 +95,17 @@ export function setDeploymentMethod( * Function that sets the machineInfo of all elements in the given xml with the given machineIds * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {object[]} machineInfo the machineAddresses and machineIps of all the elements we want to set + * @param {{[elementId: string]: {machineAddress?: string, machineId?: string}}} machineInfo the machineAddresses and machineIps of all the elements we want to set * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ export function setMachineInfo( bpmn: string | object, - machineInfo: object[], + machineInfo: { + [elementId: string]: { + machineAddress?: string; + machineId?: string; + }; + }, ): Promise; /** * Sets the 'fileName' and 'implementation' attributes of a UserTask with new values. @@ -188,10 +193,7 @@ export function addDocumentation( * @param {object} processObj * @param {string} description */ -export function addDocumentationToProcessObject( - processObj: object, - description: string, -): Promise; +export function addDocumentationToProcessObject(processObj: object, description: string): void; /** * Update the performer info of an element * From df413c3ef195b6a33523197003393f33f5a1b01c Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 15:03:35 +0200 Subject: [PATCH 07/13] throw errors for invalid bpmn in bpmn helper getter functions --- src/helper-modules/bpmn-helper/index.d.ts | 148 ++++++++---- .../bpmn-helper/src/getters.d.ts | 4 +- src/helper-modules/bpmn-helper/src/getters.js | 219 ++++++++++++------ 3 files changed, 249 insertions(+), 122 deletions(-) diff --git a/src/helper-modules/bpmn-helper/index.d.ts b/src/helper-modules/bpmn-helper/index.d.ts index 45eb29d8c..c8193412e 100644 --- a/src/helper-modules/bpmn-helper/index.d.ts +++ b/src/helper-modules/bpmn-helper/index.d.ts @@ -1,39 +1,85 @@ declare const _exports: { - ensureExtensionElements: typeof proceedExtensions.ensureExtensionElements; - removeEmptyExtensionElements: typeof proceedExtensions.removeEmptyExtensionElements; - ensureContainerElement: typeof proceedExtensions.ensureContainerElement; - removeEmptyContainerElement: typeof proceedExtensions.removeEmptyContainerElement; - setMetaData: typeof proceedExtensions.setMetaData; - setProceedElement: typeof proceedExtensions.setProceedElement; - getExporterName: typeof proceedConstants.getExporterName; - getExporterVersion: typeof proceedConstants.getExporterVersion; - generateBpmnId: typeof proceedConstants.generateBpmnId; - generateDefinitionsId: typeof proceedConstants.generateDefinitionsId; - generateProcessId: typeof proceedConstants.generateProcessId; - generateUserTaskFileName: typeof proceedConstants.generateUserTaskFileName; - getUserTaskImplementationString: typeof proceedConstants.getUserTaskImplementationString; - generateTargetNamespace: typeof proceedConstants.generateTargetNamespace; - initXml: typeof proceedConstants.initXml; - validateCalledProcess: typeof validators.validateCalledProcess; - setDefinitionsId: typeof setters.setDefinitionsId; - setDefinitionsName: typeof setters.setDefinitionsName; - setDefinitionsVersionInformation: typeof setters.setDefinitionsVersionInformation; - setProcessId: typeof setters.setProcessId; - setTemplateId: typeof setters.setTemplateId; - setTargetNamespace: typeof setters.setTargetNamespace; - setStandardDefinitions: typeof setters.setStandardDefinitions; - setDeploymentMethod: typeof setters.setDeploymentMethod; - setMachineInfo: typeof setters.setMachineInfo; - setUserTaskData: typeof setters.setUserTaskData; - addConstraintsToElementById: typeof setters.addConstraintsToElementById; - addCallActivityReference: typeof setters.addCallActivityReference; - removeCallActivityReference: typeof setters.removeCallActivityReference; - removeUnusedCallActivityReferences: typeof setters.removeUnusedCallActivityReferences; - removeColorFromAllElements: typeof setters.removeColorFromAllElements; - addDocumentation: typeof setters.addDocumentation; - addDocumentationToProcessObject: typeof setters.addDocumentationToProcessObject; - updatePerformersOnElement: typeof setters.updatePerformersOnElement; - updatePerformersOnElementById: typeof setters.updatePerformersOnElementById; + ensureExtensionElements(element: object): object; + removeEmptyExtensionElements(element: any): void; + ensureContainerElement(element: object, containerType: string): object; + removeEmptyContainerElement(element: any, containerType: any, containerElement: any): void; + setMetaData(bpmn: string | object, elId: string, metaValues: object): Promise; + setProceedElement(element: any, proceedElementType: any, value: any, attributes?: {}): {}; + getExporterName(): string; + getExporterVersion(): string; + generateBpmnId(prefix?: string): string; + generateDefinitionsId(): string; + generateProcessId(): string; + generateUserTaskFileName(): string; + getUserTaskImplementationString(): string; + generateTargetNamespace(id: any): string; + initXml(processId?: any, startEventId?: string): string; + validateCalledProcess(xml: string, processId: string): Promise; + setDefinitionsId(bpmn: string | object, id: string): Promise; + setDefinitionsName(bpmn: string | object, name: string): Promise; + setDefinitionsVersionInformation( + bpmn: string | object, + { + version, + versionName, + versionDescription, + versionBasedOn, + }: { + version?: string | number; + versionName?: string; + versionDescription?: string; + versionBasedOn?: string | number; + }, + ): Promise; + setProcessId(bpmn: string, id: string): Promise; + setTemplateId(bpmn: string, id: string): Promise; + setTargetNamespace(bpmn: string | object, id: string): Promise; + setStandardDefinitions( + bpmn: string | object, + exporterName: string, + exporterVersion: string, + ): Promise; + setDeploymentMethod(bpmn: string | object, method: string): Promise; + setMachineInfo( + bpmn: string | object, + machineInfo: { + [elementId: string]: { + machineAddress?: string; + machineId?: string; + }; + }, + ): Promise; + setUserTaskData( + bpmn: string | object, + userTaskId: string, + newFileName: string, + newImplementation?: string, + ): Promise; + addConstraintsToElementById( + bpmn: string | object, + elementId: string, + constraints: object, + ): Promise; + addCallActivityReference( + bpmn: string | object, + callActivityId: string, + calledBpmn: string, + calledProcessLocation: string, + ): Promise; + removeCallActivityReference( + bpmn: string | object, + callActivityId: string, + ): Promise; + removeUnusedCallActivityReferences(bpmn: string | object): Promise; + removeColorFromAllElements(bpmn: string | object): Promise; + addDocumentation(bpmn: string | object, description: string): Promise; + addDocumentationToProcessObject(processObj: object, description: string): void; + updatePerformersOnElement(element: object, performers: any[]): Promise; + updatePerformersOnElementById( + bpmn: string | object, + elementId: string, + performers: any[], + ): Promise; getDefinitionsId: typeof getters.getDefinitionsId; getOriginalDefinitionsId: typeof getters.getOriginalDefinitionsId; getDefinitionsName: typeof getters.getDefinitionsName; @@ -70,22 +116,26 @@ declare const _exports: { getPerformersFromElementById: typeof getters.getPerformersFromElementById; parseISODuration: typeof getters.parseISODuration; convertISODurationToMiliseconds: typeof getters.convertISODurationToMiliseconds; + ensureCorrectProceedNamespace(xml: string): string; + toBpmnObject(xml: string, typename?: string): Promise; + toBpmnXml(obj: any): Promise; + getChildren(travObj: object): any[]; + getElementsByTagName(travObj: object, tagname: string): any[]; + getAllElements(travObj: object): any[]; + getElementById(travObj: object, id: string): object; + getElementDI(element: object, definitions?: object): any; + manipulateElementById( + bpmn: string | object, + id: string, + manipFunc: util.manipulationFunction, + ): Promise; + manipulateElementsByTagName( + bpmn: string | object, + tagName: string, + manipFunc: util.manipulationFunction, + ): Promise; moddle: any; - ensureCorrectProceedNamespace: typeof util.ensureCorrectProceedNamespace; - toBpmnObject: typeof util.toBpmnObject; - toBpmnXml: typeof util.toBpmnXml; - getChildren: typeof util.getChildren; - getElementsByTagName: typeof util.getElementsByTagName; - getAllElements: typeof util.getAllElements; - getElementById: typeof util.getElementById; - getElementDI: typeof util.getElementDI; - manipulateElementById: typeof util.manipulateElementById; - manipulateElementsByTagName: typeof util.manipulateElementsByTagName; }; export = _exports; -import proceedExtensions = require('./src/proceedExtensions'); -import proceedConstants = require('./src/PROCEED-CONSTANTS.js'); -import validators = require('./src/validators.js'); -import setters = require('./src/setters.js'); import getters = require('./src/getters.js'); import util = require('./src/util.js'); diff --git a/src/helper-modules/bpmn-helper/src/getters.d.ts b/src/helper-modules/bpmn-helper/src/getters.d.ts index ea8ff3c15..ab1829ed7 100644 --- a/src/helper-modules/bpmn-helper/src/getters.d.ts +++ b/src/helper-modules/bpmn-helper/src/getters.d.ts @@ -260,9 +260,9 @@ export function getProcessIds(bpmn: string | object): Promise; * Gets deployment method of the given process * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} the deployment method used for the given process + * @returns {Promise.} the deployment method used for the given process */ -export function getDeploymentMethod(bpmn: string | object): Promise; +export function getDeploymentMethod(bpmn: string | object): Promise; /** * Get the Constraints of the BPMN process. * (The Constraint XML elements are defined in the PROCEED XML Schema diff --git a/src/helper-modules/bpmn-helper/src/getters.js b/src/helper-modules/bpmn-helper/src/getters.js index d95ddf093..ceae27170 100644 --- a/src/helper-modules/bpmn-helper/src/getters.js +++ b/src/helper-modules/bpmn-helper/src/getters.js @@ -155,7 +155,7 @@ async function getDefinitionsInfos(bpmn) { * Gets deployment method of the given process * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} the deployment method used for the given process + * @returns {Promise.} the deployment method used for the given process */ async function getDeploymentMethod(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -414,6 +414,12 @@ function getTargetDefinitionsAndProcessIdForCallActivityByObject(bpmnObj, callAc // deconstruct 'p3c2324:Process_1wqd8fv' to prefix 'p3c2c324' const [prefix, processId] = callActivityElement.calledElement.split(':'); + if (!processId) { + throw new Error( + `No processId found for the referenced process in callActivity ${callActivityId}.`, + ); + } + // find Namespace for prefix, e.g. xmlns:p3c2324="https://docs.proceed-labs.org/_17c6fed0-8a8c-4722-a62f-86ebf13243c2#1655749975324" const [definitionsElement] = getElementsByTagName(bpmnObj, 'bpmn:Definitions'); const targetNamespace = definitionsElement.$attrs[`xmlns:${prefix}`]; @@ -430,8 +436,20 @@ function getTargetDefinitionsAndProcessIdForCallActivityByObject(bpmnObj, callAc ); } + if (!importElement.location) { + throw new Error( + `No location in 'import' element found for the referenced process in callActivity ${callActivityId}.`, + ); + } + const version = importElement.version || importElement.$attrs['proceed:version']; + if (!version) { + throw new Error( + `No Process Version in 'import' element found for the referenced process in callActivity ${callActivityId}.`, + ); + } + return { definitionId: importElement.location, processId, @@ -673,11 +691,18 @@ function getMilestonesFromElement(element) { (child) => child.$type == 'proceed:Milestones', ); if (milestonesElement && milestonesElement.milestone) { - milestones = milestonesElement.milestone.map(({ id, name, description }) => ({ - id, - name, - description, - })); + milestones = milestonesElement.milestone.map(({ id, name, description }) => { + if (!id || !name) { + throw new Error( + 'Some Milestone Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + name, + description, + }; + }); } } @@ -793,60 +818,93 @@ function getLocationsFromElement(element) { ); if (locationsElement && locationsElement.company) { company = locationsElement.company.map( - ({ id, shortName, longName, description, factoryIds }) => ({ - id, - shortName, - longName, - description, - factoryIds, - }), + ({ id, shortName, longName, description, factoryIds }) => { + if (!id || !shortName || !longName) { + throw new Error( + 'Some Company Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + shortName, + longName, + description, + factoryIds, + }; + }, ); } if (locationsElement && locationsElement.factory) { factory = locationsElement.factory.map( - ({ id, shortName, longName, description, companyRef }) => ({ - id, - shortName, - longName, - description, - companyRef, - }), + ({ id, shortName, longName, description, companyRef }) => { + if (!id || !shortName || !longName) { + throw new Error( + 'Some Company Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + shortName, + longName, + description, + companyRef, + }; + }, ); } if (locationsElement && locationsElement.building) { building = locationsElement.building.map( - ({ id, shortName, longName, description, factoryRef }) => ({ - id, - shortName, - longName, - description, - factoryRef, - }), + ({ id, shortName, longName, description, factoryRef }) => { + if (!id || !shortName || !longName) { + throw new Error( + 'Some Building Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + shortName, + longName, + description, + factoryRef, + }; + }, ); } if (locationsElement && locationsElement.area) { - area = locationsElement.area.map(({ id, shortName, longName, description, buildingRef }) => ({ - id, - shortName, - longName, - description, - buildingRef, - })); - } - - if (locationsElement && locationsElement.workingPlace) { - workingPlace = locationsElement.workingPlace.map( - ({ id, shortName, longName, description, buildingRef, areaRef }) => ({ + area = locationsElement.area.map(({ id, shortName, longName, description, buildingRef }) => { + if (!id || !shortName || !longName) { + throw new Error('Some Area Elements are not valid due to missing mandatory attributes'); + } + return { id, shortName, longName, description, buildingRef, - areaRef, - }), + }; + }); + } + + if (locationsElement && locationsElement.workingPlace) { + workingPlace = locationsElement.workingPlace.map( + ({ id, shortName, longName, description, buildingRef, areaRef }) => { + if (!id || !shortName || !longName) { + throw new Error( + 'Some WorkingPlace Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + shortName, + longName, + description, + buildingRef, + areaRef, + }; + }, ); } } @@ -895,16 +953,23 @@ function getResourcesFromElement(element) { unit, quantity, description, - }) => ({ - id, - shortName, - longName, - manufacturer, - manufacturerSerialNumber, - unit, - quantity, - description, - }), + }) => { + if (!id || !shortName || !longName || !quantity) { + throw new Error( + 'Some ConsumableMaterial Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + shortName, + longName, + manufacturer, + manufacturerSerialNumber, + unit, + quantity, + description, + }; + }, ); } @@ -919,16 +984,21 @@ function getResourcesFromElement(element) { unit, quantity, description, - }) => ({ - id, - shortName, - longName, - manufacturer, - manufacturerSerialNumber, - unit, - quantity, - description, - }), + }) => { + if (!id || !shortName || !longName || !quantity) { + throw new Error('Some Tool Elements are not valid due to missing mandatory attributes'); + } + return { + id, + shortName, + longName, + manufacturer, + manufacturerSerialNumber, + unit, + quantity, + description, + }; + }, ); } @@ -943,16 +1013,23 @@ function getResourcesFromElement(element) { unit, quantity, description, - }) => ({ - id, - shortName, - longName, - manufacturer, - manufacturerSerialNumber, - unit, - quantity, - description, - }), + }) => { + if (!id || !shortName || !longName || !quantity) { + throw new Error( + 'Some InspectionInstrument Elements are not valid due to missing mandatory attributes', + ); + } + return { + id, + shortName, + longName, + manufacturer, + manufacturerSerialNumber, + unit, + quantity, + description, + }; + }, ); } } From 63c3d30e1b01763051801301ebdcd20e3b8ae240 Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 16:42:26 +0200 Subject: [PATCH 08/13] define optional parameters in definitions element --- .../bpmn-helper/src/getters.d.ts | 43 +++++++++++-------- src/helper-modules/bpmn-helper/src/getters.js | 15 ++++--- 2 files changed, 32 insertions(+), 26 deletions(-) diff --git a/src/helper-modules/bpmn-helper/src/getters.d.ts b/src/helper-modules/bpmn-helper/src/getters.d.ts index ab1829ed7..117e854ff 100644 --- a/src/helper-modules/bpmn-helper/src/getters.d.ts +++ b/src/helper-modules/bpmn-helper/src/getters.d.ts @@ -7,22 +7,26 @@ export type DefinitionsInfos = { * - definitions id */ id: string; + /** + * - definitions original id + */ + originalId?: string; /** * - definitions name */ - name: string; + name?: string; /** * - definitions exporter */ - exporter: string; + exporter?: string; /** * - definitions exporterVersion */ - exporterVersion: string; + exporterVersion?: string; /** * - definitions targetNamespace */ - targetNamespace: string; + targetNamespace?: string; }; /** * An object containing properties from defined companies @@ -191,9 +195,9 @@ export type ResourceInfos = { * Returns id of the given process definition * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} The id stored in the definitions field of the given bpmn process + * @returns {Promise.} The id stored in the definitions field of the given bpmn process */ -export function getDefinitionsId(bpmn: string | object): Promise; +export function getDefinitionsId(bpmn: string | object): Promise; /** * Returns the value of the originalId attribute in the given process definition * the originalId is the id the process had before it was imported @@ -206,9 +210,9 @@ export function getOriginalDefinitionsId(bpmn: string | object): Promise} - The name stored in the definitions field of the given bpmn process + * @returns {Promise.} - The name stored in the definitions field of the given bpmn process */ -export function getDefinitionsName(bpmn: string | object): Promise; +export function getDefinitionsName(bpmn: string | object): Promise; /** * An object containing properties from the * definitions element in a BPMN file. @@ -216,10 +220,11 @@ export function getDefinitionsName(bpmn: string | object): Promise; * @typedef DefinitionsInfos * @type {object} * @property {string} id - definitions id - * @property {string} name - definitions name - * @property {string} exporter - definitions exporter - * @property {string} exporterVersion - definitions exporterVersion - * @property {string} targetNamespace - definitions targetNamespace + * @property {string} [originalId] - definitions original id + * @property {string} [name] - definitions name + * @property {string} [exporter] - definitions exporter + * @property {string} [exporterVersion] - definitions exporterVersion + * @property {string} [targetNamespace] - definitions targetNamespace */ /** * Gets the 'definitions' root element from the given BPMN XML @@ -638,15 +643,15 @@ export function getPerformersFromElementById(bpmn: string | object, elementId: s /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds * @param {string} isoDuration - * @returns {{years?: number, months?: number, days?: number, hours?: number, minutes?: number, seconds?: number}} Object with number of years, months, days, hours, minutes and seconds + * @returns {{years: number | null, months: number | null, days: number | null, hours: number | null, minutes: number | null, seconds: number | null}} Object with number of years, months, days, hours, minutes and seconds */ export function parseISODuration(isoDuration: string): { - years?: number; - months?: number; - days?: number; - hours?: number; - minutes?: number; - seconds?: number; + years: number | null; + months: number | null; + days: number | null; + hours: number | null; + minutes: number | null; + seconds: number | null; }; /** * Convert given ISO Duration in number of miliseconds diff --git a/src/helper-modules/bpmn-helper/src/getters.js b/src/helper-modules/bpmn-helper/src/getters.js index ceae27170..12784d05f 100644 --- a/src/helper-modules/bpmn-helper/src/getters.js +++ b/src/helper-modules/bpmn-helper/src/getters.js @@ -30,7 +30,7 @@ async function getStartEvents(bpmn) { * Returns id of the given process definition * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} The id stored in the definitions field of the given bpmn process + * @returns {Promise.} The id stored in the definitions field of the given bpmn process */ async function getDefinitionsId(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -53,7 +53,7 @@ async function getOriginalDefinitionsId(bpmn) { * Returns the name of the given bpmn process definition * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @returns {Promise.} - The name stored in the definitions field of the given bpmn process + * @returns {Promise.} - The name stored in the definitions field of the given bpmn process */ async function getDefinitionsName(bpmn) { const bpmnObj = typeof bpmn === 'string' ? await toBpmnObject(bpmn) : bpmn; @@ -127,10 +127,11 @@ function getProcessDocumentationByObject(processObject) { * @typedef DefinitionsInfos * @type {object} * @property {string} id - definitions id - * @property {string} name - definitions name - * @property {string} exporter - definitions exporter - * @property {string} exporterVersion - definitions exporterVersion - * @property {string} targetNamespace - definitions targetNamespace + * @property {string} [originalId] - definitions original id + * @property {string} [name] - definitions name + * @property {string} [exporter] - definitions exporter + * @property {string} [exporterVersion] - definitions exporterVersion + * @property {string} [targetNamespace] - definitions targetNamespace */ /** @@ -1064,7 +1065,7 @@ function getPerformersFromElement(element) { /** * Parses ISO Duration String to number of years, months, days, hours, minutes and seconds * @param {string} isoDuration - * @returns {{years?: number, months?: number, days?: number, hours?: number, minutes?: number, seconds?: number}} Object with number of years, months, days, hours, minutes and seconds + * @returns {{years: number | null, months: number | null, days: number | null, hours: number | null, minutes: number | null, seconds: number | null}} Object with number of years, months, days, hours, minutes and seconds */ function parseISODuration(isoDuration) { let years = null; From 695ceaff8db844ff1f23c01f8894eb9b43dcca48 Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 16:58:08 +0200 Subject: [PATCH 09/13] remove unnecessary condition --- src/management-system-v2/lib/helpers.ts | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/src/management-system-v2/lib/helpers.ts b/src/management-system-v2/lib/helpers.ts index 971a5e834..68c8a8c3d 100644 --- a/src/management-system-v2/lib/helpers.ts +++ b/src/management-system-v2/lib/helpers.ts @@ -201,17 +201,15 @@ async function updateProcessVersionBasedOn(processDefinitionsId: string, version if (processInfo?.bpmn) { const { version, description, name } = await getDefinitionsVersionInformation(processInfo.bpmn); - if (version) { - const bpmn = (await setDefinitionsVersionInformation(processInfo.bpmn, { - version, - versionDescription: description, - versionName: name, - versionBasedOn, - })) as string; - await put('/process/{definitionId}', { - params: { path: { definitionId: processDefinitionsId } }, - body: { bpmn }, - }); - } + const bpmn = (await setDefinitionsVersionInformation(processInfo.bpmn, { + version, + versionDescription: description, + versionName: name, + versionBasedOn, + })) as string; + await put('/process/{definitionId}', { + params: { path: { definitionId: processDefinitionsId } }, + body: { bpmn }, + }); } } From 7e892aa9c10f68d819369c7ae877330b60b54674 Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 17:03:25 +0200 Subject: [PATCH 10/13] make sure basedOnBPMN variable is only a string or undefined --- src/management-system-v2/lib/helpers.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/management-system-v2/lib/helpers.ts b/src/management-system-v2/lib/helpers.ts index 68c8a8c3d..646bb27ce 100644 --- a/src/management-system-v2/lib/helpers.ts +++ b/src/management-system-v2/lib/helpers.ts @@ -98,7 +98,9 @@ async function versionUserTasks( // get the html of the user task in the based on version (if there is one and it is locally known) const basedOnBPMN = - versionBasedOn && (await getLocalVersionBpmn(processInfo, versionBasedOn)); + versionBasedOn !== undefined + ? await getLocalVersionBpmn(processInfo, versionBasedOn) + : undefined; // check if there is a preceding version and if the html of the user task actually changed from that version let userTaskHtmlAlreadyExisting = false; @@ -175,7 +177,11 @@ export async function createNewProcessVersion( const versionedBpmn = await toBpmnXml(bpmnObj); // if the new version has no changes to the version it is based on don't create a new version and return the previous version - const basedOnBPMN = versionBasedOn && (await getLocalVersionBpmn(processInfo, versionBasedOn)); + const basedOnBPMN = + versionBasedOn !== undefined + ? await getLocalVersionBpmn(processInfo, versionBasedOn) + : undefined; + if (basedOnBPMN && (await areVersionsEqual(versionedBpmn, basedOnBPMN))) { return versionBasedOn; } From 65d9ffb9bc043b30070b2c3770fe56856b237c2b Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 17:05:26 +0200 Subject: [PATCH 11/13] fix typo --- src/helper-modules/bpmn-helper/src/setters.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/helper-modules/bpmn-helper/src/setters.js b/src/helper-modules/bpmn-helper/src/setters.js index 82aed0005..6b5d0abb9 100644 --- a/src/helper-modules/bpmn-helper/src/setters.js +++ b/src/helper-modules/bpmn-helper/src/setters.js @@ -99,7 +99,7 @@ async function setProcessId(bpmn, id) { } /** - * Sets templaseId in definitions element + * Sets templateId in definitions element * * @param {string} bpmn the xml we want to update * @param {string} id the id we want to set for the template inside the bpmn From 8f33ca4b29f0a58c87c0033869e30ff4786f50dd Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 17:08:01 +0200 Subject: [PATCH 12/13] set description as optional parameter when adding documention to process --- src/helper-modules/bpmn-helper/src/setters.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/helper-modules/bpmn-helper/src/setters.js b/src/helper-modules/bpmn-helper/src/setters.js index 6b5d0abb9..15eaa8986 100644 --- a/src/helper-modules/bpmn-helper/src/setters.js +++ b/src/helper-modules/bpmn-helper/src/setters.js @@ -512,7 +512,7 @@ async function removeUnusedCallActivityReferences(bpmn) { * Adds a documentation element to the first process in the process definition * * @param {(string|object)} bpmn - the process definition as XML string or BPMN-Moddle Object - * @param {string} description the content for the documentation element + * @param {string} [description] the content for the documentation element * @returns {Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ async function addDocumentation(bpmn, description) { @@ -531,7 +531,7 @@ async function addDocumentation(bpmn, description) { * Adds documentation to a given process object * * @param {object} processObj - * @param {string} description + * @param {string} [description] */ function addDocumentationToProcessObject(processObj, description) { const docs = processObj.get('documentation'); From 3769ae5fe09caee86eb289e0dfda9d33ad6a50ad Mon Sep 17 00:00:00 2001 From: Lucas Date: Wed, 11 Oct 2023 17:09:42 +0200 Subject: [PATCH 13/13] generated updated declaration files for bpmn helper module --- src/helper-modules/bpmn-helper/index.d.ts | 148 ++++++------------ .../bpmn-helper/src/setters.d.ts | 10 +- 2 files changed, 54 insertions(+), 104 deletions(-) diff --git a/src/helper-modules/bpmn-helper/index.d.ts b/src/helper-modules/bpmn-helper/index.d.ts index c8193412e..45eb29d8c 100644 --- a/src/helper-modules/bpmn-helper/index.d.ts +++ b/src/helper-modules/bpmn-helper/index.d.ts @@ -1,85 +1,39 @@ declare const _exports: { - ensureExtensionElements(element: object): object; - removeEmptyExtensionElements(element: any): void; - ensureContainerElement(element: object, containerType: string): object; - removeEmptyContainerElement(element: any, containerType: any, containerElement: any): void; - setMetaData(bpmn: string | object, elId: string, metaValues: object): Promise; - setProceedElement(element: any, proceedElementType: any, value: any, attributes?: {}): {}; - getExporterName(): string; - getExporterVersion(): string; - generateBpmnId(prefix?: string): string; - generateDefinitionsId(): string; - generateProcessId(): string; - generateUserTaskFileName(): string; - getUserTaskImplementationString(): string; - generateTargetNamespace(id: any): string; - initXml(processId?: any, startEventId?: string): string; - validateCalledProcess(xml: string, processId: string): Promise; - setDefinitionsId(bpmn: string | object, id: string): Promise; - setDefinitionsName(bpmn: string | object, name: string): Promise; - setDefinitionsVersionInformation( - bpmn: string | object, - { - version, - versionName, - versionDescription, - versionBasedOn, - }: { - version?: string | number; - versionName?: string; - versionDescription?: string; - versionBasedOn?: string | number; - }, - ): Promise; - setProcessId(bpmn: string, id: string): Promise; - setTemplateId(bpmn: string, id: string): Promise; - setTargetNamespace(bpmn: string | object, id: string): Promise; - setStandardDefinitions( - bpmn: string | object, - exporterName: string, - exporterVersion: string, - ): Promise; - setDeploymentMethod(bpmn: string | object, method: string): Promise; - setMachineInfo( - bpmn: string | object, - machineInfo: { - [elementId: string]: { - machineAddress?: string; - machineId?: string; - }; - }, - ): Promise; - setUserTaskData( - bpmn: string | object, - userTaskId: string, - newFileName: string, - newImplementation?: string, - ): Promise; - addConstraintsToElementById( - bpmn: string | object, - elementId: string, - constraints: object, - ): Promise; - addCallActivityReference( - bpmn: string | object, - callActivityId: string, - calledBpmn: string, - calledProcessLocation: string, - ): Promise; - removeCallActivityReference( - bpmn: string | object, - callActivityId: string, - ): Promise; - removeUnusedCallActivityReferences(bpmn: string | object): Promise; - removeColorFromAllElements(bpmn: string | object): Promise; - addDocumentation(bpmn: string | object, description: string): Promise; - addDocumentationToProcessObject(processObj: object, description: string): void; - updatePerformersOnElement(element: object, performers: any[]): Promise; - updatePerformersOnElementById( - bpmn: string | object, - elementId: string, - performers: any[], - ): Promise; + ensureExtensionElements: typeof proceedExtensions.ensureExtensionElements; + removeEmptyExtensionElements: typeof proceedExtensions.removeEmptyExtensionElements; + ensureContainerElement: typeof proceedExtensions.ensureContainerElement; + removeEmptyContainerElement: typeof proceedExtensions.removeEmptyContainerElement; + setMetaData: typeof proceedExtensions.setMetaData; + setProceedElement: typeof proceedExtensions.setProceedElement; + getExporterName: typeof proceedConstants.getExporterName; + getExporterVersion: typeof proceedConstants.getExporterVersion; + generateBpmnId: typeof proceedConstants.generateBpmnId; + generateDefinitionsId: typeof proceedConstants.generateDefinitionsId; + generateProcessId: typeof proceedConstants.generateProcessId; + generateUserTaskFileName: typeof proceedConstants.generateUserTaskFileName; + getUserTaskImplementationString: typeof proceedConstants.getUserTaskImplementationString; + generateTargetNamespace: typeof proceedConstants.generateTargetNamespace; + initXml: typeof proceedConstants.initXml; + validateCalledProcess: typeof validators.validateCalledProcess; + setDefinitionsId: typeof setters.setDefinitionsId; + setDefinitionsName: typeof setters.setDefinitionsName; + setDefinitionsVersionInformation: typeof setters.setDefinitionsVersionInformation; + setProcessId: typeof setters.setProcessId; + setTemplateId: typeof setters.setTemplateId; + setTargetNamespace: typeof setters.setTargetNamespace; + setStandardDefinitions: typeof setters.setStandardDefinitions; + setDeploymentMethod: typeof setters.setDeploymentMethod; + setMachineInfo: typeof setters.setMachineInfo; + setUserTaskData: typeof setters.setUserTaskData; + addConstraintsToElementById: typeof setters.addConstraintsToElementById; + addCallActivityReference: typeof setters.addCallActivityReference; + removeCallActivityReference: typeof setters.removeCallActivityReference; + removeUnusedCallActivityReferences: typeof setters.removeUnusedCallActivityReferences; + removeColorFromAllElements: typeof setters.removeColorFromAllElements; + addDocumentation: typeof setters.addDocumentation; + addDocumentationToProcessObject: typeof setters.addDocumentationToProcessObject; + updatePerformersOnElement: typeof setters.updatePerformersOnElement; + updatePerformersOnElementById: typeof setters.updatePerformersOnElementById; getDefinitionsId: typeof getters.getDefinitionsId; getOriginalDefinitionsId: typeof getters.getOriginalDefinitionsId; getDefinitionsName: typeof getters.getDefinitionsName; @@ -116,26 +70,22 @@ declare const _exports: { getPerformersFromElementById: typeof getters.getPerformersFromElementById; parseISODuration: typeof getters.parseISODuration; convertISODurationToMiliseconds: typeof getters.convertISODurationToMiliseconds; - ensureCorrectProceedNamespace(xml: string): string; - toBpmnObject(xml: string, typename?: string): Promise; - toBpmnXml(obj: any): Promise; - getChildren(travObj: object): any[]; - getElementsByTagName(travObj: object, tagname: string): any[]; - getAllElements(travObj: object): any[]; - getElementById(travObj: object, id: string): object; - getElementDI(element: object, definitions?: object): any; - manipulateElementById( - bpmn: string | object, - id: string, - manipFunc: util.manipulationFunction, - ): Promise; - manipulateElementsByTagName( - bpmn: string | object, - tagName: string, - manipFunc: util.manipulationFunction, - ): Promise; moddle: any; + ensureCorrectProceedNamespace: typeof util.ensureCorrectProceedNamespace; + toBpmnObject: typeof util.toBpmnObject; + toBpmnXml: typeof util.toBpmnXml; + getChildren: typeof util.getChildren; + getElementsByTagName: typeof util.getElementsByTagName; + getAllElements: typeof util.getAllElements; + getElementById: typeof util.getElementById; + getElementDI: typeof util.getElementDI; + manipulateElementById: typeof util.manipulateElementById; + manipulateElementsByTagName: typeof util.manipulateElementsByTagName; }; export = _exports; +import proceedExtensions = require('./src/proceedExtensions'); +import proceedConstants = require('./src/PROCEED-CONSTANTS.js'); +import validators = require('./src/validators.js'); +import setters = require('./src/setters.js'); import getters = require('./src/getters.js'); import util = require('./src/util.js'); diff --git a/src/helper-modules/bpmn-helper/src/setters.d.ts b/src/helper-modules/bpmn-helper/src/setters.d.ts index 02bbefd51..4921b2429 100644 --- a/src/helper-modules/bpmn-helper/src/setters.d.ts +++ b/src/helper-modules/bpmn-helper/src/setters.d.ts @@ -51,7 +51,7 @@ export function setDefinitionsVersionInformation( */ export function setProcessId(bpmn: string, id: string): Promise; /** - * Sets templaseId in definitions element + * Sets templateId in definitions element * * @param {string} bpmn the xml we want to update * @param {string} id the id we want to set for the template inside the bpmn @@ -180,20 +180,20 @@ export function removeColorFromAllElements(bpmn: string | object): Promise} the BPMN process as XML string or BPMN-Moddle Object based on input */ export function addDocumentation( bpmn: string | object, - description: string, + description?: string, ): Promise; /** * Adds documentation to a given process object * * @param {object} processObj - * @param {string} description + * @param {string} [description] */ -export function addDocumentationToProcessObject(processObj: object, description: string): void; +export function addDocumentationToProcessObject(processObj: object, description?: string): void; /** * Update the performer info of an element *