@contrail/flexplm 1.3.2-alpha.328325d → 1.3.2-alpha.c32d413

package/CHANGELOG.md

@@ -7,6 +7,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.3.2] - 2026-04-24
 ### Added
 - Added `getEntityUsingIdentityService` method to `BaseEntityProcessor` for looking up entities via the identity service using a pool key and property criteria. Returns the resolved entity from the identity's `entityReference`, `undefined` if not found, or throws if multiple matches exist.
 

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

@@ -19,6 +19,11 @@ export declare abstract class BaseEntityProcessor {
     inbound(event: EntityPayloadType): Promise<any>;
     handleIncomingUpsert(event: EntityPayloadType): Promise<any>;
     getInboundStatusMessage(statusObject: any): string;
+    getIdentityEntity(params: {
+        poolKey: string;
+        propertyName: string;
+        propertyValue: string;
+    }): Promise<any | undefined>;
     getEntityUsingIdentityService(params: {
         poolKey: string;
         propertyName: string;

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

@@ -136,7 +136,7 @@ class BaseEntityProcessor {
             + ', federatedId: ' + statusObject.federatedId
             + ', orgSlug: ' + this.orgSlug;
     }
-    async getEntityUsingIdentityService(params) {
+    async getIdentityEntity(params) {
         const { poolKey, propertyName, propertyValue } = params;
         if (!poolKey || !propertyName || !propertyValue) {
             throw new Error('poolKey, propertyName, and propertyValue must be defined');
@@ -155,7 +155,13 @@ class BaseEntityProcessor {
         if (Array.isArray(identityEntities) && identityEntities.length > 1) {
             throw new Error('Multiple identity entities found for poolKey: ' + poolKey + ', ' + propertyName + ': ' + propertyValue);
         }
-        const identityEntity = Array.isArray(identityEntities) ? identityEntities[0] : identityEntities;
+        return Array.isArray(identityEntities) ? identityEntities[0] : identityEntities;
+    }
+    async getEntityUsingIdentityService(params) {
+        const identityEntity = await this.getIdentityEntity(params);
+        if (!identityEntity) {
+            return undefined;
+        }
         const entityReference = identityEntity.entityReference;
         const [entityName, id] = entityReference.split(':');
         const entity = await this.entities.get({

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

@@ -394,6 +394,94 @@ describe('BaseEntityProcessor', () => {
             expect(result).toEqual({ status: 200, data: { message: 'No Changes to persist for entity: existing-1' } });
         });
     });
+    describe('getIdentityEntity', () => {
+        const config = {};
+        const mapFileUtil = new transform_data_1.MapFileUtil(new sdk_1.Entities());
+        const dc = new data_converter_1.DataConverter(config, mapFileUtil);
+        let btep;
+        let mockEntitiesGet;
+        beforeEach(() => {
+            btep = new TestBaseEntityProcessor(config, dc, mapFileUtil, 'item');
+            mockEntitiesGet = jest.fn();
+            btep.entities = { get: mockEntitiesGet };
+        });
+        it('should throw error when poolKey is missing', async () => {
+            await expect(btep.getIdentityEntity({
+                poolKey: '',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            })).rejects.toThrow('poolKey, propertyName, and propertyValue must be defined');
+        });
+        it('should throw error when propertyName is missing', async () => {
+            await expect(btep.getIdentityEntity({
+                poolKey: 'item',
+                propertyName: '',
+                propertyValue: '12345'
+            })).rejects.toThrow('poolKey, propertyName, and propertyValue must be defined');
+        });
+        it('should throw error when propertyValue is missing', async () => {
+            await expect(btep.getIdentityEntity({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: ''
+            })).rejects.toThrow('poolKey, propertyName, and propertyValue must be defined');
+        });
+        it('should return undefined when no identity entities are found (empty array)', async () => {
+            mockEntitiesGet.mockResolvedValue([]);
+            const result = await btep.getIdentityEntity({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            });
+            expect(result).toBeUndefined();
+            expect(mockEntitiesGet).toHaveBeenCalledWith({
+                entityName: 'identity',
+                criteria: { poolKey: 'item', propertyName: 'itemNumber', propertyValue: '12345' }
+            });
+        });
+        it('should return undefined when identity entities result is null', async () => {
+            mockEntitiesGet.mockResolvedValue(null);
+            const result = await btep.getIdentityEntity({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            });
+            expect(result).toBeUndefined();
+        });
+        it('should throw error when multiple identity entities are found', async () => {
+            mockEntitiesGet.mockResolvedValue([
+                { entityReference: 'item:1' },
+                { entityReference: 'item:2' }
+            ]);
+            await expect(btep.getIdentityEntity({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            })).rejects.toThrow('Multiple identity entities found for poolKey: item, itemNumber: 12345');
+        });
+        it('should return the identity entity when one is found (array)', async () => {
+            const identityEntity = { entityReference: 'item:1' };
+            mockEntitiesGet.mockResolvedValue([identityEntity]);
+            const result = await btep.getIdentityEntity({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            });
+            expect(result).toEqual(identityEntity);
+            expect(mockEntitiesGet).toHaveBeenCalledTimes(1);
+        });
+        it('should return the identity entity when result is a single object (not array)', async () => {
+            const identityEntity = { entityReference: 'item:5' };
+            mockEntitiesGet.mockResolvedValue(identityEntity);
+            const result = await btep.getIdentityEntity({
+                poolKey: 'item:material',
+                propertyName: 'materialNumber',
+                propertyValue: 'MAT-001'
+            });
+            expect(result).toEqual(identityEntity);
+            expect(mockEntitiesGet).toHaveBeenCalledTimes(1);
+        });
+    });
     describe('getEntityUsingIdentityService', () => {
         const config = {};
         const mapFileUtil = new transform_data_1.MapFileUtil(new sdk_1.Entities());

package/lib/util/type-conversion-utils-spec-mockData.js

@@ -207,6 +207,7 @@ exports.mapping = {
         }
     },
     catName: {
+        uniquenessPool: 'catName-pool',
         getIdentifierProperties: () => ['catName', 'catNumber'],
         getInformationalProperties: () => ['longName'],
         vibe2flex: {

package/lib/util/type-conversion-utils.d.ts

@@ -11,6 +11,7 @@ export declare class TypeConversionUtils {
     static getMapKey(transformMapFile: any, mapFileUtil: MapFileUtil, entity: any, direction: string): Promise<string>;
     static getEntityType(entity: any): any;
     static getEntityClassFromObject(fileId: any, mapFileUtil: any, object: any): Promise<string>;
+    static getUniquenessPoolKeyFromObject(fileId: any, mapFileUtil: any, object: any): Promise<string>;
     static getEntityTypePathFromOjbect(fileId: any, mapFileUtil: any, object: any): Promise<string>;
     static getIdentifierPropertiesFromObject(fileId: any, mapFileUtil: MapFileUtil, object: any): Promise<string[]>;
     static getInformationalPropertiesFromObject(fileId: any, mapFileUtil: MapFileUtil, object: any): Promise<string[]>;

package/lib/util/type-conversion-utils.js

@@ -118,6 +118,22 @@ class TypeConversionUtils {
         }
         return type_defaults_1.TypeDefaults.getDefaultEntityClass(object);
     }
+    static async getUniquenessPoolKeyFromObject(fileId, mapFileUtil, object) {
+        let uniquenessPool;
+        if (fileId) {
+            const mapKey = await this.getMapKeyFromObject(fileId, mapFileUtil, object, TypeConversionUtils.FLEX2VIBE_DIRECTION);
+            if (mapKey) {
+                const mapData = await map_utils_1.MapUtil.getFullMapSection(fileId, mapFileUtil, mapKey);
+                if (mapData && mapData['uniquenessPool']) {
+                    uniquenessPool = mapData['uniquenessPool'];
+                }
+            }
+        }
+        if (uniquenessPool) {
+            return uniquenessPool;
+        }
+        return type_defaults_1.TypeDefaults.getDefaultEntityClass(object);
+    }
     static async getEntityTypePathFromOjbect(fileId, mapFileUtil, object) {
         let typePath = object['vibeIQTypePath'];
         if (typePath) {

package/lib/util/type-conversion-utils.spec.js

@@ -328,6 +328,65 @@ describe('conversion-utils', () => {
             }
         });
     });
+    describe('getUniquenessPoolKeyFromObject', () => {
+        const mapFileUtil = new transform_data_1.MapFileUtil(new sdk_1.Entities());
+        it('uses mapping-catName', async () => {
+            const expectedPool = 'catName-pool';
+            const object = {
+                flexPLMObjectClass: 'LCSLast',
+                flexPLMTypePath: 'Last\\catName'
+            };
+            const spy = jest.spyOn(mapFileUtil, 'getMapFile')
+                .mockImplementation(async () => {
+                return mapping;
+            });
+            try {
+                const results = await type_conversion_utils_1.TypeConversionUtils.getUniquenessPoolKeyFromObject(TRANSFORM_MAP_FILE, mapFileUtil, object);
+                expect(results).toEqual(expectedPool);
+            }
+            finally {
+                spy.mockRestore();
+            }
+        });
+        it('uses default-noMap', async () => {
+            const expectedClass = 'color';
+            const object = {
+                flexPLMObjectClass: 'LCSColor',
+                flexPLMTypePath: 'Color'
+            };
+            const spy = jest.spyOn(mapFileUtil, 'getMapFile')
+                .mockImplementation(async () => {
+                return mapping;
+            });
+            const spyDefaults = jest.spyOn(type_defaults_1.TypeDefaults, 'getDefaultEntityClass')
+                .mockImplementation(() => expectedClass);
+            try {
+                const results = await type_conversion_utils_1.TypeConversionUtils.getUniquenessPoolKeyFromObject(TRANSFORM_MAP_FILE, mapFileUtil, object);
+                expect(results).toEqual(expectedClass);
+                expect(spyDefaults).toBeCalledTimes(1);
+            }
+            finally {
+                spy.mockRestore();
+                spyDefaults.mockRestore();
+            }
+        });
+        it('uses default-noFileId', async () => {
+            const expectedClass = 'color';
+            const object = {
+                flexPLMObjectClass: 'LCSColor',
+            };
+            const spyDefaults = jest.spyOn(type_defaults_1.TypeDefaults, 'getDefaultEntityClass')
+                .mockImplementation(() => expectedClass);
+            try {
+                const results = await type_conversion_utils_1.TypeConversionUtils.getUniquenessPoolKeyFromObject(null, mapFileUtil, object);
+                expect(results).toEqual(expectedClass);
+                expect(spyDefaults).toBeCalledTimes(1);
+            }
+            finally {
+                spyDefaults.mockRestore();
+            }
+        });
+    });
     describe('getEntityTypePathFromOjbect', () => {
         const mapFileUtil = new transform_data_1.MapFileUtil(new sdk_1.Entities());
         it('vibeIQTypePath', async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/flexplm",
-  "version": "1.3.2-alpha.328325d",
+  "version": "1.3.2-alpha.c32d413",
   "description": "Library used for integration with flexplm.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/entity-processor/base-entity-processor.spec.ts

@@ -457,6 +457,113 @@ describe('BaseEntityProcessor', () =>{
     });
   });
 
+  describe('getIdentityEntity', () => {
+    const config = {} as FCConfig;
+    const mapFileUtil = new MapFileUtil(new Entities());
+    const dc = new DataConverter(config, mapFileUtil);
+    let btep: TestBaseEntityProcessor;
+    let mockEntitiesGet: jest.Mock;
+
+    beforeEach(() => {
+      btep = new TestBaseEntityProcessor(config, dc, mapFileUtil, 'item');
+      mockEntitiesGet = jest.fn();
+      (btep as any).entities = { get: mockEntitiesGet };
+    });
+
+    it('should throw error when poolKey is missing', async () => {
+      await expect(btep.getIdentityEntity({
+        poolKey: '',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      })).rejects.toThrow('poolKey, propertyName, and propertyValue must be defined');
+    });
+
+    it('should throw error when propertyName is missing', async () => {
+      await expect(btep.getIdentityEntity({
+        poolKey: 'item',
+        propertyName: '',
+        propertyValue: '12345'
+      })).rejects.toThrow('poolKey, propertyName, and propertyValue must be defined');
+    });
+
+    it('should throw error when propertyValue is missing', async () => {
+      await expect(btep.getIdentityEntity({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: ''
+      })).rejects.toThrow('poolKey, propertyName, and propertyValue must be defined');
+    });
+
+    it('should return undefined when no identity entities are found (empty array)', async () => {
+      mockEntitiesGet.mockResolvedValue([]);
+
+      const result = await btep.getIdentityEntity({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      });
+
+      expect(result).toBeUndefined();
+      expect(mockEntitiesGet).toHaveBeenCalledWith({
+        entityName: 'identity',
+        criteria: { poolKey: 'item', propertyName: 'itemNumber', propertyValue: '12345' }
+      });
+    });
+
+    it('should return undefined when identity entities result is null', async () => {
+      mockEntitiesGet.mockResolvedValue(null);
+
+      const result = await btep.getIdentityEntity({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      });
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should throw error when multiple identity entities are found', async () => {
+      mockEntitiesGet.mockResolvedValue([
+        { entityReference: 'item:1' },
+        { entityReference: 'item:2' }
+      ]);
+
+      await expect(btep.getIdentityEntity({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      })).rejects.toThrow('Multiple identity entities found for poolKey: item, itemNumber: 12345');
+    });
+
+    it('should return the identity entity when one is found (array)', async () => {
+      const identityEntity = { entityReference: 'item:1' };
+      mockEntitiesGet.mockResolvedValue([identityEntity]);
+
+      const result = await btep.getIdentityEntity({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      });
+
+      expect(result).toEqual(identityEntity);
+      expect(mockEntitiesGet).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return the identity entity when result is a single object (not array)', async () => {
+      const identityEntity = { entityReference: 'item:5' };
+      mockEntitiesGet.mockResolvedValue(identityEntity);
+
+      const result = await btep.getIdentityEntity({
+        poolKey: 'item:material',
+        propertyName: 'materialNumber',
+        propertyValue: 'MAT-001'
+      });
+
+      expect(result).toEqual(identityEntity);
+      expect(mockEntitiesGet).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('getEntityUsingIdentityService', () => {
     const config = {} as FCConfig;
     const mapFileUtil = new MapFileUtil(new Entities());

package/src/entity-processor/base-entity-processor.ts

@@ -163,19 +163,16 @@ export abstract class BaseEntityProcessor {
     + ', orgSlug: ' + this.orgSlug;
   }
 
-  /** This function is to get the entity using the identity service based on the passed in criteria.
-   *  If no entity is found, it will return undefined. If multiple entities are found, it will throw an error.
-   * The criteria is expected to be based on the identifier properties defined in the transformMapFile for the entity,
-   *  but it can be any criteria.
-   * If not all parameters needed for the criteria are present, it will throw an error.
+  /** 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. The default poolKey is the entityType. Ex: 'item' or 'item:material'
+   * @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'
-   * @return the entity that is found based on the criteria, or undefined if no entity is found
-   * @throws error if multiple entities are found based on the criteria
+   * @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 getEntityUsingIdentityService(params :{
+  async getIdentityEntity(params: {
     poolKey: string,
     propertyName: string,
     propertyValue: string
@@ -202,7 +199,28 @@ export abstract class BaseEntityProcessor {
       throw new Error('Multiple identity entities found for poolKey: ' + poolKey + ', ' + propertyName + ': ' + propertyValue);
     }
 
-    const identityEntity = Array.isArray(identityEntities) ? identityEntities[0] : identityEntities;
+    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: {
+    poolKey: string,
+    propertyName: string,
+    propertyValue: string
+  }): Promise<any | undefined> {
+    const identityEntity = await this.getIdentityEntity(params);
+    if(!identityEntity){
+      return undefined;
+    }
+
     const entityReference = identityEntity.entityReference;
     const [entityName, id] = entityReference.split(':');
 

package/src/util/type-conversion-utils-spec-mockData.ts

@@ -214,6 +214,7 @@ exports.mapping = {
     }
   },
   catName: {
+  uniquenessPool: 'catName-pool',
   getIdentifierProperties: () => ['catName', 'catNumber'],
   getInformationalProperties: () => ['longName'],
   vibe2flex: {

package/src/util/type-conversion-utils.spec.ts

@@ -360,6 +360,69 @@ describe('conversion-utils', () => {
     });
   });
 
+  describe('getUniquenessPoolKeyFromObject', () =>{
+    const mapFileUtil = new MapFileUtil(new Entities());
+
+    it('uses mapping-catName', async () =>{
+      const expectedPool = 'catName-pool';
+      const object = {
+        flexPLMObjectClass: 'LCSLast',
+        flexPLMTypePath: 'Last\\catName'
+      };
+      const spy = jest.spyOn(mapFileUtil, 'getMapFile')
+        .mockImplementation(async () =>{
+          return mapping;
+        });
+      try{
+        const results = await TypeConversionUtils.getUniquenessPoolKeyFromObject(TRANSFORM_MAP_FILE, mapFileUtil, object);
+        expect(results).toEqual(expectedPool);
+
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it('uses default-noMap', async () =>{
+      const expectedClass = 'color';
+      const object = {
+        flexPLMObjectClass: 'LCSColor',
+        flexPLMTypePath: 'Color'
+      };
+      const spy = jest.spyOn(mapFileUtil, 'getMapFile')
+        .mockImplementation(async () =>{
+          return mapping;
+        });
+      const spyDefaults = jest.spyOn(TypeDefaults, 'getDefaultEntityClass')
+        .mockImplementation(() => expectedClass);
+      try{
+        const results = await TypeConversionUtils.getUniquenessPoolKeyFromObject(TRANSFORM_MAP_FILE, mapFileUtil, object);
+        expect(results).toEqual(expectedClass);
+        expect(spyDefaults).toBeCalledTimes(1);
+
+      } finally {
+        spy.mockRestore();
+        spyDefaults.mockRestore();
+      }
+    });
+
+    it('uses default-noFileId', async () =>{
+      const expectedClass = 'color';
+      const object = {
+        flexPLMObjectClass: 'LCSColor',
+      };
+      const spyDefaults = jest.spyOn(TypeDefaults, 'getDefaultEntityClass')
+        .mockImplementation(() => expectedClass);
+      try{
+        const results = await TypeConversionUtils.getUniquenessPoolKeyFromObject(null, mapFileUtil, object);
+        expect(results).toEqual(expectedClass);
+        expect(spyDefaults).toBeCalledTimes(1);
+
+      } finally {
+        spyDefaults.mockRestore();
+      }
+    });
+  });
+
   describe('getEntityTypePathFromOjbect', () =>{
     const mapFileUtil = new MapFileUtil(new Entities());
 

package/src/util/type-conversion-utils.ts

@@ -224,6 +224,36 @@ export class TypeConversionUtils {
     return TypeDefaults.getDefaultEntityClass(object);
   }
 
+  /** Takes in a FlexPLM object and returns the correct VibeIQ uniqueness
+   * pool key. Order of precedence:
+   * Map file entry in 'typeConversion:flex2vibe:<value>:getUniquenessPool()'
+   *  for value from 'objectClass'
+   * TypeDefaults.getDefaultEntityClass() function
+   *
+   * @param fileId id for mapFile
+   * @param mapFileUtil class to get mapfile
+   * @param object FlexPLM object
+   * @returns Promise<string>
+   */
+  static async getUniquenessPoolKeyFromObject(fileId, mapFileUtil, object): Promise<string>{
+    let uniquenessPool;
+
+    if(fileId){
+      const mapKey = await this.getMapKeyFromObject(fileId, mapFileUtil, object, TypeConversionUtils.FLEX2VIBE_DIRECTION);
+      if(mapKey){
+        const mapData = await MapUtil.getFullMapSection(fileId, mapFileUtil, mapKey);
+        if(mapData && mapData['uniquenessPool']){
+          uniquenessPool = mapData['uniquenessPool'];
+        }
+      }
+    }
+
+    if(uniquenessPool){
+      return uniquenessPool;
+    }
+    return TypeDefaults.getDefaultEntityClass(object);
+  }
+
     /** Takes in a FlexPLM object and returns the correct VibeIQ
    * type associated to the object. Order of precedence
    * Property 'vibeIQTypePath'