InfoSphere Data Architect Pluglets Macros for Eclipse This article provides information on how to develop custom pluglets and use sample pluglets provided by InfoSphere Data Architect. InfoSphere Data Architect Pluglets Introduction IBM InfoSphere Data Architect (IDA) is a comprehensive development environment for data modeling and integration. IDA enables users to discover, model, visualize, and relate diverse and distributed data assets. Pluglet support was added to IDA when users requested a sort of "macro" that would allow them to do repeatable tasks easily. Pluglet support provides a method to do many things. You can use them to automate common tasks and task flows or even execute tasks in bulk, similar to a batch mode. They also provide a way for you to customize existing product functions and add specialized functionality to better work with your data modeling environment. If you think the product is missing something in your workflow, you can add pluglets to accomplish those tasks. Getting Started In order for you to see the sample pluglets, you will need to check the Pluglet Support option at install time. The install option for pluglets isn't selected by default when installing IDA. If you've already installed IDA, you will have to uninstall and reinstall the product and make that selection or use the modify option of Installation Manager to add that option. Copyright IBM Corporation Trademarks InfoSphere Data Architect Pluglets Page 1 of 15
developerworks ibm.com/developerworks/ Figure 1. Pluglet Install Option Sample pluglets Once you have IDA installed with Pluglet support, you can take a look at the sample pluglets that are shipped with the product. You can run the sample pluglets in order to see what they do and learn a little more about how they work. You can also take a look at the source code for the sample pluglets to aid in developing your own. Running Sample pluglets A "Run Pluglet" menu is supplied with IDA in order to easily run the samples as well as any pluglets you add. In order to access this menu, you need to have an item selected in the Data Project Explorer. In this example, a Physical Data Model is selected. InfoSphere Data Architect Pluglets Page 2 of 15
ibm.com/developerworks/ developerworks Figure 2. Run Pluglet Menu You can see that there are submenus displayed. The sample pluglets are classified within the following task groups. Only those groups which have samples that apply to the object you selected will be displayed. Deployment Tasks Diagram Tasks (IE notation diagrams only, not UML diagrams) Model Navigation Tasks Model Tasks Reporting Tasks When you create and Register your own pluglets, they will appear under Custom Tasks, unless you assign them to one of the existing task groups above. Samples The following sample pluglets are installed when you select the Pluglet Install option mentioned previously. They are categorized into the task groups. Next to the pluglet name, you can see where each pluglet is enabled. For instance, if I want to run the pluglet to "Update Selected Entities Attributes Domain Data Types", I need to make sure an entity is selected in the workspace. More in-depth information on each pluglet is included at the end of this document. Deployment Tasks - Generate DDL Per Data Object Type (enabled on: PDM) Diagram Tasks - Apply Supertype Style (enabled on: logical diagram) - Change Non-Persistent Attribute Color (enabled on: logical diagram) Model Navigation Tasks InfoSphere Data Architect Pluglets Page 3 of 15
developerworks ibm.com/developerworks/ - Select Objects By Name (enabled on: DPE or diagram (IE notation) Model Tasks - Change Owning Schema For All Indexes/ ~ Tables / ~ Views (enabled on: PDM or database(luw/z) ) - Change Owning Schema for Selected Objects (enabled on: tables, views, indexes) - Change Table Space For All Tables (enabled on: PDM or database - LUW/Z) - Export/Import Model Object Properties (enabled on: database) - Fix Broken References from Model Rename (enabled on: PDM or LDM) - Name Indexes (enabled on: PDM, database, schema) - Remove All Auxiliary Tables (enabled on: physical data model, database, schema, DB2 forz) - Set Default Values (enabled on: tables, columns) - Set Attributes of Selected Entities to Required (enabled on: entities) - Set Selected Tables Columns Not Nullable (enabled on: base tables not Views, MQTs) - Update Foreign Key Documentation from Primary Key (enabled on: entities, base tables not Views, MQTs) - Update Selected Entities Attributes Domain Data Types (enabled on: entities) - Update Selected Entities Group Attributes References (enabled on: entities) Reporting Tasks - Calculate Table and Column Length (enabled on: PDM, database - LUW/Z) Sample pluglet source The source code for the sample pluglets is shipped as a part of IDA to assist in the development of pluglets. The plug-ins that contain this information are as follows: com.ibm.datatools.pluglets.samples Sample pluglets and the source code com.ibm.datatools.pluglets.tasks Common tasks and dialogs (APIs) com.ibm.datatools.pluglets.ui UI integration ('Run Pluglet' menu) If you want to take a look at the source for a particular pluglet, you can do that by doing the following. From the run menu in the Java perspective, select to set up Internal Tools Configurations. Figure 3. Internal Tools Configuration menu option On the left side of the dialog, right-click on Pluglet and create a new configuration. Once you see this screen, click on "Browse Samples" to see the pluglets available for you to examine: InfoSphere Data Architect Pluglets Page 4 of 15
ibm.com/developerworks/ developerworks Figure 4. Internal Tools Configuration You can browse the sample source and select one of the samples to edit. In the example below, "ChangeSelectedObjectsOwnerPluglet" is selected. Figure 5. Sample Pluglet When you have selected a pluglet and clicked OK, you will see that a location has been filled in for you. At this point, you can select to edit the pluglet by clicking "Edit Pluglet". Figure 6. Edit Pluglet If you have never created a pluglets project, you will be presented with this dialog. If you already have a project, continue on to view the source code in Figure 9. Figure 7. Edit Pluglet - Message Dialog Click "Yes" on this dialog to create a sample pluglets project. You will be presented with this dialog to give your Project a name. InfoSphere Data Architect Pluglets Page 5 of 15
developerworks ibm.com/developerworks/ Figure 8. New Pluglets Project Dialog Once your project is created, you will see some pluglet source. You can scroll through the source for that particular sample pluglet and get a better idea of how it works and what you might need to do to create your own pluglet. Figure 9. Sample Pluglet Source You can also import the sample pluglet source to have the source for all sample pluglets in your workspace. From the Java Perspective, bring up the Import Menu Figure 10. Import menu Once you have selected Import, you choose which types of objects you want to import. In this case, select Plug-ins and Fragments InfoSphere Data Architect Pluglets Page 6 of 15
ibm.com/developerworks/ developerworks Figure 11. Plug-ins and Fragments At this point, you can select how you want the plug-ins to be imported. Since you want to see the source, select the option to import projects with source folders. Figure 12. Import options There are lots of plug-ins that will appear in this list, so we simply entered "*pluglets" to limit the options. You can also just scroll down if you don't want to do that. Once you see the sample pluglets project, click on it and select "Add" to move it to the right side of the dialog. Figure 13. Adding plug-ins to Import When you click "Finish", the sample pluglet source code will be imported into your workspace and you will see a list of files like this. InfoSphere Data Architect Pluglets Page 7 of 15
developerworks ibm.com/developerworks/ Figure 14. List of sample source One other file you really need to examine is the pluglets.xml file. This file specifies which Eclipse plug-ins are visible to the pluglets in the project. It also controls the pluglet classpath, both at compile and at runtime. When developing your own custom pluglets, you will need to modify this file in your own project and this example gives you an idea of the plug-ins you will need to import. Figure 15. Sample pluglets.xml Developing Custom pluglets Now that you have examined some source code, you are ready to get started creating your own pluglets. Make sure you are in the Java perspective of Eclipse. Once you are in that perspective, select the following: - File > New > Pluglet > New Pluglet wizard Select from existing pluglet templates: Data Pluglets > Data Pluglet Once you pick a pluglet template, a file will be created that contains basic code stubs with //TODO: tags that need to be acted on. In the example below, you can find an example of these tags. This pluglet also checks for a valid selected object in the workspace. If you want your pluglet to work on something like a column only, you would put code checking for that in the isvalidselection method InfoSphere Data Architect Pluglets Page 8 of 15
ibm.com/developerworks/ developerworks Figure 16. Basic pluglet code You make the modifications that you want to make and you can then run your pluglet. In the dialog below, we run a simple "Hello World" pluglet. For now, we have removed most of the sample code just to illustrate how you can run a single pluglet during development. Figure 17. Running your pluglet For this simple example, you would see the following output: Figure 18. Pluglet output This is certainly a friendly pluglet, but not very helpful! Registering pluglets Once you start creating more complex pluglets, you will want to register them to be used from the "Run Pluglet" menu. Switch to the Data Perspective, select an object in the Data Project Explorer like a Physical Data Model, and right-click to bring up the menu to register your pluglet. - Run Pluglet > Register Pluglets InfoSphere Data Architect Pluglets Page 9 of 15
developerworks ibm.com/developerworks/ Figure 19. Register Pluglets When you select to Register the Pluglets, you will see the following dialog. Click OK to register your pluglet. Figure 20. Register Workspace Pluglets Dialog A dialog will pop up informing you how many new pluglets have been registered. Figure 21. Registered Pluglets You will now be able to run your new pluglet from the "Run Pluglet" menu. Make sure and select the object in your Data Project Explorer that corresponds to the object type your pluglet works with. InfoSphere Data Architect Pluglets Page 10 of 15
ibm.com/developerworks/ developerworks Figure 22. Running a custom pluglet Debugging pluglets Once you start creating your own custom pluglets, you are bound to run into some problems and may need to debug your code. You can select to do one of the following to start debugging: You can add debug arguments to the "eclipse.ini" file. Do this after the "-vmargs" workbench argument: -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 Modify your desktop shortcut, add the "-vmargs" workbench argument as above and start IDA Once you have made one of the above changes and restarted eclipse, you can run the debugger from the Internal Tools menu in the Java Perspective. Figure 23. Pluglet debugger Once the workbench comes up, it will actually drive the debug session. Start debugging by running your pluglet. Sharing pluglets Pluglet source can be shared with other team members. You can simply export the project into an archive file and they can import it into their own workspace. InfoSphere Data Architect Pluglets Page 11 of 15
developerworks ibm.com/developerworks/ Figure 24. Export to Archive file Troubleshooting You might run into some trouble getting started. Here are a few tips on troubleshooting. No Sample Pluglets show check install option, is the option enabled for pluglets? Custom pluglets can't compile pluglets.xml must contain the referenced plugins Registering pluglets doesn't work - no plugletmain() method - not implemented getname() method? each pluglet needs unique name - no task group set? implement gettaskgroups() method - Check Error Log for error messages (Window > Show View > Error Log) Known Limitations - Pluglets not available on UML diagrams (only on IE notation diagrams) - Compilation Error in CalculateTableColumnLengthPluglet when importing sample pluglet plugin - Set Default Values pluglet: only enabled for physical models throws NPE when columns in table have User Defined Type - Select Objects By Name pluglet: only selects immediate children of selected object in DPE selected object in DPE need to be expanded in order to select any children on diagram, when selected columns in multiple tables, right-click on selected column will lose selection InfoSphere Data Architect Pluglets Page 12 of 15
ibm.com/developerworks/ developerworks Additional information on Sample Pluglets Table 1. Sample Pluglets Name of Pluglet source file Pluglet Category Valid on selected... Comments Name of pluglet in menu ApplyGeneralization SuperTypeStylePluglet "Apply Supertype Style" Diagram Tasks Entities that are subtype of a Generalization (on Diagram) Apply the color of a "Supertype entity" to its "Subtype entities" CalculateTable ColumnLengthPluglet "Calculate Table and Column Length" ChangeIndexes OwnerGlobalPluglet "Change Owning Schema For All Indexes" ChangeSelected ObjectsOwnerPluglet "Change Owning Schema For Selected Objects" ChangeTables OwnerGlobalPluglet "Change Owning Schema For All Tables" Reporting Tasks PDM, Database or Location (Z) Generates a.csv spreadsheet listing the byte size of the rows * no re-import of.csv files * bytesize will be calculated based on the data types of the columns Model Tasks PDM, Database or Location (Z) Sets all Indexes in the selected model to be contained by the specified Schema. A new Schema can be created during the process. Model Tasks Table, Views and Indexes Sets all selected objects in the selected model to be contained by the specified Schema Model Tasks PDM, Database or Location (Z) Sets all Tables in the selected model to be contained by the specified Schema ChangeTables TablespaceGlobalPluglet "Change Table Space For All Tables" Model Tasks PDM (LUW, Z, Oracle), Database (LUW, Oracle) or Location (Z) Set the Tablespace for all Tables in the selected physical model. Requires an existing Tablespace. ChangeViews OwnerGlobalPluglet "Change Owning Schema For All Views" Model Tasks PDM, Database or Location (Z) Sets all Views in the selected model to be contained by the specified Schema ColorLogical OnlyAttributesPluglet "Change Non-Persistent Attribute Color" Diagram Tasks Entities that have at least one nonpersistent attribute (on Diagram) Apply specific color or default color to all non-persistent attributes - "logical-only" attributes refers to non-persistent attributes (which are not transformed to Physical model, hence no DDL generated) ExportMass EditOfTablesPluglet "Export data to a file" FixBrokenReferences ModelRenamePluglet "Fix Broken References Model Rename" Model Tasks DPE: Database Export model object properties in CSV format. Model Tasks DPE: Model root Fixed broken references introduced by rename InfoSphere Data Architect Pluglets Page 13 of 15
developerworks ibm.com/developerworks/ GenerateDDL PerDataObjectTypePluglet "Generate DDL Per Data Object Type" Model Tasks DPE: Database, Schema, Table, Constraint, Index, Trigger Create separate files for each type of object ImportMass EditOfTablesPluglet "Import data from file" Model Tasks DPE: Database Import model object properties in CSV format. IndexNamingPluglet "Name Indexes" Model Tasks PDM, Database or Location (Z), Schema Name Indexes according to usersupplied naming rules. PullForeign KeysDefinitionsPluglet "Update Foreign Key Documentation from Primary Key" Model Tasks BaseTables (not Views, MQTs) Entities Copy the documentation from the parent primary key to the foreign keys' documentation. RemoveAuxiliary TablesGlobalPluglet "Remove All Auxiliary Tables" Model Tasks PDM (Z), Location (Z) Removes all auxiliary tables and associated table spaces from the appropriate physical data model (based on DPE element selection) SelectObjects ByNamePluglet "Select Objects By Name" Model Navigation Tasks DPE: Database, Schema, Table, Package, Entity; Diagram: empty surface, Table, Entity Selects children of selected object by name SetDefaultValuesPluglet "Set Default Values" Model Tasks Base Tables (no Views, MQTs), Columns Sets "WITH DEFAULT" on all attributes within selected entities * default value is specification is not available on all datatypes * the only default value in logical models is: USER SetSelected EntitiesAttributesRequiredPluglet "Set Attributes of Selected Entities to Required" SetSelected TablesColumnsNotNullPluglet "Set Selected Tables Columns Not Nullable" UpdateSelectedEntities AttributesDomainDataTypePluglet "Update Selected Entities Attributes Domain Data Types" UpdateSelectedEntities GroupAttributesReferencePluglet "Update Selected Entities Group Attributes References" Model Tasks Entities Set all the Attributes within the selected Entity to a "Not Null" value. For Logical models this means setting the Attributes to be "Required" Model Tasks BaseTables (not Views, MQTs) Set all the Columns within the selected Table to a "Not Null" value. Model Tasks DPE: Entity Update attribute's domain datatype with qualified name format Model Tasks DPE: Entity Update entity group attribute reference URL Helpful Resources RSA v8 Pluglets Documentation: http://publib.boulder.ibm.com/infocenter/rsahelp/v8/index.jsp?topic=/ com.ibm.xtools.pluglets.ui.doc/topics/c_whypluglets.html Developer works Codeexamples: http://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/ W0c4a14ff363e_436c_9962_2254bb5cbc60/page/Pluglets%20Developer%20Guide InfoSphere Data Architect Pluglets Page 14 of 15
ibm.com/developerworks/ developerworks Resources Stay current with developer technical events and webcasts focused on a variety of IBM products and IT industry topics. Follow developerworks on Twitter Get involved in the developerworks Community. Connect with other developerworks users while you explore developer-driven blogs, forums, groups, and wikis. For any further questions please reach out to Robert Samuel - ppaulja@us.ibm.com Copyright IBM Corporation (www.ibm.com/legal/copytrade.shtml) Trademarks (www.ibm.com/developerworks/ibm/trademarks/) InfoSphere Data Architect Pluglets Page 15 of 15