Integration definition file

Every integration of an external tool that is done using the MBSE Integration Services must have an integration definition file. Configuration of the integration definition file is mandatory for the following SOAs:

• exportCollection()
• importCollection()
• updateCollection()

The integration definition file provides a way to configure mapping of tool artifacts and its metadata to Teamcenter business objects and properties. This integration definition file is one per tool. It is stored in a dataset with name APPLICATION_NAME_BHM_INT_DEF_FILE, where APPLICATION_NAME is a unique identifier name for a tool that is being integrated. The dataset must have administrative control.

Definition of unique application name

Every tool that gets integrated with Teamcenter is identified uniquely by the integration gateway. This information is provided by the integrators in the integration definition file as follows:

<?xml version="1.0" encoding="utf-8"?>
<BHMIntegration xmlns="http://www.plmxml.org/Schemas/bhm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.plmxml.org/Schemas/bhm" applicationName="ECAD">

When various operations are performed, the integrator has to provide the value from the attribute applicationName as input.

Definition of the connector class

The integration gateway is executed in two modes:

• Push: In this mode, the integrating tools extract the model data and pushes this extracted data to the modeling gateway using the published APIs. This is typically done when the tool adapter or connector is an integral part of the tool.
• Pull: In this mode the integration gateway pulls the model data by invoking APIs published by the tool specific adapter or connector. The information related to the tool specific adapter or connector to be used is provided in the integration definition file. The pull mechanism is useful when bulk operations are to be performed for importing the modeling data from various modeling tools within a given modeling project.

The details of the connector are given in the integration definition file as follows:

<ConnectorClass fullName="com.teamcenter.behaviormodeling.matlabint.MatlabConnector" jarFilePath="" />

Definition of the containers

Every modeling tool has at least two types of artifacts: a parent which acts like a container and a child which acts like a component within the container.

The container, when the model data is exported to Teamcenter from the modeling tool, is always represented in Teamcenter as an instance of some business object type. It can be a classic business object like Item or an object like dataset that holds the files or any generic workspace or POM object. In the modeling tool some containers may have children which are termed as components. When the model data is imported in Teamcenter these components are translated into instances of relationship. These relationships could be GRM, BVR or just a typed reference property on the container or a back pointer on the child container. Thus, container is considered as some business object type to be created in Teamcenter and component as some relationship. The integration definition file facilitates defining various containers from the modeling tool and its mapping to corresponding Teamcenter business object type.

In the GolfCart example GolfCart, Battery, MotorDrive, OutPort, Inport, PowerSupply all are containers.

The following code sample is a definition of a container. For each type, you must define ObjectMapping. Mapping for a parent type is not automatically applicable to its sub-types.

GolfCart, Battery, MotorDrive all are treated as containers by the Integration Gateway. If they are of type Model in the tool, they are mapped to the Teamcenter business object Item as follows:

<ObjectMapping type="Model" behaviorType="BVR" tctype="Item">

If the InPort and OutPort containers are of type port in the modeling tool they are mapped to Teamcenter business object GeneralDesignElement.

<ObjectMapping type="port" behaviorType="MIXED" tctype="GeneralDesignElement">

If physical model file of GolfCart that is generated by the tool is GolfCart.zip then it can be stored in a Teamcenter business object of type Zip and is mapped as follows:

<ObjectMapping type="Design" behaviorType="MIXED" tctype="Zip">

where:

• ObjectMapping corresponds to the definition of a container which maps type of tool artifact to Teamcenter business object type.

ObjectMapping attributes:

• type is the type of container or artifact in the modeling tool.
• tcType is the type of business object in Teamcenter representing the container.
• behaviorType is the type of association between an object corresponding to the ObjectMapping and the object corresponding to the BHMElement. It can be overridden at the component level as explained in the component definition section. It may have one of the following values:
  • BVR — if all the components are BVR occurrences.
  • GRM — if all the components are associated with GRM relations.
  • GBVR — if all the components are of GBVR type.
  • REF — if all the components are of REF type.
  • MIXED — if components are associated with more than one type of behaviorType such as BVR, GRM, REF, or GBVR.

Definition of all the components

Within a modeling tool a container can contain various types of components.

Each of these components are usages of some container or artifact from the tool. A component represents an association between two containers. In the integration definition file BHMElement is used to configure this association.

<ObjectMapping type="Model" behaviorType="MIXED" tctype="Bhm0BehaviorModlItem">
  <BHMElement type="Model" tctype="Item" behaviorType="BVR">

  <BHMElement type="Design" tctype="Zip" behaviorType="GRM" reltype="IMAN_specification" reftype ="Design" isPrimary="false" isPrimaryAnchor="false" isSecondaryAnchor="false">

  <BHMElement type="port" tctype="GeneralDesignElement" behaviorType="GBVR">
</ObjectMapping>

where:

• BHMElement configures the component, that is the association between two containers or ObjectMapping.
• type is the component type from the modeling tool.
• behaviorType is the association definition with its components.

It may have one of the following values:

• BVR — If there is a parent-child (occurrence) association between the object corresponding to the ObjectMapping and the object corresponding to the BHMElement. The object corresponding to the ObjectMapping is parent and the object corresponding to the BHMElement is a child. When behaviorType is BVR, value of relType is not required because a Teamcenter object of type PSOccurrence is automatically created to associate the parent and the child object.

  For example, GolfCart and Battery containers of type Model are represented by the Teamcenter business object item. These containers have a parent-child association where GolfCart is a parent and Battery is a child.

• GRM — If there is a GRM relation between the object corresponding to the ObjectMapping and the object corresponding to the BHMElement. The relation object is a subtype of ImanRelation. Any relation object has one primary object and one secondary object. By default, the container object corresponding to the ObjectMapping is the primary object and the container object corresponding to the BHMElement is the secondary. This can be changed by configuring the isPrimary value.

  By default, the relation is created between the revisions of the objects. You can override this behavior by configuring the isPrimaryAnchor and isSecondaryAnchor values.

• GBVR — If the object corresponding to the BHMElement is a port object.

• REF — If the object corresponding to the BHMElement is associated with a container object corresponding to ObjectMapping through a referenced property.

• relType defines the relation between the container corresponding to ObjectMapping and the container corresponding to BHMElement. It is a subtype of the Teamcenter business object ImanRelation.

• isPrimary — This is an optional input. It is valid only if behaviorType is GRM. Every GRM relation has one primary object and one secondary object. If value of isPrimary is true, then the object mapped in BHMElement is primary. If value of isPrimary is false, then the object mapped in ObjectMapping is primary.

• isPrimaryAnchor — This is an optional input. It is valid only if behaviorType is GRM. Every GRM relation has one primary object and one secondary object. If value of isPrimaryAnchor is true, then item of the primary object is associated with the secondary object. If value of isPrimaryAnchor is false or not set, then item revision of the primary object is associated with the secondary object.

• isSecondaryAnchor — This is an optional input. It is valid only if behaviorType is GRM. Every GRM relation has one primary object and one secondary object. If value of isSecondaryAnchor is true, then item of the secondary object is associated with the primary object. If value of isSecondaryAnchor is false or not set, then item revision of the secondary object is associated with the primary object.

The following are possible combinations of isPrimaryAnchor and isSecondaryAnchor values and its result on the primary object and secondary object while creating a GRM relation:

isPrimaryAnchor	isSecondaryAnchor	Container object corresponding to ObjectMapping	Container object corresponding to BHMElement
false/empty/absent	false/empty/absent	ItemRevision	ItemRevision
false/empty/absent	true	ItemRevision	Item
true	false/empty/absent	Item	ItemRevision
true	true	Item	Item

Definition of attribute mapping

Attribute mapping provides a way to map tool side metadata to properties on Teamcenter business objects. The integration definition file provides attribute mapping capability at the container as well as component level which translates to attributes on the Teamcenter business object as well as on the Iman_relation or Occurrence. For example, when an integrating tool artifact is represented by a Teamcenter business object such as item, then the artifact name can be stored in the object_name property on item. The integration definition file provides a way to configure this mapping of artifact name to the object_name property of the item.

When the AttributeMapping is inside the BHMElement and if the type value of BHMElement is RootModel then the mapped attributes are on the Container object else they are on the association object — GRM relation or BVR occurrence.

<AttributeMappings>
      <AttributeMapping name="Description" tcattr="object_desc"/>
      <AttributeMapping name="cifContainerIdentifier" tcattr="Cif0ToolSpecificIntInfo::cif0ToolProperties"/>
      <RevisionAttributeMapping>
        <AttributeMapping name="Description" tcattr="object_desc"/>
                        <AttributeMapping name="FormDescription" tcattr="Form::object_desc"/>
                        <AttributeMapping name="cifContainerIdentifier" tcattr="Cif0ToolSpecificIntInfo::cif0ToolProperties"/>
                        <AttributeMapping name="ExtraMetaData1" tcattr="Cif0ToolSpecificIntInfo::cif0ToolProperties"/>
      </RevisionAttributeMapping>
    </AttributeMappings>

where:

• name is the name of model property from the modeling tool.
• tcattr is the name of the attribute name on the corresponding mapped Teamcenter business object.

Property on Form object is prefixed with Form::. This functionality supported only by Common Integration Framework SOAs. If there is some extra information that needs to be stored but cannot be mapped to any of the properties on a Teamcenter object it is configured as Cif0ToolSpecificIntInfo::cif0ToolProperties. This functionality supported only by Common Integration Framework SOAs.

Mapping cifContainerType as Cif0ToolSpecificIntInfo::cif0ToolProperties is mandatory if multiple ObjectMapping::type are mapped to single ObjectMapping::tctype.

Integrators can map multiple attributes. The attribute mapping is supported at the Item, ItemRevision and Form level for an item type of object.

Define and map stereotypes

In modeling tools, a stereotype is a mechanism that lets you add custom metadata to extend the standard properties of an element.

When your external tool uses stereotypes or when attributes of the external tool do not have an existing counterpart in the Teamcenter data model, you can use stereotypes.

You map the stereotype attribute with the external tool attribute at the component level in the BHMElement as follows:

<BHMElement type="xxx" tctype="yyy">
    <AttributeMappings>
        <AttributeMapping name="External-tool-attribute-1" tcattr="Cif0StereoTypeData::cif0ToolInfoOccData" />
        <AttributeMapping name="External-tool-attribute-2" tcattr="Cif0StereoTypeData::cif0ToolInfoOccData" />
    </AttributeMappings>
</BHMElement>

Map the external tool attribute to the stereotype attribute Cif0StereoTypeData::cif0ToolInfoOccData.

Example:

<BHMElement type="Block" tctype="Fnd0LogicalBlock" behaviorType="BVR" reltype="" reftype ="Block" toolReltype="Block">
    <AttributeMappings>
        <AttributeMapping name="FS.BitSize" tcattr="Cif0StereoTypeData::cif0ToolInfoOccData" includeinduplicatecheck="false" direction="ToolToTc"/>
        <AttributeMapping name="FS.Category" tcattr="Cif0StereoTypeData::cif0ToolInfoOccData" includeinduplicatecheck="false" direction="ToolToTc"/>
        <AttributeMapping name="FS.Dictionary Message Name" tcattr="Cif0StereoTypeData::cif0ToolInfoOccData" includeinduplicatecheck="false" direction="ToolToTc"/>
        <AttributeMapping name="FS.Dictionary Message Revision" tcattr="Cif0StereoTypeData::cif0ToolInfoOccData" includeinduplicatecheck="false" direction="ToolToTc"/>
        <RevisionAttributeMapping/>
    </AttributeMappings>
</BHMElement>

Definition of file mappings

In most of the integrations there are many different types of files that need to be imported and associated to the container objects in Teamcenter. Integration definition file supports mapping the file extension type to different dataset types and named reference in Teamcenter. These file mappings generate read tickets necessary for downloading files from Teamcenter datasets.

<FileMapping>
	<FileMap fileExt="txt" tcDatasetType="Text" tcNameReferencedType="Text" />
	<FileMap fileExt="png" tcDatasetType="Image" tcNameReferencedType="Image" />
	<FileMap fileExt="html" tcDatasetType="HTML" tcNameReferencedType="HTML" />
	<FileMap fileExt="jpg" tcDatasetType="JPEG" tcNameReferencedType="JPEG_Reference" />
	<FileMap fileExt="zip" tcDatasetType="Zip" tcNameReferencedType="ZIPFILE" />
	<FileMap fileExt="tif" tcDatasetType="TIF" tcNameReferencedType="TIF_Reference" />
	<FileMap fileExt="gif" tcDatasetType="GIF" tcNameReferencedType="GIF_Reference" />
	<FileMap fileExt="*" tcDatasetType="MISC" tcNameReferencedType="MISC_TEXT" />
</FileMapping>

where:

• fileExt is the file extension.
• tcDatasetType is the type of dataset that shall contain this file.
• tcNameReferencedType is the type of named reference within a dataset that should be used to associate the file to the dataset.

When a dataset contains named references that match the defined tcNameReferencedType in the file mapping, Teamcenter generates appropriate read tickets and downloads the corresponding files. If file mappings are absent or incorrectly specified, no read tickets are generated, preventing file downloads.

Definition of standard folders

Many times, a system is managed as modeling project that contains various different models as a part of that project. Each project has standard folder structure and has standard output or generated files residing in some standard folders. Many times, when the models are saved to Teamcenter this derived information has to be saved and associated to the model in Teamcenter. This configuration provides a facility for the integrators to specify such standard folders so that the integration gateway automatically imports all the files in these standard folders in Teamcenter and associates it to the model object.

<OrganizationData>
  <Folder name="MODELFOLDER" tcRelation="TC_References"/>
</OrganizationData>

where:

• name is the name of the standard folder. MODELFOLDER is keyword indicating the model in which model file is residing.
• tcRelation specifies the type of IMAN_Relation to be used to associate the files from this folder to the model object

Definition of extension points

The integration operations exhibit a certain behavior. This behavior may or may not cover all the use cases of the integration. Hence the integration gateway supports extending these operations on the client side by providing extension points on all the supported operations of save, open and update. The extension points are of three types:

• PRE-CONDITION: Executed before the base operation begins. If this extension fails, the operation fails.
• PRE-ACTION: Executed after the pre-condition but before the base operation. If this extension fails, the error is logged in log file but the operation proceeds.
• POST-ACTION: Executed after the base operation execution is complete. If this extension fails, the error is logged in log file but the operation proceeds.

The extension can be implemented as JAVA code, batch file or in tool native language.

<Extensions>
    <Extension operationName="SAVE" extensionPoint="PRE_CONDITION" >
    <Impl type="SCRIPT" location="" name="SAVE_PRE_CONDITION" />
    </Extension>
    <Extension operationName="SAVE" extensionPoint="PRE_ACTION" >
    <Impl type="BATCH" location="D:\temp" name="RunMe.bat" />
    </Extension>
    <Extension operationName="SAVE" extensionPoint="POST_ACTION" >
    <Impl type="JAVA" location="" name="com.teamcenter.matlabcustom.SaveCustom" />
    </Extension>
</Extensions>

where:

• operationName is the name of the operation for which the extension point is being defined. It can be SAVE, OPEN, or SAVEAS.
• extensionPoint is type of extension point such as PRE_CONDITION, PRE_ACTION, or POST_ACTION.
• type is the type of implementation.
• location is the location on file system where the jar, script, or batch file that implements this extension resides.
• name is the name of the class or file that actually implements the extension.