How to Control Part Numbers with User Exits

Previously we looked at how to control part numbers with Naming Rules. Naming rules work great for many cases, but they do have limitations. The counters they use to generate a part number when a user clicks the Assign button are limited, and naming rules cannot make any corrections, other than case, of the values entered. Fortunately, they are not the only tool in the Teamcenter administrator’s toolbox. To get to the next level of control over part numbers you can develop your own user exit functions to customize how part numbers are generated and validated. So, let’s review how User Exits work, the types of things you can do with them, and how to customize them.

What is a User Exit?

A User Exit is an ITK function that Teamcenter calls during the course of its operation and which customers can override by writing their own ITK code to replace the default behavior. The user exits functions are prefixed USER_ and are defined in the user_exits.h header file. Some of the ones that are useful as an alternative (or in addition) to naming rules are:

• USER_validate_item_rev_id()
• USER_new_item_id()
• USER_new_revision_id()
• USER_new_dataset_name()
• USER_new_folder_name()
• USER_new_form_name()

USER_validate_item_rev_id() is used to validate the item_id and item_revision_id fields of a newly created item, and the USER_new_* user exits are used to supply a new ID or name value when a user clicks on an Assign button. Note: user exits aren’t just for generating and validating ID and name fields; there are many others besides these that are related to completely different areas of Teamcenter, such as CAE, BOM comparisons, and validation results.

Why Use User Exits?

If you understand how naming rules work already you may be asking why you’d use user exits instead. After all, naming rules already perform the task of validating item_id and item_revision_id, AND you can define counters to generate new IDs upon demand, so what’s so great about user exits?

The answer, is flexibility.

Consider some examples:

1. Your naming authority for issuing new part numbers is something other than Teamcenter. This system has a web service for issuing part numbers. Typically users use a web application to obtain the next available number and then manually key that into Teamcenter. Using a user exit for USER_new_item_id you could automate this process. Your user exit could call the web service, obtain the next part number, and provide that to the user automatically. A naming rule could not do that.
   
2. Dataset names typically default to item_id/revision_id, so if the item ID is 100-20000 and the revision ID is 01, then the dataset is named “100-20000/01″.In Teamcenter Engineering the width of the item ID field was 32 characters, and the width of the dataset name field was… 32 characters. Do you see the Problem? What if the item ID was 30 characters long? Then the default dataset name would be 33 characters wide (30 for the item ID + “/01″ = 33). I have seen this happen while migrating legacy data into Teamcenter; it isn’t pretty.

   A solution is to create your own user exit for USER_new_dataset_name that checks the length of the item ID before generating the dataset name, abbreviating the name if necessary. Note: in Teamcenter 8+ the size of the fields is much larger, 128 characters, so the problem isn’t as likely — but I wouldn’t bet on it not happening
   

3. Besides simply validating the proposed item IDs, USER_validate_item_rev_id also allows you to alter the item ID and either propose the updated ID to the user or force the user to accept it. For example, you could force a mandatory prefix or suffix on all item IDs (do nothing if the user already added it, but add if for them if they didn’t) or you could replace illegal characters, such as replacing all spaces with underscores. All naming rules cand do is convert the ID to either uppercase or lowercase.
   

How to Customize a User Exit

There are two ways to do this:

Option A: Rebuild libuser_exits.dll

You have the option of editing some sample source code files provided with Teamcenter and then recompiling the default user exit shared library, libuser_exits.dll/so/sl. user_part_no.c contains the code for the user exits we’re discussing today. That method is documented in the User Exits module documentation (from the HTML documentation for Teamcenter, Customizing Teamcenter → Integration Toolkit (ITK) Function Reference → Modules → User Exits). If that method appeals to you, go read that. Personally, I don’t like that method at all. For one thing, the source files you edit have a lot in them; more than I’ve ever needed to customize, and I’m afraid of unintentionally altering the behavior of a user exit that’s entirely unrelated to my intended task. Mucking around with a DLL supplied by the vendor just seems like a bad idea to me.

So, I prefer…

Option B: Registering a Custom Replacement Function

In a nutshell, what you do is write your own function to perform the task of the user exit, and then call another ITK function to register your function as a replacement for the user exit. The actual process is very similar to how your go about setting up PDM Server.

1. Pick a name for a customization library. In the examples below I’m using libplmdojo
2. In your preferences, register your customization library by adding its name, without the file extension, to the preference TC_customization_libraries. When Teamcenter starts it will look for the libraries mentioned by this preference and load them.
3. Create the actual user exit library. This is a shared library (i.e. a DLL on Windows) that you write yourself. At a minimum it will contain the functions described below.
4. Within your custom library implement the actual function that will replace the user exit you’re overriding. Example:

   extern "C" // for C++ compilation DLLAPI int PLMDOJO_validate_item_rev_id( int *decision, va_list args) { // whatever you want to do... }

5. A function named your_library_name_register_callbacks(). This function needs to call CUSTOM_register_exit() to register the function defined above as the callback function for USER_invoke_pdm_server.

   // Example: Registering a user exit callback function   extern "C" // for C++ compilation DLLAPI int libplmdojo_register_callbacks() { CUSTOM_register_exit( "libplmdojo", // my library name   "USER_validate_item_rev_id", // the user exit we're customizing   (CUSTOM_EXIT_ftn_t)PLMDOJO_validate_item_rev_id // the callback function );   return 0; }

   When the library is loaded at launch (because it was listed in the TC_customization_libraries preference), the _register_callbacks function is executed. This will make sure that your customizations are registered to be called in place of the default user exit.

6. Within your own function, extract the parameters passed to the callback from the va_listargument using the standard C va_arg() macro. 

   The specific parameter list you’ll expand will match that of the user exit you’re replacing and the way you use them will be the same. So if one of the parameters of the original user exit is an in/out parameter that you can modify, then the corresponding argument of the va_list will also be an in/out parameter that you can modify.

7. Set the decision input parameter to ALL_CUSTOMIZATIONS, ONLY_CURRENT_CUSTOMIZATION, or NO_CUSTOMIZATION, as appropriate.For example, you may just set it to ALL_CUSTOMIZATIONS so that your code is always invoked, or you may do something like check the item type and then set ALL_CUSTOMIZATIONS for engineering types but NO_CUSTOMIZATION for manufacturing types so that they use the default implementation instead.

Addenda

Using Naming Rules and User Exits

Some quick points:

1. You can still attach a naming rule to an item ID if you are providing your own callback function for USER_validate_item_rev_id(); the naming rule will be evaluated after the user exit completes (see the diagram below). This might be useful if you’re primarily using the user exit to modify the input before passing control back to Teamcenter and the naming rule validation.

Sequence of user input, user exits, and naming rule checks during item creation (click to enlarge)

2. There is a NR_ module for using naming rules in ITK, so you can invoke a naming rule from a user exit, which could be used to validate the input against the naming rules and then to modify it if it fails.
3. User exits don’t just work in the Teamcenter user interface. For example, they are invoked by the Assign button in the NX new part dialog as well. I believe (but haven’t verified) that they are called by the ITK function ITEM_create_item when the item_id parameter is NULL. (The documentation states that if the item_id is null that, “the system will automatically generate an Item ID.” I presume that involves calling the user exit and not just a naming rule)

Studying user_part_no.c

Although I don’t like the approach of editing the source files provided with Teamcenter, it is very instructive to study them, especially user_part_no.c. They can be found under %TC_ROOT%/sample. You’ll get a much clearer understanding of how exactly your custom callback functions are invoked by the user exits.

Where Naming Rules Have an Advantage

Before Teamcenter “Unified”, naming rules could only validate a few fields, primarily item and revision IDs. Now, however, naming rules can be attached to pretty much any string attribute, which greatly increases their uses. User exits, however, only exist for a few specific fields.

The post How to Control Part Numbers with User Exits appeared first on The PLM Dojo.