@contrail/flexplm 1.4.0 → 1.5.0-alpha.14a4f1b

package/lib/cli/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.Cli = void 0;
+const create_1 = require("./commands/create");
+const compile_1 = require("./commands/compile");
+const upload_1 = require("./commands/upload");
+const USAGE = `Usage: flexplm-mapping <command> [args]
+
+Commands:
+  create                  Scaffold a new mapping .ts file in the current directory
+  compile <path.ts>       Transpile a mapping .ts file to .js alongside it
+  upload  <path.ts> [opts] Compile a mapping .ts file and upload the resulting .js to VibeIQ
+
+Upload options:
+  -m <message>            Git commit message (prompted if omitted)
+  -b <branch>             Create a new git branch before committing
+  --skip-git              Skip the post-upload git commit (default: commit)
+
+Environment (upload):
+  CONTRAIL_CLI_EMAIL      VibeIQ user email
+  CONTRAIL_CLI_PASSWORD   VibeIQ user password
+`;
+class Cli {
+    async main() {
+        const [, , command, ...rest] = process.argv;
+        switch (command) {
+            case 'create':
+                await new create_1.CreateCommand().run();
+                return;
+            case 'compile':
+                if (!rest[0]) {
+                    console.error('compile: missing <path.ts> argument');
+                    console.error(USAGE);
+                    process.exit(1);
+                }
+                await new compile_1.CompileCommand().run(rest[0]);
+                return;
+            case 'upload':
+                if (!rest[0]) {
+                    console.error('upload: missing <path.ts> argument');
+                    console.error(USAGE);
+                    process.exit(1);
+                }
+                await new upload_1.UploadCommand().run(rest);
+                return;
+            case undefined:
+            case '-h':
+            case '--help':
+            case 'help':
+                console.log(USAGE);
+                return;
+            default:
+                console.error(`Unknown command: ${command}`);
+                console.error(USAGE);
+                process.exit(1);
+        }
+    }
+}
+exports.Cli = Cli;
+function main() {
+    return new Cli().main();
+}
+exports.main = main;
+if (require.main === module) {
+    main().catch((err) => {
+        console.error(err && err.message ? err.message : err);
+        process.exit(1);
+    });
+}

package/lib/cli/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/cli/index.spec.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const createRunMock = jest.fn().mockResolvedValue(undefined);
+const compileRunMock = jest.fn().mockResolvedValue(undefined);
+const uploadRunMock = jest.fn().mockResolvedValue(undefined);
+jest.mock('./commands/create', () => ({
+    CreateCommand: jest.fn().mockImplementation(() => ({ run: createRunMock })),
+}));
+jest.mock('./commands/compile', () => ({
+    CompileCommand: jest.fn().mockImplementation(() => ({ run: compileRunMock })),
+}));
+jest.mock('./commands/upload', () => ({
+    UploadCommand: jest.fn().mockImplementation(() => ({ run: uploadRunMock })),
+}));
+const index_1 = require("./index");
+describe('cli main dispatcher', () => {
+    let originalArgv;
+    let logSpy;
+    let errorSpy;
+    let exitSpy;
+    beforeEach(() => {
+        originalArgv = process.argv;
+        createRunMock.mockClear();
+        compileRunMock.mockClear();
+        uploadRunMock.mockClear();
+        logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        exitSpy = jest.spyOn(process, 'exit').mockImplementation(((code) => {
+            throw new Error(`__EXIT__:${code}`);
+        }));
+    });
+    afterEach(() => {
+        process.argv = originalArgv;
+        logSpy.mockRestore();
+        errorSpy.mockRestore();
+        exitSpy.mockRestore();
+    });
+    function setArgv(...args) {
+        process.argv = ['node', 'cli', ...args];
+    }
+    it('dispatches the create command', async () => {
+        setArgv('create');
+        await (0, index_1.main)();
+        expect(createRunMock).toHaveBeenCalledTimes(1);
+        expect(compileRunMock).not.toHaveBeenCalled();
+        expect(uploadRunMock).not.toHaveBeenCalled();
+    });
+    it('dispatches the compile command with its argument', async () => {
+        setArgv('compile', 'mapping.ts');
+        await (0, index_1.main)();
+        expect(compileRunMock).toHaveBeenCalledWith('mapping.ts');
+    });
+    it('exits when compile is missing its argument', async () => {
+        setArgv('compile');
+        await expect((0, index_1.main)()).rejects.toThrow('__EXIT__:1');
+        expect(compileRunMock).not.toHaveBeenCalled();
+        expect(errorSpy).toHaveBeenCalledWith(expect.stringMatching(/missing <path\.ts>/));
+    });
+    it('dispatches the upload command and forwards remaining args', async () => {
+        setArgv('upload', 'mapping.ts', '-m', 'msg', '--skip-git');
+        await (0, index_1.main)();
+        expect(uploadRunMock).toHaveBeenCalledWith(['mapping.ts', '-m', 'msg', '--skip-git']);
+    });
+    it('exits when upload is missing its argument', async () => {
+        setArgv('upload');
+        await expect((0, index_1.main)()).rejects.toThrow('__EXIT__:1');
+        expect(uploadRunMock).not.toHaveBeenCalled();
+        expect(errorSpy).toHaveBeenCalledWith(expect.stringMatching(/missing <path\.ts>/));
+    });
+    it.each(['help', '-h', '--help'])('prints usage for %s', async (helpFlag) => {
+        setArgv(helpFlag);
+        await (0, index_1.main)();
+        expect(logSpy).toHaveBeenCalledWith(expect.stringMatching(/Usage: flexplm-mapping/));
+    });
+    it('prints usage when no command is provided', async () => {
+        setArgv();
+        await (0, index_1.main)();
+        expect(logSpy).toHaveBeenCalledWith(expect.stringMatching(/Usage: flexplm-mapping/));
+    });
+    it('exits on an unknown command', async () => {
+        setArgv('bogus');
+        await expect((0, index_1.main)()).rejects.toThrow('__EXIT__:1');
+        expect(errorSpy).toHaveBeenCalledWith(expect.stringMatching(/Unknown command: bogus/));
+    });
+});

package/lib/cli/template/mapping-template.ts.template

@@ -0,0 +1,62 @@
+import type { MappingFile } from '@contrail/flexplm';
+
+export const mapping: MappingFile = {
+  orgInfo: {
+    appIdentifier: '@vibeiq/flexplm-connector',
+    orgName: '<ORG_NAME>',
+  },
+  typeConversion: {
+    vibe2flex: {},
+    flex2vibe: {},
+  },
+  LCSSeason: {
+    vibeOwningKeys: ['flexPLMSeasonName'],
+    vibe2flex: {
+      transformOrder: [{ processor: 'REKEY', rekeyDelete: true, rekeyTransformersKey: 'rekey' }],
+      rekey: {
+        seasonName: 'flexPLMSeasonName',
+      },
+    },
+    flex2vibe: {
+      transformOrder: [{ processor: 'REKEY', rekeyDelete: true, rekeyTransformersKey: 'rekey' }],
+      rekey: {
+        flexPLMSeasonName: 'seasonName',
+      },
+    },
+  },
+  LCSProduct: {
+    vibeOwningKeys: ['itemNumber'],
+    vibe2flex: {
+      transformOrder: [{ processor: 'REKEY', rekeyDelete: true, rekeyTransformersKey: 'rekey' }],
+      rekey: {
+        vibeIQIdentifier: 'itemNumber',
+        productName: 'name',
+      },
+    },
+    flex2vibe: {
+      transformOrder: [{ processor: 'REKEY', rekeyDelete: true, rekeyTransformersKey: 'rekey' }],
+      rekey: {
+        itemNumber: 'vibeIQIdentifier',
+        name: 'productName',
+      },
+    },
+  },
+  LCSSKU: {
+    vibeOwningKeys: ['itemNumber'],
+    vibe2flex: {
+      transformOrder: [{ processor: 'REKEY', rekeyDelete: true, rekeyTransformersKey: 'rekey' }],
+      rekey: {
+        vibeIQIdentifier: 'itemNumber',
+        skuName: 'optionName',
+      },
+    },
+    flex2vibe: {
+      transformOrder: [{ processor: 'REKEY', rekeyDelete: true, rekeyTransformersKey: 'rekey' }],
+      rekey: {
+        itemNumber: 'vibeIQIdentifier',
+        optionName: 'skuName',
+      },
+    },
+  },
+
+};

package/lib/entity-processor/base-entity-processor.d.ts

@@ -19,18 +19,64 @@ export declare abstract class BaseEntityProcessor {
     inbound(event: EntityPayloadType): Promise<any>;
     handleIncomingUpsert(event: EntityPayloadType): Promise<any>;
     getInboundStatusMessage(statusObject: any): string;
+    /** Looks up an identity record from the identity service based on the passed in criteria.
+     * If no identity record is found, returns undefined. If multiple are found, throws an error.
+     *
+     * @param params.poolKey the key to use for the identity service pool. This will be the subtype uniqueness is defined on, typically the root type. Ex: 'item' or 'item:material'
+     * @param params.propertyName the name of the property to use for the criteria. Ex: 'itemNumber'
+     * @param params.propertyValue the value of the property to use for the criteria. Ex: '12345'
+     * @returns the identity entity, or undefined if no identity record is found
+     * @throws error if multiple identity entities are found, or if required parameters are missing
+     */
     getIdentityEntity(params: {
         poolKey: string;
         propertyName: string;
         propertyValue: string;
     }): Promise<any | undefined>;
+    /** Looks up an entity via the identity service. Uses {@link getIdentityEntity} to find the identity record,
+     * then resolves the entity reference to fetch and return the actual entity.
+     *
+     * @param params.poolKey the key to use for the identity service pool. This will be the subtype uniqueness is defined on, typically the root type. Ex: 'item' or 'item:material'
+     * @param params.propertyName the name of the property to use for the criteria. Ex: 'itemNumber'
+     * @param params.propertyValue the value of the property to use for the criteria. Ex: '12345'
+     * @returns the resolved entity, or undefined if no identity record is found
+     * @throws error if multiple identity entities are found, or if required parameters are missing
+     */
     getEntityUsingIdentityService(params: {
         poolKey: string;
         propertyName: string;
         propertyValue: string;
     }): Promise<any | undefined>;
+    /**This will query for the entity, and handle post-processing
+     * of any critieria that is defined at the sub-type level.
+     * Because sub-type criteria can't be used in the search done
+     * on the server. This is expected to be called by getIncomingEntity().
+     *
+     * @param entityType: the root type of the entity
+     * @param entityTypePath: the full type path of the entity. Ex: custom-entity:sample
+     * @param propertyCriteria: all the criteria to search for the entity
+     * @returns the entities that match the criteria
+     */
     queryEntityWithSubTypeCriteria(entityType: string, entityTypePath: string, propertyCriteria: any): Promise<any[]>;
+    /** This is to get the criteria for the entity that is being processed.
+     * This is to be overridden for item & project-item because of the need for
+     * setting the roles criteria.
+     *
+     * @param entityType: the root type of the entity
+     * @param entityTypePath: the full type path of the entity. Ex: custom-entity:sample
+     * @param propertyCriteria: all the criteria to search for the entity
+     * @returns the criteria for the entity
+     */
     getCriteriaForEntity(entityType: string, entityTypePath: string, propertyCriteria: any): Promise<any>;
+    /** This is to get the properties that are owned by the root type
+     * This needs to be overridded for multi-level types, such as item
+     * and project-item. And for those types, the propertyCriteria
+     * will be needed to determine the correct level.
+     *
+     * @param rootType: the full root type entity for the processed entity
+     * @param propertyCriteria: the criteria to determine the correct level (unused for single level types)
+     * @returns: string[] of the property keys
+     */
     getRootTypePropertyKeys(rootType: any, propertyCriteria?: any): string[];
     handleIncomingDelete(event: any): Promise<void>;
     getTransformedData(event: any): Promise<any>;
@@ -46,7 +92,26 @@ export declare abstract class BaseEntityProcessor {
     getOutboundEntityUpdates(event: any, flexResponse: any): Promise<any>;
     handleOutgoingDelete(entityType: any, event: any): Promise<void>;
     protected abstract getOutgoingUpsertPayload(entityType: any, event: any): Promise<EntityPayloadType>;
+    /** Create a new event-workflow-request to rerun sending the entity to FlexPLM
+     * The event must contain any information needed to ensure it is put in the correct queue for the entity
+     *
+     * @param triggerKey Ex: event.entityType + '|sendUpsertToFlexPLM'
+     * @param event
+     * @returns
+     */
     protected triggerNewEvent(triggerKey: string, event: any): Promise<any>;
+    /** Sends the current state of the entity to FlexPLM.
+     * So any changes made in Vibe between the event being generated and the event being processed are sent to FlexPLM.
+     *
+     * @param event must contain entityType, id; which are used to query for the entity
+     * @returns results of sending the entity to FlexPLM
+     */
     protected sendUpsertToFlexPLM(event: any): Promise<any>;
+    /** Generates the payload to send to FlexPLM, based on the current state of the entity.
+     * The current state of the entity are used as the newData and oldData; which is passed
+     * to getOutgoingUpsertPayload to generate the payload.
+     * @param event information about the item to send to FlexPLM
+     * @returns The payload to send to FlexPLM
+     */
     protected getEntityCurrentStateUpsertPayload(event: any): Promise<EntityPayloadType>;
 }

package/lib/entity-processor/base-entity-processor.js

@@ -23,6 +23,7 @@ class BaseEntityProcessor {
         this.entities = new sdk_1.Entities();
         this.orgSlug = this.config?.orgSlug || 'unset-orgSlug';
     }
+    // inbound
     async inbound(event) {
         const eventType = event.eventType;
         console.log(`inbound entity: ${eventType}:${event.objectClass}`);
@@ -42,6 +43,7 @@ class BaseEntityProcessor {
     async handleIncomingUpsert(event) {
         const inboundData = await this.getTransformedData(event);
         const incomingEntityResponse = await this.getIncomingEntity(event, inboundData);
+        // This case means there was an early return in the getIncomingEntity method
         if (incomingEntityResponse.earlyReturn) {
             const statusMsg = this.getInboundStatusMessage({
                 status: event_short_message_status_1.EventShortMessageStatus.FAILURE,
@@ -136,6 +138,15 @@ class BaseEntityProcessor {
             + ', federatedId: ' + statusObject.federatedId
             + ', orgSlug: ' + this.orgSlug;
     }
+    /** Looks up an identity record from the identity service based on the passed in criteria.
+     * If no identity record is found, returns undefined. If multiple are found, throws an error.
+     *
+     * @param params.poolKey the key to use for the identity service pool. This will be the subtype uniqueness is defined on, typically the root type. Ex: 'item' or 'item:material'
+     * @param params.propertyName the name of the property to use for the criteria. Ex: 'itemNumber'
+     * @param params.propertyValue the value of the property to use for the criteria. Ex: '12345'
+     * @returns the identity entity, or undefined if no identity record is found
+     * @throws error if multiple identity entities are found, or if required parameters are missing
+     */
     async getIdentityEntity(params) {
         const { poolKey, propertyName, propertyValue } = params;
         if (!poolKey || !propertyName || !propertyValue) {
@@ -157,6 +168,15 @@ class BaseEntityProcessor {
         }
         return Array.isArray(identityEntities) ? identityEntities[0] : identityEntities;
     }
+    /** Looks up an entity via the identity service. Uses {@link getIdentityEntity} to find the identity record,
+     * then resolves the entity reference to fetch and return the actual entity.
+     *
+     * @param params.poolKey the key to use for the identity service pool. This will be the subtype uniqueness is defined on, typically the root type. Ex: 'item' or 'item:material'
+     * @param params.propertyName the name of the property to use for the criteria. Ex: 'itemNumber'
+     * @param params.propertyValue the value of the property to use for the criteria. Ex: '12345'
+     * @returns the resolved entity, or undefined if no identity record is found
+     * @throws error if multiple identity entities are found, or if required parameters are missing
+     */
     async getEntityUsingIdentityService(params) {
         const identityEntity = await this.getIdentityEntity(params);
         if (!identityEntity) {
@@ -170,7 +190,18 @@ class BaseEntityProcessor {
         });
         return entity;
     }
+    /**This will query for the entity, and handle post-processing
+     * of any critieria that is defined at the sub-type level.
+     * Because sub-type criteria can't be used in the search done
+     * on the server. This is expected to be called by getIncomingEntity().
+     *
+     * @param entityType: the root type of the entity
+     * @param entityTypePath: the full type path of the entity. Ex: custom-entity:sample
+     * @param propertyCriteria: all the criteria to search for the entity
+     * @returns the entities that match the criteria
+     */
     async queryEntityWithSubTypeCriteria(entityType, entityTypePath, propertyCriteria) {
+        //allCriteria; identifierKeys; entityType; entityTypePath
         if (!entityType || !entityTypePath) {
             throw new Error('type and entityTypePath must be defined');
         }
@@ -181,6 +212,15 @@ class BaseEntityProcessor {
         const returnedEntities = await this.dc.getAllObjectReferences(entityType, rootTypeCriteria, subTypeCriteria);
         return returnedEntities;
     }
+    /** This is to get the criteria for the entity that is being processed.
+     * This is to be overridden for item & project-item because of the need for
+     * setting the roles criteria.
+     *
+     * @param entityType: the root type of the entity
+     * @param entityTypePath: the full type path of the entity. Ex: custom-entity:sample
+     * @param propertyCriteria: all the criteria to search for the entity
+     * @returns the criteria for the entity
+     */
     async getCriteriaForEntity(entityType, entityTypePath, propertyCriteria) {
         if (!entityType || !entityTypePath) {
             throw new Error('type and entityTypePath must be defined');
@@ -205,6 +245,15 @@ class BaseEntityProcessor {
         }
         return { rootTypeCriteria, subTypeCriteria };
     }
+    /** This is to get the properties that are owned by the root type
+     * This needs to be overridded for multi-level types, such as item
+     * and project-item. And for those types, the propertyCriteria
+     * will be needed to determine the correct level.
+     *
+     * @param rootType: the full root type entity for the processed entity
+     * @param propertyCriteria: the criteria to determine the correct level (unused for single level types)
+     * @returns: string[] of the property keys
+     */
     getRootTypePropertyKeys(rootType, propertyCriteria = null) {
         const props = rootType['typeProperties'];
         const rootTypePropertyKeys = props.map(prop => prop.slug);
@@ -237,6 +286,8 @@ class BaseEntityProcessor {
     async getVibeOwningKeys(entity) {
         let vibeOwningKeys = [];
         if (this.transformMapFile && entity) {
+            //Technically the transform is flex->vibe.  But the vibe entity being updated was passed in,
+            // so we use VIBE2FLEX_DIRECTION to get the mapKey
             const mapKey = await type_conversion_utils_1.TypeConversionUtils.getMapKey(this.transformMapFile, this.mapFileUtil, entity, type_conversion_utils_1.TypeConversionUtils.VIBE2FLEX_DIRECTION);
             const mapSection = await map_utils_1.MapUtil.getFullMapSection(this.transformMapFile, this.mapFileUtil, mapKey);
             vibeOwningKeys = mapSection?.vibeOwningKeys || [];
@@ -271,6 +322,7 @@ class BaseEntityProcessor {
         console.log('updateEntity: ' + JSON.stringify(options));
         return await new sdk_1.Entities().update(options);
     }
+    // outbound
     async outbound(event) {
         const entityType = event.entityType;
         const eventType = event.eventType;
@@ -347,6 +399,13 @@ class BaseEntityProcessor {
     async handleOutgoingDelete(entityType, event) {
         console.warn('delete is not configured', entityType, event.oldData);
     }
+    /** Create a new event-workflow-request to rerun sending the entity to FlexPLM
+     * The event must contain any information needed to ensure it is put in the correct queue for the entity
+     *
+     * @param triggerKey Ex: event.entityType + '|sendUpsertToFlexPLM'
+     * @param event
+     * @returns
+     */
     async triggerNewEvent(triggerKey, event) {
         const newEvent = {
             entityName: 'event-workflow-request',
@@ -358,6 +417,12 @@ class BaseEntityProcessor {
         const response = await this.entities.create(newEvent);
         return response;
     }
+    /** Sends the current state of the entity to FlexPLM.
+     * So any changes made in Vibe between the event being generated and the event being processed are sent to FlexPLM.
+     *
+     * @param event must contain entityType, id; which are used to query for the entity
+     * @returns results of sending the entity to FlexPLM
+     */
     async sendUpsertToFlexPLM(event) {
         const payload = await this.getEntityCurrentStateUpsertPayload(event);
         if (!payload) {
@@ -398,6 +463,12 @@ class BaseEntityProcessor {
             throw e;
         }
     }
+    /** Generates the payload to send to FlexPLM, based on the current state of the entity.
+     * The current state of the entity are used as the newData and oldData; which is passed
+     * to getOutgoingUpsertPayload to generate the payload.
+     * @param event information about the item to send to FlexPLM
+     * @returns The payload to send to FlexPLM
+     */
     async getEntityCurrentStateUpsertPayload(event) {
         const id = event.id;
         if (!id) {

package/lib/entity-processor/base-entity-processor.spec.js

@@ -269,6 +269,7 @@ describe('BaseEntityProcessor', () => {
             const rootCriteriaResults = Object.assign({}, rootCriteria);
             const subCriteriaResults = Object.assign({}, subCriteria);
             const mockGetByRootTypeProperties = jest.spyOn(btep, 'getRootTypePropertyKeys').mockReturnValue(['rootText']);
+            // const mockDCgetAllObjectReferences = jest.spyOn(dc, 'getAllObjectReferences').mockReturnValue(Promise.resolve([]));
             const { rootTypeCriteria, subTypeCriteria } = await btep.getCriteriaForEntity(entityType, entityTypePath, propertyCriteria);
             expect(mockTypeUtilGetByRootAndPath).toBeCalledTimes(1);
             expect(mockTypeUtilGetByRootAndPath).toBeCalledWith({ root: entityType });

package/lib/index.d.ts

@@ -16,6 +16,7 @@ export * from './util/map-utils';
 export * from './interfaces/interfaces';
 export * from './interfaces/item-family-changes';
 export * from './interfaces/publish-change-data';
+export * from './interfaces/mapping-file';
 export * from './publish/base-process-publish-assortment';
 export * from './publish/base-process-publish-assortment-callback';
 export * from './entity-processor/base-entity-processor';

package/lib/index.js

@@ -32,6 +32,7 @@ __exportStar(require("./util/map-utils"), exports);
 __exportStar(require("./interfaces/interfaces"), exports);
 __exportStar(require("./interfaces/item-family-changes"), exports);
 __exportStar(require("./interfaces/publish-change-data"), exports);
+__exportStar(require("./interfaces/mapping-file"), exports);
 __exportStar(require("./publish/base-process-publish-assortment"), exports);
 __exportStar(require("./publish/base-process-publish-assortment-callback"), exports);
 __exportStar(require("./entity-processor/base-entity-processor"), exports);