This topic provides general information about the mapping in Smart 3D. Mapping ensures a meaningful transfer of data between Smart 3D and the rest of the integrated environment.
For more information about mapping, see the SmartPlant Schema Editor User's Guide, available in the SmartPlant Foundation documentation. You can also find more information about mapping in the documentation for each authoring tool.
Adapters
Each authoring tool has an adapter that processes information during the publish and retrieve operations. One of the functions of the adapter is to map information between the particular authoring tool and the SmartPlant schema.
Smart 3D currently has the following adapters:
-
Publish Adapter
-
Retrieve Adapter
-
Metadata Adapter
The publish adapter uses a tool schema file (generated from the Smart 3D Catalog Schema and supplemented with mapping information) and a schema called the P3DComponent schema, which is derived from the SmartPlant schema.
The retrieve adapter for Smart 3D requires that each document type have a registry entry present. These registry entries define the map file used and define callback objects that perform additional processing. It is possible that each document type could have its own map file.
The retrieve adapter uses a map file, which is defined by tool schema files.
The metadata adapter simplifies the process of mapping when you are using the Schema Editor, which is delivered with the SmartPlant Foundation software. This adapter synchronizes the tool map schema with the tool metadata. In Smart 3D, tool metadata is the data in the Catalog Schema database. When you are in the Schema Editor, the Smart 3D metadata is saved when you save the tool schema file (File > Save > Tool Schema File). For more information, see the Schema Editor User's Guide, delivered with SmartPlant Foundation.
Tool Map Schemas (Map Files)
For publish, two map files exist: SP3DPublishMap.xml and Dwgs3dmap.xml. SP3DPublishMap.xml is used for generating the XML data for 3D model data. Dwgs3dmap.xml is used for publishing drawing documents (isometric drawings, orthographic drawings, reports, and Smart 3D model data).
For retrieve, the map file is DesignBasis_map.xml.
The map file for correlating design basis objects with Smart 3D objects is SP3DPublishMap.xml. For more information about correlating in general, see the Common User's Guide, available from Help > Printable Guides.
The following lists the map files delivered and their use for mapping.
-
DesignBasis_map.xml - This file is used during the retrieval of the design basis. It contains mapping relations between SmartPlant objects (classes and interfaces) and the design basis objects (classes and interfaces). This file is generated/updated by running the GenerateDesignBasis command in the Smart 3D Project Management. You MUST use this command to update DesignBasis.xml so that the SCEF Package schema in the Smart 3D catalog is synchronized with this .xml file.
-
P3DComponent.xml and SP3DPublishMap.xml - These files are used to generate XML data for 3D model data during the publishing process. The SP3DPublishMap.xml contains the Smart 3D schema and the mapping relations between Smart 3D objects, such as classes and interfaces (properties, codelists, and relationships), and the 3D SmartPlant objects. The SP3DComponent.xml contains the 3D SmartPlant schema of the data that can be published to the SmartPlant Foundation data warehouse.
-
ExemptCorrelateClasses.xml - This xml file is used to add conditions that cause the correlation basis of an object to be set to 'Ignored' when that object meets the conditions.
The map files are delivered to the SharedContent share folder that is associated with the catalog for the site.
How Mapping is Configured for Publish
If you are working in full integration mode, you can configure the publish mapping in the Schema Editor. You can add new interfaces, properties, select lists, and select list values, and the Schema Editor changes the tool map schema (SP3DPublishMap.xml) and updates the Catalog Schema database accordingly. For more information about the Schema Editor, see the SmartPlant Schema Editor User's Guide, available with SmartPlant Foundation.
If you are working with a model that is not registered (such as when you view your 3D model data in Intergraph Smart Review outside of an integrated environment), you can still edit the tool map schema in the Schema Editor, but you cannot modify the Catalog Schema database directly from the Schema Editor. Instead, you must add the objects to the database using internal development utilities. The net result of the process is that the tool map schema and the Catalog Schema database include the applicable mapping information. For more information about the publish map process, see Maintaining Tool Map Schemas.
During a publish operation, the tool map schema (with added mapping information) and the P3DComponent component schema (derived from the SmartPlant schema) are used to convert Smart 3D objects to SmartPlant integration objects.
How Mapping is Configured for Retrieve
You use the Generate Design Basis tool provided by the Smart 3D software to do the mapping for retrieve. Modification to the map file is automatic and does not require manual editing. The Generate Design Basis tool creates the mapping based on a set of component schemas: EFSchema (also known as SmartPlant schema), PIDComponentSchema, WBSComponentSchema, and so forth. The tool output is a Smart 3D schema package, which is loaded into the Smart 3D Catalog Schema database, and the retrieve map file. For more information about the retrieve map process, see Maintaining Tool Map Schemas.
During a retrieve operation, the map file is used to translate the incoming data into the form defined in the Catalog. For example, attributes in a document are typically passed as strings. The corresponding attribute in Smart 3D could be a string, a long, a double, a select list, or another type. The map file could translate a string such as "TRUE" to the Boolean value True in Smart 3D.
Design Basis Mapping
In the design basis map file, the mapping is not always one-to-one. You can use helper software to assist in mapping. For example, in the SmartPlant schema, NPD is a single property. A helper splits the NPD property into the two properties required by Smart 3D. The helper is designated in the <ConvertPROGID> line in the map file .xml code.
Mapping Enumerated Lists
To use an enumerated list (also called codelist or select list) in an integrated environment that includes Smart 3D, you must map the list in the SmartPlant schema in order for the codelist values to be published or correlated. If the list does not already exist in the SmartPlant schema, then it has to be created there and mapped. If it already exists in the SmartPlant schema, then you must define the mapping between the SmartPlant schema and the tool map schema.
In most cases, enumerated lists in Smart 3D are not mapped in the Schema Editor. These lists use the index number defined in the enumerated definition to map from the tool to the SmartPlant schema. You must ensure that the Number for the enumerated list entry in the SmartPlant Schema matches the codelist numerical value in the 3D catalog. When these values match, list values for mapped properties that use the lists are automatically mapped based on those numbers. When necessary, you may override that default mapping by manually creating a publish relationship between a Smart 3D codelist and an enumerated list entry in the SmartPlant schema.
If the Number for the enumerated list entry in the SmartPlant Schema does not match
the codelist numerical value in the 3D catalog, then you must use the Schema Editor to explicitly map the entries between the SmartPlant
Schema and the Smart 3D catalog.
For example, if you want to add Fluid System values, modify the SmartPlant schema to include the fluid codes that are missing. You can examine the catalog data in the Catalog task or in the Excel .xls files that were bulk loaded to find out which fluid codes to add and their numbers. You must also regenerate the component schemas to create a new P3DComponent.xml file, which is part of the SmartPlant schema. For more information, see Example: Mapping for Retrieve.
For publishing operations and correlation, make the corresponding changes and additions in the publish map file. This process is automated using the metadata adapter within the Schema Editor.
User reference data codes start at 10,000. Values less than 10,000 are reserved for use by Hexagon PPM.
For example, if you are extending an existing list, such as Fluid System, then any
new list entries must be greater than 10,000, less than 40,000 and unique in that
list. However, if you are creating a completely new list, the numbers for the entries
can be anything (no range limit) so long as they are unique in the list.
To map custom enumerated list data type properties at the document level, you cannot use the metadata adapter. You must perform the following using the Schema Editor:
-
Create an SPMapPropertyDef in the Dwgs3DMap.xml file that corresponds to the Smart 3D custom property.
-
Create an SPMapEnumListDef in the Dwgs3DMap.xml file that corresponds to the Smart 3D custom codelist table.
-
Make the new SPMapPropertyDef scoped by the new SPMapEnumListDef.
-
Map the new SPMapPropertyDef and SPMapEnumListDef to the corresponding PropertyDef and EnumListDef in EFSchema.
Other Information about Mapping
You might wonder how the software knows which object corresponds to a property. During a retrieve operation, each object is identified by its UID. A one-to-one relationship exists between an object and its UID. After the object is identified and brought into memory, the mapped properties are stored.
You might also wonder if you can map attributes on the document object itself. This mapping is possible as long as the attributes are defined in both the SmartPlant schema and the Smart 3D Catalog Schema. Typically, a document object implements the IDocument interface in addition to other special purpose interfaces.