Composer Guide for JavaScript Development

IBM Initiate Master Data Service Version 10 Release 0 Composer Guide for JavaScript Development GI13-2630-00

Note Before using this information and the product that it supports, read the information in Notices and trademarks on page 135. Copyright IBM Corporation 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Introduction to Composer....... v Features................ v Key benefits.............. v Initiate Composer architecture........ vi Initiate Composer widgets......... viii Initiate Composer blueprints......... ix Accessing the Dojo API documentation (JSDoc).. ix System requirements............ x Chapter 1. Getting started....... 1 Summary steps for creating an application.... 1 Launching the IBM Rational Application Developer. 2 Importing the composer.war file into the IBM Rational Application Developer........ 2 Adding the Dojo toolkit to your project..... 3 Editing the validation exclude rules...... 3 Validating the composer.war file and re-indexing links................. 4 Making the Initiate Composer server properties file available to the IBM Rational Application Developer project................ 5 Opening Initiate Composer......... 6 Creating the default Initiate Composer configuration 6 Configuring blueprints........... 6 Configuring the Quick View blueprint..... 7 Configuring the Multi-Domain Entity Search blueprint.............. 9 Configuring a source.......... 11 Changing your application's default locale... 12 Configuring the type label........ 13 Configuring the composite view...... 14 Assigning a default attribute set...... 14 Assigning icons for display on the Visualize tab 15 Configuring an instance label pattern..... 15 Creating and configuring an attribute set... 16 Cloning an attribute set......... 17 Configuring an attribute pattern...... 17 Generating Initiate Composer Blueprints.... 18 Copying the Initiate Composer files into the IBM Rational Application Developer........ 19 Testing an application using the blueprint wrapper 20 Testing an application in the IBM Rational Application Developer........... 20 Chapter 2. Configuration Editor.... 23 The Blueprints view........... 23 The Model view............. 23 The Composite View column....... 23 Attribute Sets view............ 24 Chapter 3. Customizing your application............. 27 Extending Composer widgets........ 27 Designating that an input field is required... 27 Validating a user s input using a regular expression.............. 27 Using templates to extend fields...... 28 Creating a custom command....... 31 Creating a custom widget........ 33 Dojo attach events........... 36 Configuring your application interface..... 36 Validating a user s input using a regular expression.............. 37 Customizing applications using CSS..... 37 Configuring EDTs (enumerated data types)... 38 Configuring label icons in forms...... 40 Editing the application title as it appears in the browser.............. 41 Editing the application masthead images... 42 Editing the application masthead image spacing 43 Editing the links in the application header... 44 Editing the application masthead background.. 44 Managing authentication for Initiate Composer applications.............. 45 Configuring authentication for editing entities and adding members.......... 46 Configuring the session timeout and timeout warning.............. 46 Customizing the login panel........ 48 Choosing how to link records when making edits to entities................ 48 Choosing how to link edited entity records for a particular entity type........... 50 Chapter 4. Initiate Composer application infrastructure....... 51 Composer Application object........ 51 Event Manager............. 51 Master Data Service........... 52 Configuration Service........... 53 Metadata Service............ 53 Blueprint infrastructure.......... 54 Dojo widgets.............. 55 Dojo templates............. 56 Kinds of Dojo templates......... 57 Dojo template scope.......... 58 Dojo attach points............ 58 Events................ 59 Types of Composer event listeners...... 60 Event listeners and handlers........ 60 Error handling............. 62 Chapter 5. Extending services..... 63 Using Spring.............. 63 Creating a REST service.......... 63 Verifying dependencies......... 63 Defining the service interface....... 64 Defining the service implementation..... 65 Defining the REST interface........ 66 Copyright IBM Corp. 2011 iii

Defining the REST implementation..... 68 Defining the service deployment...... 69 Extending the Dojo MasterDataService..... 70 Enabling a MasterDataService extension within your application.............. 73 Chapter 6. Creating a custom Dojo build................ 75 Disabling browser utilities......... 75 Using ShrinkSafe to compress your application.. 75 Executing the custom Dojo build....... 76 Preparing the custom Dojo build for deployment.. 77 Chapter 7. Deploying applications... 79 Setting Master Data Engine connection parameters for Tomcat, WebSphere, and WebLogic..... 79 Setting Master Data Engine connection parameters for Tomcat.......... 79 Setting Master Data Engine connection parameters for WebSphere........ 80 Setting Master Data Engine connection parameters for WebLogic......... 81 Configuring the IBM WebSphere Application Server with the IBM Rational Application Developer... 82 Configuring the IBM WebSphere Application Server to recognize composer.icc...... 84 Configuring Apache Tomcat with the IBM Rational Application Developer........... 84 Configuring Oracle WebLogic with the Rational Application Developer........... 85 Setting Master Data Engine SSL connection parameters.............. 86 Configuring the default start page for your application.............. 87 Deploying an application to a J2EE Tomcat environment.............. 87 Deploying an application to WebSphere..... 88 Deploying an application to WebLogic..... 89 Chapter 8. Reference........ 93 Accessing the Dojo API documentation (JSDoc).. 93 Widget reference............. 93 Add Form widget........... 94 Entity Details widget.......... 95 Flexible Search Form widget........ 96 Get Form widget........... 108 Graph Viewer widget.......... 109 Record Details widget......... 111 Record List widget.......... 112 Related Entities widget......... 113 Relationship Graph Container widget.... 114 Search Form widget.......... 115 Search Results widget......... 120 Tree Viewer widget.......... 121 Additional widgets.......... 122 Event reference............. 124 AddEvent.js............. 124 FlexibleSearchEvent.js......... 124 GetListEvent.js............ 125 RelatedEntityEvent.js.......... 125 SearchEvent.js............ 126 SelectEvent.js............ 126 UpdateEvent.js............ 127 Command reference........... 127 AddCommand.js........... 128 FlexibleSearchCommand.js........ 128 GetListCommand.js.......... 129 RelatedEntityCommand.js........ 129 SearchCommand.js.......... 130 UpdateCommand.js.......... 130 REST API reference........... 131 Legal Statement.......... 133 Notices and trademarks....... 135 Index............... 139 Contacting IBM.......... 143 iv Composer Guide for JavaScript Development

Introduction to Composer Features Key benefits IBM Initiate Master Data Service Composer is a unified development environment for quickly building lightweight but robust applications to display, access, and manipulate the data managed by the IBM Initiate Master Data Service. Each application is an assembly of widgets configured within the Composer interface and assembled within a Dojo development environment (for JavaScript implementations) or within Adobe Flash Builder (for Flex implementations). For example, a developer might quickly assemble widgets into an application that allows a user to search for an entity, see a sorted list of results, and view the relationships to other entities for any item in the list. Composer is an Eclipse plug-in included by default within the IBM Initiate Workbench environment. Developers creating Dojo-based applications, can use the Eclipse-based Rational Application Developer or an IDE of their choice. For developers creating Flex-based applications, by installing the Flash Builder Plugin into the Workbench Eclipse environment, you can create, configure, and test applications within a single development environment. IBM Initiate Master Data Service Composer offers widgets and blueprints for quickly assembling applications, while also offering the ability to customize the appearance and behavior of applications to suit your particular needs. Composer offers: v Widget Library A full suite of reusable widgets are provided to enable common use cases of MDM technology, such as adding, editing, searching, relationship management, and duplicate prevention. v Solution Blueprints Solution blueprints are included that combine widgets together into end-to-end applications. v Configuration Composer widgets and blueprints can be customized without any coding. For example, users can select the fields to be displayed on a search form, or custom icons to be displayed on a Relationship Viewer widget. IBM Initiate Master Data Service Composer helps both developers and users to achieve greater efficiency without sacrificing quality or transparency. In particular, Composer applications provide: v Fast time to value Build solutions quickly with reusable widgets and solution blueprints. v Reduce implementation costs Enable your developers to customize UI widgets instead of building interfaces and APIs from scratch. v Increase capabilities of existing applications Improve your existing applications by integrating robust search and data management functions. v Reduced architectural complexity Work with any data model so the functionality and user interfaces can be reused across business processes. Copyright IBM Corp. 2011 v

v Initiate Composer architecture Extensibility Swiftly customize the behavior and appearance of your applications. IBM Initiate Master Data Service Composer is included by default as an Eclipse plug-in within the IBM Initiate Workbench environment. Because the Rational Application Developer operates on a different version of Eclipse, it is not possible with the current release to run Composer and the Rational Application Developer within single Eclipse environment. Figure 1. Composer design-time architecture As part of the deployment process, you deploy the Composer services to the application server to manage communication between your applications and the IBM Initiate Master Data Service. At run time, the application you deploy is available to users via the browser. vi Composer Guide for JavaScript Development

Figure 2. Composer runtime architecture Composer provides generic widgets that read in configuration settings at run time. By separating the configuration settings from the widget code itself, Composer allows administrators to make adjustments quickly and account for changes like new attributes within the underlying data model -- without having to recreate applications from the ground up. The advantages of this dynamic model extend beyond day-to-day development to include the upgrade process: Administrators can take advantage of new features in subsequent versions of Composer without configuring the new widgets from scratch. Within the Composer configuration file (composer.icc), administrators can specify data settings such as which fields to display within an application, how to label widgets, and how to map attributes in the underlying data model to the fields that display in applications. The Composer Configuration file also contains information about what blueprints to generate. A REST service layer governs how the resulting application communicates with the IBM Initiate Master Data Service. Configuration for your applications is a combination of context configuration (which establishes the wiring between the Composer widgets) and data configuration (which indicates the MDM data you want to be available to the Introduction to Composer vii

application). The application reads the data configuration at run time to populate the widgets. To make queries to the Master Data Engine, the application uses REST service calls. Figure 3. Composer context configuration and data configuration Initiate Composer widgets The Composer Library contains the widgets such as Search Form, Search Results, and Details, which serve as the raw materials for applications. It does not include screens, contexts, and other infrastructure elements used for wiring widgets together. Within your IBM Initiate Master Data Service Composer applications, Composer widgets interact with the IBM Initiate Master Data Service to add member records, search for entities, display relationships, and so on. Each Initiate Composer widget represents a complete piece of functionality that manages a specific task such as searching or editing. Before exploring interconnected widgets, become familiar with the individual widgets and their configuration options by browsing the Widget reference on page 93. viii Composer Guide for JavaScript Development

Initiate Composer blueprints If extensive customization of the widgets is required for your application, be certain to extend existing widgets rather than rewriting them. Changing the core widget code delivered with IBM Initiate Master Data Service Composer is not supported. The IBM Initiate Master Data Service Composer blueprints gather together individual Initiate Composer widgets into sample MDM applications, which you can quickly configure and customize to explore the range of capabilities offered with Initiate Composer. Initiate Composer blueprints are offered AS IS and may be used, executed, copied and modified for instruction and study, or in order to develop applications designed either for your own use or for redistribution. The pre-configured blueprints assemble several widgets together to fulfill sample business functions. Blueprints demonstrate how the widgets can be wired together into applications. In particular, they demonstrate how to manage the events flowing from one widget to another. v Quick View Combines the Search Form, Search Results, and Details widgets into a basic application for searching and viewing. (Optionally, you can configure the Quick View blueprint to use the Flexible Search Form instead of the standard Search Form. Or you can configure the blueprint to use both search forms simultaneously.) The Quick View blueprint is offered primarily as a sample application. The QuickViewBlueprint.jsp file contains extensive documentation that describes the Dojo infrastructure, event handling, and more. v Multi-Domain Entity Search Combines the Search Form, Search Results, Add Form, Entity Details, Record Details, and Record List widgets into a more sophisticated demonstration application ready to be customized and deployed to enable users to search, compare, edit, and add records and entities. The Entity Details view also includes the Record List, Graph Viewer and Related Entities widgets. Related concepts Blueprint infrastructure on page 54 An overview of the container infrastructure for the IBM Initiate Master Data Service Composer blueprints. Related reference Widget reference on page 93 Per-widget topics provide an easy reference to the main IBM Initiate Master Data Service Composer widgets including a short description, configuration options, and a list of any blueprints that demonstrate the widget. Accessing the Dojo API documentation (JSDoc) IBM Initiate Master Data Service Composer includes HTML-based documentation for commands, widgets, and so on using JSDoc. About this task After you have extracted the composerdocs.zip file as described below, users can view the JSDoc documentation using a browser. Introduction to Composer ix

Procedure System requirements 1. Navigate in the file system to the...\runtime\doc\ directory within the Composer plug-in in your IBM Initiate Workbench installation. For example: C:\Program Files\IBM\Initiate\Workbench10.0.0\plugins\ com.initiatesystems.workbench.composer_10.0.0\runtime\doc\ 2. Copy the composerdocs.zip file. 3. Extract composerdocs.zip to a location of your choosing. Note that a permissions restriction prevents you from extracting composerdocs.zip into the...\runtime\doc\ directory itself. 4. In the new folder, navigate to the jsdoc directory and open index.html in a browser. In general, the system requirements for IBM Initiate Master Data Service Composer are the same as those for the IBM Initiate Workbench. By default Composer is embedded within Workbench, and so all Composer system requirements for operating system, memory, and so on are identical to the requirements for Workbench. Refer to IBM Initiate Master Data Service System Requirements for detailed information about system requirements for Workbench, including supported web application servers and their versions. With this release, Composer is supported on the IBM WebSphere Application Server version 7.0, Apache Tomcat 6 application server, and the Oracle WebLogic 11g application server. If you use WebSphere 7.0, you must use IBM JDK 1.6 (SR8); a bug within earlier versions of the IBM JDK interferes with certain Composer functionality. For developers creating Dojo-based applications, Composer uses JS/Dojo version 1.5. This documentation specifically describes using the Rational Application Developer version 8.0. With the Rational Application Developer, you can quickly deploy applications to WebSphere for testing or production. For developers creating Flex-based applications, Composer requires users to install Adobe Flash Builder version 4. See the Flash Builder documentation for specific system requirements. x Composer Guide for JavaScript Development

Chapter 1. Getting started A sequence of topics intended to get you up and running with IBM Initiate Master Data Service Composer. About this task This section describes all steps required for configuring Composer, installing the Adobe Flash Builder plug-in, and enabling Composer widgets, blueprints, and services for use within Flash Builder. Once these steps are complete, you will be ready to quickly build your own MDM applications. Summary steps for creating an application Creating an application using IBM Initiate Master Data Service Composer requires administrators to configure the Composer environment as well as an IDE for editing JavaScript to customize application blueprints. Developers can choose whichever JavaScript IDE they wish. However, this documentation specifically describes using the IBM Rational Application Developer, which includes special features for developing with the JavaScript Dojo toolkit. With the IBM Rational Application Developer, you can quickly deploy applications to your preferred application server for testing or production. The following steps are discussed in detail within this Composer documentation: v Ensure that you have installed the WebSphere Application Server or other application server. This documentation focuses on working with the WebSphere Application Server, Version 7.0. v Configure Master Data Engine connection parameters. Within the IBM Rational Application Developer: v Import the composer.war file. v Add the Dojo toolkit to the project. v Validate the composer.war file and filter irrelevant warnings. Within the IBM Initiate Workbench: v Create the default Initiate Composer configuration. v Configure the settings for blueprints and generate them. Once again within the IBM Rational Application Developer: v Copy configuration and blueprint files from the IBM Initiate Workbench to the IBM Rational Application Developer. v Optionally configure and customize the application. v Test the application locally on your machine. v Deploy the finished application from the IBM Rational Application Developer. v Run the application. Copyright IBM Corp. 2011 1

Launching the IBM Rational Application Developer The IBM Rational Application Developer can serve as the IDE for customizing and deploying your Composer JavaScript applications. About this task Developers are free to use a JavaScript development environment of their choice in order to customize Composer applications, however the Rational Application Developer is recommended because it provides tools and features specific to Dojo development. Much of the documentation about developing Composer application for JavaScript uses the IBM Rational Application Developer environment as a template. The following instructions assume that you have Rational Application Developer installed on a machine running Microsoft Windows. Procedure 1. From the Start menu, launch the Rational Application Developer. For example, Start > All Programs > IBM Software Delivery Platform > IBM Rational Application Developer > Rational Application Developer. 2. If you have not done so already, specify the workspace or accept the default. On Windows7 installation, the path is C:\Users\Impala\IBM\rationalsdp\ workspace 3. Optionally check the box to Use this as the default and don't ask again. Importing the composer.war file into the IBM Rational Application Developer In order to customize, test, and deploy your IBM Initiate Master Data Service Composer application, import the composer.war file from the IBM Initiate Workbench into the IBM Rational Application Developer. Procedure 1. Within the IBM Rational Application Developer, from the main menu, choose Project and uncheck Build Automatically. As you'll see, doing so allows you to circumvent a time-consuming validation of the standard Dojo distribution. 2. Choose File > Import > Web > WAR file. 3. Click Next. 4. For WAR file, click the Browse button. 5. Navigate to the Initiate Composer WAR file included within your IBM Initiate Workbench installation. For example: C:\Program Files (x86)\ibm\initiate\ Workbench10.0.0\plugins\com.initiatesystems.workbench.composer_10.0.0\ runtime\bin\composer.war 6. Click Open. 7. For Web Project, accept composer or specify a name of your choice. 8. If it is checked, uncheck the option to Add project to an EAR. 9. If the AJAX Test Server Runtime does not already appear in the list, for Target runtime, click New. 10. From the list, choose IBM > AJAX Test Server Runtime and click Finish. Do not proceed to the next screen and select jars to import. 11. If a window asks whether you want to open the Web perspective, click Yes. 2 Composer Guide for JavaScript Development

Related tasks Adding the Dojo toolkit to your project To support your Composer project in the IBM Rational Application Developer, add the Dojo toolkit. Validating the composer.war file and re-indexing links on page 4 Once you have added the Dojo toolkit, you can re-enable the automatic build process that performs validation on composer.war and then re-index links to remove remaining warnings. Adding the Dojo toolkit to your project To support your Composer project in the IBM Rational Application Developer, add the Dojo toolkit. Procedure 1. Within the IBM Rational Application Developer, right-click your project and select Properties > Project facets. 2. Expand Web 2.0 and select Dojo toolkit. 3. Click the Further configuration available link that appears. 4. Click Change these setup options. 5. Select Dojo is in a project in the workspace, and will be deployed from there. 6. Click Next. 7. Click the Workspace button and navigate to projectname\webcontent\scripts\ src\dojo. 8. Click OK then Finish then OK then OK to close the windows. Results As part of the process of adding the Dojo toolkit, the IBM Rational Application Developer implements a set of exclude rules to filter from view known errors within the standard Dojo distribution. You can view the exclude rules by right-clicking the project and choosing Properties > Validation then clicking the gray box with the three dots in the rows for: v Client-side JavaScript v HTML Syntax Validator v JSON Syntax Validator v XML Validator v XSL Validator Editing the validation exclude rules After adding the Dojo toolkit, you can edit the default validation exclude rules. About this task Adding the Dojo toolkit as a project facet prompts the IBM Rational Application Developer to set up validation exclude rules so that known errors and issues with the Dojo standard distribution. However, the rules inadvertently exclude warnings and errors associated with Initiate Composer while failing to exclude a directory where Initiate Composer packages additional standard code. Follow the steps below to edit the validation exclude rules so that warnings and errors associated with your Initiate Composer application will be visible and so that known Chapter 1. Getting started 3

warnings and errors associated with standard code do not appear. Procedure 1. Within the IBM Rational Application Developer, right-click your project and select Properties > Validation. 2. Click the gray box with the three dots in the row for Client-side JavaScript. 3. Within the Exclude Group, select Folder: WebContent/scripts/src/dojo/ composer and click Remove. 4. Click OK. 5. Repeat the previous steps to remove the Folder: WebContent/scripts/src/dojo/ composer exclude rule for the following validators: v HTML Syntax Validator v JSON Syntax Validator v XML Validator v XSL Validator 6. Return to the configuration for the Client-side JavaScript validator. 7. Select Exclude Group and then click Add Rule. 8. Select Folder or file name then Next. 9. Click the Browse Folder button and browse to select projectname/composer/ WebContent/scripts/release. 10. Click OK and then Finish. 11. Click OK to close the Properties window. Validating the composer.war file and re-indexing links Once you have added the Dojo toolkit, you can re-enable the automatic build process that performs validation on composer.war and then re-index links to remove remaining warnings. About this task Before importing the composer.war file into the IBM Rational Application Developer, you disabled the automatic build process that performs validation. Now that you have added the Dojo toolkit, which implements a set of validation exclude rules, re-enable Build Automatically. You can then re-index links and create filters. Procedure 1. Within IBM Rational Application Developer, right-click your project and choose Properties > Validation. 2. Verify that the Enable project specific settings option at the top of the window is checked. 3. Click OK to close the window. 4. From the main menu, choose Project and check Build Automatically. The IBM Rational Application Developer performs validation on the composer.war file that you imported. 5. Navigate to the Problems view to view any errors and warnings. 6. To repair warnings about broken links, navigate in the main menu to Window > Preferences then to Web > Links and click Re-index links. 7. Click OK to close the Preferences window. 4 Composer Guide for JavaScript Development

Making the Initiate Composer server properties file available to the IBM Rational Application Developer project Configure the composersvcs.properties server properties file to allow your IBM Initiate Master Data Service Composer applications to communicate with the IBM Initiate Master Data Service. Before you begin Often developers create and refine Composer applications using a local installation of the IBM Initiate Master Data Service and then deploy the application to a production installation. The composersvcs.properties file allows you to configure server information to connect to the appropriate IBM Initiate Master Data Service installation. Edit the file to reflect the installation that your application will access. You may wish to maintain a single copy of the composersvcs.properties file and simply edit the file before packaging your application for deployment. If so, maintain your copy of the file within the IBM Rational Application Developer at projectname/java Resources/src. When your application runs, it will find the file in the WEB-INF/classes directory of your web application. As an alternative, you may wish to create multiple versions of your application by maintaining separate projects within the IBM Rational Application Developer. Each version of the application can be specific to a particular IBM Initiate Master Data Service installation. If so, create a version of the composersvcs.properties file for each project, as described in the steps below. Procedure 1. In the file system, navigate to the bin directory for the Composer plugin. For example: C:\Program Files (x86)\ibm\initiate\workbench10.0.0\plugins\ com.initiatesystems.workbench.composer_10.0.0\runtime\bin 2. Copy the composersvcs.properties.example file. 3. Within the IBM Rational Application Developer, enable the Enterprise Explorer view if it is not already active: Window > Show View > Other > General > Enterprise Explorer. 4. Paste the composersvcs.properties.examples file into the projectname/java Resources/src folder for your project. 5. Rename the file to composersvcs.properties. 6. For each project, open the composersvcs.properties file. 7. Uncomment the following lines by removing the initial pound signs (#) and set the values to reflect a valid host name and port for the installation where the Initiate Composer application will run: contextfactory.hostname= contextfactory.hostport= For example, if your configuration runs the Master Data Engine at localhost:16000, verify that the values are: contextfactory.hostname=localhost contextfactory.hostport=16000 8. Save and close the composersvcs.properties file. Chapter 1. Getting started 5

Results Opening Initiate Composer When your application runs, it will find the file in the WEB-INF/classes directory of your web application. To open IBM Initiate Master Data Service Composer open the IBM Initiate Workbench and choose from the Composer options in the main menu bar. About this task By default, Workbench includes Composer. Procedure 1. Start the IBM Initiate Workbench. 2. In the top menu, choose Composer. 3. Verify that the list of options includes Create Default Composer Configuration and Generate Composer Blueprints. 4. If you have not already done so, connect Workbench to an Engine. If necessary, create a new Initiate project and import a hub configuration. After you create the new project, you may see an error ("Must define at least 1 member type."). The error should resolve when you import the hub configuration. For full instructions, see the IBM Initiate Workbench User's Guide. Creating the default Initiate Composer configuration Generate the default configuration for IBM Initiate Master Data Service Composer. About this task Configuring blueprints The generation process opens the Composer Configuration Editor and creates the projectname/composer/config/composer.icc configuration file, visible in the Workbench Navigator view. As described in subsequent topics, you edit the composer.icc file using the Composer Configuration Editor to choose and configure the blueprints you want to serve as the basis of your applications. Procedure 1. Within IBM Initiate Workbench, from the Composer menu, click Create Default Composer Configuration. 2. Select a project from the list and click OK. The Composer Configuration Editor opens. 3. Verify that the composer.icc file appears within projectname/composer/config/ in the left-pane. IBM Initiate Master Data Service Composer includes blueprints included to demonstrate how Initiate Composer widgets can be assembled into applications. 6 Composer Guide for JavaScript Development

About this task Using blueprints is optional, though much of the information in the topics that follow applies even if you assemble widgets into applications from scratch. With the Configuration Editor for IBM Initiate Master Data Service Composer within the IBM Initiate Workbench, configure the names, labels, attribute sets, and composite views for your blueprints. Each blueprint you configure appears on a separate tab within the application you generate. Configuring the Quick View blueprint In order to configure blueprints, you specify settings in the Composer Configuration Editor, such as the name, label, member type, and attribute sets. About this task The settings you configure for the blueprint are saved within the composer.icc configuration file. In general, IBM Initiate Master Data Service Composer widgets parallel standard widgets in Dojo (buttons, forms, and so on); by contrast blueprints are pre-wired arrangements of Composer widgets designed to enable common sets of tasks. By default, the Quick View blueprint combines three different Composer widgets: Search Form, Search Results, and Details. (Optionally, you can configure the Quick View blueprint to use the Flexible Search Form instead of the standard Search Form. Or you can configure the blueprint to use both search forms simultaneously.) Blueprints indicate the flow of events from one widget to another. They can be used without alteration as a simple but complete application, or the relevant code can be copied and used within a larger application. As part of the configuration process, you can choose the Search Type for the blueprint, either Entity or Record. Doing so configures the blueprint widgets as entity search form, results, and details versus record search form, results, and details. For more information about the individual widgets including a description of available configuration options, see the Widget reference on page 93. Procedure 1. If it is not already open, launch the Composer Configuration Editor within the IBM Initiate Workbench by double-clicking the composer.icc file within the projectname/composer/config/ directory in the Navigator view. 2. On the Blueprints view, click the green plus-sign. A pane populates with a list of available blueprints. 3. Select Quick View and click Add. The blueprint appears in the list, as the lower pane populates with configuration options. 4. For Name specify a value that reflects the role the blueprint plays in your application. 5. Set the Label for the blueprint. The label appears as the name of the blueprint in the UI tab. 6. Package refers to the Java package generated for the blueprint. Change the package name if you must have more than one instance of the same blueprint. The package name must be unique across your deployment environment. 7. Choose a Member Type from the drop-down menu. The values here are drawn from your underlying data model. Chapter 1. Getting started 7

8. Choose a Search As option from the drop-down menu. Composer uses this entity type when conducting a search. As with the Member Type, the available values are drawn from your data model. 9. Choose a Search Type option from the drop-down menu. Your choice determines whether the blueprint widgets are configured for entities or records. 10. Select an Attribute Set for each widget. An attribute set is a container that administrators can create and configure in order to specify the set of attributes that display within a Composer widget. Because an attribute set is required for each widget, if no attribute sets appear in the drop-down menus for the widgets, you must configure at least one attribute set before you can save the blueprint configuration. For instructions about creating attribute sets, see Creating and configuring an attribute set on page 16. Be sure to return to the Blueprints view to assign the attribute sets you create. The drop-down menus in the Blueprints view only offer attribute sets that match the member type you have chosen for the blueprint. 11. When you finish, save your changes. Changes are saved to the composer.icc file. Note: When you generate blueprints, the Composer Configuration Editor writes a second copy of the composer.icc file into the projectname/composer/ WebContent/config directory. If you make additional changes to the composer.icc file within projectname/composer/config, Initiate Composer automatically propagates the changes to the copy of composer.icc file within projectname/composer/webcontent/config. However, any changes you make to the composer.icc file within projectname/composer/webcontent/config are not propagated to the composer.icc file within projectname/composer/config. What to do next Continue with the blueprint configuration using the Model view and Attribute Sets view. Configuring the Quick View blueprint to use the Flexible Search Form By commenting and un-commenting code within the QuickViewBlueprint.jsp, you can enable the Flexible Search Form instead of the default Search Form. Or you can choose to enable both search forms simultaneously. About this task By default, the Quick View blueprint includes the standard Search Form widget. It also contains code for including the Flexible Search Form widget. The Flexible Search Form widget code is commented out by default. Follow the steps below to enable it. Procedure 1. If you have not already done so, configure and generate a Quick View blueprint. 2. Navigate to the QuickViewBlueprint.jsp file: projectname/composer/ WebContent/blueprints/quickview/QuickViewBlueprint.jsp. 3. Open QuickViewBlueprint.jsp for editing. 4. Locate the following code: 8 Composer Guide for JavaScript Development

<div dojotype="composer.mds.widgets.searchform" attributeset="ding" enttype="id" searchtype="entitysearch" eventscope="blueprints.quickview" showadvanced="true" id="blueprints.quickviewsearchpanel" > </div>              5. As instructed, to enable the Flexible Search Form and disable the standard Search Form, edit the code to uncomment the Flexible Search Form code and comment out the standard Search Form code. 6. Save your changes and close the QuickViewBlueprint.jsp file. Related tasks Configuring the Quick View blueprint on page 7 In order to configure blueprints, you specify settings in the Composer Configuration Editor, such as the name, label, member type, and attribute sets. Related reference Flexible Search Form widget on page 96 With the Flexible Search Form widget, your users can search data that has been indexed using IBM Initiate Flexible Search mechanism. Configuring the Multi-Domain Entity Search blueprint For the Multi-Domain Entity Search blueprint, configure a label, source, and attribute set for each entity type that the application manages. About this task At run time IBM Initiate Master Data Service Composer reads the composer.icc configuration file. In general, Composer widgets parallel standard widgets in Dojo (buttons, forms, and so on); by contrast blueprints are pre-wired arrangements of Composer widgets designed to enable common sets of tasks. The Multi-Domain Entity Search blueprint combines the following Composer widgets: Search Form, Search Results, Add Form, Entity Details, Record Details, and Record List. Embedded within the Entity Details view, the blueprint also includes the Related Entities widget and Relationship Viewer widget. Blueprints indicate the flow of events from one widget to another. They can be used as-is within an application or the relevant code can be copied and used from within a larger application. For details about the individual widgets including a description of available configuration options, see Widget reference on page 93. Chapter 1. Getting started 9

Procedure 1. If it is not already open, launch the Composer Configuration Editor within the IBM Initiate Workbench by double-clicking the composer.icc within the projectname/composer/config/ directory in the Navigator. 2. On the Blueprints view, click the green plus-sign. The right pane populates with a list of available blueprints. 3. Select Multi-Domain Entity Search and click Add. The blueprint appears in the list within the left pane of the Editor, and the right pane populates with configuration options for the particular blueprint. Blueprints function as containers for widgets. 4. For Name specify a value that reflects the role the blueprint plays in your application. 5. Set the Label for the blueprint. The label appears as the name of the blueprint in the UI tab. Using non-alphanumeric characters for Label causes an error within Flash Builder. 6. Package refers to the Java package generated for the blueprint. Only change the package name if you must have more than one instance of the same blueprint. The package name must be unique across your deployment environment. 7. For each Entity Type in the drop-down menu, indicate whether it should be Enabled. Enabled entity types are available to the blueprint, meaning that the blueprint's widgets can search against the entity type, display details for the entity type, and so on. For the Multi-Domain Entity Search blueprint, each entity type you enable appears as a tab within the application. The Relationship Viewer widget and Related Entities widget display relationships with entity types that are not enabled, but your users cannot view the details for those entity types. The following steps assume that the entity type is enabled. For entity type that you designate as Enabled, you must specify a Label, Add/Edit Source, and attribute sets for each widget. 8. Set the Label for the blueprint. The label appears as the name of the blueprint in the UI tab. 9. For Add/Edit Source, choose from the drop-down menu. The application created from this blueprint includes widgets for adding and editing records and entities. Choosing the source indicates to which repository the application writes the additions and changes. Typically it is best to choose a Hub-controlled source. A Hub-controlled source is one maintained by the IBM Initiate Master Data Service itself in order to aggregate additions and changes in one easily accessible location. Be certain to specify a source for every entity type that you have enabled. See Configuring a source on page 11 and Configuring authentication for editing entities and adding members on page 46. 10. Select an Attribute Set for each widget. You might need to expand the pane to see the full list of widgets. As explained in later sections of this guide, an attribute set is a container that administrators can create and configure in order to specify the set of attributes that display within a Composer widget. Because an attribute set is required for each widget, if no attribute sets appear in the drop-down menus for the widgets, you must configure at least one attribute set before you can save the blueprint configuration. For instructions about creating attribute sets, see Creating and configuring an attribute set on page 16. Be sure to return to the Blueprints view to assign the attribute sets you create. The drop-down menus in the Blueprints view only offer attribute sets that match the member type you have chosen for the blueprint. 10 Composer Guide for JavaScript Development

11. When you finish, save your changes. Changes are saved to the composer.icc file. Note: When you generate blueprints, the Composer Configuration Editor writes a second copy of the composer.icc file into the projectname/composer/ WebContent/config directory. If you make additional changes to the composer.icc file within projectname/composer/config, Initiate Composer automatically propagates the changes to the copy of composer.icc file within projectname/composer/webcontent/config. However, any changes you make to the composer.icc file within projectname/composer/webcontent/config are not propagated to the composer.icc file within projectname/composer/config. What to do next Continue with the blueprint configuration using the Model view and Attribute Sets view. Configuring a source For IBM Initiate Master Data Service Composer blueprints whose widgets add records or edit entities, you can create a dedicated Hub-controlled source and specify that source when configuring your blueprints. About this task Creating a dedicated Hub-controlled source allows Composer applications to maintain added records and edited entities in one easily accessible location. Once you have created the source, specify it as the Add/Edit Source within the Blueprints view of the Composer Configuration Editor for any blueprints that enable adding records or editing entities. Note that the Quick View blueprint does not include any widgets that add records or perform entity editing and so the Add/Edit Source drop-down does not appear. Once the new Hub-controlled source is created and configured, when a user adds a record within the application, the application writes the new record to that source. Specifically, the application creates an entity which contains the single record you have just created. (Remember that entities are simply containers for one or more records.) The application behavior for editing an existing entity is somewhat more complex. Suppose that an existing entity consists of three records maintained by three different sources. When a user edits the entity within your application, the changes are written to the record that is maintained in the source you specified as the Add/Edit Source. If you indicated a new Hub-controlled source (and if the entity has not previously been edited within your application), the application creates a record in the Hub-controlled source and links the record to the other three records in the other sources. If the entity has already been edited within your application, the application writes the updates into the existing record in the Hub-controlled source and links the record to the other sources. The record maintained by the Hub-controlled source typically becomes the most current record within an entity, unless edits are also made to records within other sources. How the application links the record to the other records depends on your configuration. By default, the application "hard links" the records, meaning that the application issues a command that binds together the associated records for the entity using an identity rule. The identity rule indicates that two or more members Chapter 1. Getting started 11

have been assigned the same Member ID. (In the API, this is known as an entity rule, specifically EntRule.) This linking occurs each time a user edits an entity. As an alternative, you can configure the application to "soft link" the records so that when the user edits an entity, rather than linking the member records as occurs with hard linking, Composer reads the values from the other member records that comprise the entity and writes those values into the member record within the selected source, where they appear as inactive values. See Choosing how to link records when making edits to entities on page 48. Procedure 1. Within the projectname directory in the Navigator, double-click projectname.imm file. 2. In the window that opens in the right pane, click Member Types in the vertical list of options. 3. From the Member type drop-down menu at the top of the pane, choose the member type for which you want to create a Hub-controlled source. 4. Click to open the Sources tab. 5. Click the Add button. A new row appears in the table of sources. 6. Edit the fields in the table to assign a Source Name and Source Code. For example, assign a source name of Composer Add and Edit and a source code of COMPSR. 7. In the right column, ensure that all attributes are enabled for the selected source. 8. Repeat the process for all member types for which users can add new records or edit entities. 9. Save your changes. The new source is available within the Add/Edit Source drop-down menu on the Blueprints view of the Composer Configuration Editor. Changing your application's default locale You can configure your Composer application to display locale-specific labels and messages by creating copies of resource files and editing them to provide the translated text. About this task Note that creating locale-specific resource files does not alter the Locale drop-down menu available within the Model view and Attribute Sets view in the Composer Configuration Editor. For the current release, the drop-down only displays English (United States) regardless of changes to the locale files. Also note that the labels.js file applies only to the model and attribute set labels. Static labels used in widgets (for example, error messages and button labels) are not translated through labels.js. A second file (messages.js) contains message catalog entries for all strings found in the Initiate Composer application within the IBM Initiate Workbench. You should have no cause to edit messages.js. Procedure 1. If it is not already started, open the IBM Initiate Workbench. 2. In the left pane of the Workbench, navigate to the projectname/composer/ WebContent/scripts/src/dojo/composer/nls folder. 12 Composer Guide for JavaScript Development

3. Create a new directory and assign the name of your locale. For example, for German-speaking Germany create a de-de directory. For Dojo, locale specifications are all lowercase and use a hyphen rather than an underscore. 4. Copy the labels.js file within projectname/composer/webcontent/scripts/ src/dojo/composer/nls and paste it into your new locale-specific directory. 5. Edit the file to specify the locale-specific text for interface labels. The labels.js file within projectname/composer/webcontent/scripts/src/dojo/composer/nls specifies the default labels to be used if the user's browser does not specify a locale for which you have created a locale-specific directory. If the default language for your application is not US English, directly edit the labels.js file within projectname/composer/webcontent/scripts/src/dojo/composer/nls. Note: You must save any changes to labels.js in UTF-8 format to ensure that international characters appear correctly in your Initiate Composer application. 6. Test your changes by altering the locale setting in your browser and redeploying the application. Example The Dojo locale specification allows you to supply localized strings at different levels of detail. For example, suppose your application will be accessible to French speakers in several locales (fr_fr, fr_ca, and fr_ch), yet you want to specify a label that will be the same for all three French locales. Specifically, you want to specify Prénom as the label for a person's first name. In addition to directories called fr-fr, fr-ca, and fr-ch, you can create a directory called simply fr. Create copies of labels.js and messages.js within labels.js in the fr directory and specify the Prénom string for attrset.yourattributeset.fieldset.lglname.field.onmfirst.label. Next remove the attrset.yourattributeset.fieldset.lglname.field.onmfirst.label label specification from the labels.js file in the fr-fr, fr-ca, and fr-ch directories. When a user whose browser locale is set to fr_ch accesses the application, Dojo looks first for referenced strings within the fr-ch directory. When it does not find the label specification within the fr-ch directory, it automatically steps up to the fr directory where it finds the specification. In turn, if it had not found the specification for the string within the fr directory, it would have looked within the default versions of the labels.js and messages.js files within projectname/composer/webcontent/scripts/src/dojo/composer/nls. Configuring the type label You can assign a user-readable label to the database names of member types and entity types using the Model view, which includes a Type Label column. Procedure 1. If it is not already open, launch the IBM Initiate Master Data Service Composer Configuration Editor by double-clicking the composer.icc within the projectname/composer/config/ directory in the Navigator. 2. Navigate to the Model view. 3. Under the Type Label table heading click within the cell that corresponds to the member or entity you want to configure. 4. If a label is already present, you can edit it. If no label is present, you can add one. 5. Repeat as necessary to configure the entities and members. 6. Save your changes. Chapter 1. Getting started 13