CDW customization - SmartPlant Foundation - IM Update 48 - Help - Hexagon

Consolidation customization

The following method definitions have been defined against the new ISPFCDWPublishedDocVersion interface:

• PerformMappingAndTransformation

• ConsolidateChunkOfObjects – Takes a set of items from the input source and decides how to process them, filling the SmartPlant Foundation transaction. This method is now obsolete and is no longer called during consolidation.

• ConsolidateChunkOfRels – Acts the same as the ConsolidateChunkOfObjects method. This method is now obsolete and is no longer called during consolidation.

The methods defined below can be overridden once you have done the sideways override of ISPFCDWPublishedDocVersion. See the Sideways override topic in Interface Overrides for details.

• ConsolidateChunkOfTaggedItems – Takes a group of tagged items from the transformed file and decides how to process them, adding the changes to the transaction object for commit to the database.

• ConsolidateRels - Consolidates relationships in a tagged item group.

• ProcessConsolidatedDeleteInstructions - Processes delete instructions.

• TerminateCDWRelsForTerminateRels - Processes delete instructions for relationships.

• ProcessSameAsDeleteInstructions - Processes delete instructions for SameAs relationships.

• ProcessConsolidatedUpdateInstructions - Processes update and update class instructions.

• ProcessConsolidatedUnClaimedInstructions - Processes unclaim instructions.

• ProcessConsolidatedClaimInstructions - Processes claim instructions.

• ConsolidateDataObjects - Processes the tool data objects to determine the UIDs of the CDW objects.

• ConsolidateCDWObjectsPropertiesAndRels - Updates the SPFTEFComprisedOf relationships, properties, and other relationships of the CDW objects.

• ConsolidateCDWPropertiesAndRels - Updates the SPFTEFComprisedOf relationships, properties, and any other relationships of the individual CDW objects.

• OnCreateComprisedOfRel - Creates a SPFTEFComprisedOf relationship between the CDW object and the published object.

• OnDetermineTargetCDWUIDForLocalUID - Determines the CDW object UID for the current published object being processed and updates it in the ComprisedOfUIDs collections provided in the input parameters.

• OnLookForTargetCDWUIDForMultipleSameAs - Determines the target CDW UID from SameAs for the local object.

• OnProcessAllSameAsForLocalUID - Processes all SameAs for the current published object and updates the target CDW UID for all the involved local and external published objects.

• ReconsolidateObjectProperties - Reconsolidates the CDW object.

• OnUpdateObjectAndMergeWithInputs - Calls OnSetPropertiesFromSource to update the properties on the CDW object.

• OnSetPropertiesFromSource - Updates the properties on the CDW object.

• OnSetProperty - Updates the current property on the CDW object.

• OnCreateRelationship - Creates the given CDW relationship.

• OnCreateObject - Creates the CDW object.

• OnThisIsMappedOutputFile - A method that can be overridden to allow the customization of the transformed tool data file.

Use the object browser to view each individual method available.

Consolidation process

This is pseudo code to describe the current process for CDW consolidation. The following steps describe the consolidation process:

1. ConsolidateObjects calls PersistFileWithTaggedItemsInContainers to rearrange the tool data and tombstone files into one combined file in tagged items.

2. ConsolidateObjects calls the method definition PerformMappingAndTransformation.

3. Using the output stream from the mapping function, process the file.

   Extract the component schema and SameAs mappings.

4. Read the file in chunks of tagged items, where the size of the chunks is configurable using the PublishDataProcessingChunkSize setting in Server Manager.

   1. For each chunk, call ConsolidateChunkOfTaggedItems.

   2. Inside this function, try to lock the CDW objects and the published objects that they are comprised of that would be affected. If the objects are locked successfully, process the instructions and objects. If the objects are not successfully locked, then store the chunk for processing at the end, once the entire file is completed.

   3. If all tagged items have been successfully processed, commit the chunk to the database.

5. Try again to consolidate chunks that could not be locked during the first attempt.

6. If objects still fail to lock successfully, then fail consolidation.

7. In the case of failed consolidation, set the number of committed chunks on the SPFTEFTagItmGrpConsCnt property on the ISPFTEFPublishedDocVersion interface on the document.

If you submit a consolidate task that attempts to lock objects currently locked by another consolidate task, you receive the following message, "Consolidation was unable to lock required objects. Please retry" Retry the failed consolidation task when the first completes and the objects are unlocked.

Delete instructions

Three method definitions are implemented on ISPCDWObject to allow control of the behavior when a delete occurs.

1. ProcessItemBeforeToolDelete – Checks to see how many ComprisedOf relationships exist.

2. OnProcessItemWithSingleComprisedOfRel - Checks to see if the CDW object last updated date is more recent than the creation date of the ComprisedOf relationship. If the last updated date is more recent, it indicates the CDW object has been updated and so it will not delete the CDW object. If the object has not been updated since the creation of the ComprisedOf relationship, it looks to see if there are relationships to any other objects that are not part of the mapping. If the object has no other relationships to anything else in SmartPlant Foundation, it will be deleted.

3. OnProcessItemWithMultipleComprisedOfRel – Terminates any current properties that have a source domain equal to the domain of the tool data being removed. For each of the properties being terminated this looks to see if it had a previous value with a different source domain and if so, re-instates it.

Precedence customization

The default precedence process always updates the data on the CDW object as new data is published. This process makes the published data represent the last in wins data. This can be changed through customization.

On the ISPFCDWPublishedDocVersionDefault code class there is an override method called OnSetProperty. This method is called each time you set a property on a new or existing CDW object.

The inputs into this function are currently:

OnSetProperty(ByVal pobjTargetIDef As IInterface, ByVal pstrPropertyDefUID As String, ByVal pobjValue As Object)

Access the properties collection from pobjTargetIDef, find the PropertyDefault object for the property of interest, and see the existing value and the source domain.

There are two properties, TargetDomain and SourceDomain, that help with precedence.

Mapping customization

The PerformMappingAndTransformation method definition on ISPFCDWPublishedDocVersion controls mapping. You can perform a sideways override on the ISPFCDWPublishedDocVersionDefault interface to be able to override the following Methods:

• OnCreateInputAdapter – Allows you to write a new class and inherit from InputAdapter, must implement ISPFInputAdapter.

• OnCreateOutputAdapter – Allows you to write a new class and inherit from OutputAdapter, must implement IOutputAdapter.

• OnCreateMappingClass – Allows you to write a new class and inherit from SPFMappingClass, must implement ISPFMappingClass.

• OnCreateInterpreter – Allows you to write a new interpreter class and inherit from Interpreter, must implement Interpreter class.

The previous methods allow any project to replace any of the classes with their own custom version of the class; this replacement is for mapping only. The mapping output class does not consider the SameAs relationship; it maps the properties using the same UID’s. The consolidate code performs the required logic for the SameAs relationship.

Input adapter

To override the GetNextObject and GetObject methods, as well as construct custom AdapterObject (IAdapterObject), use the CreateAdapterObject method.

Output adapter

Ten methods can be overridden. Six are defined on the IOutputAdapter interface.

SPFMappingClass

The role of this class is to interrogate the database to provide mapping information by class definition or relationship definition. Several methods can be overridden, allowing customization of what mapping is returned. The IMapClass interface is used to send back instructions (property mapping) and IDefInstructions (interface mapping).

Interpreter

The interpreter is a simple class that asks the input adapter for an object (IAdapterObject). If it is an object, the interpreter calls the function OnExecuteObj, which is an override function. If it finds a relationship, the interpreter calls OnExecuteRel. If it finds an instruction, the interpreter calls OnExecuteInstruction.

OnExecuteObj

The process logic is described below:

1. Ask mapping class for the mapping for this class definition.

2. If no mapping is found, ignore this input item.

   • The current setup means it will always default to CDWObject.

3. Call BringCreate on the output adapter, which creates a new object using the map to class definition.

4. Set the output object name and description from the input source.

5. Process each of the SetInstructions (properties).

   1. Ask the input adapter for the source property value.

   2. Tell the output adapter to write the target property with the source property value.

6. Process each of the ISetInstructions (interface).

   • If the input source has the interface, then create the mapped interface onto the output source.

   This is a mapping exercise that adds an interface onto the output source if it exists on the input source.

7. Call FinishCreate on output class.

OnExecuteRel

The process logic is described as below:

1. Extract the relationship definition UID.

2. Ask mapping class for the mapping for this RelDefUID.

3. If no mapping is found, ignore the relationship.

4. Extract the UID, UID1, and UID2 from the input source.

5. Ask the output adapter to create a new relationship using the mapto RelDefUID, UID, UID1, and UID2 (BeginCreateRel).

6. Process each of the SetInstructions (properties).

   1. Ask the input adapter for the source property value.

   2. Tell the output adapter to write the target property with the source property value.

7. Process each of the ISetInstructions (interface).

   • If the input source has the interface, then create the mapped interface onto the output source.

   This is a mapping exercise that adds an interface onto the output source if it exists on the input source.

8. Call FinishCreateRel on output class.

OnExecuteInstruction

The process logic is described below:

1. Call BringCreate on the output adapter to create a new instruction object using the class definition of the instruction.

2. Process each of the interfaces and properties.

   1. Ask the adapter for the source property value.

   2. If the property is PropValues, AddedInterfaces, RemovedInterfaces, RemovedProperties, or RelDefUID, then determine the mapped property values.

   3. Tell the output adapter to write the property with the determined property value.

3. Call FinishCreate on output class.

Map function customization

You can perform a sideways override of ISPFMapFunctionDefDefault and override the ExecuteMapFunction method definition. This function takes the return value and uses it to set the target mapped property.