@contrail/flexplm 1.5.0-alpha.6d9ffc4 → 1.5.0-alpha.aaef470

package/CHANGELOG.md

@@ -8,6 +8,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 ### Added
 - Added support for Inbound `LCSMaterial` to sync to the entity class `item` with type path `item:material` and `itemNumber` as identifier.  This is controlled by an `LCSMaterial.processAsItem` (default `false`) config default.
+- Added optional identity-service lookup in `DataConverter.setObjectReferenceValue` for resolving inbound `object_reference` values. Enabled per referenced entity type via `config.search.<entityType>.useIdentityServiceForInboundData`. When enabled the reference is resolved via the identity service using a uniqueness pool key; otherwise behavior falls through to the existing `getAllObjectReferences` query path.
 
 ## [1.4.0] - 2026-05-06
 ### Added

package/lib/util/data-converter.d.ts

@@ -28,6 +28,11 @@ export declare class DataConverter {
     setEnumerationKeys(prop: any, nd: any, matchByDisplay: any): any;
     getPersistableChanges(entity: object, changes: object): object;
     setObjectReferenceValue(prop: any, nd: any): Promise<any>;
+    private applyInboundTransformMap;
+    private buildObjectReferenceContext;
+    private lookupObjectReferenceViaIdentityService;
+    private lookupObjectReferenceViaQuery;
+    private assertSingleObjectReference;
     getAllObjectReferences(entityType: string, rootTypeCriteria: any, postProcessCriteria?: any): Promise<any[]>;
     checkKeysAndValues(criteria: any, arrayOfObjects: any, entityTypePath: any): any[];
     filterOutArchivedAndTrashedEntities(entities: any[]): any[];

package/lib/util/data-converter.js

@@ -7,6 +7,7 @@ const app_framework_1 = require("@contrail/app-framework");
 const util_1 = require("@contrail/util");
 const type_conversion_utils_1 = require("./type-conversion-utils");
 const map_utils_1 = require("./map-utils");
+const config_defaults_1 = require("./config-defaults");
 class DataConverter {
     static clearStaticUserCache() {
         DataConverter.staticUserCache = {};
@@ -347,30 +348,51 @@ class DataConverter {
         return diffValues;
     }
     async setObjectReferenceValue(prop, nd) {
-        let objectReferenceId = "";
         if (!nd) {
-            return objectReferenceId;
+            return "";
+        }
+        nd = await this.applyInboundTransformMap(nd);
+        const ctx = await this.buildObjectReferenceContext(prop, nd);
+        if (!ctx) {
+            return "";
+        }
+        if (this.objRefCache[ctx.cacheKey]) {
+            if (app_framework_1.Logger.isDebugOn()) {
+                console.debug(`object reference cache hit: ${ctx.cacheKey}`);
+            }
+            return this.objRefCache[ctx.cacheKey];
         }
-        if (this.transformMapFile) {
-            const mapKey = await type_conversion_utils_1.TypeConversionUtils.getMapKeyFromObject(this.transformMapFile, this.mapFileUtil, nd, type_conversion_utils_1.TypeConversionUtils.FLEX2VIBE_DIRECTION);
-            nd = await map_utils_1.MapUtil.applyTransformMap(this.transformMapFile, this.mapFileUtil, nd, mapKey, type_conversion_utils_1.TypeConversionUtils.FLEX2VIBE_DIRECTION);
+        const objectReferenceId = ctx.useIdentityService
+            ? await this.lookupObjectReferenceViaIdentityService(ctx, nd)
+            : await this.lookupObjectReferenceViaQuery(ctx);
+        if (objectReferenceId) {
+            this.objRefCache[ctx.cacheKey] = objectReferenceId;
         }
+        return objectReferenceId;
+    }
+    async applyInboundTransformMap(nd) {
+        if (!this.transformMapFile) {
+            return nd;
+        }
+        const mapKey = await type_conversion_utils_1.TypeConversionUtils.getMapKeyFromObject(this.transformMapFile, this.mapFileUtil, nd, type_conversion_utils_1.TypeConversionUtils.FLEX2VIBE_DIRECTION);
+        return map_utils_1.MapUtil.applyTransformMap(this.transformMapFile, this.mapFileUtil, nd, mapKey, type_conversion_utils_1.TypeConversionUtils.FLEX2VIBE_DIRECTION);
+    }
+    async buildObjectReferenceContext(prop, nd) {
         const entityType = prop['referencedTypeRootSlug'];
         const entityTypePath = prop['referencedTypePath'];
         const entityKeys = Object.keys(nd);
         const identifierKeys = await type_conversion_utils_1.TypeConversionUtils.getIdentifierPropertiesFromObject(this.transformMapFile, this.mapFileUtil, nd);
         const hasAllIdentifiers = identifierKeys.every(key => entityKeys.includes(key));
-        if (identifierKeys.length == 0 || !hasAllIdentifiers) {
+        if (identifierKeys.length === 0 || !hasAllIdentifiers) {
             console.warn(`The inbound ${entityType} for prop '${prop['slug']}' doesnt have all "identifier" properties, so there is no processing. Identifier properties: ${identifierKeys}`);
-            return objectReferenceId;
+            return null;
         }
         const rootType = await this.typeUtils.getByRootAndPath({ root: entityType });
         const rootTypeProps = this.typeUtils.filterTypeProperties(rootType, nd);
-        let rootTypeCriteria = {};
-        let typeCriteria = {};
+        const rootTypeCriteria = {};
+        const typeCriteria = {};
         identifierKeys.forEach(keyName => {
-            const foundInObjects = rootTypeProps.some(obj => obj.slug === keyName);
-            if (foundInObjects) {
+            if (rootTypeProps.some(obj => obj.slug === keyName)) {
                 rootTypeCriteria[keyName] = nd[keyName];
             }
             else {
@@ -379,30 +401,41 @@ class DataConverter {
         });
         const combinedCriteria = { ...rootTypeCriteria, ...typeCriteria, typePath: entityTypePath };
         const cacheKey = Object.values(combinedCriteria).join('_');
-        if (this.objRefCache[cacheKey]) {
-            if (app_framework_1.Logger.isDebugOn()) {
-                console.debug(`object reference cache hit: ${cacheKey}`);
-            }
-            return this.objRefCache[cacheKey];
-        }
-        let arrObjectReferences = await this.getAllObjectReferences(entityType, rootTypeCriteria);
-        if (entityType !== entityTypePath) {
-            arrObjectReferences = this.checkKeysAndValues(typeCriteria, arrObjectReferences, entityTypePath);
-        }
-        if (arrObjectReferences.length) {
-            if (arrObjectReferences.length === 1) {
-                objectReferenceId = arrObjectReferences[0].id;
-            }
-            else {
-                console.warn(`The passed in object reference criteria has duplicate records found ${JSON.stringify(combinedCriteria)}.`);
-            }
+        const rolesIsTypeDiscriminator = entityType === 'item' || entityType === 'project-item';
+        const identityLookupKeys = rolesIsTypeDiscriminator
+            ? identifierKeys.filter(key => key !== 'roles')
+            : identifierKeys;
+        const useIdentityService = config_defaults_1.ConfigDefaults.isPropertyTrue(this.config?.search?.[entityType]?.useIdentityServiceForInboundData)
+            && identityLookupKeys.length === 1;
+        return { entityType, entityTypePath, rootTypeCriteria, typeCriteria, combinedCriteria, cacheKey, useIdentityService, identityLookupKeys };
+    }
+    async lookupObjectReferenceViaIdentityService(ctx, nd) {
+        const propertyName = ctx.identityLookupKeys[0];
+        const propertyValue = nd[propertyName];
+        const poolKey = await type_conversion_utils_1.TypeConversionUtils.getUniquenessPoolKeyFromObject(this.transformMapFile, this.mapFileUtil, nd);
+        const identityResults = await new sdk_1.Entities().get({
+            entityName: 'identity',
+            criteria: { poolKey, propertyName, propertyValue }
+        }) ?? [];
+        return this.assertSingleObjectReference(identityResults, ctx.combinedCriteria, (r) => r.entityReference.split(':')[1]);
+    }
+    async lookupObjectReferenceViaQuery(ctx) {
+        let arrObjectReferences = await this.getAllObjectReferences(ctx.entityType, ctx.rootTypeCriteria);
+        if (ctx.entityType !== ctx.entityTypePath) {
+            arrObjectReferences = this.checkKeysAndValues(ctx.typeCriteria, arrObjectReferences, ctx.entityTypePath);
         }
-        if (!objectReferenceId) {
+        return this.assertSingleObjectReference(arrObjectReferences, ctx.combinedCriteria, (r) => r.id);
+    }
+    assertSingleObjectReference(results, combinedCriteria, getId) {
+        if (!results.length) {
             console.warn(`The passed in object reference criteria ${JSON.stringify(combinedCriteria)} didn't match any entities.`);
-            return objectReferenceId;
+            return "";
         }
-        this.objRefCache[cacheKey] = objectReferenceId;
-        return objectReferenceId;
+        if (results.length > 1) {
+            console.warn(`The passed in object reference criteria has duplicate records found ${JSON.stringify(combinedCriteria)}.`);
+            return "";
+        }
+        return getId(results[0]);
     }
     async getAllObjectReferences(entityType, rootTypeCriteria, postProcessCriteria = null) {
         const entities = new sdk_1.Entities();

package/lib/util/data-converter.spec.js

@@ -454,6 +454,393 @@ describe('getObjectReferenceValue bad value', () => {
         }
     });
 });
+describe('setObjectReferenceValue - identity service', () => {
+    const baseConfig = () => ({
+        apiHost: 'host',
+        userName: () => 'user',
+        password: () => 'pass',
+        urlContext: 'xxx',
+        vibeEventEndpoint: '/rfa/vibeiq/vibeEvents',
+        csrfEndpoint: '/servlet/rest/security/csrf',
+        itemPreDevelopmentLifecycleStages: ['concept']
+    });
+    const refProp = {
+        id: 'cJoZQvoj7dkfCBJq',
+        propertyType: 'object_reference',
+        slug: 'material',
+        label: 'Material',
+        referencedTypeRootSlug: 'item',
+        referencedTypePath: 'item:material'
+    };
+    let identifierSpy;
+    let poolKeySpy;
+    let getByRootAndPathSpy;
+    let filterTypePropertiesSpy;
+    const setupTypeUtilsSpies = (dc, rootPropSlugs = ['itemNumber']) => {
+        getByRootAndPathSpy = jest.spyOn(dc['typeUtils'], 'getByRootAndPath')
+            .mockImplementation(async () => ({ typePath: 'item', typeProperties: [] }));
+        filterTypePropertiesSpy = jest.spyOn(dc['typeUtils'], 'filterTypeProperties')
+            .mockImplementation(() => rootPropSlugs.map(slug => ({ slug })));
+    };
+    afterEach(() => {
+        identifierSpy?.mockRestore();
+        poolKeySpy?.mockRestore();
+        getByRootAndPathSpy?.mockRestore();
+        filterTypePropertiesSpy?.mockRestore();
+        mockGetFunction.mockReset();
+        mockGetFunction.mockImplementation((options) => ((options?.criteria?.id === 1234) ? [mockObj1234] : [mockObj2222]));
+    });
+    it('flag off - uses getAllObjectReferences path', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'abc123', typePath: 'item:material' }]);
+        const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+        const result = await dc.setObjectReferenceValue(refProp, nd);
+        expect(mockGetFunction).toHaveBeenCalled();
+        const callArg = mockGetFunction.mock.calls[0][0];
+        expect(callArg.entityName).toEqual('item');
+        expect(callArg.entityName).not.toEqual('identity');
+        expect(result).toEqual('abc123');
+        expect(poolKeySpy).not.toHaveBeenCalled();
+    });
+    it('flag on, single identity match - returns parsed id', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ entityReference: 'item:abc123' }]);
+        const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+        const result = await dc.setObjectReferenceValue(refProp, nd);
+        expect(mockGetFunction).toHaveBeenCalledTimes(1);
+        const callArg = mockGetFunction.mock.calls[0][0];
+        expect(callArg.entityName).toEqual('identity');
+        expect(callArg.criteria).toEqual({
+            poolKey: 'item:material',
+            propertyName: 'itemNumber',
+            propertyValue: 'MAT-100'
+        });
+        expect(result).toEqual('abc123');
+    });
+    it('flag on, no identity match - returns empty and warns', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => []);
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        const getAllSpy = jest.spyOn(dc, 'getAllObjectReferences');
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+            expect(result).toEqual('');
+            expect(warnSpy).toHaveBeenCalled();
+            expect(getAllSpy).not.toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+            getAllSpy.mockRestore();
+        }
+    });
+    it('flag on, multiple identity matches - returns empty and does not throw', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [
+            { entityReference: 'item:abc123' },
+            { entityReference: 'item:def456' }
+        ]);
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+            expect(result).toEqual('');
+            expect(warnSpy).toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it('flag on, ambiguous identifier set - falls back to getAllObjectReferences', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber', 'season', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'season', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'abc123', typePath: 'item:material' }]);
+        const nd = { itemNumber: 'MAT-100', season: 'SS24', roles: ['family'] };
+        const result = await dc.setObjectReferenceValue(refProp, nd);
+        expect(mockGetFunction).toHaveBeenCalled();
+        const callArg = mockGetFunction.mock.calls[0][0];
+        expect(callArg.entityName).toEqual('item');
+        expect(callArg.entityName).not.toEqual('identity');
+        expect(result).toEqual('abc123');
+        expect(poolKeySpy).not.toHaveBeenCalled();
+    });
+    it('flag on, cache hit - second call short-circuits', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ entityReference: 'item:abc123' }]);
+        const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+        const r1 = await dc.setObjectReferenceValue(refProp, nd);
+        const r2 = await dc.setObjectReferenceValue(refProp, nd);
+        expect(r1).toEqual('abc123');
+        expect(r2).toEqual('abc123');
+        expect(mockGetFunction).toHaveBeenCalledTimes(1);
+    });
+    it('flag on, project-item entityType - roles is filtered, identity path used', async () => {
+        const projectItemProp = {
+            ...refProp,
+            referencedTypeRootSlug: 'project-item',
+            referencedTypePath: 'project-item'
+        };
+        const config = baseConfig();
+        config.search = { 'project-item': { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'project-item');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ entityReference: 'project-item:pi-789' }]);
+        const result = await dc.setObjectReferenceValue(projectItemProp, { itemNumber: 'X1', roles: ['family'] });
+        expect(mockGetFunction).toHaveBeenCalledTimes(1);
+        const callArg = mockGetFunction.mock.calls[0][0];
+        expect(callArg.entityName).toEqual('identity');
+        expect(callArg.criteria.propertyName).toEqual('itemNumber');
+        expect(result).toEqual('pi-789');
+    });
+    it('flag on, non-item entityType - roles is NOT filtered, falls back to query path', async () => {
+        const colorProp = {
+            ...refProp,
+            referencedTypeRootSlug: 'color',
+            referencedTypePath: 'color'
+        };
+        const config = baseConfig();
+        config.search = { color: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['colorNumber', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['colorNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'color');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'col-1', typePath: 'color' }]);
+        const result = await dc.setObjectReferenceValue(colorProp, { colorNumber: 'C1', roles: ['family'] });
+        expect(mockGetFunction).toHaveBeenCalled();
+        const callArg = mockGetFunction.mock.calls[0][0];
+        expect(callArg.entityName).toEqual('color');
+        expect(callArg.entityName).not.toEqual('identity');
+        expect(result).toEqual('col-1');
+        expect(poolKeySpy).not.toHaveBeenCalled();
+    });
+    it('query path, multiple matches - returns empty with single warn (no double warn)', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber']);
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [
+            { id: 'a1', typePath: 'item:material' },
+            { id: 'a2', typePath: 'item:material' }
+        ]);
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100' });
+            expect(result).toEqual('');
+            expect(warnSpy).toHaveBeenCalledTimes(1);
+            expect(warnSpy.mock.calls[0][0]).toMatch(/duplicate records/);
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it('flag on, identity returns null - normalized to empty array, returns empty', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => null);
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+            expect(result).toEqual('');
+            expect(warnSpy).toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it('null nd - returns empty string and does not query', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        mockGetFunction.mockClear();
+        const result = await dc.setObjectReferenceValue(refProp, null);
+        expect(result).toEqual('');
+        expect(mockGetFunction).not.toHaveBeenCalled();
+    });
+    it('zero identifier keys - warns and returns empty string', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => []);
+        mockGetFunction.mockClear();
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100' });
+            expect(result).toEqual('');
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringMatching(/doesnt have all "identifier" properties/));
+            expect(mockGetFunction).not.toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it('missing identifier keys on nd - warns and returns empty string', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'season']);
+        mockGetFunction.mockClear();
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100' });
+            expect(result).toEqual('');
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringMatching(/doesnt have all "identifier" properties/));
+            expect(mockGetFunction).not.toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it('transformMapFile set - applyInboundTransformMap is invoked before context build', async () => {
+        const config = baseConfig();
+        config['transformMapFile'] = 'file1';
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        const mapKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getMapKeyFromObject')
+            .mockImplementation(async () => 'LCSMaterial');
+        const applyMapSpy = jest.spyOn(map_utils_1.MapUtil, 'applyTransformMap')
+            .mockImplementation(async (...args) => args[2]);
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'q-1', typePath: 'item:material' }]);
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+            expect(mapKeySpy).toHaveBeenCalledTimes(1);
+            expect(applyMapSpy).toHaveBeenCalledTimes(1);
+            expect(applyMapSpy.mock.calls[0][3]).toEqual('LCSMaterial');
+            expect(result).toEqual('q-1');
+        }
+        finally {
+            mapKeySpy.mockRestore();
+            applyMapSpy.mockRestore();
+        }
+    });
+    it('transformMapFile unset - applyInboundTransformMap does not invoke map utilities', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        const mapKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getMapKeyFromObject');
+        const applyMapSpy = jest.spyOn(map_utils_1.MapUtil, 'applyTransformMap');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'q-2', typePath: 'item:material' }]);
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+            expect(mapKeySpy).not.toHaveBeenCalled();
+            expect(applyMapSpy).not.toHaveBeenCalled();
+            expect(result).toEqual('q-2');
+        }
+        finally {
+            mapKeySpy.mockRestore();
+            applyMapSpy.mockRestore();
+        }
+    });
+    it('query path success - writes id to cache (second call short-circuits)', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'cached-q', typePath: 'item:material' }]);
+        const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+        const r1 = await dc.setObjectReferenceValue(refProp, nd);
+        const callsAfterFirst = mockGetFunction.mock.calls.length;
+        const r2 = await dc.setObjectReferenceValue(refProp, nd);
+        expect(r1).toEqual('cached-q');
+        expect(r2).toEqual('cached-q');
+        expect(mockGetFunction.mock.calls.length).toEqual(callsAfterFirst);
+    });
+    it('query path with subtype filter - applies checkKeysAndValues when entityType !== entityTypePath', async () => {
+        const dc = new data_converter_1.DataConverter(baseConfig(), new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc, ['itemNumber']);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'season']);
+        const checkSpy = jest.spyOn(dc, 'checkKeysAndValues')
+            .mockImplementation((_criteria, arr) => arr);
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ id: 'sub-1', typePath: 'item:material' }]);
+        try {
+            const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', season: 'SS24' });
+            expect(checkSpy).toHaveBeenCalledTimes(1);
+            expect(checkSpy.mock.calls[0][2]).toEqual('item:material');
+            expect(result).toEqual('sub-1');
+        }
+        finally {
+            checkSpy.mockRestore();
+        }
+    });
+    it('assertSingleObjectReference single result - returns id via callback', async () => {
+        const config = baseConfig();
+        config.search = { item: { useIdentityServiceForInboundData: true } };
+        const dc = new data_converter_1.DataConverter(config, new transform_data_1.MapFileUtil(new sdk_1.Entities()));
+        setupTypeUtilsSpies(dc);
+        identifierSpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+            .mockImplementation(async () => ['itemNumber', 'roles']);
+        poolKeySpy = jest.spyOn(type_conversion_utils_1.TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+            .mockImplementation(async () => 'item:material');
+        mockGetFunction.mockClear();
+        mockGetFunction.mockImplementation(() => [{ entityReference: 'item:parsed-id-from-ref' }]);
+        const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+        expect(result).toEqual('parsed-id-from-ref');
+    });
+});
 describe('getObjectReferenceValue - use mapping', () => {
     const maps = require('./data-converter-spec-mockData');
     const mapping = maps['mapping'];

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

@@ -5,6 +5,7 @@ export declare class TypeDefaults {
     static processLCSMaterialAsItem: boolean;
     constructor();
     static applyConfig(config: any): void;
+    static isPropertyTrue(value: any): boolean;
     static getDefaultObjectClass(entity: any): string;
     static getDefaultObjectTypePath(entity: any): string;
     static getDefaultIdentifierProperties(entity: any): string[];

package/lib/util/type-defaults.js

@@ -5,9 +5,10 @@ class TypeDefaults {
     constructor() {
     }
     static applyConfig(config) {
-        const val = config?.LCSMaterial?.processAsItem;
-        TypeDefaults.processLCSMaterialAsItem =
-            val === true || (typeof val === 'string' && val.toLowerCase() === 'true');
+        TypeDefaults.processLCSMaterialAsItem = TypeDefaults.isPropertyTrue(config?.LCSMaterial?.processAsItem);
+    }
+    static isPropertyTrue(value) {
+        return value === true || (typeof value === 'string' && value.toLowerCase() === 'true');
     }
     static getDefaultObjectClass(entity) {
         const entityType = this.getEntityType(entity);

package/package.json

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

package/src/util/data-converter.spec.ts

@@ -509,6 +509,463 @@ describe('getObjectReferenceValue bad value', () =>{
 
 });
 
+describe('setObjectReferenceValue - identity service', () => {
+  const baseConfig = (): FCConfig => ({
+    apiHost: 'host',
+    userName: () => 'user',
+    password: () => 'pass',
+    urlContext: 'xxx',
+    vibeEventEndpoint: '/rfa/vibeiq/vibeEvents',
+    csrfEndpoint: '/servlet/rest/security/csrf',
+    itemPreDevelopmentLifecycleStages: ['concept']
+  });
+
+  const refProp = {
+    id: 'cJoZQvoj7dkfCBJq',
+    propertyType: 'object_reference',
+    slug: 'material',
+    label: 'Material',
+    referencedTypeRootSlug: 'item',
+    referencedTypePath: 'item:material'
+  };
+
+  let identifierSpy: jest.SpyInstance;
+  let poolKeySpy: jest.SpyInstance;
+  let getByRootAndPathSpy: jest.SpyInstance;
+  let filterTypePropertiesSpy: jest.SpyInstance;
+
+  const setupTypeUtilsSpies = (dc: DataConverter, rootPropSlugs: string[] = ['itemNumber']) => {
+    getByRootAndPathSpy = jest.spyOn(dc['typeUtils'], 'getByRootAndPath')
+      .mockImplementation(async () => ({ typePath: 'item', typeProperties: [] }) as any);
+    filterTypePropertiesSpy = jest.spyOn(dc['typeUtils'], 'filterTypeProperties')
+      .mockImplementation(() => rootPropSlugs.map(slug => ({ slug })) as any);
+  };
+
+  afterEach(() => {
+    identifierSpy?.mockRestore();
+    poolKeySpy?.mockRestore();
+    getByRootAndPathSpy?.mockRestore();
+    filterTypePropertiesSpy?.mockRestore();
+    mockGetFunction.mockReset();
+    mockGetFunction.mockImplementation((options) =>
+      ((options?.criteria?.id === 1234) ? [mockObj1234] : [mockObj2222]) as any
+    );
+  });
+
+  it('flag off - uses getAllObjectReferences path', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'abc123', typePath: 'item:material' }] as any);
+
+    const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+    const result = await dc.setObjectReferenceValue(refProp, nd);
+
+    expect(mockGetFunction).toHaveBeenCalled();
+    const callArg = mockGetFunction.mock.calls[0][0];
+    expect(callArg.entityName).toEqual('item');
+    expect(callArg.entityName).not.toEqual('identity');
+    expect(result).toEqual('abc123');
+    expect(poolKeySpy).not.toHaveBeenCalled();
+  });
+
+  it('flag on, single identity match - returns parsed id', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ entityReference: 'item:abc123' }] as any);
+
+    const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+    const result = await dc.setObjectReferenceValue(refProp, nd);
+
+    expect(mockGetFunction).toHaveBeenCalledTimes(1);
+    const callArg = mockGetFunction.mock.calls[0][0];
+    expect(callArg.entityName).toEqual('identity');
+    expect(callArg.criteria).toEqual({
+      poolKey: 'item:material',
+      propertyName: 'itemNumber',
+      propertyValue: 'MAT-100'
+    });
+    expect(result).toEqual('abc123');
+  });
+
+  it('flag on, no identity match - returns empty and warns', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [] as any);
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const getAllSpy = jest.spyOn(dc, 'getAllObjectReferences');
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+      expect(result).toEqual('');
+      expect(warnSpy).toHaveBeenCalled();
+      expect(getAllSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+      getAllSpy.mockRestore();
+    }
+  });
+
+  it('flag on, multiple identity matches - returns empty and does not throw', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [
+      { entityReference: 'item:abc123' },
+      { entityReference: 'item:def456' }
+    ] as any);
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+      expect(result).toEqual('');
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('flag on, ambiguous identifier set - falls back to getAllObjectReferences', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber', 'season', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'season', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'abc123', typePath: 'item:material' }] as any);
+
+    const nd = { itemNumber: 'MAT-100', season: 'SS24', roles: ['family'] };
+    const result = await dc.setObjectReferenceValue(refProp, nd);
+
+    expect(mockGetFunction).toHaveBeenCalled();
+    const callArg = mockGetFunction.mock.calls[0][0];
+    expect(callArg.entityName).toEqual('item');
+    expect(callArg.entityName).not.toEqual('identity');
+    expect(result).toEqual('abc123');
+    expect(poolKeySpy).not.toHaveBeenCalled();
+  });
+
+  it('flag on, cache hit - second call short-circuits', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ entityReference: 'item:abc123' }] as any);
+
+    const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+    const r1 = await dc.setObjectReferenceValue(refProp, nd);
+    const r2 = await dc.setObjectReferenceValue(refProp, nd);
+
+    expect(r1).toEqual('abc123');
+    expect(r2).toEqual('abc123');
+    expect(mockGetFunction).toHaveBeenCalledTimes(1);
+  });
+
+  it('flag on, project-item entityType - roles is filtered, identity path used', async () => {
+    const projectItemProp = {
+      ...refProp,
+      referencedTypeRootSlug: 'project-item',
+      referencedTypePath: 'project-item'
+    };
+    const config = baseConfig();
+    config.search = { 'project-item': { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'project-item');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ entityReference: 'project-item:pi-789' }] as any);
+
+    const result = await dc.setObjectReferenceValue(projectItemProp, { itemNumber: 'X1', roles: ['family'] });
+
+    expect(mockGetFunction).toHaveBeenCalledTimes(1);
+    const callArg = mockGetFunction.mock.calls[0][0];
+    expect(callArg.entityName).toEqual('identity');
+    expect(callArg.criteria.propertyName).toEqual('itemNumber');
+    expect(result).toEqual('pi-789');
+  });
+
+  it('flag on, non-item entityType - roles is NOT filtered, falls back to query path', async () => {
+    const colorProp = {
+      ...refProp,
+      referencedTypeRootSlug: 'color',
+      referencedTypePath: 'color'
+    };
+    const config = baseConfig();
+    config.search = { color: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['colorNumber', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['colorNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'color');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'col-1', typePath: 'color' }] as any);
+
+    const result = await dc.setObjectReferenceValue(colorProp, { colorNumber: 'C1', roles: ['family'] });
+
+    expect(mockGetFunction).toHaveBeenCalled();
+    const callArg = mockGetFunction.mock.calls[0][0];
+    expect(callArg.entityName).toEqual('color');
+    expect(callArg.entityName).not.toEqual('identity');
+    expect(result).toEqual('col-1');
+    expect(poolKeySpy).not.toHaveBeenCalled();
+  });
+
+  it('query path, multiple matches - returns empty with single warn (no double warn)', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber']);
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [
+      { id: 'a1', typePath: 'item:material' },
+      { id: 'a2', typePath: 'item:material' }
+    ] as any);
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100' });
+      expect(result).toEqual('');
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0][0]).toMatch(/duplicate records/);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('flag on, identity returns null - normalized to empty array, returns empty', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => null as any);
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+      expect(result).toEqual('');
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('null nd - returns empty string and does not query', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    mockGetFunction.mockClear();
+    const result = await dc.setObjectReferenceValue(refProp, null);
+    expect(result).toEqual('');
+    expect(mockGetFunction).not.toHaveBeenCalled();
+  });
+
+  it('zero identifier keys - warns and returns empty string', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => []);
+    mockGetFunction.mockClear();
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100' });
+      expect(result).toEqual('');
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringMatching(/doesnt have all "identifier" properties/));
+      expect(mockGetFunction).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('missing identifier keys on nd - warns and returns empty string', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'season']);
+    mockGetFunction.mockClear();
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100' });
+      expect(result).toEqual('');
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringMatching(/doesnt have all "identifier" properties/));
+      expect(mockGetFunction).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('transformMapFile set - applyInboundTransformMap is invoked before context build', async () => {
+    const config = baseConfig();
+    config['transformMapFile'] = 'file1';
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    const mapKeySpy = jest.spyOn(TypeConversionUtils, 'getMapKeyFromObject')
+      .mockImplementation(async () => 'LCSMaterial');
+    const applyMapSpy = jest.spyOn(MapUtil, 'applyTransformMap')
+      .mockImplementation(async (...args) => args[2]);
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'q-1', typePath: 'item:material' }] as any);
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+      expect(mapKeySpy).toHaveBeenCalledTimes(1);
+      expect(applyMapSpy).toHaveBeenCalledTimes(1);
+      expect(applyMapSpy.mock.calls[0][3]).toEqual('LCSMaterial');
+      expect(result).toEqual('q-1');
+    } finally {
+      mapKeySpy.mockRestore();
+      applyMapSpy.mockRestore();
+    }
+  });
+
+  it('transformMapFile unset - applyInboundTransformMap does not invoke map utilities', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    const mapKeySpy = jest.spyOn(TypeConversionUtils, 'getMapKeyFromObject');
+    const applyMapSpy = jest.spyOn(MapUtil, 'applyTransformMap');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'q-2', typePath: 'item:material' }] as any);
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+      expect(mapKeySpy).not.toHaveBeenCalled();
+      expect(applyMapSpy).not.toHaveBeenCalled();
+      expect(result).toEqual('q-2');
+    } finally {
+      mapKeySpy.mockRestore();
+      applyMapSpy.mockRestore();
+    }
+  });
+
+  it('query path success - writes id to cache (second call short-circuits)', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber', 'roles']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'cached-q', typePath: 'item:material' }] as any);
+
+    const nd = { itemNumber: 'MAT-100', roles: ['family'] };
+    const r1 = await dc.setObjectReferenceValue(refProp, nd);
+    const callsAfterFirst = mockGetFunction.mock.calls.length;
+    const r2 = await dc.setObjectReferenceValue(refProp, nd);
+
+    expect(r1).toEqual('cached-q');
+    expect(r2).toEqual('cached-q');
+    expect(mockGetFunction.mock.calls.length).toEqual(callsAfterFirst);
+  });
+
+  it('query path with subtype filter - applies checkKeysAndValues when entityType !== entityTypePath', async () => {
+    const dc = new DataConverter(baseConfig(), new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc, ['itemNumber']);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'season']);
+    const checkSpy = jest.spyOn(dc, 'checkKeysAndValues')
+      .mockImplementation((_criteria, arr) => arr);
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ id: 'sub-1', typePath: 'item:material' }] as any);
+
+    try {
+      const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', season: 'SS24' });
+      expect(checkSpy).toHaveBeenCalledTimes(1);
+      expect(checkSpy.mock.calls[0][2]).toEqual('item:material');
+      expect(result).toEqual('sub-1');
+    } finally {
+      checkSpy.mockRestore();
+    }
+  });
+
+  it('assertSingleObjectReference single result - returns id via callback', async () => {
+    const config = baseConfig();
+    config.search = { item: { useIdentityServiceForInboundData: true } };
+    const dc = new DataConverter(config, new MapFileUtil(new Entities()));
+    setupTypeUtilsSpies(dc);
+
+    identifierSpy = jest.spyOn(TypeConversionUtils, 'getIdentifierPropertiesFromObject')
+      .mockImplementation(async () => ['itemNumber', 'roles']);
+    poolKeySpy = jest.spyOn(TypeConversionUtils, 'getUniquenessPoolKeyFromObject')
+      .mockImplementation(async () => 'item:material');
+
+    mockGetFunction.mockClear();
+    mockGetFunction.mockImplementation(() => [{ entityReference: 'item:parsed-id-from-ref' }] as any);
+
+    const result = await dc.setObjectReferenceValue(refProp, { itemNumber: 'MAT-100', roles: ['family'] });
+    expect(result).toEqual('parsed-id-from-ref');
+  });
+});
+
 describe('getObjectReferenceValue - use mapping', () => {
 
   const maps = require('./data-converter-spec-mockData');

package/src/util/data-converter.ts

@@ -6,6 +6,18 @@ import { Logger } from '@contrail/app-framework';
 import { ObjectDiff, ObjectUtil } from '@contrail/util';
 import { TypeConversionUtils } from './type-conversion-utils';
 import { MapUtil } from './map-utils';
+import { ConfigDefaults } from './config-defaults';
+
+interface ObjectReferenceContext {
+  entityType: string;
+  entityTypePath: string;
+  rootTypeCriteria: Record<string, any>;
+  typeCriteria: Record<string, any>;
+  combinedCriteria: Record<string, any>;
+  cacheKey: string;
+  useIdentityService: boolean;
+  identityLookupKeys: string[];
+}
 
 export class DataConverter {
   private typeUtils: TypeUtils;
@@ -426,33 +438,60 @@ export class DataConverter {
    * @returns the object reference id from VibeIQ
    */
   async setObjectReferenceValue(prop, nd) {
-    let objectReferenceId = "";
-    if(!nd) {
-      return objectReferenceId;
+    if (!nd) {
+      return "";
     }
-    if(this.transformMapFile){
-      const mapKey = await TypeConversionUtils.getMapKeyFromObject(this.transformMapFile, this.mapFileUtil, nd, TypeConversionUtils.FLEX2VIBE_DIRECTION);
-      nd = await MapUtil.applyTransformMap(this.transformMapFile, this.mapFileUtil, nd, mapKey, TypeConversionUtils.FLEX2VIBE_DIRECTION)
+
+    nd = await this.applyInboundTransformMap(nd);
+
+    const ctx = await this.buildObjectReferenceContext(prop, nd);
+    if (!ctx) {
+      return "";
+    }
+
+    if (this.objRefCache[ctx.cacheKey]) {
+      if (Logger.isDebugOn()) {
+        console.debug(`object reference cache hit: ${ctx.cacheKey}`);
+      }
+      return this.objRefCache[ctx.cacheKey];
     }
 
+    const objectReferenceId = ctx.useIdentityService
+      ? await this.lookupObjectReferenceViaIdentityService(ctx, nd)
+      : await this.lookupObjectReferenceViaQuery(ctx);
+
+    if (objectReferenceId) {
+      this.objRefCache[ctx.cacheKey] = objectReferenceId;
+    }
+    return objectReferenceId;
+  }
+
+  private async applyInboundTransformMap(nd: any): Promise<any> {
+    if (!this.transformMapFile) {
+      return nd;
+    }
+    const mapKey = await TypeConversionUtils.getMapKeyFromObject(this.transformMapFile, this.mapFileUtil, nd, TypeConversionUtils.FLEX2VIBE_DIRECTION);
+    return MapUtil.applyTransformMap(this.transformMapFile, this.mapFileUtil, nd, mapKey as string, TypeConversionUtils.FLEX2VIBE_DIRECTION);
+  }
+
+  private async buildObjectReferenceContext(prop: any, nd: any): Promise<ObjectReferenceContext | null> {
     const entityType = prop['referencedTypeRootSlug'];
     const entityTypePath = prop['referencedTypePath'];
     const entityKeys = Object.keys(nd);
-    const identifierKeys = await TypeConversionUtils.getIdentifierPropertiesFromObject(this.transformMapFile, this.mapFileUtil, nd)
+    const identifierKeys = await TypeConversionUtils.getIdentifierPropertiesFromObject(this.transformMapFile, this.mapFileUtil, nd);
     const hasAllIdentifiers = identifierKeys.every(key => entityKeys.includes(key));
-    if(identifierKeys.length == 0 || !hasAllIdentifiers){
+    if (identifierKeys.length === 0 || !hasAllIdentifiers) {
       console.warn(`The inbound ${entityType} for prop '${prop['slug']}' doesnt have all "identifier" properties, so there is no processing. Identifier properties: ${identifierKeys}`);
-      return objectReferenceId;
+      return null;
     }
-    
+
     const rootType = await this.typeUtils.getByRootAndPath({root: entityType});
     const rootTypeProps = this.typeUtils.filterTypeProperties(rootType, nd);
 
-    let rootTypeCriteria = {};
-    let typeCriteria = { };
+    const rootTypeCriteria: Record<string, any> = {};
+    const typeCriteria: Record<string, any> = {};
     identifierKeys.forEach(keyName => {
-      const foundInObjects = rootTypeProps.some(obj => obj.slug === keyName);
-      if (foundInObjects) {
+      if (rootTypeProps.some(obj => obj.slug === keyName)) {
         rootTypeCriteria[keyName] = nd[keyName];
       } else {
         typeCriteria[keyName] = nd[keyName];
@@ -461,35 +500,47 @@ export class DataConverter {
 
     const combinedCriteria = { ...rootTypeCriteria, ...typeCriteria, typePath: entityTypePath };
     const cacheKey = Object.values(combinedCriteria).join('_');
+    const rolesIsTypeDiscriminator = entityType === 'item' || entityType === 'project-item';
+    const identityLookupKeys = rolesIsTypeDiscriminator
+      ? identifierKeys.filter(key => key !== 'roles')
+      : identifierKeys;
+    const useIdentityService = ConfigDefaults.isPropertyTrue(this.config?.search?.[entityType]?.useIdentityServiceForInboundData)
+      && identityLookupKeys.length === 1;
+
+    return { entityType, entityTypePath, rootTypeCriteria, typeCriteria, combinedCriteria, cacheKey, useIdentityService, identityLookupKeys };
+  }
 
-    if (this.objRefCache[cacheKey]) {
-      if (Logger.isDebugOn()) {
-        console.debug(`object reference cache hit: ${cacheKey}`);
-      }
-      return this.objRefCache[cacheKey];
-    }
+  private async lookupObjectReferenceViaIdentityService(ctx: ObjectReferenceContext, nd: any): Promise<string> {
+    const propertyName = ctx.identityLookupKeys[0];
+    const propertyValue = nd[propertyName];
+    const poolKey = await TypeConversionUtils.getUniquenessPoolKeyFromObject(this.transformMapFile, this.mapFileUtil, nd);
 
-    let arrObjectReferences = await this.getAllObjectReferences(entityType, rootTypeCriteria);
-    if(entityType !== entityTypePath) {
-      arrObjectReferences = this.checkKeysAndValues(typeCriteria, arrObjectReferences, entityTypePath);
-    }
+    const identityResults = await new Entities().get({
+      entityName: 'identity',
+      criteria: { poolKey, propertyName, propertyValue }
+    }) ?? [];
 
-    if(arrObjectReferences.length) {
-      if(arrObjectReferences.length === 1) {
-        objectReferenceId = arrObjectReferences[0].id;
-      } else {
-        console.warn(`The passed in object reference criteria has duplicate records found ${JSON.stringify(combinedCriteria)}.`);
-      }
+    return this.assertSingleObjectReference(identityResults, ctx.combinedCriteria, (r) => r.entityReference.split(':')[1]);
+  }
+
+  private async lookupObjectReferenceViaQuery(ctx: ObjectReferenceContext): Promise<string> {
+    let arrObjectReferences = await this.getAllObjectReferences(ctx.entityType, ctx.rootTypeCriteria);
+    if (ctx.entityType !== ctx.entityTypePath) {
+      arrObjectReferences = this.checkKeysAndValues(ctx.typeCriteria, arrObjectReferences, ctx.entityTypePath);
     }
+    return this.assertSingleObjectReference(arrObjectReferences, ctx.combinedCriteria, (r) => r.id);
+  }
 
-    if (!objectReferenceId) {
+  private assertSingleObjectReference(results: any[], combinedCriteria: any, getId: (r: any) => string): string {
+    if (!results.length) {
       console.warn(`The passed in object reference criteria ${JSON.stringify(combinedCriteria)} didn't match any entities.`);
-      return objectReferenceId;
+      return "";
     }
-
-    this.objRefCache[cacheKey] = objectReferenceId;
-
-    return objectReferenceId;
+    if (results.length > 1) {
+      console.warn(`The passed in object reference criteria has duplicate records found ${JSON.stringify(combinedCriteria)}.`);
+      return "";
+    }
+    return getId(results[0]);
   }
 
   /**

package/src/util/type-defaults.ts

@@ -15,9 +15,11 @@ export class TypeDefaults {
    *  through multiple layers of function calls.
    */
   static applyConfig(config: any): void {
-    const val = config?.LCSMaterial?.processAsItem;
-    TypeDefaults.processLCSMaterialAsItem =
-      val === true || (typeof val === 'string' && val.toLowerCase() === 'true');
+    TypeDefaults.processLCSMaterialAsItem = TypeDefaults.isPropertyTrue(config?.LCSMaterial?.processAsItem);
+  }
+
+  static isPropertyTrue(value: any): boolean {
+    return value === true || (typeof value === 'string' && value.toLowerCase() === 'true');
   }
   /**Takes in full entity and returs the default FlexPLM
    * object class.
@@ -189,6 +191,7 @@ export class TypeDefaults {
     const customEntityClasses = TypeDefaults.processLCSMaterialAsItem
       ? ['LCSRevisableEntity', 'LCSLifecycleManaged', 'LCSLast']
       : ['LCSRevisableEntity', 'LCSLifecycleManaged', 'LCSLast', 'LCSMaterial'];
+
     if(itemClasses.includes(objectClass)){
       entityClass = 'item';
     }else if(['LCSProductSeasonLink', 'LCSSKUSeasonLink'].includes(objectClass)){
@@ -300,6 +303,7 @@ export class TypeDefaults {
       const itemClasses = TypeDefaults.processLCSMaterialAsItem
         ? ['LCSProduct', 'LCSMaterial']
         : ['LCSProduct'];
+
       if (itemClasses.includes(objectClass)) {
         properties.push('name');
       } else if ('LCSSKU' === objectClass) {