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

package/CHANGELOG.md

@@ -7,6 +7,9 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### 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,11 @@ export declare abstract class BaseEntityProcessor {
     inbound(event: EntityPayloadType): Promise<any>;
     handleIncomingUpsert(event: EntityPayloadType): Promise<any>;
     getInboundStatusMessage(statusObject: any): string;
+    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,34 @@ class BaseEntityProcessor {
             + ', federatedId: ' + statusObject.federatedId
             + ', orgSlug: ' + this.orgSlug;
     }
+    async getEntityUsingIdentityService(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);
+        }
+        const identityEntity = Array.isArray(identityEntities) ? identityEntities[0] : identityEntities;
+        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,107 @@ describe('BaseEntityProcessor', () => {
             expect(result).toEqual({ status: 200, data: { message: 'No Changes to persist for entity: existing-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/flexplm",
-  "version": "1.3.1",
+  "version": "1.3.2-alpha.328325d",
   "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,126 @@ describe('BaseEntityProcessor', () =>{
     });
   });
 
+  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,56 @@ 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.
+   *
+   * @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.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
+   */
+  async getEntityUsingIdentityService(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);
+    }
+
+    const identityEntity = Array.isArray(identityEntities) ? identityEntities[0] : identityEntities;
+    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