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

package/lib/util/map-util-spec-mockData.js

@@ -31,12 +31,26 @@ exports.mapping = {
                 }
             }
         }
+        // flex2vibe: {
+        //   LCSRevisableEntity: {
+        //     getMapKey: (object) =>{ return object;}
+        //   },
+        //   LCSLast: {
+        //     getMapKey: (object) => {return object;}
+        //   },
+        //   LCSMaterial: {
+        //     getMapKey: (object) =>{ return object;}
+        //   },
+        //   LCSBusinessObject: {
+        //     getMapKey: (object) => {return object;}
+        //   }
+        // },
     },
     LCSProduct: {
         vibeOwningKeys: ['itemNumber', 'lifecycleStage'],
         vibe2flex: {
             getClass: () => 'LCSProduct',
-            getSoftType: (entity) => {
+            getSoftType: (entity /*, dependencies*/) => {
                 const prodType = entity['prodType'];
                 let val = '';
                 switch (prodType) {
@@ -61,7 +75,7 @@ exports.mapping = {
                 vibeIQIdentifier: 'itemNumber'
             },
             valueTransform: {
-                transformEx: (row) => {
+                transformEx: (row /*, dependencies*/) => {
                     return row['otherProp'] + 'xxx';
                 }
             }
@@ -79,7 +93,7 @@ exports.mapping = {
         vibeOwningKeys: ['itemNumber', 'lifecycleStage'],
         vibe2flex: {
             getClass: () => 'LCSSKU',
-            getSoftType: (entity) => {
+            getSoftType: (entity /*, dependencies*/) => {
                 const prodType = entity['prodType'];
                 let val = '';
                 switch (prodType) {

package/lib/util/map-utils.d.ts

@@ -1,6 +1,33 @@
 import { MapFileUtil } from '@contrail/transform-data';
 export declare class MapUtil {
+    /** Transforms the data, assumes mapSectionKey has been correctly determined.
+     *
+     * @param transformMapFile id of map file
+     * @param mapFileUtil
+     * @param data
+     * @param mapSectionKey key for section of map file
+     * @param direction vibe2flex or flex2vibe
+     * @param transformTaskOrderKey key for the list of tasks to be processed. default is 'transformOrder'
+     * @returns The converted data
+     */
     static applyTransformMap(transformMapFile: any, mapFileUtil: any, data: any, mapSectionKey: string, direction: string, transformTaskOrderKey?: string): Promise<any>;
+    /** Returns the mapKey based on the 'typeConversion' section of the map file.
+     * If the map file doesn't have a section for the type in question, 'undefined' is returned.
+     *
+     * @param fileId
+     * @param mapFileUtil
+     * @param data The full object
+     * @param type The entity or object class of the object.  The functions are keyed based on this.
+     * @param direction
+     * @returns
+     */
     static getMapKey(transformMapFile: any, mapFileUtil: MapFileUtil, data: any, type: string, direction: string): Promise<string>;
+    /** Returns the full map section with both directions; identifier and informational properties; etc.
+     *
+     * @param transformMapFile id if map file
+     * @param mapFileUtil
+     * @param mapSectionKey key of the map section
+     * @returns
+     */
     static getFullMapSection(transformMapFile: string, mapFileUtil: MapFileUtil, mapSectionKey: string): Promise<any>;
 }

package/lib/util/map-utils.js

@@ -2,12 +2,39 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapUtil = void 0;
 class MapUtil {
+    /** Transforms the data, assumes mapSectionKey has been correctly determined.
+     *
+     * @param transformMapFile id of map file
+     * @param mapFileUtil
+     * @param data
+     * @param mapSectionKey key for section of map file
+     * @param direction vibe2flex or flex2vibe
+     * @param transformTaskOrderKey key for the list of tasks to be processed. default is 'transformOrder'
+     * @returns The converted data
+     */
     static async applyTransformMap(transformMapFile, mapFileUtil, data, mapSectionKey, direction, transformTaskOrderKey = 'transformOrder') {
         return await mapFileUtil.applyTransformMap(transformMapFile, data, mapSectionKey, direction, transformTaskOrderKey);
     }
+    /** Returns the mapKey based on the 'typeConversion' section of the map file.
+     * If the map file doesn't have a section for the type in question, 'undefined' is returned.
+     *
+     * @param fileId
+     * @param mapFileUtil
+     * @param data The full object
+     * @param type The entity or object class of the object.  The functions are keyed based on this.
+     * @param direction
+     * @returns
+     */
     static async getMapKey(transformMapFile, mapFileUtil, data, type, direction) {
         return await mapFileUtil.getMapKey(transformMapFile, data, type, direction);
     }
+    /** Returns the full map section with both directions; identifier and informational properties; etc.
+     *
+     * @param transformMapFile id if map file
+     * @param mapFileUtil
+     * @param mapSectionKey key of the map section
+     * @returns
+     */
     static async getFullMapSection(transformMapFile, mapFileUtil, mapSectionKey) {
         return await mapFileUtil.getFullMapSection(transformMapFile, mapSectionKey);
     }

package/lib/util/thumbnail-util.d.ts

@@ -6,6 +6,7 @@ interface ContentCustomSize {
 }
 export declare class ThumbnailUtil {
     private config;
+    /** The max_thumbnail_size is for limiting the size of the thumbnail being sent to FlexPLM.  It is used when checking the size of the auto generated thumbnails (smallViewable, tinyViewable, etc.). */
     private max_thumbnail_size;
     private entities;
     static NEW_THUMBNAIL_ID: string;
@@ -16,11 +17,31 @@ export declare class ThumbnailUtil {
     }[];
     constructor(config: FCConfig);
     setOutboundThumbnail(data: any, event: any): Promise<any>;
+    /** Determines if a new image has been generated.  If any viewable is new, there might be a better
+   * sized image.  So send the fileId as new.
+   */
     isThumbnailNew(event: any, customSizes: any[]): boolean;
     getFileId(primaryViewableId: string): Promise<string | undefined>;
     getCustomSizes(): Promise<ContentCustomSize[]>;
     getContentEntity(primaryViewableId: any, sizes: ContentCustomSize[]): Promise<any>;
+    /** This outputs the content entity, without the inflated file entities.
+   * To help debugging issues with sending the thumbnail info.
+   * The inflated entities are removed, because are large and cause
+   * problems with log file size limits.
+   *
+   * @param content: the content with inflated objects
+   * @param relations: string[] of the slugs for inflated objects
+   */
     logContentResults(content: any, relations: string[]): void;
+    /** Syncs the thumbnail from FlexPLM to VibeIQ. Handles creating, replacing, or removing
+     * the primary viewable content and persists the updates directly to the entity.
+     *
+     * @param entityId - The ID of the entity to update with thumbnail properties.
+     * @param primaryViewableId - The existing primary viewable content ID, if any.
+     * @param event - The inbound event containing thumbnail data (NEW_THUMBNAIL_ID / EXISTING_THUMBNAIL_ID).
+     * @param entityName - The entity type name (e.g. 'item', 'color') used for API calls.
+     * @returns The updated entity, or undefined if no thumbnail changes were needed.
+     */
     syncThumbnailToVibeIQ({ entityId, primaryViewableId, event, entityName }: {
         entityId: string;
         primaryViewableId?: string;

package/lib/util/thumbnail-util.js

@@ -8,6 +8,7 @@ const flexplm_connect_1 = require("./flexplm-connect");
 class ThumbnailUtil {
     constructor(config) {
         this.config = config;
+        /** The max_thumbnail_size is for limiting the size of the thumbnail being sent to FlexPLM.  It is used when checking the size of the auto generated thumbnails (smallViewable, tinyViewable, etc.). */
         this.max_thumbnail_size = 5 * 1024 * 1024;
         this.entities = new sdk_1.Entities();
         if (this.config['max_thumbnail_size']) {
@@ -17,6 +18,7 @@ class ThumbnailUtil {
     async setOutboundThumbnail(data, event) {
         if (event?.newData?.primaryViewableId && event?.newData?.largeViewableDownloadUrl) {
             const primaryViewableId = event.newData.primaryViewableId;
+            //get custom sizes
             const fileId = await this.getFileId(primaryViewableId);
             if (fileId) {
                 const customSizes = await this.getCustomSizes();
@@ -31,6 +33,9 @@ class ThumbnailUtil {
         }
         return data;
     }
+    /** Determines if a new image has been generated.  If any viewable is new, there might be a better
+   * sized image.  So send the fileId as new.
+   */
     isThumbnailNew(event, customSizes) {
         const propertyDiffs = event?.propertyDiffs;
         if (propertyDiffs) {
@@ -52,6 +57,7 @@ class ThumbnailUtil {
         const OOBSizes = JSON.parse(JSON.stringify(ThumbnailUtil.OOB_SIZES));
         sizes.push(...OOBSizes);
         console.info('sizes: ' + JSON.stringify(sizes));
+        //get Content
         const content = await this.getContentEntity(primaryViewableId, sizes);
         if (!content) {
             return undefined;
@@ -99,6 +105,14 @@ class ThumbnailUtil {
         this.logContentResults(content, relations);
         return content;
     }
+    /** This outputs the content entity, without the inflated file entities.
+   * To help debugging issues with sending the thumbnail info.
+   * The inflated entities are removed, because are large and cause
+   * problems with log file size limits.
+   *
+   * @param content: the content with inflated objects
+   * @param relations: string[] of the slugs for inflated objects
+   */
     logContentResults(content, relations) {
         if (app_framework_1.Logger.isDebugOn() && content && relations) {
             const contentCopy = JSON.parse(JSON.stringify(content));
@@ -108,12 +122,22 @@ class ThumbnailUtil {
             console.debug('content: ' + JSON.stringify(contentCopy));
         }
     }
+    /** Syncs the thumbnail from FlexPLM to VibeIQ. Handles creating, replacing, or removing
+     * the primary viewable content and persists the updates directly to the entity.
+     *
+     * @param entityId - The ID of the entity to update with thumbnail properties.
+     * @param primaryViewableId - The existing primary viewable content ID, if any.
+     * @param event - The inbound event containing thumbnail data (NEW_THUMBNAIL_ID / EXISTING_THUMBNAIL_ID).
+     * @param entityName - The entity type name (e.g. 'item', 'color') used for API calls.
+     * @returns The updated entity, or undefined if no thumbnail changes were needed.
+     */
     async syncThumbnailToVibeIQ({ entityId, primaryViewableId, event, entityName }) {
         console.debug(`syncThumbnailToVibeIQ: entityId=${entityId}, primaryViewableId=${primaryViewableId}, entityName=${entityName}`);
         const eventData = event.data || {};
         const newThumbnailId = eventData[ThumbnailUtil.NEW_THUMBNAIL_ID];
         const existingThumbnailId = eventData[ThumbnailUtil.EXISTING_THUMBNAIL_ID];
         const thumbnailUrl = newThumbnailId || existingThumbnailId;
+        // Case 1: REMOVE_THUMBNAIL
         if (newThumbnailId === ThumbnailUtil.REMOVE_THUMBNAIL) {
             if (primaryViewableId) {
                 await this.entities.delete({ entityName: 'content', id: primaryViewableId });
@@ -123,10 +147,12 @@ class ThumbnailUtil {
             console.debug(`syncThumbnailToVibeIQ: applied clear updates for entityId=${entityId}`);
             return updatedEntity;
         }
+        // Early return if no thumbnail URL
         if (!thumbnailUrl) {
             console.debug(`syncThumbnailToVibeIQ: no thumbnail URL for entityId=${entityId}`);
             return undefined;
         }
+        // Case 2: No existing primaryViewableId — create new content
         if (!primaryViewableId) {
             const content = await this.createContentFromFlexPLM(thumbnailUrl, entityId, entityName);
             await this.entities.update({ entityName: 'content', id: content.id, object: { flexplmThumbnailUrl: thumbnailUrl } });
@@ -135,10 +161,11 @@ class ThumbnailUtil {
             console.debug(`syncThumbnailToVibeIQ: created new content ${content.id} for entityId=${entityId}`);
             return updatedEntity;
         }
+        // Case 3: Has primaryViewableId — check if thumbnail changed
         const primaryViewable = await this.entities.get({ entityName: 'content', id: primaryViewableId });
         if (primaryViewable?.flexplmThumbnailUrl === thumbnailUrl) {
             console.debug(`syncThumbnailToVibeIQ: thumbnail already synced for entityId=${entityId}`);
-            return undefined;
+            return undefined; // Already synced
         }
         const content = await this.createContentFromFlexPLM(thumbnailUrl, entityId, entityName);
         await this.entities.update({ entityName: 'content', id: content.id, object: { flexplmThumbnailUrl: thumbnailUrl } });

package/lib/util/thumbnail-util.spec.js

@@ -327,11 +327,13 @@ describe('ThumbnailUtil Tests', () => {
                 contentType: 'image/png',
                 contentHolderReference: 'color:entity1',
             }));
+            // Updates content with flexplmThumbnailUrl
             expect(mockEntitiesUpdate).toHaveBeenCalledWith(expect.objectContaining({
                 entityName: 'content',
                 id: 'newContent1',
                 object: { flexplmThumbnailUrl: '/rest/thumbnail/thumb.png' },
             }));
+            // Updates the main entity
             expect(mockEntitiesUpdate).toHaveBeenCalledWith(expect.objectContaining({
                 entityName: 'color',
                 id: 'entity1',
@@ -405,13 +407,17 @@ describe('ThumbnailUtil Tests', () => {
             mockContentCreate.mockResolvedValue(createdContent);
             const event = { data: { [thumbnail_util_1.ThumbnailUtil.NEW_THUMBNAIL_ID]: '/rest/thumbnail/new.jpg' } };
             await tu.syncThumbnailToVibeIQ({ entityId: 'entity1', primaryViewableId: 'oldPv', event, entityName: 'item' });
+            // Creates new content
             expect(mockContentCreate).toHaveBeenCalled();
+            // Updates new content with flexplmThumbnailUrl
             expect(mockEntitiesUpdate).toHaveBeenCalledWith(expect.objectContaining({
                 entityName: 'content',
                 id: 'newContent2',
                 object: { flexplmThumbnailUrl: '/rest/thumbnail/new.jpg' },
             }));
+            // Updates the main entity
             expect(mockEntitiesUpdate).toHaveBeenCalledWith(expect.objectContaining({ entityName: 'item', id: 'entity1' }));
+            // Deletes old content
             expect(mockEntitiesDelete).toHaveBeenCalledWith({ entityName: 'content', id: 'oldPv' });
         });
         it('does not update when primaryViewable.flexplmThumbnailUrl matches', async () => {

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

@@ -57,7 +57,7 @@ exports.mapping = {
         vibeOwningKeys: ['itemNumber', 'lifecycleStage'],
         vibe2flex: {
             getClass: () => 'LCSProduct',
-            getSoftType: (entity) => {
+            getSoftType: (entity /*, dependencies*/) => {
                 const prodType = entity['prodType'];
                 let val = '';
                 switch (prodType) {
@@ -82,7 +82,7 @@ exports.mapping = {
                 vibeIQIdentifier: 'itemNumber'
             },
             valueTransform: {
-                transformEx: (row) => {
+                transformEx: (row /*, dependencies*/) => {
                     return row['otherProp'] + 'xxx';
                 }
             }
@@ -100,7 +100,7 @@ exports.mapping = {
         vibeOwningKeys: ['itemNumber', 'lifecycleStage'],
         vibe2flex: {
             getClass: () => 'LCSSKU',
-            getSoftType: (entity) => {
+            getSoftType: (entity /*, dependencies*/) => {
                 const prodType = entity['prodType'];
                 let val = '';
                 switch (prodType) {

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

@@ -1,24 +1,175 @@
 import { MapFileUtil } from '@contrail/transform-data';
+/** This class is helper functions to get the data for converting
+ * VibeIQ entities to / from FlexPLM Objects
+*/
 export declare class TypeConversionUtils {
     static NO_ENTITY_TYPE: string;
     static VIBE2FLEX_DIRECTION: string;
     static FLEX2VIBE_DIRECTION: string;
     constructor();
+    /** Takes in a VibeIQ entity object and returns the correct FlexPLM
+     * object class associated to the entity. Order of precedence
+     * Property 'flexPLMObjectClass'
+     * Map file entry in 'typeConversion:vibe2flex:<value>:getObjectClass()'
+     *  for value from 'entityClass' or root from 'typePath'
+     * TypeDefaults.getDefaultObjectClass() function
+     * @param transformMapFile id for mapFile
+     * @param mapFileUtil class to get mapfile
+     * @param entity
+     * @returns Promise<string>
+     */
     static getObjectClass(transformMapFile: any, mapFileUtil: any, entity: any): Promise<string>;
+    /** Takes in a VibeIQ entity object and returns the correct FlexPLM
+     * FlexType associated to the entity. Order of precedence
+     * Property 'flexPLMTypePath'
+     * Map file entry in 'typeConversion:vibe2flex:<value>:getSoftType()'
+     *  for value from 'entityClass' or root from 'typePath'
+     * TypeDefaults.getDefaultObjectTypePath() function
+     *
+     * @param transformMapFile id for mapFile
+     * @param mapFileUtil class to get mapfile
+     * @param entity VibeIQ entity
+     * @returns Promise<string>
+     */
     static getObjectTypePath(transformMapFile: any, mapFileUtil: any, entity: any): Promise<string>;
+    /**Takes in a VibeIQ entity object and returns the correct
+     * identifier properties.  Order of precedence
+     * Property 'flexPLMIdentifierProperties'
+     * Map file entry in 'typeConversion:vibe2flex:<value>:getIdentifierProperties()'
+     *  for value from 'entityClass' or root from 'typePath'
+     * TypeDefaults.getDefaultIdentifierProperties() function
+     *
+     * @param transformMapFile id for mapFile
+     * @param mapFileUtil class to get mapfile
+     * @param entity
+     * @returns Promise<string[]>
+     */
     static getIdentifierProperties(transformMapFile: any, mapFileUtil: any, entity: any): Promise<string[]>;
+    /**Takes in a VibeIQ entity object and returns the correct
+   * informational properties.  Order of precedence
+   * Property 'flexPLMInformationalProperties'
+   * Map file entry in 'typeConversion:vibe2flex:<value>:getInformationalProperties()'
+   *  for value from 'entityClass' or root from 'typePath'
+   * TypeDefaults.getDefaultObjectTypePath() function
+   *
+   * @param transformMapFile id for mapFile
+   * @param mapFileUtil class to get mapfile
+   * @param entity
+   * @returns string
+   */
     static getInformationalProperties(transformMapFile: any, mapFileUtil: any, entity: any): Promise<string[]>;
+    /**Takes in a VibeIQ entity object and returns the correct mapKey
+   * Order of precedence:
+   * Map file entry in 'typeConversion:<direction>:<value>:getObjectClass()'
+   *  for value from 'entityClass' or root from 'typePath'
+   * TypeDefaults.getDefaultObjectClass() function
+     *
+     * @param transformMapFile
+     * @param mapFileUtil
+     * @param entity
+     * @param type
+     * @param direction
+     * @returns
+     */
     static getMapKey(transformMapFile: any, mapFileUtil: MapFileUtil, entity: any, direction: string): Promise<string>;
+    /** Returns the VibeIQ entity type from an entity.
+     * Throws error if it can't determine the entity type
+     *
+     * @param entity
+     * @returns string
+     */
     static getEntityType(entity: any): any;
+    /** Takes in a FlexPLM object and returns the correct VibeIQ entity
+     * class associated to the object. Order of precedence
+     * Property 'vibeIQEntityClass'
+     * Map file entry in 'typeConversion:flex2vibe:<value>:getObjectClass()'
+     *  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 getEntityClassFromObject(fileId: any, mapFileUtil: any, object: any): Promise<string>;
+    /** 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 getUniquenessPoolKeyFromObject(fileId: any, mapFileUtil: any, object: any): Promise<string>;
     static getEntityTypePathFromOjbect(fileId: any, mapFileUtil: any, object: any): Promise<string>;
+    /** Takes in a FlexPLM object and returns the correct VibeIQ
+   * type associated to the object. Order of precedence
+   * Property 'vibeIQTypePath'
+   * Map file entry in 'typeConversion:flex2vibe:<value>:getSoftType()'
+   *  for value from 'objectClass' or root from 'flexPLMTypePath'
+   * TypeDefaults.getDefaultEntityTypePath() function
+   *
+   * @param transformMapFile id for mapFile
+   * @param mapFileUtil class to get mapfile
+   * @param entity VibeIQ entity
+   * @returns Promise<string>
+   */
+    static getEntityTypePathFromObject(fileId: any, mapFileUtil: any, object: any): Promise<string>;
+    /**Takes in a FlexPLM object and returns the correct
+   * identifier properties.  Order of precedence
+   * Property 'vibeIQIdentifierProperties'
+   * Map file entry in 'typeConversion:flex2vibe:<value>:getIdentifierProperties()'
+   *  for value from 'objectClass'
+   * TypeDefaults.getDefaultIdentifierPropertiesFromObject() function
+   *
+   * @param transformMapFile id for mapFile
+   * @param mapFileUtil class to get mapfile
+   * @param object
+   * @returns Promise<string[]>
+   */
     static getIdentifierPropertiesFromObject(fileId: any, mapFileUtil: MapFileUtil, object: any): Promise<string[]>;
+    /**Takes in a FlexPLM object and returns the correct
+ * identifier properties.  Order of precedence
+ * Property 'vibeIQIdentifierProperties'
+ * Map file entry in 'typeConversion:flex2vibe:<value>:getInformationalProperties()'
+ *  for value from 'objectClass'
+ * TypeDefaults.getDefaultIdentifierPropertiesFromObject() function
+ *
+ * @param transformMapFile id for mapFile
+ * @param mapFileUtil class to get mapfile
+ * @param object
+ * @returns Promise<string[]>
+ */
     static getInformationalPropertiesFromObject(fileId: any, mapFileUtil: MapFileUtil, object: any): Promise<string[]>;
     static getMapKeyFromObject(fileId: any, mapFileUtil: MapFileUtil, object: any, direction: string): Promise<string | undefined>;
     static isInboundCreatableFromObject(fileId: string, mapFileUtil: MapFileUtil, object: any, context?: any): Promise<boolean>;
     static isOutboundCreatableFromEntity(fileId: string, mapFileUtil: MapFileUtil, entity: any, context?: any): Promise<boolean>;
+    /** Takes in a FlexPLM object and determines whether inbound
+     * images should be synced. In most cases, the creation owning system
+     * will also control image syncing. Defaults to false if no mapping exists.
+     * Map file entry in '<mapKey>:syncInboundImages()'
+     *
+     * @param fileId id for mapFile
+     * @param mapFileUtil class to get mapfile
+     * @param object FlexPLM object
+     * @param context optional context object
+     * @returns Promise<boolean>
+     */
     static syncInboundImages(fileId: string, mapFileUtil: MapFileUtil, object: any, context?: any): Promise<boolean>;
+    /** Takes in a VibeIQ entity object and determines whether outbound
+     * images should be synced. In most cases, the creation owning system
+     * will also control image syncing. Defaults to true if no mapping exists.
+     * Map file entry in '<mapKey>:syncOutboundImages()'
+     *
+     * @param fileId id for mapFile
+     * @param mapFileUtil class to get mapfile
+     * @param entity VibeIQ entity
+     * @param context optional context object
+     * @returns Promise<boolean>
+     */
     static syncOutboundImages(fileId: string, mapFileUtil: MapFileUtil, entity: any, context?: any): Promise<boolean>;
     static getObjectType(object: any): any;
 }