@contrail/flexplm 1.3.1 → 1.3.2-alpha.30ca8bf

package/CHANGELOG.md

@@ -7,6 +7,10 @@ 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.
+
 ## [1.3.0] - 2026-04-15
 ### Added
 - Added inbound thumbnail/primary content syncing from FlexPLM to VibeIQ via `ThumbnailUtil.syncThumbnailToVibeIQ`.

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

@@ -19,6 +19,16 @@ 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;
+        propertyValue: string;
+    }): Promise<any | undefined>;
     queryEntityWithSubTypeCriteria(entityType: string, entityTypePath: string, propertyCriteria: any): Promise<any[]>;
     getCriteriaForEntity(entityType: string, entityTypePath: string, propertyCriteria: any): Promise<any>;
     getRootTypePropertyKeys(rootType: any, propertyCriteria?: any): string[];

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

@@ -136,6 +136,40 @@ class BaseEntityProcessor {
             + ', federatedId: ' + statusObject.federatedId
             + ', orgSlug: ' + this.orgSlug;
     }
+    async getIdentityEntity(params) {
+        const { poolKey, propertyName, propertyValue } = params;
+        if (!poolKey || !propertyName || !propertyValue) {
+            throw new Error('poolKey, propertyName, and propertyValue must be defined');
+        }
+        const identityEntities = await this.entities.get({
+            entityName: 'identity',
+            criteria: {
+                poolKey,
+                propertyName,
+                propertyValue
+            }
+        });
+        if (!identityEntities || (Array.isArray(identityEntities) && identityEntities.length === 0)) {
+            return undefined;
+        }
+        if (Array.isArray(identityEntities) && identityEntities.length > 1) {
+            throw new Error('Multiple identity entities found for poolKey: ' + poolKey + ', ' + propertyName + ': ' + propertyValue);
+        }
+        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({
+            entityName,
+            id
+        });
+        return entity;
+    }
     async queryEntityWithSubTypeCriteria(entityType, entityTypePath, propertyCriteria) {
         if (!entityType || !entityTypePath) {
             throw new Error('type and entityTypePath must be defined');

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

@@ -394,4 +394,195 @@ 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());
+        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.getEntityUsingIdentityService({
+                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.getEntityUsingIdentityService({
+                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.getEntityUsingIdentityService({
+                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.getEntityUsingIdentityService({
+                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.getEntityUsingIdentityService({
+                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.getEntityUsingIdentityService({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            })).rejects.toThrow('Multiple identity entities found for poolKey: item, itemNumber: 12345');
+        });
+        it('should return the entity when one identity entity is found (array)', async () => {
+            const mockEntity = { id: '1', name: 'Test Item' };
+            mockEntitiesGet
+                .mockResolvedValueOnce([{ entityReference: 'item:1' }])
+                .mockResolvedValueOnce(mockEntity);
+            const result = await btep.getEntityUsingIdentityService({
+                poolKey: 'item',
+                propertyName: 'itemNumber',
+                propertyValue: '12345'
+            });
+            expect(result).toEqual(mockEntity);
+            expect(mockEntitiesGet).toHaveBeenCalledTimes(2);
+            expect(mockEntitiesGet).toHaveBeenNthCalledWith(1, {
+                entityName: 'identity',
+                criteria: { poolKey: 'item', propertyName: 'itemNumber', propertyValue: '12345' }
+            });
+            expect(mockEntitiesGet).toHaveBeenNthCalledWith(2, {
+                entityName: 'item',
+                id: '1'
+            });
+        });
+        it('should return the entity when identity result is a single object (not array)', async () => {
+            const mockEntity = { id: '5', name: 'Test Material' };
+            mockEntitiesGet
+                .mockResolvedValueOnce({ entityReference: 'item:5' })
+                .mockResolvedValueOnce(mockEntity);
+            const result = await btep.getEntityUsingIdentityService({
+                poolKey: 'item:material',
+                propertyName: 'materialNumber',
+                propertyValue: 'MAT-001'
+            });
+            expect(result).toEqual(mockEntity);
+            expect(mockEntitiesGet).toHaveBeenNthCalledWith(2, {
+                entityName: 'item',
+                id: '5'
+            });
+        });
+    });
 });

package/lib/util/config-defaults.d.ts

@@ -4,5 +4,6 @@ export declare class ConfigDefaults {
     static STATIC_CONFIG_CACHE: {};
     static setConfigDefaults(config: any): Promise<FCConfig>;
     static getConfigFile(fileId: string): Promise<any>;
+    static isPropertyTrue(value: any): boolean;
     static clearConfigCache(): void;
 }

package/lib/util/config-defaults.js

@@ -76,6 +76,9 @@ class ConfigDefaults {
             return {};
         }
     }
+    static isPropertyTrue(value) {
+        return value === true || (typeof value === 'string' && value.toLowerCase() === 'true');
+    }
     static clearConfigCache() {
         ConfigDefaults.STATIC_CONFIG_CACHE = {};
     }

package/lib/util/config-defaults.spec.js

@@ -264,6 +264,38 @@ describe('all tests', () => {
             }
         });
     });
+    describe('isPropertyTrue', () => {
+        it('returns true for boolean true', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue(true)).toBe(true);
+        });
+        it('returns true for string true', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue('true')).toBe(true);
+        });
+        it('returns true for string TRUE', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue('TRUE')).toBe(true);
+        });
+        it('returns true for string True', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue('True')).toBe(true);
+        });
+        it('returns false for boolean false', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue(false)).toBe(false);
+        });
+        it('returns false for string false', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue('false')).toBe(false);
+        });
+        it('returns false for null', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue(null)).toBe(false);
+        });
+        it('returns false for undefined', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue(undefined)).toBe(false);
+        });
+        it('returns false for empty string', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue('')).toBe(false);
+        });
+        it('returns false for number 1', () => {
+            expect(config_defaults_1.ConfigDefaults.isPropertyTrue(1)).toBe(false);
+        });
+    });
     describe('getConfigFile', () => {
         beforeEach(() => {
             config_defaults_1.ConfigDefaults.clearConfigCache();

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.1",
+  "version": "1.3.2-alpha.30ca8bf",
   "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,4 +457,233 @@ 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());
+    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.getEntityUsingIdentityService({
+        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.getEntityUsingIdentityService({
+        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.getEntityUsingIdentityService({
+        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.getEntityUsingIdentityService({
+        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.getEntityUsingIdentityService({
+        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.getEntityUsingIdentityService({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      })).rejects.toThrow('Multiple identity entities found for poolKey: item, itemNumber: 12345');
+    });
+
+    it('should return the entity when one identity entity is found (array)', async () => {
+      const mockEntity = { id: '1', name: 'Test Item' };
+      mockEntitiesGet
+        .mockResolvedValueOnce([{ entityReference: 'item:1' }])
+        .mockResolvedValueOnce(mockEntity);
+
+      const result = await btep.getEntityUsingIdentityService({
+        poolKey: 'item',
+        propertyName: 'itemNumber',
+        propertyValue: '12345'
+      });
+
+      expect(result).toEqual(mockEntity);
+      expect(mockEntitiesGet).toHaveBeenCalledTimes(2);
+      expect(mockEntitiesGet).toHaveBeenNthCalledWith(1, {
+        entityName: 'identity',
+        criteria: { poolKey: 'item', propertyName: 'itemNumber', propertyValue: '12345' }
+      });
+      expect(mockEntitiesGet).toHaveBeenNthCalledWith(2, {
+        entityName: 'item',
+        id: '1'
+      });
+    });
+
+    it('should return the entity when identity result is a single object (not array)', async () => {
+      const mockEntity = { id: '5', name: 'Test Material' };
+      mockEntitiesGet
+        .mockResolvedValueOnce({ entityReference: 'item:5' })
+        .mockResolvedValueOnce(mockEntity);
+
+      const result = await btep.getEntityUsingIdentityService({
+        poolKey: 'item:material',
+        propertyName: 'materialNumber',
+        propertyValue: 'MAT-001'
+      });
+
+      expect(result).toEqual(mockEntity);
+      expect(mockEntitiesGet).toHaveBeenNthCalledWith(2, {
+        entityName: 'item',
+        id: '5'
+      });
+    });
+  });
+
 });

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

@@ -163,6 +163,74 @@ export abstract class BaseEntityProcessor {
     + ', 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: {
+    poolKey: string,
+    propertyName: string,
+    propertyValue: string
+  }): Promise<any | undefined> {
+    const {poolKey, propertyName, propertyValue} = params;
+    if(!poolKey || !propertyName || !propertyValue){
+      throw new Error('poolKey, propertyName, and propertyValue must be defined');
+    }
+
+    const identityEntities = await this.entities.get({
+      entityName: 'identity',
+      criteria: {
+        poolKey,
+        propertyName,
+        propertyValue
+      }
+    });
+
+    if(!identityEntities || (Array.isArray(identityEntities) && identityEntities.length === 0)){
+      return undefined;
+    }
+
+    if(Array.isArray(identityEntities) && identityEntities.length > 1){
+      throw new Error('Multiple identity entities found for poolKey: ' + poolKey + ', ' + propertyName + ': ' + propertyValue);
+    }
+
+    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(':');
+
+    const entity = await this.entities.get({
+      entityName,
+      id
+    });
+
+    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

package/src/util/config-defaults.spec.ts

@@ -314,6 +314,48 @@ describe('all tests', () => {
 
   });
 
+  describe('isPropertyTrue', () => {
+    it('returns true for boolean true', () => {
+      expect(ConfigDefaults.isPropertyTrue(true)).toBe(true);
+    });
+
+    it('returns true for string true', () => {
+      expect(ConfigDefaults.isPropertyTrue('true')).toBe(true);
+    });
+
+    it('returns true for string TRUE', () => {
+      expect(ConfigDefaults.isPropertyTrue('TRUE')).toBe(true);
+    });
+
+    it('returns true for string True', () => {
+      expect(ConfigDefaults.isPropertyTrue('True')).toBe(true);
+    });
+
+    it('returns false for boolean false', () => {
+      expect(ConfigDefaults.isPropertyTrue(false)).toBe(false);
+    });
+
+    it('returns false for string false', () => {
+      expect(ConfigDefaults.isPropertyTrue('false')).toBe(false);
+    });
+
+    it('returns false for null', () => {
+      expect(ConfigDefaults.isPropertyTrue(null)).toBe(false);
+    });
+
+    it('returns false for undefined', () => {
+      expect(ConfigDefaults.isPropertyTrue(undefined)).toBe(false);
+    });
+
+    it('returns false for empty string', () => {
+      expect(ConfigDefaults.isPropertyTrue('')).toBe(false);
+    });
+
+    it('returns false for number 1', () => {
+      expect(ConfigDefaults.isPropertyTrue(1)).toBe(false);
+    });
+  });
+
   describe('getConfigFile', () => {
     beforeEach(() => {
       ConfigDefaults.clearConfigCache();

package/src/util/config-defaults.ts

@@ -87,6 +87,10 @@ export class ConfigDefaults {
     }
   }
 
+  static isPropertyTrue(value: any): boolean {
+    return value === true || (typeof value === 'string' && value.toLowerCase() === 'true');
+  }
+
   static clearConfigCache(){
     ConfigDefaults.STATIC_CONFIG_CACHE = {};
   }

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'