PLMXML Custom Import/Export Extensions

The goal of this document is to discuss the different extension points available to the developer when
importing or exporting a PLMXML file in Teamcenter and provide a walkthrough example in how to
implement these extensions.

The option to import and export PLMXML files provides a wide array of extension points for a user to
take advantage of. The follow customization points are available:

Business Operation name ITK PIE registration Description

Object (as listed in the BMIDE) function
PLMXML BMF_PLMXML_register_filter PIE_register_user_filter Allows you to register custom filter rules used during
import/export. For this extension point to be called
you need to define a FilterRule in PLMXML
Administrator and use the filter in the TransferMode
definition. This function is called every time the
specific object of interest is encountered.
PLMXML BMF_PLMXML_register_actions PIE_register_user_action Allows you to register custom pre, during, and post
action rules used during import/export. For this
extension point to be called a ActionRule must be
defined in PLMXML Administrator and then use the
Action in the TransferMode definition.
PLMXML BMF_PLMXML_register_export_methods PIE_register_user_methods Allows the user to register custom export methods.
This function will override the existing OOTB export
method and will be called if the specific Context is
used. This function will need to provide necessary
export code for the mapped object.
PLMXML BMF_PLMXML_register_import_methods PIE_register_user_methods Allows the user to register custom import methods.
This function will override the existing OOTB import
method and will be called if the specific Context is
used. This function will need to provide necessary
import code. (currently, very limited)
PLMXML BMF_PLMXML_register_schema_mappings PIE_register_user_schema Allows you to map Teamcenter and PLM XML
objects. Only applicable in Export. Import mapping
uses PLMXML attribute subType.

Following is the order user extensions are called when exporting a PMLXML file:

pre-action

export process
filters
user methods

during-action (PLMXML file not save and XML document still loaded)

xslt (optional)

post-action
Following is the order user extensions are called when importing a PMLXML file:

pre-action
xslt (optional)
load/parse the PLM XML document
during action
import process
filters
user methods
post action

To begin, it is assumed you have created a BMIDE project using the “foundation” template. The project
name used in this example is, “PLMXMLUserExt” and uses a prefix string of, “G4”.

BMIDE PLMXML Extension setup

We start by creating a new Library:

Add the “pie” dependency because it will include the need PLMXML library.

Next, in the Extension view, select Rules->Extensions, right click on Extensions and click “New Extension
Definition…”
Provide an Extension name of “G4PLMXMLUserExt” and click the “Add” button to the right of
Availability. Populate the New Extension Availability dialog:

Likewise, add a new Extension Availability for Filters and Export methods.

Once finished, the new Extension Definition dialog should look as follows:
Clicking Finish the Extension View should update showing the new Extension:

Next, expand the User Exits in the Extension view and double click on “PLMXML.”

Select BMF_PLMXML_register_actions and add the “G4PLMXMLUserExt” to the Base-Action List.

Likewise do the same for Filter registrations and Export methods.

The meta data model requirements for Import/Export Extensions is now complete.

Save the DataModel by doing File->Save Data Model.

BMIDE PLMXML Extension Code generation

To generate the need extension ‘C’ code, select the “G4PLMXMLUserExt” from the Extension View and right click,
“Generate extension code…”

In the Navigator View, select the root project node and press F5 to refresh the project.

If you expand the output/server/gensrc/G4PLMXMLUserExt folder you should see the auto generated
G4PLMXMLUserExt.c & .h file. Open the G4PLMXMLUserExt.c file.

In the .c file you will see a function similar to:

int G4PLMXMLUserExt(METHOD_message_t *msg, va_list args)

{
return 0;
}

In this function we want to call the PLMXML registration code.

Update the G4PLMXMLUserExt.c as follows:
#include <pie/pie.h>
#include <tccore/tctype.h>

#include <G4PLMXMLUserExt/G4PLMXMLUserExt.h>

#define CUSTOM_PIE_CONTEXT_STRING "CUSTOM_PIE_CONTEXT_STRING"

int G4PLMXMLUserExt( METHOD_message_t *msg, va_list args ) // ignore argument list.

{
PIEUserMethodList_t userMethodList[] = {
{CUSTOM_PIE_CONTEXT_STRING, "ProductRevision", (PIE_user_method_func_t)G4UserImportExtension}, // PLMXML classname.
{CUSTOM_PIE_CONTEXT_STRING, "ItemRevision", (PIE_user_method_func_t)G4UserExportExtension} }; // Teamcenter classname.

printf("G4PLMXMLUserExt registration\n");

/* user actions */
PIE_register_user_action("GTACCustomExportPreAction", (PIE_user_action_func_t)G4PreExportExtension);
PIE_register_user_action("GTACCustomExportDuringAction", (PIE_user_action_func_t)G4DuringExportExtension);
PIE_register_user_action("GTACCustomExportPostAction", (PIE_user_action_func_t)G4PostExportExtension);

/* filters */
PIE_register_user_filter("GTACCustomFilterRule", (PIE_user_filter_func_t)G4FilterExtension);

/* (override) import/export methods */

PIE_register_user_methods(userMethodList, 2);

return 0;
}

PIE_rule_type_t G4FilterExtension(void* userPath)

{
tag_t tag = NULLTAG;
tag_t type_tag = NULLTAG;
char type_name[TCTYPE_name_size_c + 1] = { 0 };

printf("G4FilterExtension\n");
PIE_get_obj_from_callpath(userPath, &tag);

TCTYPE_ask_object_type(tag, &type_tag);
TCTYPE_ask_name(type_tag, type_name);

printf("Filter Object Type: %s\n", type_name);

return PIE_process; // or skip

}

int G4PreExportExtension(tag_t session)

{
printf("G4PreExportExtension\n");

// .xslt file used to beautify PLMXML file for easy reading.

PIE_session_set_user_xslt_file(session, "C:\\TCU83\\dev\\xslt\\prettyprint.xsl");
return 0;
}

int G4DuringExportExtension(tag_t session)

{
printf("G4DuringExportExtension\n");
return 0;
}

int G4PostExportExtension(tag_t session)

{
printf("G4PostExportExtension\n");
return 0;
}

int G4UserImportExtension(void* userPath)

{
printf("G4UserImportExtension\n");
return 0;
}

int G4UserExportExtension(void* userPath)

{
printf("G4UserExportExtension\n");
return 0;
}

Update G4PLMXMLUserExt.h as follows:

extern G4PLMXMLUSEREXT_API PIE_rule_type_t G4FilterExtension(void* userPath);

extern G4PLMXMLUSEREXT_API int G4PreExportExtension(tag_t session);

extern G4PLMXMLUSEREXT_API int G4DuringExportExtension(tag_t session);
extern G4PLMXMLUSEREXT_API int G4PostExportExtension(tag_t session);

extern G4PLMXMLUSEREXT_API int G4UserImportExtension(void* userPath);

extern G4PLMXMLUSEREXT_API int G4UserExportExtension(void* userPath);
extern G4PLMXMLUSEREXT_API int G4PLMXMLUserExt(METHOD_message_t* msg, va_list args);

Save the source files and do a Project->Build All. Your project should build without errors.

Argument overview

PIE_register_user_methods

The PIEUserMethodList_t structure is defined in header pie/pie.h and is defined as follows:

typedef struct PIEUserMethodList_s

{
const char *contextStr; /* Context String */
const char *name; /* Class or type name */
PIE_user_method_func_t func; /* User method */
} PIEUserMethodList_t;

contextStr: A unique string and the string value is entered in the “Context” field in TransferMode
definition. This string allows the user to group user-methods with different names for a given context.

name: This string maps an import/export method to a specific Teamcenter Object or PLMXML element.

For example:
Names used in Export user-methods Names used in Import user-methods
Teamcenter objects PLM XML element
Item ProcessorProduct
Item Product
Item Software
ItemRevision ProcessorProductRevision
ItemRevision ProductRevision
ItemRevision SoftwareRevision

A full list of schema mappings is available in the PLM XML Export Import Administration Guide in
the PLM XML/Teamcenter entity mapping section.

func: A function pointer that has a function signature of:

int foo_method(void* userPath)

The userPath argument can be used in any of the PIE_* ITK functions that takes a void* named
“userPath”. Please see the Integration Toolkit (ITK) Function Reference documentation for a full listing of
available PIE functions.

The function body will generally use the PLMXML SDK to implement the writing or reading of the PLMXML
document. The details of this implementation however are beyond the scope of this document.
PIE_register_user_filter

filterRuleName: A unique string that will be displayed in the FilterRule, Filter Rule Name, drop down list.

user_m: A function pointer that has a function signature of:

PIE_rule_type_t foo_filter(void* userPath)

The userPath argument can be used in any of the PIE_* ITK functions that takes a void* named
“userPath”. Valid return values are defined in the PIE_rule_type_e enum (pie/pie.h):

typedef enum PIE_rule_type_e

{
PIE_skip = 1,
PIE_process = 2,
PIE_travers_no_process = 4,
PIE_travers_and_process = 6
} PIE_rule_type_t;

PIE_register_user_action

handleName: A unique string that will be displayed in the ActionRule, Action handler, drop down list

user_m: A function pointer that has a function signature of:

int foo_action(tag_t session)

The session tag_t can be used in any of the PIE_* ITK functions that takes a tag_t session. Please see the
Integration Toolkit (ITK) Function Reference documentation for a full listing of available PIE functions.

BMIDE Template Deployment

If your project built successfully you are now ready to deploy the project.

In the Extension View, right click the root node and click, Deploy Template…
Enter the User ID and Password and click “Connect.” When the connection is established, click “Finish.”

As the deployment is processing you should see similar out to your TAO window:

When the deployment is completed you should get the following confirmation dialog:
We are done with the BMIDE.

Loading the Custom Extension DLL

In order to load the custom DLL the user needs to set BMF_CUSTOM_IMPLEMENTOR_PATH preference.

Do so with the Edit->Options…

For the preference setting to take effect exit and restart the RAC.
PLM XML Export Import Administration Application

Once RAC has started, open the “PLM XML Export Import Administration Application.”

Click on “ActionRule” in lower left pane.

Enter the “Action Rule Name”, set the “Scope of Action” to Export, “Location of Action” to “Pre Action”, and the
drop down list for Action Handler should list, “GTACCustomExportPreAction”. Once complete, click the “Create”
button to create the new Action Rule object.

Likewise, create an Export Action for “During” and “Post” action extensions.

Click on “ClosureRule”.
Enter the Traversal Rule Name of “GTACCustomClosureRule”, select Export for Scope and PLMXML for Output
Format.

Click the “+” button on the right to create a new row and populate the row as shown.

Click “Create” button when done to create a new “ClosureRule” object.

Click on “FilterRule”.
Enter “GTACItemRevExportFilter” for the Filter Rule Name, select Export for Scope and PLMXML for Output
Format.

Click the “+” button on the right to create a new row and populate the row as shown. The “GTACCustonFileRule”
should be listed in the Filter Rule Name drop down list.

Click “Create” button when done to create a new FilterRule object.

Click on TransferMode.
Enter “GTACCustomExport” for the name, set Export for the Transfer Type, PLMXML for the Output Format, for the
Closure Rule select “GTACCustomClosureRule”, for Filter Rule select “GTACItemRevExportFilter” and in the Action
list move the actions using the “+” button.

Click “Create” button when done to create a new “TransferMode” object.

Export a PLMXML File

Create a new Item called “Export”

From the top menu, click, Tools->Export->Objects…

Clicking on “OK” should generate the following output in the TAO window showing the call sequence of PLMXML
extensions:

The Exporting of the Item and ItemRevision should look similar to the XML file below:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- GENERATED BY: PLM XML SDK 7.0.2.173 -->
<PLMXML xmlns="http://www.plmxml.org/Schemas/PLMXMLSchema" schemaVersion="6" language="en-us" date="2011-06-03" time="10:45:32" author="Teamcenter
V8000.3.0.20100916.00 - gtac@IMC--2118502821(-2118502821)">
<Header id="id1" traverseRootRefs="#id2" transferContext="GTACCustomExport"/>
<ProductRevision id="id6" name="Export" accessRefs="#id3" subType="ItemRevision" masterRef="#id2" revision="A">
<ApplicationRef version="wJC1OqqpYs6Y1C" application="Teamcenter" label="wFJ1OqqpYs6Y1C"/>
</ProductRevision>
<Product id="id2" name="Export" accessRefs="#id3" subType="Item" productId="000025">
<ApplicationRef version="wFJ1OqqpYs6Y1C" application="Teamcenter" label="wFJ1OqqpYs6Y1C"/>
</Product>
<AccessIntent id="id3" intent="reference" ownerRefs="#id4"/>
<Site id="id4" name="IMC--2118502821" siteId="-2118502821">
<ApplicationRef version="wxPxfJW5Ys6Y1C" application="Teamcenter" label="wxPxfJW5Ys6Y1C"/>
<UserData id="id5">
<UserValue value="1" title="dbms"/>
</UserData>
</Site>
</PLMXML>

The OOTB schema mapping is “Product” to “Item” and “ProductRevision” to “ItemRevision”

Remarks

PIE_register_user_schema:

PIE_register_user_schema is designed to alter the export schema mapping of Teamcenter properties to

PLMXML element attributes. It is not used in the case of import. Each PLMXML element has a limited set
of attributes available for use, for example; PLMXML element “Product” has the following defined
attributes:

id checkoutRefs productId
name subType alternateForRef
nameRef effectivityRefs unitRef
descriptionTextRef releaseStatusRefs designRequired
attributeRefs catalogueId source
accessRefs optionRefs vendorRef
statusRef propertyRefs

Attempting to map PLMXML attributes not listed will have no effect. For more information in regards to
other PLMXML elements and their available attributes please see the PLMXML SDK documentation.

To map Teamcenter custom user properties into the PLMXML file use a PropertySet. A PropertySet will
place Teamcenter user properties within a PLMXML <UserData>…</UserData> element structure. Please
see the PLM XML Export Import Administration Guide for more information about PropertySets.
TransferMode Context

You may have noticed that the “Context” field was left blank. This was intentional. By entering the
Context string used in the PIEUserMethodList_t, CUSTOM_PIE_CONTEXT_STRING this will use user
defined method extensions to export or import a specific Teamcenter business object or PLMXML
element respectively. Because the body of our ItemRevision method extension is empty the data will not
be exported. You would export the data using the PLMXML SDK which is unfortunately beyond the scope
of this document.

XSLT

The XSLT option provides the option to translate a PLMXML file before import or after export. In the
sample code for function G4PreExportExtension you for will find the following code to set the XSLT file:

PIE_session_set_user_xslt_file(session, "C:\\TCU83\\dev\\xslt\\prettyprint.xsl");

This function will set the XSLT file for both import and export. If you wish to set the XSLT file for a
TransferMode object without using customization, use command line utility plmxml_tm_edit_xsl.
Please see the Utilities Reference manual for more information.
 Sample pretty-print XSLT files are available on the internet. Use your favorite internet search engine and
search for “XSLT pretty print”.

The XSLT processor is invoked by the PLMSDK.

Here are some links that I found useful for pretty-print output:

http://www.printk.net/~bds/indent.html
http://www.xml.com/pub/a/2006/11/29/xslt-xml-pretty-printer.html?page=1

Ver: 1.3
Patrick Hoonhout
GTAC Support