Composer Guide

COMPOSER GUIDE Release 9.2

“Initiate,” “Initiate Identity Hub,” “Initiate Master Data Service,” and the Initiate logo are registered trademarks in the United States and certain foreign jurisdictions. “Initiate Consumer,” “Initiate Organization,” “Initiate Citizen,” “Initiate Patient,” “Initiate Provider,” and “Initiate Inspector” are trademarks of Initiate Systems. All rights reserved. All other marks are owned by their respective owners. The information in this document is protected under the applicable federal law as an unpublished work, and is confidential and proprietary to Initiate Systems, Inc. Its use, disclosure, reproduction, or publication, in whole or in part, without the express prior written consent of Initiate Systems, Inc. is prohibited. © 2010 Initiate Systems, Inc.

Contents

Introduction ..................................................................................................................................................... 5 Overview ........................................................................................................................................................ 5 Features ...................................................................................................................................................... 5 Key Benefits ................................................................................................................................................ 5 The Composer components ........................................................................................................................... 5 Organization of the document ........................................................................................................................ 6 Summary steps for creating Composer application ....................................................................................... 6 Architecture .................................................................................................................................................... 7 Common Terms .............................................................................................................................................. 8 Additional reference documents .................................................................................................................... 9 System requirements ..................................................................................................................................... 9 How to get help ............................................................................................................................................ 10 ATSC ......................................................................................................................................................... 10 Support Center Knowledge Base .............................................................................................................. 10 Acknowledgments ........................................................................................................................................ 10 Chapter 1 Getting Started ............................................................................................................................. 11 Overview ...................................................................................................................................................... 11 Installing Composer ..................................................................................................................................... 11 Downloading the BlazeDS WAR file ............................................................................................................ 12 Installing the Adobe® Flex® Builder™ plug-in ............................................................................................. 12 Installing Apache Tomcat ............................................................................................................................. 13 Creating the default Composer configuration .............................................................................................. 15 Configuring components within Composer .................................................................................................. 15 Generating and enabling Composer artifacts .............................................................................................. 16 Configuring your local Tomcat installation ................................................................................................. 18 Setting Master Data Engine connection parameters for the local Tomcat installation ................................. 18 Configuring Flex settings for your Initiate project ......................................................................................... 19 Testing an application in the Flex Development perspective ....................................................................... 21 Preparing to edit Composer components within the Java perspective ........................................................ 22 Regenerating Composer artifacts ................................................................................................................ 22 Uninstalling Composer ................................................................................................................................. 23

Proprietary and Confidential

3

www.Initiate.com

Composer Guide

Chapter 2 Components and Blueprints Reference ..................................................................................... 25 Overview ...................................................................................................................................................... 25 Composer Configuration Editor .................................................................................................................... 25 Components view ...................................................................................................................................... 25 Model view ................................................................................................................................................. 26 Configuring the Composite View ............................................................................................................. 27 Assigning an Attribute Set ....................................................................................................................... 28 Setting instance label patterns for Relationship Viewer entities ............................................................. 28 Attribute Sets view ..................................................................................................................................... 29 Example: Configuring a blueprint ................................................................................................................. 30 Composer components ................................................................................................................................ 32 Composer blueprints .................................................................................................................................... 33 Managing authentication for your applications ............................................................................................. 34 Configuring authentication for editing entities and adding members ......................................................... 34 Turning off the login panel for your application .......................................................................................... 34 Editing the login panel image .................................................................................................................... 37 Managing edits made to entities ................................................................................................................ 37 Hiding member records within an Entity Search Results component .......................................................... 38 Changing the default icon for the Relationship Viewer ................................................................................ 38 Chapter 3 Deploying Composer Applications ............................................................................................. 41 Overview ...................................................................................................................................................... 41 Setting Master Data Engine connection parameters for Tomcat and WebSphere ....................................... 41 Manually packaging J2EE Java and Flex .................................................................................................... 43 Deploying a Composer application to a J2EE Tomcat environment ............................................................ 43 Manual file copy and Tomcat restart .......................................................................................................... 44 Tomcat Deployment Manager .................................................................................................................... 44 Testing the Tomcat deployment ................................................................................................................. 45 Debugging Tomcat Java Composer Services ............................................................................................ 45 Deploying a Composer application to a WebSphere environment ............................................................... 46 Debugging Flex ............................................................................................................................................ 47 Chapter 4 Managing Composer Events ....................................................................................................... 49 Overview ...................................................................................................................................................... 49 Event Code .................................................................................................................................................. 50 Code within the Event Map ........................................................................................................................ 50 Code within Composer components .......................................................................................................... 51 Composer Events ......................................................................................................................................... 51 Index ............................................................................................................................................................... 55

Initiate Systems, Inc.

4


Introduction

Overview Initiate Composer is a unified development environment for quickly building lightweight but robust applications to display, access, and manipulate the data managed by the Initiate Master Data Service. Each application is an assembly of components generated by Composer and assembled and configured within Adobe® Flex® Builder™. For example, a developer might quickly assemble components into an application that allows an end 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 a separately installable Eclipse plugin designed to be installed within the Initiate® Workbench environment. By installing the Flex Builder Plugin into Workbench as well, users are able to create, configure, and test applications within a single development environment.

Features Component Library — A full suite of reusable components are provided to enable common use cases of MDM technology, such as adding, editing, searching, relationship management, and duplicate prevention. Solution Blueprints — Solution blueprints are included that combine components together into an end-to-end solution mashup, such as a 360 degree customer view. Configuration — Initiate Composer components 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 component.

Key Benefits Fast time to value — Build solutions quickly with reusable components and solution blueprints. Reduce implementation costs — Enable your developers to customize UI components instead of building interfaces and APIs from scratch. Increase capabilities of existing applications — Improve your existing applications by integrating robust search and data management functions. Reduced architectural complexity — Work with any data model so the functionality and user interfaces can be reused across business processes.

The Composer components The Composer components include: Member Add View Search Form Proprietary and Confidential

5

www.Initiate.com

Composer Guide

Member Entity Search Results Member Entity Details View Member Entity (as a pane in the application or as a popup) Relationship Viewer Related Entities Viewer Subsequent releases of Composer will include additional components. In addition to the components listed above, Composer includes a set of pre-configured blueprints which assemble several components for a particular function and establish how the components are wired together to manage the events flowing from one component to another. For example, the Member Search blueprint provides a default assembly of the Member Add View, Member Search Form, Member Search Results, and Member Details View components.

Organization of the document The current document is organized into the following chapters: “Introduction” — The current chapter. Offers a summary view of the Composer application. “Getting Started” — Spells out the steps for installing Composer, Flex Builder, and (optionally) Apache Tomcat; generating the default Composer configuration; configuring Composer components; integrating with Flex Builder; and so on. If you configure a local installation of Tomcat, by the end of the chapter, you will have created and run a locally available web application that can search and display Master Data Engine data. “Components and Blueprints Reference” — Offers details about the Composer building blocks you’ll use to create applications for end users. “Deploying Composer Applications” — Describes the process for deploying your application to an application server. The first release Composer is supported on Apache Tomcat and IBM WebSphere®. “Managing Composer Events” — Explains the notion of Flex events and describes the event mechanisms and event code that Composer components use to communicate with one another.

Summary steps for creating Composer application Creating an application using Composer requires the following high-level steps: Setup steps: Download and install the Composer plugin. Download and install the Flex Builder plugin. Download and install Apache Tomcat (optional). Configure Master Data Engine connection parameters. Within Initiate Composer and Flex Builder:


6


Introduction

Generate the default Composer configuration, which examines your current data model to prime the components and services. Configure the settings for components and blueprints prior to generating those components and blueprints for use within Flex Builder. Generate Composer components, blueprints, and services. Optionally configure component and blueprint settings within Flex Builder. Test the application locally on your machine. Debug your application within the Flex Debugging perspective. Optionally edit Composer components within the Java perspective. Deploy your application to a J2EE Tomcat or WebSphere environment.

Architecture As explained earlier, Composer is a separately installable Eclipse plugin designed to be installed within the Initiate® Workbench environment. Initiate recommends installing Flex Builder into Workbench as well so that all necessary tools reside in a single desktop environment.


7

www.Initiate.com

Composer Guide

As part of the deployment process, you will deploy the Composer services to the application server to manage communication between your applications and the Master Data Service. At runtime, the application you deploy will be available to end users via the browser.

Common Terms The following terms occur throughout this document: attribute set — A container that administrators can create and configure in order to specify the set of attributes that will display within a Composer component — or for a member type or entity type across all Composer components. Attribute sets offer administrators a convenient way to reuse sets of attributes across multiple components rather than configuring the same individual attributes each time they create a new component. BirdEye — An open-source effort to create a visualization and visual analytics library for Adobe Flex Builder. Composer takes advantage of BirdEye technology for its Relationship Viewer component. BlazeDS — An open-source messaging technology that manages communication between the Composer APIs on the application server and the Initiate Master Data Service. blueprint — An assembly of several components wired together to manage the events flowing from one component to another. Blueprints are intended to answer specific common business needs.


8


Introduction

component — A GUI-based element that performs a function within a Flex application. A component can be as simple as a button or as sophisticated as a viewer for displaying complex relationships between entities. composite view — A defined way of displaying attribute information for an entity. Because an entity record typically encompasses multiple member records, the attribute values to display for a particular entity can vary. For example, one of an entity’s member records may indicate that the person lives in Chicago while another indicates that the same person lives in Phoenix. Choosing a composite view allows an administrator to set rules for which value to display. The EMCA composite view (Enterprise Most Current Available) displays whichever attribute value across all the member records that was most recently created or edited. By contrast, a Trusted Source composite view always displays the attribute value from the member record associated with a single trusted source even if that information is not the most recent. Finally, the Controlled composite view displays a selection of attributes from multiple specified sources. For example, you can specify to display name and address information from Source A, phone and birth date from Source B, and Social Security number and address from Source C. event — Flex applications are driven by events which may include external/network events, internal application events, and user actions. In the context of Composer, all events result from user actions to perform a search, add a new member records, and so on. event map — A file created automatically with each Composer blueprint. The event map aggregates event handlers that indicate how to manage each of the events that an application can generate. Composer uses the Mate Flex framework for managing events. Flex Builder — Built on Eclipse, Flex Builder is an IDE (integrated development environment) that allows developers to assemble and configure GUI-based components into applications for the internet or desktop. Mate Flex — A tag-based, event-driven framework that facilitates handling of events passing between components within Flex applications. plugin — In the Eclipse environment, a program that provides a certain set of functionality. Initiate Workbench, Initiate Composer, and Adobe Flex Builder are all Eclipse plugins.

Additional reference documents The following related publications supplement this guide: Initiate Master Data Service® Master Data Engine Installation Guide Initiate Master Data Service® Data Model Description Initiate® Workbench Reference Guide

System requirements Administrators will install Composer within the Initiate® Workbench. With this first release, Composer is supported on the Apache Tomcat 6 application server and the IBM WebSphere application server versions 6.1 (build 6.1.0.29 or later) and 7.0. Note that 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. Otherwise, the Composer system requirements for operating system, memory, and so on are identical to the requirements for the Workbench. Refer to Initiate Master Data Service® Technology Requirements for detailed information on system requirements for using Workbench, including supported web application servers and their versions.” Composer requires users to install Adobe Flex Builder version 3. See the Flex Builder documentation for specific system requirements.


9

www.Initiate.com

Composer Guide

How to get help ATSC Each organization designates two (2) or more individuals to act as Authorized Technical Support Contacts (ATSC) for Initiate software issues. These individuals interact with users in your organization and, when necessary, work with the technical support staff at Initiate Systems, Inc. to resolve issues. When you have questions or concerns about the software, and if the information in this guide does not answer your questions, contact your ATSC. Your ATSC will try to determine if the problem is a hardware system issue or an operational issue before contacting Initiate Systems for assistance.

Support Center Knowledge Base We realize that you might have questions that may not be addressed in the documentation, training, or within your standard workflow procedure. The Initiate Systems Customer Support Web site (https://support.initiatesystems.com/) provides a knowledge base that offers additional information about Initiate products and their use. New items are frequently added, so please refer to the Web site when possible.

Acknowledgments Third party software code files are shipped along with the Initiate Master Data Service Release 9.2 (the “Third Party Code”). Third Party Code files are the property of their respective owners and not Initiate Systems and Initiate Systems claims no rights in or to the Third Party Code. Your use and access to the Third party Code is governed by the specific restrictions and limitations set forth in the applicable licenses provided by the Third Party Code owners. The Third Party Code is provided to you by Initiate solely for use with the Initiate Master Data Service product and Initiate Systems does not authorize or promote any other use of the Third Party Code by you. The full text of the applicable Third Party Code licenses is provided in the Third Party License.zip file included along with the Initiate Master Data Service Release 9.2, located on the Initiate Systems product CD or downloaded CD image.


10


1 Getting Started

Overview This chapter describes all steps required for installing and configuring Initiate® Composer, installing the Adobe® Flex® Builder™ plug-in, and enabling Composer components and services for use within Flex Builder. Once these steps are complete, you’ll be ready to quickly build your own MDM applications using Flex Builder. For definitions of frequently-used terminology, see “Common Terms” on page 8.

Installing Composer As mentioned previously, Composer installs within the Initiate® Workbench environment. How to install Composer 1

From the product CD, copy the Composer zip file (ISI_Composer_9.2.0.zip) into a local directory.

2

Unzip the file into the Workbench folder. The folder will typically be: C:\Program Files\InitiateSystems\Workbench9.2.0\ Unzipping creates the ..\plugins\com.initiatesystems.workbench.composer_9.2.0 folder, which contains: JARs that enable Composer functionality. MXML files that define the view layer and define elements of the Flex components. ActionScript files that implement server integration and also serve as controllers or managers of view components. ActionScript files that define templates that serve as controllers for use within components Mate_08_9.swc, An open source flash component that provides an implementation of the Model-View-Controller (MVC) design pattern. flexlib.swc, another a Flash component file. The flexlib.swc file contains a set of open-source user interface components for Flex. libRaVis.swc, an open source Flash component that provides graphing functionality.

3

Start Initiate Workbench.

4

If you haven’t already done so, connect Workbench to an Engine. If necessary, create a new Initiate project and import a hub configuration. See the Master Data Engine Installation Guide.

5

Verify that the Initiate menu contains the options Create Default Composer Configuration and Generate Composer Artifacts.


11

www.Initiate.com

Composer Guide

Downloading the BlazeDS WAR file As mentioned in the “Common Terms” on page 8, BlazeDS is an open-source messaging technology that manages communication between the Composer APIs on the application server and the Initiate Master Data Service. To enable this technology, you must first download the BlazeDS WAR file and save it within your application server installation. How to download the BlazeDS WAR file 1

Navigate to the Open Source home page at opensource.adobe.com.

2

Click the BlazeDS icon and, on the page that appears, choose Downloads from the list in the right pane.

3

On the page that appears, choose Download BlazeDS 3.x branch Nightly builds from under Nightly Builds.

4

On the page that appears, under Milestone Release Builds, choose the most recent build from the Binary column.

5

If asked, log in with your Adobe ID (or create a new Adobe account) and accept the End User License Agreement.

6

Navigate in your local file system to the downloaded zip file and extract the contents of the file.

7

Save the blazeds.war file in a temporary folder.

Installing the Adobe® Flex® Builder™ plug-in Initiate recommends installing the Flex Builder plug-in within the Initiate Workbench environment to allow for a single Eclipse development environment. Adobe’s Flex Builder 3 download page includes downloads both for Flex Builder 3 Professional and for Flex Builder 3 Professional Eclipse Plug-in. Be sure to download the Flex Builder Professional Eclipse Plug-in, unless you wish to develop Flex applications within an independent Eclipse environment. In that case, download and install Flex Builder 3 Professional. Note: Adobe allows users to download free trials of Flex Builder 3 Professional Eclipse Plug-in, effective for sixty days. Ultimately, be sure to use a fully licensed version of Flex Builder 3. How to install the Flex Builder plug-in within Workbench 1

Close all browsers.

2

Close Workbench.

3

Browse to the workbench.ini configuration file. Typically you can find the file at C:\Program Files\InitiateSystems\Workbench9.2.0\

4

Edit the file to set the following parameters: -Xms128m -Xmx512m -XX:MaxPermSize=256m -XX:PermSize=64m Note that the default workbench.ini file contains a setting for -Xmx that you’ll overwrite; the other parameters will be new.


12


1 Getting Started

5

Save and close workbench.ini.

6

Navigate to the Adobe homepage (adobe.com) and search for “Flex 3 downloads.”

7

Navigate among the search results to the Flex Downloads page.

8

Choose Flex Builder 3 and on the page that appears download the Windows version of the Flex Builder 3 Eclipse Plug-in — which differs from the standalone Flex Builder 3 Professional application.

9

Run the executable.

10 Accept the terms of the license agreement and the default installation directory. 11 When asked to Choose an Existing Eclipse Folder, browse to the Workbench installation directory. For example: C:\Program Files\Initiate Systems\Workbench9.2.0 12 Click OK to close the browsing window and then click Next. 13 On the Additional Installations panel of the installer, select the option for JSEclipse - JavaScript plugin. 14 Choose to complete the installation. As indicated by a pop-up window in the installer, administrators can manually configure the Flex Builder plug-in as a Product Extension. The following steps describe the process. 15 Restart Workbench and navigate in the main menu to Window > Preferences > General > Capabilities. 16 In the list of capabilities, check the box for Classic Update and click OK. 17 Navigate in the main menu to Help > Software Updates > Manage Configuration. You may notice that the menu lists Software Updates twice. Choose the one that expands to display Manage Configuration. 18 In the window that appears, choose Add an Extension Location in the right pane. 19 Browse to the eclipse folder within the Flex Builder 3 Plug-in installation directory. By default, this will be: C:\Program Files\Adobe\Flex Builder 3 Plug-in\eclipse\ 20 Click OK. 21 Restart Workbench as recommended. 22 Once Workbench has restarted, navigate to Window > Open Perspective > Other to verify that Flex Debugging, Flex Development, and Flex Profiling appear.

Installing Apache Tomcat Even if you will deploy your Composer application to a remote Apache Tomcat or IBM WebSphere® application server, you must install Tomcat on the same machine where you will install Composer. If you do not already have a local installation of Tomcat, download and install it as described below. Tomcat requires that you have a compatible JDK (Java Development Kit) installed. On Windows, to verify that the JDK is installed, open a command-line window and type java -version. If the JDK is installed, you will see something like: java version "1.6.0_17" Java(TM) SE Runtime Environment (build 1.6.0_17-b04) Java HotSpot(TM) Client VM (build 14.3-b01, mixed mode, sharing)


13

www.Initiate.com

Composer Guide

If you get the message “java is not recognized as an internal or external command“ it means that the JDK is not installed and you will need to download and configure it. How to download and configure the Java JDK 1

Navigate in your browser to http://java.sun.com/javase/downloads/index.jsp.

2

Choose to download the Java Platform (JDK).

3

Make sure that the Platform is set to Windows and click Download.

4

When prompted to Log In for Download, choose to Skip this Step.

5

Choose to save the JDK executable.

6

Run the executable and accept the defaults.

7

Navigate to Start > Control Panel > System > Advanced.

8

Click Environment Variables.

9

For System variables, choose New, and set the new variable name to JAVA_HOME and the value to the path of the new JDK installation, for example: C:\Program Files\Java\jdk1.6.0_17

10 Click OK. 11 Still in System variables, choose to Edit the PATH variable. 12 At the end of the string, append a semicolon and include a pointer to the bin subdirectory of JAVA_HOME. You can specify either the new JAVA_HOME variable followed by \bin (for example, %JAVA_HOME%\bin) or the full path (for example, C:\Program Files\Java\jdk1.6.0_17\bin). 13 To test the JDK, open a command-line window and type java -version. You should now see the output described above. You’re now ready to install Tomcat. How to install Apache Tomcat 1

Navigate to http://tomcat.apache.org

2

In the left column, click the link to download Apache 6.x. Refer to the 9.2 Initiate Master Data Service® Technology Requirements for details on supported versions. The steps below use version 6.0.24.

3

From among the Binary Distributions choose the version appropriate to your operating system.

4

Unzip the file to C:\. This creates the directory C:\apache-tomcat-6.0.xx.

5

Navigate to Start > Control Panel > System > Advanced.

6

Click Environment Variables.

7

For System variables, choose New, and set the new variable name to CATALINA_HOME and the value to the path of the new Tomcat installation: C:\apache-tomcat-6.0.24

8

Click OK.

9

In a command-line window, navigate to C:\apache-tomcat-6.0.24\bin and type startup.bat. Tomcat starts and prints status messages.

10 To verify that Tomcat is running, browse to http://localhost:8080. You should see the Tomcat home page.


14


1 Getting Started

Creating the default Composer configuration Note: Administrators should plan to regenerate the Composer configuration and regenerate the Composer components and services whenever the data model changes. Once you have installed Composer, the Flex Builder plugin, and Tomcat, return to Initiate Workbench to generate the default Composer configuration against your existing data model. The process opens the Composer Configuration Editor and creates the project-name/composer/composer.icc configuration file, visible in the Workbench Navigator view. As described in subsequent sections, you will edit the composer.icc using the Composer Configuration Editor to choose and configure the components and blueprints you want to be available as building blocks for your applications. How to create the default Composer configuration 1

From the Initiate menu, click Create Default Composer Configuration.

2

In the pop-up window that appears, choose the project into which to save the configuration file. The Composer Configuration Editor opens.

3

Verify that the composer.icc file appears within project-name/composer/ in the Workbench Navigator view.

4

Configure the Composer components as described in the section “Configuring components within Composer” on page 15.

Configuring components within Composer As mentioned, Composer has a one-step process for generating components and services to be assembled within Flex Builder into applications. As part of that generation process, Composer reads the composer.icc configuration file which specifies attribute and field settings for each component and blueprint that you choose to generate. Composer components parallel standard components in Flex (buttons, forms, and so on); by contrast blueprints are pre-wired arrangements of Composer components designed to enable common sets of tasks, for example the Member Search blueprint combines the Member Search Form component, the Member Search Results component, and the Member Details View component, all of which are optimized for member data. Blueprints indicate the flow of events from one component 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. By editing Composer components and blueprints with the Composer Configuration Editor prior to generating the components for Flex Builder, administrators can govern the name, member type, and search functionality. How to select the components and blueprints you want to make available as building blocks for your applications 1

If it is not already open, launch the Composer Configuration Editor by double-clicking the composer.icc within the project-name/composer/ directory in the Navigator.

2

On the Components view, click the green plus-sign. The right pane populates with a list of available blueprints and components.

3

Select a blueprint or component and click Add. The selected blueprint or component appears in the list within the left pane of the Editor, and the right pane populates with configuration options for the particular blueprint or component. As you’ll see, blueprints function as containers for components. Edit the settings for the blueprint itself or select any component within the blueprint to edit its settings.


15

www.Initiate.com

Composer Guide

For details about the individual components and blueprints including a description of available configuration options, see “Components and Blueprints Reference” on page 25. Note: Be sure to complete the configuration steps described in the rest of this chapter before attempting a detailed configuration of components and blueprints. For now, simply add one or two components to your configuration and continue with the steps. Within this chapter, a later section, “Regenerating Composer artifacts” on page 22, describes the subset of steps required for generating Composer artifacts after you have configured components and blueprints in detail. 4

For Name, Generated File Name, and (for components) Title, specify values that reflect the role the component or blueprint will play in your application.

5

Specify values for Member Type and Search As or Entity Type for each blueprint and component. Note that for components contained within blueprints, the same Member Type and Search As settings apply across all components in the blueprint, and they are therefore set for the blueprint rather than for the individual components.

6

Optionally, select an Attribute Set for each component. 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 will display within a Composer component, these are the fields that will appear by default within the generated components. For more information about attribute sets, see “Attribute Sets view” on page 29.

7

Navigate to the Model view and expand the pane until the Member/Entity type table and Attribute drop-down menu are both visible. The Model view offers a way to attach meaningful labels to the display of member instances and entity instances. When a Composer application retrieves the instance of a member or entity, it can display the specified label for the data. For a full explanation, see the discussion of the “Model view” on page 26.

8

As you complete the configuration for each blueprint or component, click the Save icon in the Workbench toolbar to record your changes. Changes are saved to the composer.icc file.

9

Repeat the process for all blueprints or components that you want to make available in Flex Builder.

10 When you finish, save your changes. Once you generate the components and services as described in the next section, the configuration settings you’ve chosen are reflected in a set of component-specific .mxml files. Additionally, for each blueprint, Composer generates blueprint-specific .mxml file as well as an event mapping file named blueprint-name_eventMap.mxml which describes the flow of events between the components that the blueprint contains.

Generating and enabling Composer artifacts Note: Administrators should plan to regenerate the Composer configuration and regenerate the Composer components and services whenever the data model changes. Depending on which components and blueprints you selected to be generated, the steps below generate the Composer components and blueprints that administrators will use to assemble applications. To generate the components and blueprints, the generation process reads configuration information from the composer.icc configuration file, whose contents you manipulated by editing components and blueprints within the Composer Configuration Editor described in “Configuring components within Composer” on page 15. After you have generated the components and blueprints according to the steps below, you can further customize them within Flex Builder to adjust colors, fonts, layout, event processing, and so on.


16


1 Getting Started

How to generate the Composer components and blueprints 1

Within Workbench, from the Initiate menu, click Generate Composer Artifacts.

2

In the window that appears, choose a project from the drop-down menu. By default all of the following options are selected: Clean the Composer services directory. Indicates that the process will delete any Initiate-generated folders and files. The process does not delete the blazeds.war file that you will copy into the directory in the steps below. Generate Composer services source code. Indicates that the process will generate the service layer code, which will execute on the server. The process creates the Java services used by the Flex client. Note that the system that is ultimately deployed is three tiers: Master Data Service and Relationship Service; J2EE Web Server; and Flex Client. If you are making changes only to the Flex configuration, you can save time by not regenerating the Java layer. Compile and package the Composer services. Indicates that the generation process will output a composersvcs.war file in the project-name/composer/services/dist/ directory. The composersvcs.war file bundles the Composer services so that administrators can deploy them to an application server. (Note that the process writes the source files for the war file to the project-name/composer/services/WEB-INF directory.) For more information, see “Deploying Composer Applications” on page 41. Clean the Composer client directory. Indicates that, prior to generating, the process will delete the contents of the client directory which contains UI component and blueprint code. This is recommended when regenerating the source files and is helpful if you encounter errors and need to start over. Generate Composer user interface components source code. Indicates that the process generates the UI code, which is currently Flex code. The code is ultimately executed on the browser.

3

The first time you generate Composer artifacts you must first create services and components code that can be consumed by the BlazeDS WAR file. Until those artifacts are created and the BlazeDS WAR file is copied into place, Composer cannot compile and package the Composer services. Therefore in the list of options above, deselect Compile and package the Composer services.

4

Click Finish. The generation process creates two new folders within project-name/composer/: client/ — This folder contains the libs/ folder and the src/ folder. The libs/ folder contains the libraries that are needed by the generated client code. Similarly, the src/ folder contains the Composer-generated Flex application source files. The directory also includes any blueprint-specific event mapping files created as part of generating Composer artifacts. services/ — This folder contains the Composer-generated services to support the components and blueprints. The source files can be either interaction handler Java source files or Composer source files.

Note: If you do not immediately see the directories within the project, right-click the project-name/composer folder and choose Refresh. 5

Copy the BlazeDS WAR file from the temporary directory where you saved it in Step 7: “Save the blazeds.war file in a temporary folder.” on page 12.

6

Paste the WAR file into the newly created project-name/composer/services/lib/ directory within the Workbench Navigator.


17

www.Initiate.com

Composer Guide

7

Generate the Composer artifacts again (Initiate > Generate Composer Artifacts), but this time select the option to Compile and package the Composer services. Once the blazeds.war file is in place and active, you should not need to deselect the compile-and-package option when you generate Composer artifacts in the future.

8

Next, follow the instructions for “Configuring your local Tomcat installation” on page 18.

Configuring your local Tomcat installation 1

Stop Tomcat if it is running. To do so, navigate at a command-line prompt to the bin/ directory within your Tomcat installation and type shutdown.bat.

2

Navigate in the file system to the composer/services/dist/ directory within your Workbench project. For example: C:\Documents and Settings\username\workspace\project-name\composer\services\dist\

3

Copy the composersvcs.war file.

4

Paste composersvcs.war within the Tomcat webapps directory (or into a subdirectory of webapps). For example, paste the file within: C:\apache-tomcat-6.0.24\webapps\

Note: Deploying the composersvcs.war file at this point functions as a preliminary test of your environment. As you’ll see in “Deploying Composer Applications” on page 41, the version of composersvcs.war that ultimately gets deployed to your application server will contain the full set of Flex and Java classes required for your Composer application. 5

Ensure that the Initiate engine is running.

6

Restart the Tomcat by navigating at a command-line prompt to the bin/ directory within your Tomcat installation and type startup.bat.

7

Navigate in your browser to verify that Tomcat is running as expected. By default, the Tomcat home page is available at: http://localhost:8080/

8

Configure connection information as described in “How to set Master Data Engine connection parameters for Tomcat:” on page 18.

Setting Master Data Engine connection parameters for the local Tomcat installation The following instructions apply to your local installation of Tomcat. Before deploying your Composer application, you will need to perform the same configuration on your remote installation of Tomcat or WebSphere as described in the chapter “Deploying Composer Applications” on page 41. In order for the Composer applications that you generate to connect with the Master Data Engine, the application server needs the appropriate connection information. As described below, edit the composersvcs.properties template delivered with Composer and save it in a new shared/classes/ directory. How to set Master Data Engine connection parameters for Tomcat: 1


2

Navigate in the file system to your Tomcat installation’s conf directory.

3

Open catalina.properties in a text editor.


18


1 Getting Started

4

Verify that the entry beginning with shared.loader= reads: shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar

5

Save and close catalina.properties.

6

Within the Tomcat installation directory, create a directory named shared, for example: C:\apache-tomcat-6.0.24\shared

7

Within the new shared directory, create a classes directory.

8

Navigate in the file system to the composer/services/ directory within the Workbench workspace, for example: C:\Documents and Settings\username\workspace\project-name\composer\services\

9

Copy the composersvcs.properties file and paste it into the shared/classes/ directory you created.

10 Open composersvcs.properties. 11 Uncomment the following lines by removing the initial pound signs (#) and set the values to reflect a valid username and password for your installation: adminloginProvider.username=system adminloginProvider.password=system If your configuration uses the default system/system credentials and running the Master Data Engine at localhost:16000, you do not need to uncomment the lines or change the values. 12 Save and close the file. 13 Restart Tomcat.

Configuring Flex settings for your Initiate project Before you can view and edit the Composer artifacts within the Flex Builder development environment, you must enable Flex Builder by setting various parameters. Follow the steps below to allow your Initiate project to function as a Flex project and to set the compiler and SDK settings that Flex Builder requires. How to configure Flex settings for your Initiate project 1

Within Initiate Workbench, right-click your Initiate project and choose Flex Project Nature > Add Flex Project Nature.

Note: If you wish to develop Flex functionality within an independent Flex project, instead of adding Flex Project Nature to your Initiate project, create a separate Flex project by enabling the Flex Development perspective (Window > Open Perspective > Other > Flex Development) and creating a new Flex project (File > New > Flex Project). Copy the libs and src directories from the project-name/composer/client/ directory to your new Flex project. 2

Within the popup window, for Server technology, set Application server type to J2EE and accept the defaults that appear. Specifically, leave Use remote object access service and LiveCycle Data Services selected.

3

Click Next.

4

For Server location, deselect the checkbox for Use default location for local LiveCycle Data Services server.


19

www.Initiate.com

Composer Guide

5

For Root folder, browse to and select the folder created when Tomcat unpacked the composersvcs.war. For example: C:\apache-tomcat-6.0.24\webapps\composersvcs\ This must be the parent directory of the WEB-INF folder.

6

Click OK.

7

For Root URL, indicate where the composersvcs will be deployed. For example: http://localhost:8080/composersvcs

8

For Context root, input: /composersvcs

9

Click Validate Configuration to verify that the application server is running properly at the location you’ve specified. If so, the wizard indicates that The web root folder and root URL are valid.

10 For Compilation options, accept the default selection: Compile application locally in Flex Builder. 11 For Compiled Flex application location, choose an Output folder. By default, this is the project-name-debug folder within the webapps directory or subdirectory. For example: C:\apache-tomcat-6.0.24\webapps\composer\project-name-debug 12 Click Finish. 13 When prompted to Switch to the Flex Development perspective, click Yes. 14 Right-click the project-name/ folder and choose New > Folder to create the following new folders: flex_src flex_libs 15 In order to prevent configured blueprints and components from being overwritten the next time you choose to Generate Composer Artifacts, distribute the contents of the project-name/composer folder into the folders you just created. In particular: Copy the contents of project-name/composer/client/src/ into project-name/flex_src/ — Besides the Composer-generated Flex application source files, use this folder to contain any custom-created Flex components that you want to include in your Flex application. Copy the contents of project-name/composer/client/libs/ into project-name/flex_libs/ — This folder will contain the Flex libraries consumed by the Flex application. 16 In the Flex Navigator, right-click the project and choose Properties. 17 Choose Flex Compiler. 18 In the section Flex SDK version, make sure that the project is using the Flex 3.2 SDK. 19 Click Apply. 20 Still within the Properties window for the project, choose Flex Build Path from the left pane. 21 Change the Main source folder to flex_src. 22 Click the Library path tab to change the right-pane view. 23 Select the libs folder and click Edit. 24 On the Edit Folder Path dialog, choose Browse and navigate to the flex_libs directory. For example:


20


1 Getting Started

Desktop > My Computer > Local Disc (C:) > Documents and Settings > username > workspace > project-name > flex_libs 25 Click OK to exit the browse popup. 26 Click OK to confirm the folder path. 27 Click OK to close the Properties window. Workbench updates the compiler settings. 28 Once again, right-click the project and choose Properties. 29 Choose Flex Applications. 30 Click Add. 31 In the Add Application Files dialog that appears, choose DemoMainApplication.mxml and click OK. 32 Select DemoMainApplication.mxml and click Set as Default and OK. The Properties window closes as Workbench updates the compiler settings. 33 Within the project-name/flex_src directory, double-click any of the .mxml files to open that file within the Flex Development perspective. You can now manipulate components and blueprints in the Flex Development perspective according to your needs. For details about the individual Composer components, see “Components and Blueprints Reference” on page 25. For details about generating and deploying Flex applications, see “Deploying Composer Applications” on page 41.

Testing an application in the Flex Development perspective As mentioned earlier, DemoMainApplication.mxml is the default Composer application file. To test your application, run DemoMainApplication.mxml as described below. 1

Within the Flex Development perspective, select DemoMainApplication.mxml within the project-name/ flex_src directory.

2

From the main menu, choose Run > Run, or click the green run button.

3

If a Run As popup appears, choose Flex Application and click OK.

4

If a Save and Launch popup appears, accept the defaults and click OK. Flex Builder launches a browser and displays the login panel for the application.

5

Enter your username and password credentials for the Master Data Engine. The defaults are system and system. For details about managing login, see “Managing authentication for your applications” on page 34.

If you have completed all of the steps above, you should now be able to use the application to search the data available within the hub configuration you imported in Step 4 of the instructions “How to install Composer” on page 11. Now that you have tested the application locally in the Flex Development, you’re ready to make the application available to end users. See “Deploying Composer Applications” on page 41. If you first need to change or add Composer’s Java layer, see “Preparing to edit Composer components within the Java perspective” on page 22. If at any time you need to regenerate the Composer artifacts, see the quick reference information for doing so: “Regenerating Composer artifacts” on page 22.


21

www.Initiate.com

Composer Guide

Preparing to edit Composer components within the Java perspective By editing Composer generated files, users can make changes or add services to Composer’s Java layer. Follow the steps below to prepare the environment and artifacts for editing. How to prepare to edit Composer components within the Java perspective 1

Create a temporary directory in the file system.

2

Navigate in the file system to the project-name/composer/services/dist/ directory within your Workbench project. For example: C:\Documents and Settings\username\workspace\project-name\composer\services\dist\

3

Create a copy of the composersvcs.war file and rename the copy to composersvcs.zip.

4

Using WinZip or a similar extraction program, extract composersvcs.zip into the temporary directory you created. You’ll see two subdirectories: META-INF and WEB-INF.

5

Navigate to the WEB-INF\lib directory.

6

If it does not exist already, create a project-name/lib directory in the file system. By default, this would be: C:\Documents and Settings\username\workspace\project-name\lib

7

Copy all of the JAR files and paste them into the project-name/lib directory.

8

Within Workbench, right-click your project and choose Refresh.

9

Right-click your project and choose Properties.

10 Choose Java Build Path. 11 Choose the Libraries tab and click Add JARs. 12 Navigate to the project-name/lib directory and shift-select all of the JAR files. 13 Click OK to exit the JAR Selection window. 14 Click OK to exit the Properties window. 15 Copy the contents of project-name/composer/services/src/ into project-name/src — This folder will contain Java source code, including interaction handlers for communication with the Master Data Service and Relationship Service, as well as source code for J2EE Composer web services. 16 Navigate to Window > Open Perspective > Other and choose Java. You should now be able to edit and compile the Composer Java files.

Regenerating Composer artifacts If you have completed the steps in “Getting Started” on page 11, you only need perform a subset of the steps each time you need to regenerate Composer artifacts. How to regenerate composer artifacts 1

Within Workbench, from the Initiate menu, click Generate Composer Artifacts. If you don’t want to overwrite existing artifacts, deselect Clean the Composer client directory.

2

Stop Tomcat if it is running. To do so, navigate at a command-line prompt to the bin/ directory within your Tomcat installation and type shutdown.bat.


22


1 Getting Started

3


4

Copy the composersvcs.war file and paste it within the Tomcat webapps directory (or into a subdirectory of webapps). For example, paste the file within: C:\apache-tomcat-6.0.24\webapps\

5


6

Restart Tomcat. To do so, navigate at a command-line prompt to the bin/ directory within your Tomcat installation and type startup.bat.

7

Navigate in your browser to verify that Tomcat is running as expected. By default, the Tomcat home page is available at: http://localhost:8080/

8

Within Workbench, copy the contents of project-name/composer/client/src/ into project-name/flex_src/

9

Still within Workbench, copy the contents of project-name/composer/client/libs/ into project-name/ flex_libs/

10 Right-click the project and choose Properties. 11 Choose Flex Applications. 12 Click Add. 13 In the Add Application Files dialog that appears, choose DemoMainApplication.mxml and click OK. 14 If DemoMainApplication is not already specified as the default, select it and click Set as Default, then OK. The Properties window closes as Workbench updates the compiler settings. 15 Within the project-name/flex_src directory, double-click any of the .mxml files to open that file within the Flex Development perspective.

Uninstalling Composer How to remove Initiate Composer from your Workbench installation 1

Close Workbench.

2

Navigate to the Workbench plugins directory. The folder will typically be: C:\Program Files\InitiateSystems\Workbench9.2.0\plugins

3

Delete the Composer directory: com.initiatesystems.workbench.composer_9.2.0.

4

Restart Workbench.

5

Confirm that the Initiate menu no longer contains the options Create Default Composer Configuration and Generate Composer Artifacts.


23

www.Initiate.com

Composer Guide


24


2 Components and Blueprints Reference

Overview Note: This chapter assumes that you have completed the steps described in the chapter “Getting Started” on page 11. As explained elsewhere, a component is a GUI-based element that performs a function within an Adobe® Flex® Builder™ application. A component can be as simple as a button or as sophisticated as a viewer for displaying complex relationships between entities. By extension, a blueprint is an assembly of several components wired together to manage the events flowing from one component to another. Blueprints are intended to answer certain common business needs. For example the Member Search blueprint combines the Member Search Form component, the Member Search Results component, and the Member Details View component in an attempt to answer an end user’s need to search for an individual (or product, etc), display the search results, and view details for any particular item in the returned list. Behind the scenes, each blueprint includes a blueprint-name_eventMap.mxml file that governs the flow of events from one component to another. For example, clicking a button in one component may prompt a database query whose results are deployed in a second component. This chapter describes the steps for configuring and extending individual Composer components and for configuring Composer blueprints. It also offers the steps for managing and customizing the login panel that appears by default for Composer applications.

Composer Configuration Editor Note that changes made via the Composer Configuration Editor are written to the composer.icc file. When you have completed and saved your changes, you will run a generation process that uses composer.icc to create the specified set of components and blueprints for further configuration within Flex Builder.

Components view The Components view allows you to specify and configure the components and blueprints you generate for use within Flex-based applications. The Components view is the default view when you open the Composer Configuration Editor. If the view is not active, navigate to it by clicking the button that displays geometric solids (at the top of the editor). Within the view, clicking the green plus sign populates a list of choices. Selecting a blueprint or component and clicking Add opens a configuration pane specific to that blueprint or component. As you’ll see, blueprints function as containers for components. Edit the settings for the blueprint itself or select any component within the blueprint to edit its settings.


25

www.Initiate.com

Composer Guide

In general, the Component Configuration view allows you to indicate the Name, Generated File Name, Title, Member Type, Search As, and Attribute Set. Ensure that the names and titles you choose are unique across your Composer configuration. The Name field governs the name of the component as it appears within the Components and Blueprints tree of the Composer Configuration Editor and within the Workbench Navigator. The Generated File Name allows you to specify the name of the generated .mxml file. You might change the Generated File Name if you want to indicate more precisely what this component will do in the context of your application. You may also have particular filename conventions that you want all component files to obey. Note that besides needing to be unique across your Composer configuration, Generated File Names must adhere to the following conventions for MXML files: Filenames must start with a letter or underscore character (_), and they can only contain letters, numbers, and underscore characters after that. Filenames must not be the same as ActionScript class names, component id values, or the word application. Do not use filenames that match the names of MXML tags that are in the mx namespace. Filenames must end with a lowercase .mxml file extension. The Title field allows you to specify a string that will appear in the upper left of the generated component within the Flex Development environment — and within the application itself. Each blueprint allows you to specify Member Type and Search As. The values available for Member Type will depend on the model for your underlying data. Once you have chosen a value for Member Type, the Search As field populates with the entity types available for populating a view of that member type. Typically, Member Type and Search As have a one-to-one relationship. However with some data sets, typically those specific to healthcare, a single member type may be searchable using any of several entity types. Notice that individual components also allow you to specify Member Type and Search As (which, for some components appears as Entity Type) — but only if the component is not contained within a blueprint. The Member Type and Search As settings must be the same across all components in a blueprint, and they are therefore set for the blueprint rather than for the individual components when the components are contained within a blueprint. The Attribute Set field allows you to indicate which attributes and fields to display for the component. The drop-down menu displays any attribute sets you have created within the Attribute Sets view (a sibling to the current Components view). Note that attribute sets will not appear within the drop-down for the component until you have chosen the Member Type for the blueprint — or for the component itself if the component is an independent component. As described within “Common Terms” on page 8, an attribute set is a container that administrators can create and configure in order to specify the set of attributes that will display within an individual Composer component — or for a member type or entity type across all Composer components. Note that the Composer Configuration Editor does not allow you to configure a single attribute set for a blueprint, based on the assumption that the different components within a blueprint will typically need to use different attribute sets. For more information about the Attribute Sets view, see “Attribute Sets view” on page 29.

Model view The Composer Configuration Editor also includes the Model view, which allows administrators to configure how Master Data Engine data appears within Composer components. In order to switch to the Model view within the Configuration Editor, click the button that shows the purple cube. Initiate Systems, Inc.

26



As explained in the instructions that follow, the Model view allows administrators to: Configure the composite view for members and entities. Assign attribute sets for members and entities. Set instance labels for Relationship Viewer entities. Note: Because the Composer configuration accesses a single data model, the view within the Model view does not vary by component or blueprint.

Configuring the Composite View The table within the Model view includes a Composite View column which allows administrators to configure the composite view for individual members and entities. You will only need to consider the Composite View column if you have created one or more composite views within your project’s member model. By default, Composer components will use the EMCA (Entity Most Current Attribute) composite view for the display of entity information, and the MMCA (Member Most Current Attribute) composite view for the display of member information. A composite view determines which value to display when multiple values are available for an individual member or entity attribute. For example, one of the member records associated with an entity may indicate that the person lives in Chicago while another indicates that the same person lives in Phoenix. Adhering to the default EMCA composite view for the entity, the Composer component will display whichever entity attribute value for city was most recently created or modified, regardless of which member record contains the value. The same mechanism applies to the display of member attribute values. Adhering to the default MMCA composite view for the member, the Composer component will display whichever attribute value was most recently created or modified, again regardless of which member record contains the value. By contrast, configuring your own composite view for the project will alter the mechanism that determines what to display. For example, configuring a Trusted Source composite view will cause Composer components to display whichever value for an attribute comes from the member record associated with the single trusted source — even if that value is not the most recent. It is also possible to designate a Controlled composite view that displays a selection of attributes from multiple specified sources. For example, you can configure the composite view to display name and address information from Source A, phone and birth date from Source B, and Social Security number and address from Source C. For complete details about creating and configuring composite views, see the Workbench Reference Guide. Any composite views created for a project appear in the drop-down menu within the Composer Configuration Editor Model view. Composite views for entities appear in the drop-down menu for entities, while composite views for members appear in the drop-down menu for members. Note: If you have just created new composite views, they may not immediately appear in the Composer Configuration Editor. You may need to close and re-open the Composer Configuration Editor. How to configure the Composite View for a member or entity: 1

Within the Composer Configuration Editor, navigate to the Model view.

2

Under the Composite View table heading click within the cell that corresponds to the member or entity you want to configure.

3

Click the down arrow that appears at the right of the cell.

4

Choose from the composite views available.

5

Repeat as necessary to configure the entities and members.


27

www.Initiate.com

Composer Guide

6

Save your changes.

Assigning an Attribute Set The Model view includes a Attribute Set column which allows you to indicate which pre-configured set of attributes should display by default for a member type or entity type across all the Composer components where the member type or entity type appears. In other words, the setting serves as the global setting for the member or entity type. If you set a different attribute set within an individual component, that setting will override the global setting. To create a new attribute set, use the Attribute Set view within the Composer Configuration Editor. See “Attribute Sets view” on page 29. For a definition of attribute sets, see “Common Terms” on page 8.

Setting instance label patterns for Relationship Viewer entities The Model view offers a way to set a label for instances of members and entities when they appear within the Relationship Viewer component. For example, consider a graph in the Relationship Viewer that is populated with instances of entities. By default, the label for each entity in the graph is entity name:entity id — which is unlikely to be meaningful to end users. Using the lower pane of the Model view, you can build a meaningful label that consists of formatted attribute fields for each entity. Selecting an entity or member in the left column of the table activates the lower pane where you can select an attribute and one or more of its fields to use when constructing the label. Once you have selected an attribute, click the Insert Field button to choose from the list of available fields for that attribute. For example, to format an instance label using a Name attribute so that it appears as “Last Name, First Name,” configure the instance label as lastname_attribute, firstname_attribute. The values of lastname_attribute and firstname_attribute will depend on your underlying data model. For a data model with the attributes onmlast and onmfirst, the instance label could be formatted as onmlast, onmfirst. An instance of the member “John Smith” would be rendered in the Relationship Viewer as Smith, John. In the same interface, the Insert Optional Tag button inserts into the line of markup. Within the optional tag, insert any fields that may or may not be available for the particular instance. For example, a particular person record may not include a middle name. You might therefore configure the following markup: onmlast, onmfirst onmmiddle Note in the example above that the optional tag includes a leading space to separate the value for onmmiddle from the value for onmfirst. Because the leading space appears within the optional tag, if no value is available for onmmiddle, the interface will not display the space. How to configure an instance label for entities in the Relationship Viewer: 1

Within the Composer Configuration Editor, navigate to the Model view.

2

From the table, choose the entity type corresponding to the instances that the Relationship Viewer will display. In our example, the entity type is id. Once you have selected the entity type, the Attribute selector in the lower portion of the pane becomes active. (Drag to expand the pane if you do not see the Attribute selector and Insert buttons.)

3

Choose the attribute that corresponds to the individual’s name, for example Legal Name.

4

Click the Insert Field button. A popup displays the available fields for the attribute.

5

Choose a field that corresponds to an individual’s last name and click OK.

6

Add a comma and space after the tag.


28



7

Click the Insert Field button again and add the field that corresponds to an individual’s first name.

8

Optionally, click the Insert Optional Tag to configure the display behavior for fields that may or may not have a value for a particular instance. Place your cursor within the optional tag, choose Insert Field, and insert the relevant field along with any punctuation that the component should include or omit based on the presence of a value for the field.

9

Save your changes.

Attribute Sets view To navigate to the Attribute Sets view within the Composer Configuration Editor, click the button that displays the overlapping cards (at the top of the editor). Attribute sets are containers that administrators can create and configure in order to specify the set of attributes that will display within a Composer component — or for a member type or entity type across all Composer components. Attribute sets offer administrators a convenient way to reuse sets of attributes across multiple components rather than configuring the same individual attributes each time they create a new component. For example, for a Entity Search Form component, suppose you want to allow the user to search by first name, last name, zip code, or Social Security number. Let’s further suppose that you would like the Entity Search Details component to display not only the attributes just mentioned but also gender, street address, telephone numbers. You might therefore create and configure two attribute sets, one called EntitySearchFormAttributes to indicate the fields to display within the Entity Search Form component, and a second called EntitySearchDetailsAttributes to indicate the fields to display within the Entity Search Details component. By contrast, you may decide that all components should always display the same attributes regardless of the component, you can set the attribute set for the member type or entity type within the Attribute Set column of the Model view. The setting will serve as a global setting for across components. If you do not create and assign attribute sets, each Composer component will display all the attributes for the Member Type you selected for the component or blueprint. How to create and configure an attribute set: 1

Within the Composer Configuration Editor, navigate to the Attribute Sets view.

2

Click the green plus-sign. A new attribute set appears in the first available table row.

3

In the Name column, click the new attribute set and assign a name that reflects how you will use the attribute set, for example EntitySearchFormAttributes or EntitySearchDetailsAttributes.

4

In the Member Type column, choose a member type from the drop-down list. The fields available in the list depend on the model for your underlying data. Note that you can create multiple attribute sets for a single member type. As mentioned in the example, you might choose to use one attribute set for one component and a different attribute set for another component.

5

Next choose which attributes and fields you want to include in the attribute set by moving those attributes from the Currently Hidden list to the Currently Displayed list.

6

Optionally, configure the Label setting for the attributes in the Currently Displayed list. The labels you configure will appear as labels for the corresponding field within any component that uses this attribute set.

Note: The Attribute Pattern column is not functional for the current release of Composer. 7

Click the Save icon in the main menu bar.


29

www.Initiate.com

Composer Guide

Example: Configuring a blueprint The steps below offer a complete example of configuring and editing the Entity Search blueprint. Applying the steps in the example to your own data and needs can help you to become familiar with the end-to-end process. Subsequent sections offer details for each component and blueprint. Note: This example assumes that you have completed all of the steps described in “Getting Started” on page 11. How to configure the Entity Search blueprint 1

From the Initiate menu, choose Create Default Composer Configuration.

2

Select your project and click OK.

3

If prompted that an existing Composer Configuration already exists in the selected project, choose OK to replace it.

4

If prompted to load changes from the configuration file into the Composer Configuration Editor, click Yes.

5

In the Composer Configuration Editor, click the green plus-sign and select Entity Search from the list of blueprints.

6

Click Add.

7

Change the Name of the blueprint to Patient Search.

8

Change the Generated File Name to PatientSearch.

9

For Member Type, choose a member type corresponding to an individual. The underlying data in this example includes the PERSON member type.

10 For Search As, choose the entity type to use when conducting the search. The underlying data in this example includes the id entity type. 11 Click the Save icon in the main menu bar. 12 Navigate to the Attribute Sets view by clicking the button with the overlapping cards. 13 Click the green plus-sign to create a new attribute set. 14 Click the attribute set name and rename it to PatientSearchFormAndResultsAttributes. 15 Click in the Member Type column and select PERSON from the drop-down list. (Again, your data model will vary; for this example, the underlying data includes the PERSON member type.) 16 Among the attributes and fields that display, move the attributes corresponding to first name and last name from the Currently Hidden column to the Currently Displayed column. 17 In the Label column, edit the values to reflect the text you would like to display for these fields in the component interface, for example First name and Last name. Note: The Attribute Pattern column is not functional for the current release of Composer. 18 Once again, click the green plus-sign to create a new attribute set. 19 Click the attribute set name and rename it to PatientSearchDetailsAttributes. 20 Click in the Member Type column and select PERSON from the drop-down list. 21 This time, move the attributes corresponding to first name, last name, city, state, zip code, and Social Security number from the Currently Hidden column to the Currently Displayed column.


30



22 Again, edit the values in the Label column to reflect the text you would like to display for these fields in the component interface. 23 Click the Save icon in the main menu bar. 24 Still within the Composer Configuration Editor, navigate back to the Components view. 25 Under the Patient Search blueprint, choose Entity Search Form 1. 26 Change the Name of the component to Patient Search Form. 27 Change the Generated File Name to PatientSearchForm. 28 Change the Title to Search. 29 From the Attribute Set drop-down menu, choose PatientSearchFormAndResultsAttributes. 30 In the list of Patient Search components, choose Entity Search Results 1. 31 Change the Name of the component to Patient Search Results. 32 Change the Generated File Name to PatientSearchResults. 33 Change the Title to Search Results. 34 From the Attribute Set drop-down menu, choose PatientSearchFormAndResultsAttributes. 35 In the list of Patient Search components, choose Entity Details View 1. 36 Change the Name of the component to Patient Details View. 37 Change the Generated File Name to PatientDetailsView. 38 Change the Title to Details. 39 From the Attribute Set drop-down menu, choose PatientSearchDetailsAttributes. 40 Leave checked the setting for Enable entity editing and choose a Source from the drop-down menu. 41 Click the Save icon in the main menu bar. We’ll next generate the Composer artifacts and manipulate components within the Flex Development perspective. 1

From the Initiate menu, choose Generate Composer Artifacts.

2

Leave all options selected and click Finish.

Note: These steps assume that you have already copied the blazeds.war file as explained in “Generating and enabling Composer artifacts” on page 16. 3

Copy the contents of project-name/composer/client/src/ into project-name/flex_src/

4

Copy the contents of project-name/composer/client/libs/ into project-name/flex_libs/

5

Navigate to project-name/flex_src/ and double-click PatientSearchResults.mxml. The file opens in the right pane. By default, the component displays rows labeled Branch 1, Branch 2, and so on. At runtime, those labels will be names of the individual patient entities.

6

Suppose that we want to change the height of the rows in the results view. Begin by clicking on a row in the Search Results panel. Notice that the Flex Properties pane in the lower right of the Flex Development perspective changes to display the options available for mx:AdvancedDataGrid.

7

Click the second icon to the right of the Flex Properties tab label to change to the Category View.

8

Double-click rowHeight and specify a value of 35. The row height in the component changes accordingly.


31

www.Initiate.com

Composer Guide

9


10 Make sure that the Initiate Engine and Tomcat are both running. 11 In the main menu bar, click the green Run icon. 12 If prompted, choose to run as a Flex Application. Flex Builder opens a browser, prompts for login information (which is the same as the authentication for the Master Data Engine), and displays the application. Search against a known entity instance in your database to verify that search works as expected. Notice that Flex Builder launches DemoMainApplication, which you specified as the default application in Step 32 within “configure Flex settings for your Initiate project” on page 19. If you have configured multiple blueprints, the DemoMainApplication displays each blueprint on its own tab.

Finally, let’s manipulate the CSS for the blueprint to adjust a font color. 1

Navigate to project-name/flex_src/styles and double-click composer.css.

2

Search for the .mypanelTitle style. By default, color is set to ffffff, the hexadecimal code for white.

3

Change the value to ff0000, the hexadecimal code for primary red.

4


5

In the left pane, double-click project-name/flex_src/PatientSearchResults.mxml. The title text (“Search Results”) should now appear in red.

Composer components Member Add View — A popup form for adding a new member to a source you specify when configuring the component. Users authorized to add members will see a link to Add Member Record at the top right of the generated Flex application. The link will not appear for users who are not authorized. For more information, see “Configuring authentication for editing entities and adding members” on page 34. Member Search Form — A simple form for conducting searches based on member type attributes you specify in the Composer Configuration Editor. By default, the form includes Search and Clear buttons. Entity Search Form — A simple form for conducting searches based on entity type attributes you specify in the Composer Configuration Editor. By default, the form includes Search and Clear buttons. Member Search Results — A tabular display of search results in descending order according to a matching score. The table columns are based on the member type attributes you specify in the Composer Configuration Editor. Entity Search Results — A tabular display of search results in descending order according to a matching score. The table columns are based on the entity type attributes you specify in the Composer Configuration Editor. Note that by default, the Entity Search Results component displays the member records associated with an entity. However administrators can configure the component to hide those records. See “Hiding member records within an Entity Search Results component” on page 38. Member Details View — For a member you select from a Member Search Results list, a display of all the fields you specify in the Composer Configuration Editor. Note that the Design View within Flex Builder displays an empty panel for Member Details View components. The panel populates at runtime.


32



Entity Details View — For an entity you select from an Entity Search Results list, a display of all the fields you specify in the Composer Configuration Editor. Note that the Design View within Flex Builder displays an empty panel for Entity Details View components. The panel populates at runtime. When configuring an Entity Details View component in the Composer Configuration Editor, you will decide whether to Enable entity editing. If you leave the option enabled, you will then select the Source to which Composer will write the edits made by end users. In the deployed application, authorized users can click and edit the attributes for entities. For more information, see “Configuring authentication for editing entities and adding members” on page 34. In addition to Enable entity editing and Source, the Composer Configuration Editor offers a choice about whether to hard link the member records of an entity. For details, see “Managing edits made to entities” on page 37. Entity Details Popup View — As with the Entity Details View component, the Entity Details Popup View displays details for an entity you select from an Entity Search Results list. Rather than displaying the details within a separate pane or tab, Composer launches a popup. Note that unlike the Entity Details View component, the Entity Details Popup View component cannot be configured to allow end users to edit entity information. Relationship Viewer — A graphical display of connections between entities. The view is configurable at runtime. By default, the Design View for the component displays the configuration controls in a pane to the left of the display. Note that you can change the default icon that displays for each entity instance. See “Changing the default icon for the Relationship Viewer” on page 38. Related Entities — A read-only tabular display of entities related to the entity you select in an Entity Search Results component. Each tab in the display represents a relationship type such as boss or friend. The relationship types available will depend on your data model. To configure the attributes displayed in each tab, define a default attribute set for each entity type.

Composer blueprints Note: Events passing between the components are managed by the blueprint-name_eventMap.mxml file. See “Managing Composer Events” on page 49. Member Search — Combines the Member Search Form, Member Search Results, Member Details View, and Member Add View components into a default, single-page layout. Entity Search — Combines the Entity Search Form, Entity Search Results, and Entity Details View components into a default, single-page layout. Entity Search with Detail Popup — Combines the Entity Search Form, Entity Search Results, and Entity Details Popup View components into a default, single-page layout. Entity Search with Relationship Viewer — Combines the three components of the Entity Search blueprint with the Relationship Viewer component. By default, these are combined in a tabbed layout, with the Entity Search Form and Entity Search Results components on one tab, and the Entity Details View and Relationship Viewer component on a second tab. Entity Search with Related Entities View — Combines the three components of the Entity Search blueprint with the Related Entities component. By default, all four components are combined in a single layout.


33

www.Initiate.com

Composer Guide

Managing authentication for your applications The DemoMainApplication.mxml file contains code that launches a popup window to prompt application users for username and password information. Users should supply the same credential information they would use to log in to the Master Data Engine itself. The defaults for administrative privileges are system and system. When a user logs in, Composer sets a session cookie in memory that remains valid for as long as the user is actively using the application. By default the session ends when the user clicks Logout in the upper right within the application or after twenty minutes of inactivity. In either case the user must then log in again. To configure the timeout, edit the session-timeout parameter within your application’s web.xml file for the Composer application, for example: Tomcat: C:\apache-tomcat-6.0.26\webapps\composersvcs\WEB-INF\web.xml WebSphere: \\machine-name\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\installedApps \machine-nameNode01Cell\composersvcs_war.ear\composersvcs.war\WEB-INF\web.xml

Configuring authentication for editing entities and adding members Composer components that enable users to edit entities or add members require a higher level of authentication than is required for read-only functions. Because Composer authentication uses the Master Data Engine authentication framework, configure authentication permissions for Composer using the Workbench User Management tool as described below. How to configure authentication for editing entities and adding members within Composer applications: 1

Within Workbench, navigate to Window > Open Perspective > Other > User Management.

2

On the User Management tab that opens, if you are not already connected to a Directory Server, click the icon in the upper right of the perspective to Connect to a Directory Server.

3

Create or edit a user.

4

In the Group Membership pane in the lower right, assign the user as appropriate. Users assigned to All Segments Read Write will be able to add members and edit entities. Users assigned to All Segments Read Only will not.

Turning off the login panel for your application To turn off the login panel, you must configure Composer to pass a default set of credentials to the application for all operations. To do so, modify WEB-INF/beans-common.xml to replace the existing defaultLoginProvider bean definition with the login class and credentials. Instructions vary depending on your application server. To turn off logging for Tomcat, see “How to turn off the Composer login panel for Tomcat:” on page 34. To do so for WebSphere, see “How to turn off the Composer login panel for WebSphere:” on page 36. How to turn off the Composer login panel for Tomcat: 1

Navigate to the WEB-INF directory for your application. For example: C:\apache-tomcat-6.0.24\webapps\composersvcs\WEB-INF

2

Open beans-common.xml for editing.

3

Find and remove the defaultLoginProvider bean definition:

4

Paste in the following:


34



5

Save and close the file.

6

Navigate to the application server’s shared/classes/ directory. For example: C:\apache-tomcat-6.0.24\shared\classes\

7

Open composersvcs.properties for editing.

8

At the end of the file, paste in the following lines: loginProvider.classname=com.initiate.client.internal.DefaultLoginProvider loginProvider.username=system loginProvider.password=system

Note: By default, the username and password are system. If you have configured a different username and password for authentication to the Master Data Engine, in the lines above, specify the values you have configured. 9

Save and close composersvcs.properties.

10 If it is not already running, start Workbench. 11 Within the Flex Development perspective, open DemoMainApplication.mxml for editing. 12 In the mx:Application tag, remove the following event: creationComplete="applicationInit()" 13 Remove the complete mx:Script tag: 14 Remove the mx:LinkButton tag that defines the Logout button: 15 Save and close DemoMainApplication.mxml. 16 Test the change by running the application within the Flex Development environment.


35

www.Initiate.com

Composer Guide

How to turn off the Composer login panel for WebSphere: 1

Navigate to the WEB-INF directory for your application on the machine where WebSphere is running. For example: C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\ installedApps\machinenameNode01Cell\composersvcs_war.ear\composersvcs.war\WEB-INF\

2

Open beans-common.xml for editing.

3

Find and remove the defaultLoginProvider bean definition:

4

Paste in the following:

5

Save and close the file.

6

On the same machine, navigate to the properties directory for the appropriate server and profile. For example, C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\properties\

7


8

At the end of the file, paste in the following lines: loginProvider.classname=com.initiate.client.internal.DefaultLoginProvider loginProvider.username=system loginProvider.password=system

Note: By default, the username and password are system. If you have configured a different username and password for authentication to the Master Data Engine, in the lines above, specify the values you have configured. 9

Save and close composersvcs.properties.

10 If it is not already running, start Workbench. 11 Within the Flex Development perspective, open DemoMainApplication.mxml for editing. 12 In the mx:Application tag, remove the following event: creationComplete="applicationInit()" 13 Remove the complete mx:Script tag:

36



private function logout():void LoginManager.getInstance().logout(); */ LoginManager.getInstance().checkAuthentication(this); } ]]> 14 Remove the mx:LinkButton tag that defines the Logout button: 15 Save DemoMainApplication.mxml. 16 Test the change by running the application within the Flex Development environment.

Editing the login panel image You may edit the image associated with the login panel by supplying a new image and editing the composer.css style sheet: 1

Copy the new image file into the project-name/flex_src/assets/images/ folder.

2

Edit the .loginWindow style within project-name/flex_src/styles/composer.css to point to the new image.

3

Save and close the file.l

Note: By default, Composer expects an image that is 641 pixels wide by 375 pixels tall. If your image does not conform to those dimensions, edit width and height attributes within project-name/flex_src/com/initiate/ security/LoginWindow.mxml and edit the upper-left coordinates of the login window as specified by the .loginForm style within composer.css.

Managing edits made to entities Editing entities within the Entity Details View requires you to decide between two different behaviors. Because an entity record is composed of one or more member records, editing an entity record means the end user is editing one of the particular member records that comprises that entity record. For this reason, when as an administrator you configure the Entity Details View, you choose from among the sources whose records contribute to the entity record. When an end user clicks Update within the Entity Details View to record edits, he or she has made to an entity, Composer writes the new values into the member record within the particular source that you specified during configuration. If you have not done so already, you may wish to create a definitional source as the repository for the edited member records. For details, see Workbench Reference Guide. In the configuration pane for the Entity Details View, by default the checkbox for Hard link is checked indicating that Composer writes the new values to the member record within the specified source — and then issues a command that binds together the associated records for the entity using an identity rule, indicating that two or more members have been assigned the same Member ID. (In the API, this is known as a MemRule.) Note that this linking occurs each time a user edits an entity. If you uncheck the Hard link option, when the user updates the entity record, Composer writes the edited values into a member record within the selected source just as with Hard link. However, rather than linking the member records as occurs with Hard link, Composer then reads the values from the other member records that comprise the entity record — and writes those values into the member record within the selected source, where they appear as inactive values. If a member record does not yet exist within the selected source for the entity, Composer creates one. If there are multiple values for an attribute across the other source records, all values are written to the specified member record as inactive values.


37

www.Initiate.com

Composer Guide

Choosing this non-default behavior may be important for installations that also use the Initiate Entity Manager especially if the algorithms within the Entity Manager leverage inactive values to compare and score member attribute similarities and differences.

Hiding member records within an Entity Search Results component As mentioned earlier, by default the Entity Search Results component shows the member records associated with an entity. If you prefer that those records be hidden, set the memberRecordsEnabled parameter to false within the blueprint that contains the Entity Search Results component as described below. Doing so sets a MXML state that governs the behavior of the component. In particular, the memberRecordsEnabled within the blueprint setting governs whether the currentState for the component is set to ShowMemberRecords or HideMemberRecords. How to hide member records within an Entity Search Results component: 1

Within the Flex Development perspective, open the blueprint that contains the Entity Search Results component whose behavior you want to change.

2

Find the line that calls the Entity Search Results component. For example:

3

To hide member records, edit the line to set memberRecordsEnabled to false. For example:

4

Save your changes. At runtime, the memberRecordsEnabled setting will toggle the setting within the component.

Changing the default icon for the Relationship Viewer By default, each node in the Relationship Viewer is represented by a blue cube. To change the icon, copy your preferred icon into the project-name/flex_src/assets/images/ folder and edit the .mxml file for the Relationship Viewer component, as described below. The default icon (cube_blue.png) is 48 x 48 pixels and 71 dpi. Ideally, the icon you use to replace it should be a .png file with the same dimensions and a comparable resolution. If the images is larger, Flex Builder will attempt to resize it in the display. How to change the default icon for the Relationship Viewer 1

Navigate project-name/flex_src/assets/images/ folder.

2

Paste your icon into the folder.

3

Within the Flex Development perspective, double-click the.mxml file for the Relationship Viewer component. If you have followed the steps elsewhere in this guide, the file will be within the project-name/flex_src/ folder.

4

If it is not already active, switch to the Source View.

5

Press Ctrl+F to bring up the Find/Replace dialog.

6

Do a case-sensitive search for “ICON”. The Find mechanism locates a line of the following form: public static var entity-name_ICON:String = "url::assets/images/cube_blue.png"; The file contains multiple references to cube_blue.png. Perform the search as many times as necessary to find all references.


38



7

Edit the lines to change the file name to the file you pasted into the project-name/flex_src/assets/ images/ folder.

8

Save your changes.

9

In the main menu bar, click the green Run icon.

10 If prompted, choose to run as a Flex Application. 11 Perform a search and select an entity to view in the Details View. Verify that the Relationship Viewer display uses the new icon.


39

www.Initiate.com

Composer Guide


40


3 Deploying Composer Applications

Overview Once you have generated the Composer application and verified that it functions within the Flex Development environment, you are ready to deploy the application to an application server where it can be available to users. For the application to run properly on the application server, it must access the services that facilitate communication with the Master Data Engine. To provide this access you will first set connection parameters on the application servers to allow them to access the Master Data Engine. You will next bundle your application into a WAR file that includes the suite of Composer’s Java services as well as the BlazeDS libraries required to manage the communication itself. Packaging the Adobe® Flex® Builder™ application and Java services into a single WAR file — composersvcs.war — ensures that the application has any resources required when deployed to the application server. This chapter describes the deployment process for the Apache Tomcat and IBM WebSphere application servers. Future releases of Composer will support additional application servers.

Setting Master Data Engine connection parameters for Tomcat and WebSphere The following instructions apply to the remote installation of Tomcat or WebSphere. These instructions parallel the configuration you did for the local Tomcat installation “Setting Master Data Engine connection parameters for the local Tomcat installation” on page 18. In order for the Composer applications that you generate to connect with the Master Data Engine, the application server needs the appropriate connection information. As described below, edit the composersvcs.properties template delivered with Composer and save it in the appropriate location on the application server. How to set Master Data Engine connection parameters for Tomcat: Note: The following instructions assume that Tomcat is not running on the same machine as the Master Data Engine. 1


2

On the machine where Tomcat is running, navigate in the file system to the Tomcat installation’s conf directory.

3

Open catalina.properties in a text editor.

4

Verify that the entry beginning with shared.loader= reads:


41

www.Initiate.com

Composer Guide

shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar 5

Save and close catalina.properties.

6

Within the Tomcat installation directory, create a directory named shared, for example: C:\apache-tomcat-6.0.24\shared

7

Within the new shared directory, create a classes directory.

8

On the machine where Composer is installed, navigate in the file system to the composer/services/ directory within the Workbench workspace, for example: C:\Documents and Settings\username\workspace\project-name\composer\services\

9

Copy the composersvcs.properties file.

10 Transfer the composersvcs.properties file to the machine running Tomcat and paste it into the shared/ classes/ directory you created on that machine. 11 Open composersvcs.properties. 12 Uncomment the following lines by removing the initial pound signs (#) and set the values to reflect a valid username and password for your installation: adminloginProvider.username=system adminloginProvider.password=system If your configuration uses the default system/system credentials and running the Master Data Engine at localhost:16000, you do not need to uncomment the lines or change the values. 13 Save and close the file. 14 Restart Tomcat. How to set Master Data Engine connection parameters for WebSphere: Note: The following instructions assume that WebSphere is not running on the same machine as the Master Data Engine. 1


2

Navigate in the local file system to the composer/services/ directory within the Workbench workspace, for example: \\machine-name\Documents and Settings\username\workspace\project-name\composer\services\

3

Copy the composersvcs.properties file.

4

Connect to the machine where WebSphere is running.

5

Navigate on that machine to the properties directory for the appropriate server and profile. For example, \\machine-name\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\properties\

6

Paste composersvcs.properties into the properties directory.

7


8

By removing the initial pound signs (#), uncomment the following lines and set the values to reflect a valid username and password for your installation: adminLoginProvider.username=system adminLoginProvider.password=system


42



9

Uncomment the line for contextFactory.hostName.

10 The default value for contextFactory.hostName is localhost. Change the value to indicate the machine where the Master Data Engine is running. If the Master Data Engine is running on a port other than the default 16000, uncomment and change the value for contextFactory.hostPort. If the Master Data Engine is running on 16000, leave the line commented out. 11 Save and close the file.

Manually packaging J2EE Java and Flex The following directions provide manual steps on how to package compiled Flex and Java classes in a single web enabled resource file ("WAR file"). The instructions assume that you have successfully generated Composer components and services and tested your application within the Flex Development environment. See “Getting Started” on page 11. How to create the Composer WAR file: 1

On your local machine, create a temporary directory in the file system.

2


3

Create a copy of the composersvcs.war file and rename the copy to composersvcs.zip.

4

Using WinZip or similar extraction tool, extract composersvcs.zip into the temporary directory you created. You’ll see two subdirectories: META-INF and WEB-INF.

5

Within Workbench, change to the Flex Development perspective.

6

From the main menu, choose Project > Export Release Build.

7

In the Export Release Build dialog, choose Browse and set the value of Export to folder to the temporary directory where you unzipped composersvcs.zip.

8

Click Finish.

9

Zip up the contents of the temporary directory.

Note: Do not zip the directory temporary directory itself. Include only the contents of the directory. 10 Rename the zip file to composersvcs.war. The composersvcs.war file now contains both compiled Java web services and Flex client classes in a single WAR file. To deploy composersvcs.war to Tomcat, see “Deploying a Composer application to a J2EE Tomcat environment” on page 43. To deploy to WebSphere, see “Deploying a Composer application to a WebSphere environment” on page 46.

Deploying a Composer application to a J2EE Tomcat environment Tomcat offers two options for deploying the composersvcs.war file, each described in detail below. Copy composersvcs.war directly to the Tomcat installation’s webapps directory and restart Tomcat Use Tomcat’s online Deployment Manager to install the composersvcs.war


43

www.Initiate.com

Composer Guide

Manual file copy and Tomcat restart Follow the steps below to copy composersvcs.war and restart the application server. How to manually copy the composersvcs.war file and restart Tomcat: 1

Navigate to the temporary directory where you created the new composersvcs.war file.

2

Copy the file into the Tomcat webapps directory. For example, C:\apache-tomcat-6.0.24\webapps\

3

Stop and restart Tomcat. To do so, navigate at a command-line prompt to the bin/ directory within your Tomcat installation and type shutdown.bat, and then startup.bat.

4

Verify that the BlazeDS service on the Master Data Engine is started. You can do so by navigating in your browser to: http://machine-name:8080/composersvcs/messagebroker/amf. If the service is working, the URL displays a blank screen. If the service is not working, the URL displays a Java error stack.

Note: If you encounter any errors during Tomcat startup, verify that the Master Data Engine is running by browsing to the scripts directory within the Master Data Engine installation and running madconfig ping_instance. If the engine is running, next verify the accuracy of the property settings within the composersvcs.properties file. See “Setting Master Data Engine connection parameters for the local Tomcat installation” on page 18. Finally, review the latest localhost and catalina logs in Tomcat's log directory (or from Tomcat's console out) for errors.

Tomcat Deployment Manager Follow the steps below to launch the Tomcat Manager. How to launch the Tomcat Manager: 1

If it is not already started, start Tomcat. To do so, navigate at a command-line prompt to the bin/ directory within your Tomcat installation and type startup.bat.

2

Login into the Tomcat Manager. Typically, the Tomcat Manager runs at: http://localhost:8080/manager/html

Note: If you have not done so already, you will need to enable a Tomcat user with the manager role. To do so, edit tomcat-users.xml to add the manager role to an existing user as described in the Manager App HOW-TO. 3

Scroll down to the Deploy section.

4

Within the WAR file to deploy section, click Browse.

5

Navigate to the temporary directory where you created the new composersvcs.war file.

6

Select the file and click OK.

7

Verify that the BlazeDS service on the Master Data Engine is started. You can do so by navigating in your browser to: http://localhost:8080/composersvcs/messagebroker/amf. If the service is working, the URL displays a blank screen. If the service is not working, the URL displays a Java error stack.


44



Note: If you encounter any errors during Tomcat startup, verify that the Master Data Engine is running by browsing to the scripts directory within the Master Data Engine installation and running madconfig ping_instance. If the engine is running, next verify the accuracy of the property settings within the composersvcs.properties file. See “Setting Master Data Engine connection parameters for the local Tomcat installation” on page 18. Finally, review the latest localhost and catalina logs in Tomcat's log directory (or from Tomcat's console out) for errors.

Testing the Tomcat deployment After deploying the composersvcs.war file to Tomcat, navigate to Tomcat's HTTP URL, followed by the composersvcs context and DemoMainApplication.html. For example: http://localhost:8080/composersvcs/DemoMainApplication.html Verify that you see Composer's generated web page.

Debugging Tomcat Java Composer Services This section describes setting up Tomcat and Workbench for remote debugging. The process allows you to set break points, step through the Java source code, and inspect the data returned from the Initiate Master Data Engine. Note: Debugging Composer's J2EE Java sources requires that Tomcat's debug port be enabled. 1

Navigate to your Tomcat installation’s bin/ directory and open catalina.bat in a text editor.

2

Edit catalina.bat to add the following lines immediately after the remarks section: set "JPDA_TRANSPORT=dt_socket" set "JPDA_ADDRESS=8000" set "JPDA_SUSPEND=n" By default, the remarks section ends with the line: rem ---------------------------------------------------------------------------

3

From the command line within the bin directory, type catalina.bat jpda start to start Tomcat with debugging enabled.

4

Within Workbench, navigate to project-name/src.

5

Create a new Java runtime debug configuration: a

Open the Workbench Configuration perspective: Window > Open Perspective > Other > Configuration (default).

b

In the Navigator, right-click the project and choose Debug As > Debug Configurations.

c

Highlight Remote Java Application

d

Click the New launch configuration button.

e

Confirm that the Connection Type is Standard (Socket Attach). You should have no need to modify the settings on the other tabs of the Debug Configurations dialog.

f

Click OK.

You should now be able to set break points in your Workbench or Eclipse Java sources and step through the web services source code.


45

www.Initiate.com

Composer Guide

Deploying a Composer application to a WebSphere environment Use the WebSphere Integrated Solutions Console to create a new install a new application. 1

Open a browser and navigate to the WebSphere Integrated Solutions Console web application, for example: https://machine-name:9043/ibm/console/logon.jsp

2

Log in and navigate to Applications > Install New Application.

3

Choose Local file system, and browse in the file system to select the composersvcs.war that you created in “Manually packaging J2EE Java and Flex” on page 43.

4

For Context root specify: /composersvcs

5

Leave selected the option to Prompt me only when additional information is required.

6

Click Next.

7

Accept the defaults for Step 1: Select installation options and click Next.

8

On the panel for Step 2: Map modules to servers, check the box to map the Initiate Composer Services module to the WebSphere server.

9

Click Next.

10 On the panel for Step 3: Map virtual hosts for Web modules, check the box to map the Initiate Composer Services web module to the default Virtual host. 11 Click Next. 12 On the panel for Step 4: Map context roots for Web modules, verify that the context root is: /composersvcs 13 Click Next. 14 On the panel for Step 5: Summary, verify that all values are correct and click Finish. WebSphere installs the application. Look for the message Application composersvcs_war installed successfully. 15 If you are satisfied with the installation, click Save to save your changes directly to the master configuration. 16 Still within the WebSphere Integrated Solutions Console, navigate to Applications > Enterprise Applications. 17 Set a checkmark next to composersvcs_war. 18 Click Start. Once WebSphere has processed the command, you should see the message: “Application composersvcs_war on server server-name and node node-name started successfully.” 19 Browse to the application to verify that it is running, for example:


46



http://machine-name:9080/composersvcs/project-name-debug/DemoMainApplication.html Note: If you encounter any errors during WebSphere startup, verify that the Master Data Engine is running by browsing to the scripts directory within the Master Data Engine installation and running madconfig ping_instance. If the engine is running, next verify the accuracy of the property settings within the composersvcs.properties file. See “Setting Master Data Engine connection parameters for the local Tomcat installation” on page 18. Finally, review the latest logs in WebSphere's log directory.

Debugging Flex Setting up Workbench for Flex debugging allows you to set break points and step through Composer's Flex sources. 1

Ensure that Tomcat is running.

2

Open the Flex Debugging perspective: Window > Open Perspective > Other > Flex Debugging.

3

Open one of the generated components within the project-name/flex_src/ folder.

4

Set a breakpoint within the ActionScript section of the component by clicking within a line of ActionScript code and navigating in the main menu to Run > Toggle Breakpoint. (As shown in the menu, you can also use Ctrl+Shift+B to toggle breakpoints.)

5

Within the project-name/flex_src/ folder, right-click DemoMainApplication.mxml and choose Debug As > Debug Configurations > Flex Application. If you see a popup message that indicates your version of the Flash Player is not a debugger, follow the link to the Adobe Flash Player downloads and download the appropriate Flash Player. Depending on your browser of choice, download either the Windows Flash Player 10 Active X control content debugger (for IE) or the Windows Flash Player 10 Plugin content debugger (for Netscape-compatible browsers). Install the new player and resume the steps above. If you encounter errors when attempting to launch, you must resolve them before proceeding. Errors may occur if the .mxml files contain illegal characters such as parentheses or if the file names and attribute names are not unique across the project. When you have successfully launched the application, the Flex Debugging perspective opens a browser and displays the application.

Note: The following example assumes that you have the chosen to generate the Entity Search Form component. Flex Builder provides a built-in debugger and profiler. There will be times when it will be necessary to debug your Flex project to track down problems. Use the debugger to diagnose runtime logic errors, and the profiler to troubleshoot Flash memory leaks. The following example shows how to set a break point and step into it. This can be useful to look a the payload returned from the server and troubleshooting the client side data conversion process. Example: 1

Within the Flex Debugging perspective, navigate to the project-name/flex_src/com/initiate/controller/ directory.

2

Open EntitySearch_SearchController.as.

3

Put the cursor within the line: searchResultHandler( event:ResultEvent ):void


47

www.Initiate.com

Composer Guide

4

In the main menu, choose Run > Toggle Breakpoint.

5

Walk through the code and inspect the data in the personObj parameter.

6

Perform a search.

The Flex debugger stops on your breakpoint. This will allow you to step through and inspect the data returned from the Composer Java web service.


48


4 Managing Composer Events

Overview Flex applications like those created with Composer are driven by events, which may include external/network events, internal application events, and user actions. In the context of Composer, all events result from user actions intended to: Perform a search for an entity or member based on user-provided values. Retrieve details for a specific entity or member returned by a search. For a specific entity, display the constituent member records. Add a new member to a source. Edit an entity and update the record in the source. Graphically display the relationships between entities. Display a table of entities related to a selected entity. Clear search parameters from a search form. Consider a search event: clicking Search within a Search Form component prompts the display of results within a Search Results component. Notice that the event is passed between the two components: from the Search Form component to the Search Results component. Because of the need to pass events between components, Composer takes advantage of the Mate Flex Framework, which aggregates event handlers (also called event listeners) within event map files. Each type of event (search, clear, etc.) has a corresponding event handler in the event map file which indicates how to manage that event. “Event Code” on page 50 describes the mechanism in greater detail. Note that because Composer events typically pass between different components, event maps are only necessary for components that are functioning as part of a common application, such as a Composer blueprint. Each blueprint consists of a set of related components and an event map that manages the communication between those components. When you generate Composer artifacts for any blueprint you've configured, Composer creates the corresponding event map file (named blueprint-name_eventMap.mxml). If you add custom components (or custom events within existing components), you will need to edit the corresponding event map file to manage the new events. For more information about handling Flex 3 events, visit adobe.com: http://learn.adobe.com/wiki/display/Flex/3b.+Handling+Events http://livedocs.adobe.com/flex/3/html/help.html?content=events_01.html


49

www.Initiate.com

Composer Guide

Event Code Composer event code relies on event map files — one event map file per blueprint. Each event map specifies what happens when specific events are dispatched. Each event type you want to listen for has its own event handlers block in the event map: ...event handlers blocks here... An event map is typically an stand-alone mxml file. By default, Composer points to the event map file from within the application file (for example, DemoMainApplication). This requirement is due to the component creation cycle that Flex follows. If you place your event map deep inside your application, it may not be instantiated early enough to listen to all the events. Placing it in the application file also allows you to be able to listen to early Flex events such as FlexEvent.PREINITIALIZE. . . . ...other application components here... The names of Composer events and event types will reflect your own data model. In the examples that follow, “Person” and “IDENTITY” reflect the data model according to the following pattern: member-nameSearchEvent.SEARCH_ENTITY_entity-name member-nameDetailEvent.DETAIL_MEMBER_entity-name and so on. For a complete discussion of event handling in Flex applications that use Mate, visit see the Mate Flex Framework documentation available at http://mate.asfusion.com/page/documentation/.

Code within the Event Map As mentioned above, each Composer event map file aggregates handlers that manage the events generated by the components that make up the associated blueprint. After a single line that specifies the xml version and the encoding, the event map file consists entirely of a single EventMap tag. within the EventMap tag are one or more EventHandlers tags, one for each event type. An example of the handler for SEARCH_ENTITY_IDENTITY event type is shown in bold below: . .


50



. . In this case, when the handler catches a SEARCH_ENTITY_IDENTITY event, it passes the search arguments to the Master Data Service (MDS) with the searchForIdentityList method. The MDS returns the results, which the handler stores in the model for the view to show.

Code within Composer components The code within the individual component .mxml files specifies which events to launch under which circumstances. For example in the code for the Search Entity Form component shown below, the searchPerson function dispatches the PersonSearchEvent:SEARCH_ENTITY_IDENTITY event: private function searchPerson() : void { var personSearchEvent:PersonSearchEvent = new PersonSearchEvent(PersonSearchEvent.SEARCH_ENTITY_IDENTITY, true); var person:com.initiate.model.Person = new com.initiate.model.Person(); . . . personSearchEvent.person = person; dispatchEvent( personSearchEvent ); The component code also specifies the button control that calls the searchPerson function: Note that the event specification as defined by Mate follows the format: event.EVENT_TYPE, bubbling_setting, for example: PersonSearchEvent.SEARCH_ENTITY_IDENTITY, true. The bubbling setting determines whether the event should be passed up the chain of the event's ancestors in search of an event handler. See the documentation at adobe.com for details. Note that in order for the handlers in the event map file to be able to listen for the given event, the event must have its bubbling setting as true and be dispatched from an object that has Application as its root ancestor. Alternatively, the event must be dispatched by a Mate Dispatcher, which is the case when dispatching events from a PopUp window. See the Mate Flex documentation for details. Note: The EventMap tag can also contain Injectors, which allow Master Data Engine data from one class to be injected into another class. For example, an event map might invoke an intermediary controller to manipulate data and then inject the data into a destination controller.

Composer Events The following table describes the Composer events that are currently available. Note: Each event map file also contains a generic event for changing properties: PropertyChangeEvent.PROPERTY_CHANGE


51

www.Initiate.com

Composer Guide

Table 4.1 Composer component events Event.EventType

Description

member-nameSearchEvent.SEARCH_ENTITY_entity-name

When the user clicks the Search button within an Entity Search Form component, passes search parameters to the Master Data Service, which passes back results. In other words, the event invokes a service request and populates the appropriate controls according to the event map.

member-nameSearchEvent.CLEAR_ENTITY_entity-name

When the user clicks the Clear button within an Entity Search Form component, clears all search fields.

member-nameDetailEvent.DETAIL_ENTITY_entity-name

Within an Entity Search Result component, when a user double-clicks a result, passes the ID for that entity to the Master Data Service which passes back details for the entity. (Note that search fields and details fields are specified when configuring the Composer component in the Composer Configuration Editor.)

member-nameDetailEvent.POPUP_ENTITY_entity-name

Launches a popup to display entity details. Within an Entity Search Result component, when a user double-clicks a result, the code passes the ID for that entity to the Master Data Service which passes back details for the entity.

member-nameDetailEvent.OPEN_ENTITY_entity-name

Within an Entity Search Result component, when a user double-clicks an entity, displays the member records that comprise the selected entity record.

RelationshipEvent.RELATIONSHIP_SEARCH_entity-name

If you chose to create the Entity Search blueprint that contains the Relationship Viewer component, the Search Results Component launches the Relationship Viewer when the user double-clicks an entity.

RelatedEntitiesEvent.GET_RELATED_ENTITIES_entity-name

For the Entity Search with Related Entities blueprint, the Search Results Component launches the Related Entities component when the user double-clicks an entity.

RelatedEntitiesEvent.GET_ENTITY_RECORDS_entity-name

For the Related Entities View, populates the records tab. The event is for internal use only and should not be edited.


52



Table 4.1 Composer component events Event.EventType

Description

member-nameSearchEvent.SEARCH_MEMBER_entity-name

When the user clicks the Search button within a Member Search Form component, passes search parameters to the Master Data Service, which passes back results.

member-nameSearchEvent.CLEAR_MEMBER_entity-name

When the user clicks the Clear button within a Member Search Form component, clears all search fields.

member-nameDetailEvent.DETAIL_MEMBER_entity-name

Within a Member Search Result component, when a user double-clicks a result, passes the ID for that member to the Master Data Service, which passes back details for the member. (Note that search fields and details fields are specified when configuring the Composer component in the Composer Configuration Editor.)

member-nameDetailEvent.UPDATE_MEMBER_entity-name

Within a Entity Details View component that has been enabled for entity editing, when the user clicks the Update button, the event sends to the Master Data Service any entity values that the user has updated.


53

www.Initiate.com

Composer Guide


54


Index

Index

A

J

Apache Tomcat 6, 7, 9, 13, 18, 20, 22, 23 deploying applications 41, 43 Deployment Manager 44 installing 13, 14 testing deployment 45 architecture 7 ATSC (Authorized Technical Support Contacts) 10 attribute set 8

J2EE 7, 17, 19, 22, 43, 45 Java 7, 13, 14, 17, 18, 22, 41, 43, 44, 45, 48

B

OPEN_ENTITY event 52

BirdEye 8 BlazeDS 8, 41, 44

P

M Mate Flex 9, 49, 50, 51

O

POPUP_ENTITY event 52

C R

cascading style sheets 32 CLEAR_ENTITY event 52 CLEAR_MEMBER event 53 Composer Configuration Editor 15, 16, 25, 26, 30 composite view 9 CSS 32

RELATIONSHIP_SEARCH event 52

S SEARCH_ENTITY event 52 SEARCH_MEMBER event 53 Support Center Knowledge Base 10

D DETAIL_ENTITY event 52 DETAIL_MEMBER event 53

T third party software 10

E U

event 9, 49 event handler 49 event map 9, 49

uninstalling 23 UPDATE_MEMBER event 53

G GET_ENTITY_RECORDS event 52 GET_RELATED_ENTITIES event 52

H Hard link 37

I IBM WebSphere 6, 7, 9, 13 deploying applications 41, 46


55

www.Initiate.com

Composer Guide


56


Composer Guide

Composer Guide

Suggest Documents

Conference Composer User Guide - Polycom

Composer Guide for Flex Development

Media Composer Editing Guide - Avid

Code Composer Studio Getting Started Guide

User's Guide EPiServer Composer - EPiServer World

NoteWorthy Composer™

Code Composer Studio/Emulator Selection Guide - JTAG Emulators

pdf-1284\isaac-albeniz-a-guide-to-research-composer-resource ...

Avid Media Composer and Film Composer Getting ... - SIM Digital

Code Composer Studio™ v5.2 User's Guide for MSP430 - Mouser ...

Code Composer Studio v4.2 for MSP430(tm) User's Guide ... - Farnell

LIBERTANGO - peter petrof, composer

Avid Media Composer - Sony

Zappa as Composer/Performer

Workflow Composer Data Sheet

composer institute - Minnesota Orchestra

Workflow Composer Data Sheet

COMPOSER . OLIVIER TOUSSAINT

Media Composer 6 - Avid

Media Composer 6 - Avid

Media Composer - Avid

composer institute - Minnesota Orchestra

Elmo Composer User Manual

Media Composer - Avid