PLMXML Custom Import/Export Extensions

Transcription

1 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

2 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

3 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:

4 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.

5 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:

6 #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);

7 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 Teamcenter objects Item Item Item ItemRevision ItemRevision ItemRevision Names used in Import user-methods PLM XML element ProcessorProduct Product Software ProcessorProductRevision ProductRevision 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.

8 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

9 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:

10 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.

11 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.

12 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.

13 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.

14 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.

15 Export a PLMXML File Create a new Item called Export From the top menu, click, Tools->Export->Objects

16 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 "?> <!-- GENERATED BY: PLM XML SDK > <PLMXML xmlns=" schemaversion="6" language="en-us" date=" " time="10:45:32" author="teamcenter V gtac@imc ( )"> <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 " siteid=" "> <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

17 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.

18 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.

19 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: Ver: 1.3 Patrick Hoonhout GTAC Support