8 Defining a Management User Interface

8.1.1 Flex Implementation

If you are using the Flex implementation option, then you are responsible for the following steps:

1. Obtain a copy of Adobe Flash Builder or download the Adobe Flex Software Development Kit (SDK).

   For more information, see Section 8.27, "Development Environment Options".

   Note:

   The Adobe Flex SDK is free but it does not provide graphical editing or debugging capabilities.

2. Create a project (if using Adobe Flash Builder) to hold the source code for your custom UI. You can use the sample project included in the EDK as a template. Ensure that the project settings are correct.

   For more information, see Section 8.27.2, "Developing MPCUI in Adobe Flash or Flex Builder".

3. Implement an MXML class that extends the MpApplication class. This is the Flex application class.

   For more information, see Section 8.6, "Defining the MPCUI Application".

4. Implement an MXML class that extends the Integration class. This defines the set of activities included in the custom UI.

   For more information, see Section 8.6.1, "Defining the Application Activities (Integration Class)".

5. Develop each activity (such as page or dialog). Typically, each page includes a page class (written in MXML, extending the Page class) and a controller class (written in ActionScript extending the ActivityController class).

   For more information, see Section 8.6.2, "Defining Pages", Section 8.6.3, "Defining Dialogs", and Section 8.6.4, "Defining Trains and Train Pages".

6. Build and test your custom UI from Adobe Flash Builder.

   Note:

   You must deploy at least one version of your plug-in before building and testing. The deployed plug-in must include the target metadata (such as metrics and configuration data). However, the plug-in does not have to include your MPCUI metadata for testing.

7. Create the MPCUI metadata file.

   This file includes:

   • SQL statements used by your custom UI

   • Menu items you want to include to support navigation to different pages defined in your UI

   • Reference to the Flex UI that you built

   For more information, see Section 8.4, "Creating the MPCUI Metadata File".

8. Modify your plug-in to include the MPCUI metadata file and the SWF file built in Adobe Flash Builder.

   Place these files in the oms/metadata/mpcui directory of the plug-in staging area.

   For more information, see Section 8.7, "Packaging the MPCUI Implementation With the Plug-in".

9. Test your custom UI by accessing a target home page from the Enterprise Manager console.

   This loads your custom UI in the context of the Enterprise Manager application and displays the Enterprise Manager application and target menus.

8.1.2 Metadata-only Implementation

If you are using the metadata-only implementation option, then you are responsible for the following steps:

1. Create the MPCUI metadata file.

   This file includes:

   • SQL statements used by your custom UI

   • Menu items you want to include to support navigation to different pages defined in your UI

   • All the metadata definitions discussed in the following steps

   For more information, see Section 8.4, "Creating the MPCUI Metadata File".

2. Add the integration metadata to the MPCUI metadata file.

   The integration metadata defines the set of activities included in the custom UI.

   For more information, see Section 8.5.2, "Defining Integration Metadata".

3. Add the page definitions (ActivityDefinitions) to the MPCUI metadata file.

   For more information, see Section 8.5.3, "Defining Navigation".

4. Modify your plug-in to include the MPCUI metadata file.

   Place these files in the oms/metadata/mpcui directory of the plug-in staging area.

   For more information, see Section 8.7, "Packaging the MPCUI Implementation With the Plug-in".

5. Test your custom UI by accessing a target home page from the Enterprise Manager console.

   This loads your custom UI in the context of the Enterprise Manager application and displays the Enterprise Manager application and target menus.

8.1.3 Assumptions and Prerequisites

This chapter assumes you are familiar with the following:

• Plug-in development overview, including how to package a plug-in and its XML files.

• The XML-based user interface markup language known as MXML.

8.2.1 Integration Class

The integration class is the bootstrap for your application, and is used to define the set of pages, dialogs, and trains that are included in the application. The MPCUI framework uses the information included in the integration class to drive the application including managing navigation between UI elements.

8.2.2 Activity

Top-level UI elements in the MPCUI are referred to generally as activities. Activities include pages, dialogs, trains and train pages, URLs, and jobs.

8.2.3 Page

Flex does not include the notion of a page, though this is a construct that is provided by the MPCUI framework to simplify the construction of the UI and make it fit more naturally into the larger Enterprise Manager console.

The MPCUI framework manages pages within the application, providing simple navigation between pages and integrating them into the browser history and the Enterprise Manager menu system.

8.2.4 Services

The MPCUI framework provides a series of services that can be used to retrieve data from the Management Server or to process actions (jobs or remote operations).

8.2.5 URL

MPCUI provides a number of different capabilities related to the generation of URLs and the ability to embed links to:

• Other Enterprise Manager pages

• Other pages within the MPCUI application

• External pages

Because MPCUI is a Flex application, it is not quite as easy as embedding a link to a URL. For more information about URLs, see Section 8.10.2, "URL and Links".

8.3.1 Metadata-only Implementation

MPCUI metadata is XML that describes the layout of the UI and the binding to Enterprise Manager services. For more information about MPCUI metadata, see Section 8.4, "Creating the MPCUI Metadata File"

Use the Demo Host Sample (demo_hostsample) as a starting point or else you can develop a new UI. The UI must include at least one page (the home page), and can optionally include other pages. Each page definition is included in the MPCUI metadata file.

In addition to the metadata description of each page, the metadata must also include an integration definition. For more information about integration definitions, see Section 8.5.2, "Defining Integration Metadata".

8.3.2 Flex Implementation

The Flex implementation option provides additional capabilities for providing a customized UI on top of administrative capabilities included in the plug-in as jobs or as Agent scripts.

While one of the goals of the MPCUI framework is to provide a simplified layer of abstraction over the Flex framework with which it is implemented, you must become familiar with the Flex framework and how to develop using the Flex framework.

• MXML

• ActionScript

• SWF Binary File

8.4.1 Overview of MPCUI Metadata Elements

Table 8-1 describes the key elements that define the discovery metadata.

<UIMetadata>
  
  <!-- The meta-data only definition must include an Integration element 
  which defines the set of activities (pages, dialogs, etc.) that make up
  the application -->
  <Integration>
    <intg:Integration targetType='demo_hostsample' xmlns:intg="oracle.sysman.emx.intg" >
    ..
    </intg:Integration>
  </Integration>
    
  <!-- The meta-data only definition must include 1 or more ActivityDefinition
  elements each of which defines an activity (e.g. page, dialog, etc.) -->
  <ActivityDefintion>
    <intg:Page id=”homePg” label=”Home Page” ...>
    </intg:Page>
  </ActivityDefintion>
 
</UIMetadata>

8.5.1 Limitations of the Metadata Implementation

This implementation supports the definition of pages only, and does not support the definition of dialogs or trains. If the custom UI requires dialogs or trains, then you must use the Flex-based option for building your home page. For more information, see Section 8.3.2, "Flex Implementation".

The ability to perform manipulation of data for display or the ability to respond to some UI events and to invoke jobs or remote operations is not available in this implementation.

8.5.2 Defining Integration Metadata

Use the integration metadata to specify the set of pages and to define task flows between these pages (if required).

<Integration> 
       <mp:Integration targetType="demo_hostsample" xmlns:mp="http://www.oracle.com/mpcui">
         <mp:PageActivityDef id="homePg" label="Home" isDefaultPage="true" />  
         <mp:PageActivityDef id="perfPg" label="Performance" />
         <mp:PageActivityDef id="processesPg" label="Processes" />
         <mp:PageActivityDef id="adminPg" label="Configuration" /> 
         <mp:DialogActivityDef id="detailsDialog" label="Metrics Detail" /> 
         <mp:DialogActivityDef id="metricHistory" label="Metric History">
           <mp:inputParams>
             <mp:InputParam name="targetName" /> 
             <mp:InputParam name="targetType" /> 
             <mp:InputParam name="metric" /> 
             <mp:InputParam name="columns" /> 
             <mp:InputParam name="period" /> 
             <mp:InputParam name="title" /> 
           </mp:inputParams>
         </mp:DialogActivityDef>
         <mp:DialogActivityDef id="metricDetails" label="Metric Details">
           <mp:inputParams>
             <mp:InputParam name="targetName" /> 
             <mp:InputParam name="targetType" /> 
             <mp:InputParam name="metric" /> 
             <mp:InputParam name="columns" /> 
             <mp:InputParam name="period" /> 
             <mp:InputParam name="title" /> 
           </mp:inputParams>
         </mp:DialogActivityDef>
       </mp:Integration>
    /<Integration>

<ActivityDefinition>
    <!--
      Each page included in the plugin UI should extend the Page class and be
      coded in MXML.
      The page file specifies the layout of the page, declares some of the data
      binding (see below) and specifies handlers for events that are initiated in
      the page, when a user clicks a button or link for example.  The page also
      has a controller class (that extends PageController)that is associated with
      the page.  The controller loads data shown in the page and includes
      functions that are called as event handlers.
    -->
    <mp:Page id="homePg" label="Home Page"   
             xmlns:mx="http://www.adobe.com/2006/mxml"
             xmlns:mp="http://www.oracle.com/mpcui" >

      <!-- 
          Data Services - these are sources of data that will be shown in the
          page. Data can either be bound from a data service declared here, or it
          may be loaded within the controller.
      -->
      <mp:services>
        <!--
          SQLDataService - this service allows you to execute a SQL query packaged
          with your plugin and then refer to the result set from the query
          execution. Properties passed to the query are declared as name-value
          pairs.  If the properties are runtime/dynamic properties then 
          you will have to use the SQL service within the controller, load the 
          data there and then map the result set to the page model.
        -->
        <mp:SQLDataService id="ids" queryID="INSTANCE_INFO" properties="{props('TARGET_GUID',appModel.target.guid)}" />

        <mp:SQLDataService id="cht1" queryID="CHTSQL1" properties="{props('HC_TARGET_GUID',appModel.target.guid)}" />   

        <!--
          MetricValuesDataService - this service allows you to obtain data for a
          metric, for some period of time.  This time period may be a historical
          time period, or it may be REALTIME which creates a data service that 
          will poll for the current value of the metric through the Agent.  
        -->
        <mp:MetricValuesDataService id="mv1" 
          flattenData="true"
          targetName="{appModel.target.name}" targetType="{appModel.target.type}" 
          metricName="CPUProcessorPerf"
          columns="{['CPUUser','CPUIdle']}"
          timePeriod="LAST_DAY" />     

        <!--
          AvailDataService - this service obtains target availability, that 
          includes current status, availability for the last 24 hours, and up
          since time.
        -->
        <mp:AvailDataService id="ads" targetName="{appModel.target.name}" targetType="{appModel.target.type}" />

        <!-- 
          AssociationService - this service obtains associated targets 
        -->
        <mp:AssociationDataService id="asc" targetName="{appModel.target.name}" targetType="{appModel.target.type}" assocTypes="{['hosted_by']}" /> 
      </mp:services>  

   <!-- 
          Page Content - the page should be laid out in a grid pattern using a
          combination or columns (VBox)and rows (HBox).  Also to ensure property
          sizing/resizing behavior relative height/width should be used in
          percentages. 
      -->
      <mx:VBox width="100%" height="100%">
          <!--
              1st Row - will occupy 30% of the height of the page and includes a
              Summary region, Availability region and Job Summary region. The
              Availability and Job Summary region require no parameters.  The
              Summary region uses the InfoDisplay component to show a series of
              name-value pairs.  Each item may also specify an optional
              destination and image.

              The example below also demonstrates the ways data may be bound to a
              UI component included in the page:

             1. Data Service Reference
             2. Global/Application Model Reference
             3. Page Model Reference 
             4. Set Directly from Controller
          -->
          <mx:HBox width="100%" height="30%">
              <mp:Region title="Summary" width="25%" height="100%"  >
                  <mp:InfoDisplay id="summaryInfo">
                      <mp:InfoItem label="CPU Model" value="{ids.result.getString(0,'CPU Model')}" />   <!-- ref to SQLDataService --> 
                      <mp:InfoItem label="Target Name" value="{appModel.target.name}" />   <!-- ref to global/application model -->
                      <mp:InfoItem label="Current Status" value="{ads.currentStatus}"  image="{ads.currentStatusIcon}" />   <!-- ref to AvailDataService -->
                      <mp:InfoItem source="{ads.statusSinceItem}" />   <!-- ref to AvailDataService -->
                  <!--    <mp:InfoItem label="{model.osVersLabel}" value="{model.osVersion}" /> -->   <!-- ref to page model; model set in controller in SQL svc handler -->
                  <!--    <mp:InfoItem id="infoItem" label="Controller Set" />   -->   <!-- value property set directly in controller -->
                      <mp:InfoItem label="Hosted By" value="{asc.assocs.getAssoc('hosted_by').name}" />   <!-- ref to AssociationService -->
                  </mp:InfoDisplay>
              </mp:Region>

              <!--
              <mp:AvailabilityRegion width="33%" height="100%" daySpan="1" />
              -->

              <mp:Region title="Memory Usage (Last 24 Hrs)" width="45%" height="100%">
                  <mp:AreaChart id="memHist" width="100%" height="100%" 
                               metricName="MemoryPerf"
                               metricColumns="['Active','MemFree']"
                               timePeriod="LAST_DAY" />
                <!--  <mp:Link label="Current" click="{controller.showCpuMetricDetails(event)}" /> -->
              </mp:Region>

              <mp:Region title="Memory Used (Current)" width="30%" height="100%">
                  <mp:LineChart id="memRt" width="100%" height="100%"
                               metricName="MemoryPerf"
                               metricColumns="['Active']"
                               timePeriod="REALTIME"
                               interval="15"/> 
                <!--  <mp:Link label="History" click="{invokeActivity('metricHistory', 
                bean('targetName', appModel.target.name, 'targetType', appModel.target.type,
                'metric', 'Response', 'columns', ['Load'], 'period', 'LAST_DAY', 'title', 'Metric History'))}" /> -->
              </mp:Region>

              <!-- <mp:JobSummaryRegion width="25%" height="100%" /> -->
          </mx:HBox>


          <!-- 
              2nd row - will occupy 35% of the overall page height and shows three
              charts and shows the ability to access other activities (pages,
              dialogs, etc.)  

              The 1st chart shows a line chart that displays a metric in
              real-time. 
              It will automatically start polling the metric value in the
              background and will continue to update the chart on the page until
              the page is not shown. The 2nd chart shows a line chart that
              displays a metric history.  The 3rd chart shows a barch chart
              showing metric data grouped by the key in the data, in this case the
              CPU #.

              Each region also includes a Link component and shows the ability to
              navigate to other activites.  This may be any activity (page, 
              dialog, train, URL, job).  The 1st chart shows using the 
              invokeActivity method being called directly from the page and 
              passing context to the activity using the bean method to form the 
              input context for the metricDetails activity.

              The 2nd link shows calling a function in the controller, and then
              navigating to another activity from within the controller.  The 
              final link shows the use of the invokeActivity method again, however 
              shows navigating to an activity that requires no additional context 
              (the Processes page).
          -->
          <mx:HBox width="100%" height="35%">

              <mp:Region title="Per Processor Idle Time (%)" width="25%" height="100%">
                 <mp:BarChart id="bchart" timePeriod="LAST_DAY" width="100%" groupBy="byKey" metricName="CPUProcessorPerf" metricColumns="{['CPUIdle']}"/>
                  <mp:Link label="Show Processes" click="{invokeActivity('processesPg')}" />                  
              </mp:Region>

              <mp:Region title="CPU Utilization % (Last 24 Hrs)" width="45%" height="100%">
                  <mp:LineChart id="cpuutil" width="100%" height="100%" 
                               metricName="CPUPerf"
                               metricColumns="['system','idle','io_wait']"
                               timePeriod="LAST_DAY" />                         
                  <mp:Link label="Current" click="{controller.showCpuMetricDetails(event)}" />
              </mp:Region>

              <mp:Region title="CPU Load (Current)" width="30%" height="100%">
                  <mp:LineChart id="cpuload" width="100%" height="100%"
                               metricName="Response"
                               metricColumns="['Load']"
                               timePeriod="REALTIME"
                               interval="15"/> 
                  <mp:Link label="History" click="{invokeActivity('metricHistory', 
                  bean('targetName', appModel.target.name, 'targetType', appModel.target.type, 
                  'metric', 'Response', 'columns', ['Load'], 'period', 'LAST_DAY', 'title', 'Metric History'))}" />
              </mp:Region>

              <!--
              <mp:Region title="Per Processor Idle Time (%)" width="34%" height="100%">
                 <mp:BarChart id="bchart" timePeriod="LAST_DAY" width="100%" groupBy="byKey" metricName="CPUProcessorPerf" metricColumns="{['CPUIdle']}"/>
                  <mp:Link label="Show Processes" click="{invokeActivity('processesPg')}" />                  
              </mp:Region>
              --> 
          </mx:HBox>

          <!-- 3rd row - events region -->
          <mx:HBox width="100%" height="35%">
              <mp:IncidentRegion width="75%" height="100%" />
              <!--
              <mp:Region title="Memory Details" width="25%" height="100%" >
                  <mx:ComboBox id="selMemChart" dataProvider="{model.memChoices}" labelField="choiceLabel" change="{controller.changeMemChart(event)}" />
                  <mp:PieChart id="memChart" targetName="{appModel.target.name}" targetType="{appModel.target.type}" 
                      metricName="MemoryPerf" 
                      metricColumns="{model.memoryColumns}"
                      timePeriod="REALTIME" interval="15" />
              </mp:Region>
              -->
              <mp:JobSummaryRegion width="25%" height="100%" /> 
          </mx:HBox>

      </mx:VBox>
    </mp:Page>

  </ActivityDefinition>

<mp:InfoItem label="Target Name"
value="{appModel.target.name}" />

8.5.3 Defining Navigation

The metadata UI definition support included in MPCUI is limited to the definition of pages, and does not support other activities such as dialogs, trains, jobs, and so on. Therefore, the only navigation possible between pages in the UI is by one of the following:

• Defining a menu item in the metadata that can be used to access a page

  The MenuMetadata item includes the menuItem elements that define navigation to activities defined in the MPCUI metadata. For example, if the metadata includes the following page definition:

  <ActivityDefinition>
      <intg:Page id="processesPg" label="Processes" ..>
          <!-- the body of the processes page would be declared here ?
      </intg:Page>
    </ActivityDefinition>
  

  Specify a menuItem in the MenuMetadata element to allow navigation to the previous page:

  <menuItem>
     <command id="processesPg" label="Processes"
               class="oracle.sysman.emSDK.pagemodel.menu.EMNavigationMenuCommand
               partialSubmit="true" >
        <property name="actionOutcome" value="goto_core-mpcustom-nav" /><property name="paramsMap"><mapEntry name="pageid" value="processesPg" />
        </property>      
     </command>
   </menuItem>
  

  The key properties in the menuItem element are:

  • label within the command element.

    label specifies the label that appears in the target menu on the home page. In the example given, a menu item “Processes” would be included.

  • the value specified for the actionOutcome property.

    actionOutcome specifies the view ID for the page containing the SWF file.

• Navigating from within a page using the invokeActivity directive

  Use the invokeActivity directive to navigate between activities defined in an MPCUI metadata implementation. Associate this directive with the click property of the Link or Button components. When the end user clicks one of these components, the click property specifies the action that should be taken.

  The invokeActivity directive takes the following:

  • one required parameter (the activity id)

    The activity id specifies the activity to which control should be passed

  • one optional parameter (a bean to provide input context to the activity)

    The input context specifies information to be passed to the activity.

  For example, if the implementation includes two activities, 'homePg' and 'processesPg' (two pages). Include a link in the home page that when clicked, it changes the display to the processes page.

  <ActivityDefinition>
  <intg:Page id="homePg" label="Home Page"   
  ...
  <mx:Link label=”Show Processes” click=”{invokeActivity('processesPg')}” />
  

  Use the activity content parameter to define an activity that is parameterized and therefore can be invoked from different contexts. The requirement for parameter input must be specified as part of the activity definition included in the metadata. For example, suppose you want a dialog activity that can show a historical line chart for any number of different metrics, and possibly event different targets. In the integration metadata the activity definition would appear similar to Example 8-5:

  Example 8-5 Defining Activity

  <intg:DialogActivityDef id='metricHistory' label='Metric History' >
        <intg:inputParams>
            <intg:InputParam name='targetName'/>
            <intg:InputParam name='targetType'/>
            <intg:InputParam name='metric'/>
            <intg:InputParam name='columns'/>
            <intg:InputParam name='period'/>
            <intg:InputParam name='title'/>
       </intg:inputParams>
   </intg:DialogActivityDef>
  

  The inputParams elements specify the input parameters to the dialog (activity). Then from another page activity, two different links can direct to the same dialog, but with different parameters:

  <comp:Region title="Memory Used (Current)" width="30%" height="100%">          
    <c:LineChart id="memRt" width="100%" height="100%"
          metricName="MemoryPerf" metricColumns="['Active']"
          timePeriod="REALTIME" interval="15"/> 
    <comp:Link label="History" 
          click="{invokeActivity('metricHistory', 
                  bean('targetName', appModel.target.name, 
                       'targetType', appModel.target.type, 
                       'metric', 'Response', 
                       'columns', ['Load'], 
                       'period', 'LAST_DAY', 
                       'title', 'Memory Used (History)'))}" />
  </comp:Region>   
   
  <comp:Region title="CPU Used (Current)" width="30%" height="100%">          
    <c:LineChart id="memRt" width="100%" height="100%"
          metricName="CPUProcessorPerf" metricColumns="['CPUUser,'CPUIdle']"
          timePeriod="REALTIME" interval="15"/> 
    <comp:Link label="History" 
          click="{invokeActivity('metricHistory', 
                  bean('targetName', appModel.target.name, 
                       'targetType', appModel.target.type, 
                       'metric', 'CPUProcessorPerf', 
                       'columns', ['CPUUser','CPUIdle'], 
                       'period', 'LAST_DAY',
                       'title', 'CPU Used (History)'))}" />                
  </comp:Region>  
  

8.6.1 Defining the Application Activities (Integration Class)

The integration class defines the set of UI elements that make up the application. The MPCUI framework interacts with the integration class to understand the structure of the application, allowing the framework to be the primary driver behind the display of and navigation between the UI elements that make up the application.

The application registers the integration class with the MPCUI framework in the application class through the getIntegrationClass method. Each application should have a single integration class only.

<?xml version="1.0" encoding="utf-8"?>
<intg:Integration
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:intg="oracle.sysman.emx.intg.*" 
    >
      <!-- The integration class defines the pages, dialogs 
               and trains included in the application -->  

      <intg:activities>
        <intg:PageActivityDef id='homePg' label='Home' pageClass='{HomePage}' pageControllerClass='{HomePageController}' isDefaultPage="true"  />
        <intg:PageActivityDef id='processesPg' label='Processes' pageClass='{ProcessesPage}' pageControllerClass='{ProcessesPageController}' />
        <intg:PageActivityDef id='adminPg' label='Administration' pageClass='{CredentialsPage}' pageControllerClass='{CredentialsPageController}' />
        -->
        <intg:DialogActivityDef id='metricHistory' label='Metric History' dialogClass='{MetricHistoryDialog}' >
            <intg:inputParams>
                <intg:InputParam name='targetName'/>
                <intg:InputParam name='targetType'/>
                <intg:InputParam name='metric'/>
                <intg:InputParam name='columns'/>
                <intg:InputParam name='period'/>
                <intg:InputParam name='title'/>
            </intg:inputParams>
        </intg:DialogActivityDef>

        <intg:DialogActivityDef id='availDialog' label='Availability' dialogClass='{AvailabilityDialog}' />

     </intg:activities>
</intg:Integration>

In Example 8-7, the availability activities include PageActivityDef, DialogActivity, and TrainActivityDef. Each activity typically specifies an “id” property that will be used throughout the application to refer to this activity.

The pageClass and dialogClass properties specify the view class or the UI layout for each activity. For example, the homePg activity has a pageClass of HomePage. This means that included in the application should be a class called HomePage typically written in MXML.

Activities can specify a controller class (pageControllerClass). This property points to a class (often written in ActionScript) that will be associated with the activity and called by the MPCUI framework to initialize data in the page and respond to UI events from user interaction within the page.

8.6.2 Defining Pages

Each page must be registered with the MPCUI framework through the Integration class by adding a PageActivityDef. The PageActivityDef is defined by:

• Page class

  The page class is the concrete implementation of the page, that is its layout and contents and is a class that must extend the Page class.

• Page controller

  The page controller is a class that extends the ActivityController base class and encapsulates the set of handlers that support interacting with the Enterprise Manager services layer to obtain data and bind it to the UI components and respond to events issued by the UI on behalf of the end-user (e.g.button presses or link clicks)

Each application must include at least one page (one page activity) and you must identify one of the page activities as the default page.

<components:Link label="Show Process" click="{invokeActivity('processPg')}" />

8.6.3 Defining Dialogs

The Dialog activity extends the MPCUI Dialog class. Dialogs are popup windows that display on top of the application without navigating away from the current Page displayed. Dialogs are typically defined in MXML files and do not have separate controller classes (although they can).

<?xml version="1.0" encoding="utf-8"?>
<intg:Dialog 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns:cht="oracle.sysman.emx.components.charts.*"
    xmlns:intg="oracle.sysman.emx.intg.*"
  xmlns:ds="oracle.sysman.emx.service.util.*"     
  xmlns:comp="oracle.sysman.emx.components.*"
  xmlns:tbl="oracle.sysman.emx.components.table.*"
    height="250" width="450"
    title="{model.title}"
    >  
    <cht:LineChart id="hchart" targetName="{model.targetName}" targetType="{model.targetType}" timePeriod="{model.period}" interval="15"
                                    metricName="{model.metric}" metricColumns="{model.columns}" keys="{model.keys}" width="100%" height="100%" />
</intg:Dialog>

In the previous example, the dialog references model as the source of the properties it uses in the UI components.

Initialize the dialog model either:

• In a controller associated with the dialog

• By the MPCUI framework if the Dialog definition in the Integration class specifies input parameters

  <intg:DialogActivityDef id='metricHistory' label='Metric History' dialogClass='{MetricHistoryDialog}' >
              <intg:inputParams>
                  <intg:InputParam name='targetName'/>
                  <intg:InputParam name='targetType'/>
                  <intg:InputParam name='metric'/>
                  <intg:InputParam name='columns'/>
                  <intg:InputParam name='period'/>
                  <intg:InputParam name='title'/>
              </intg:inputParams>
          </intg:DialogActivityDef>
  

  Note:

  In this case, you must supply a bean as input that includes the input parameters required by the dialog.

  <components:Link label="Show History" 
          click="{invokeActivity('metricHistory', 
          bean('targetName', appModel.target.name, 
                  'targetType', appModel.target.type, 
                  'metric', 'Response', 
                  'columns', ['Load'], 
                  'period', '', 
                          'title', 'Metric History'))}" />                                                          
  

8.6.4 Defining Trains and Train Pages

The train activity enables you to define a train (a guided workflow or wizard) by stringing together a series of pages.

To define a train, include a declaration of the train itself (TrainActivityDef) and each of the steps (TrainStepActivityDef) in the Integration class:

<intg:TrainActivityDef id='addNewUserEmbeddedTrain' label='Add New User'>
      <intg:stepActivities>
         <mx:Array>
           <intg:TrainStepActivityDef id='anuStep1' label='User Info'pageClass='{trainSamp.S1_UserInfo}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
           <intg:TrainStepActivityDef id='anuStep2' label='Expiry' pageClass='{trainSamp.S2_Expiry}'pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
           <intg:TrainStepActivityDef id='anuStep3' label='Credentials' pageClass='{trainSamp.S3_Credentials}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
           <intg:TrainStepActivityDef id='anuStep4' label='Schedule' pageClass='{trainSamp.S4_Schedule}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
           <intg:TrainStepActivityDef id='anuStep5' label='Notifications' pageClass='{trainSamp.S5_Notifications}' pageControllerClass='{trainSamp.NotificationsTrainStepController}'/>
           <intg:TrainStepActivityDef id='anuStep6' label='Confirmation' pageClass='{trainSamp.S6_Confirm}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>                
         </mx:Array>
      </intg:stepActivities>
   </intg:TrainActivityDef>

The TrainController includes the following methods:

• init(Train): a method that is called when the train is loaded, and enables you to control the model associated with the train.

• trainDone: a method that is called when the user clicks the Finish or Cancel button within the train. At that point, you can inspect the train state (whatever is stored in the train model) to do one of the following

  • Control if the train should complete and continue to the completion activity

  • Take some other action such as moving the train back to a previous step by using the train.setStep method or end the train and invoke another activity.

Each train step within the train must extend the TrainStepPage (a special type of Page) and be associated with a controller (TrainStepController). In this case, the controller is a special type of PageController, and includes support for the init(Page) method that enables you to initialize the contents of the train page. Because the page is within a train, it might refer to either its own page model (such as model.property) or it might refer to data stored in the train model (such as train.model.property).

Finally, in either the train step controller or the train controller, the code can check for state and if the train can complete, that is, all the required information is entered, then the controller code can call train.setMayFinish().

8.9.1 Defining systemUiIntegration Metadata

To use the default system home page with some customized content:

1. Define a systemUiIntegration Metadata XML file for your target type including the following information:

   • Preferred layout

   • Add or remove regions (only required if you want to modify regions)

     Example 8-9 provides an example of a systemUiIntegration Metadata XML file.

     For information about the XML Schema Definition (XSD) that governs the systemUiIntegration Metadata XML file, see ORACLE_HOME/sysman/emSDK/core/system/xml/SystemUiIntegration.xsd.

   Example 8-9 systemUiIntegration Metadata XML

   <systemUiIntegration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/SystemUiIntegration.xsd"
          xmlns="http://www.oracle.com/EnterpriseGridControl/SystemUiIntegration">
   
   <general targetType="demo_hostsystem"
                defaultLayout="twoColumnNarrowLeft"  
           showOptionalRegions="false" 
           topLevelTarget="true" 
           allowCreateFromSystemsUi="true"/>
   
    
    <region taskFlowId="/WEB-INF/db/system/region/db-system-region-hihgavail-task-flow.xml#db-system-region-hihgavail-task-flow"
               titleResBundle="oracle.sysman.db.rsc.inst.DBMsg"
                                                   titleNlsId="GENERAL"
                                                   titleDefText="General"
                                                   regionType="add" 
                                                   displayOrder="1" />
   
    <region taskFlowId="/WEB-INF/sdk/core/regions/events/console/incident-overview-task-flow.xml#incident-overview-task-flow"
               titleResBundle="oracle.sysman.core.groups.ui.CoreGroupsUiMsg"
                                                                           titleNlsId="ISSUE_OVERVIEW"
                                                                           titleDefText="Issue Overview"
                                                                           regionType="add" 
                                                                           displayOrder="4" />  
   
    <region taskFlowId="/WEB-INF/sdk/core/regions/jobs/jobs-activity-task-flow.xml#jobs-activity-task-flow"
               titleResBundle="oracle.sysman.db.rsc.inst.DBMsg"
                                                                                                   titleNlsId="JOB_ACTIVITY"
                                                                                                   titleDefText="Job Activity"
                                                                                                   regionType="add" 
                                                                                                   displayOrder="7" />
   
    <region taskFlowId="/WEB-INF/db/system/region/db-system-region-dep-members-task-flow.xml#db-system-region-dep-members-task-flow"
               titleResBundle="oracle.sysman.core.groups.ui.CoreGroupsUiMsg"
                                                                                                   titleNlsId="DEPENDENT_TARGETS"
                                                                                                   titleDefText="Dependent Targets"
                                                                                                   regionType="add" 
                                                                                                   displayOrder="9" />    
   
    <region taskFlowId="/WEB-INF/sdk/core/regions/gccompliance/target/compliance-overview-task-flow-brief.xml#compliance-overview-task-flow-brief" 
               titleResBundle="oracle.sysman.core.groups.ui.CoreGroupsUiMsg"
                                                                                                   titleNlsId="COMPLIANCE_SUMMARY"
                                                                                                   titleDefText="Compliance Standard Summary"
                                                                                                   regionType="add" 
                                                                                                   displayOrder="6" />                        
   
    <region taskFlowId="/WEB-INF/sdk/core/regions/mos/patch/target-patch-recommendation-task-flow.xml#target-patch-recommendation-task-flow" 
               titleResBundle="oracle.sysman.db.rsc.inst.DBMsg"
                                                                                                   titleNlsId="PATCH_RECOMMEND"
                                                                                                   titleDefText="Patch Recommendations"
                                                                                                   regionType="add" 
                                                                                                   displayOrder="12"/> 
   
    <region taskFlowId="/WEB-INF/config/adfc/blackout/region/emcore-groups-blackout-task-flow.xml#blackout_group_taskflow" 
               titleResBundle="oracle.sysman.core.groups.ui.CoreGroupsUiMsg"
                                                                                                   titleNlsId="BLACKOUTS"
                                                                                                   titleDefText="Blackouts"
                                                                                                   regionType="add" 
                                                                                                   displayOrder="2" />
   
    <region taskFlowId="/WEB-INF/sdk/core/regions/ecm/history/config-history-task-flow.xml#config-history-task-flow" 
               titleResBundle="oracle.sysman.db.rsc.inst.DBMsg"
                                                                                                   titleNlsId="CONFIG_CHANGES"
                                                                                                   titleDefText="Configuration Changes (24 Hours)"
                                                                                                   regionType="add" 
                                                                                                   displayOrder="5" />                      
   
   </systemUiIntegration>
   

2. Save the systemUiIntegration Metadata XML file to the following directory:

   plugin_stage/stage/oms/metadata/systemUiIntegration
   

3. If your plug-in is deployed already, then you can use the emctl register oms metadata command to update the MPCUI part of your plug-in only. For more information about the emctl register oms metadata command, see Section 13.7, "Updating Deployed Metadata Files Using the Metadata Registration Service (MRS)".

8.9.2 Defining System Regions

The MPCUI framework supports a number of regions that can be used as part of a home page built to display information for a system target.

8.9.2.1 Defining System Status Region

The system status region shows the recent availability of the system target and all of its members. The region is included in the system home page by using the following tag:

<mp:StatusOverviewRegion id="statusOverview" height="50%"/>

Figure 8-4 System Status Region

Description of "Figure 8-4 System Status Region"

8.9.2.2 Defining System Issues Region

The system issues region shows the summary count of incidents for all of the targets in the system. The region is included in the system home page by using the following tag:

<mp:IssuesOverviewRegion id="issuesOverview" height="50%"/>

Figure 8-5 Issues Overview Region

Description of "Figure 8-5 Issues Overview Region"

8.9.2.3 Defining the System Job Activity Region

The system job activity region displays the number of jobs in each of the primary job status for the system target and the summary for all the system members.

<mp:JobsActivityRegion id="jobsOverview" height="40%"/>

Figure 8-6 System Job Activity Region

Description of "Figure 8-6 System Job Activity Region"

8.10.1 Navigation to Activities

Section 8.5.3, "Defining Navigation" describes the approach to navigating between activities from a metadata implementation. These descriptions apply to navigating to activities from the menu or from another activity defined in MXML.

This section describes how to navigate to another activity from within the controller code, that is the ActionScript code associated with an activity.

public function showProcessorHistory(even:MouseEvent):void
  {
    // show an example of invoking an activity (a dialog in this case) and
    // getting information from the dialog when it returns (is closed)
 
    // create the context to be passed to the dialog
    var bean:Bean = new Bean('targetName', 
      ApplicationContext.getTargetName(), 'targetType', 
      ApplicationContext.getTargetType(), 
        'metric', 'CPUProcessorPerf', 'columns', ['CPUIdle'], 
        'period', 'LAST_DAY', 'title', 'Metric History');

     page.invokeActivity('metricHistory', bean, processorHistoryDone);                                      
  }

The preceding example shows a controller method that uses the page.invokeActivity method to redirect to another activity (in this case, a dialog).

The significant difference between this method and the method available from within the MXML page (described in Section 8.5.3, "Defining Navigation") is the ability to associate a callback (processorHistoryDone in this example) that will be called when the called activity completes. This callback is only useful for activities that do not cause the current activity to go out of scope.

8.10.2 URL and Links

There are a number of different methods for navigating from components in the MPCUI application to other locations through a URL. Use the Link component to render an HTML-style link including a tool tip and location.

• Absolute URL (external to Enterprise Manager)

  To provide a link to an absolute URL, use the “UrlAbs” class and an instance of this class can then be associated with a Link destination or can be accessed through the invokeActivity method.

  In the Page Class:
      <comp:Link id=”gotoOracle” label=”Oracle” destination=”{model.oracleUrl}” />
  
      In the Controller Class:
      page.setModel(“oracleUrl”, new UrlAbs("http://www.oracle.com", "Oracle"));
  

  Alternative method using invokeActivity:

  In the Page Class:
      <mx:Button label=”Go To Oracle” click=”{invokeActivity(model.oracleUrl)}” />
  
      In the Controller Class:
      page.setModel(“oracleUrl”, new UrlAbs("http://www.oracle.com", "Oracle"));
  

• Link to Enterprise Manager Page

  In addition to absolute URLs, the MPCUI framework supports the ability to link to well known Enterprise Manager pages by constructing a “UrlEm” object that can be referenced from the Link destination or passed to the invokeActivity method as part of a click handler. The reference guide includes a complete list in the oracle.sysman.emx.Constants class of all page constants available and the corresponding parameters that must be specified to produce a URL.

  // setup link to availability page
    var availLink:UrlEm = new UrlEm(Constants.PAGE_AVAILABILITY,
                                  [new InputParam(Constants.P_TARGET_NAME,  
                                   ApplicationContext.getTargetName()), 
                                   new InputParam(Constants.P_TARGET_TYPE, 
                                   ApplicationContext.getTargetType()),
                                   new InputParam(Constants.P_PAGE_TYPE, 
                                   Constants.BY_DAY)]);
    page.setModel("availPageLink", availLink);                        
  

• Link to Enterprise Manager Target Home page

  A special case is to produce the URL to an Enterprise Manager target home page. For this situation, use the static UrlEm.homepageUrl method:

  page.setModel("relatedHostLink", UrlEm.homepageUrl(host.name, host.type));
  

8.11.1 Metric Services

The MPCUI provides a simple service for retrieving metric data from the Management server in either real-time or historical form. For real-time data, the Oracle Management Service accesses the Management Agent to retrieve the data, so use this for cases where the metric can be collected efficiently in real time.

<mp:LineChart id="cacheChart" 
                        width="100%" height="100%" 
                        metricName="MSSQL_MemoryStatistics" 
                        metricColumns="['cache_hit_ratio']"
                        timePeriod="REALTIME" interval="15" >
            </mp:LineChart>

<c:Table id="processesTable" width="100%" height="100%"
              metricName="CPUProcessesPerf"
              metricColumns="['ProcUser', 'ProcCPU', 'ProcCmd']"
              timePeriod="REALTIME"
              interval="30"
              >
    <c:columns>
      <mx:AdvancedDataGridColumn width="50" dataField="key" />
      <mx:AdvancedDataGridColumn width="100" dataField="ProcUser" />
      <mx:AdvancedDataGridColumn width="80" dataField="ProcCPU" />
      <mx:AdvancedDataGridColumn width="400" dataField="ProcCmd" />
   </c:columns>                
</c:Table>

<intg:services>
      <dataserv:MetricValuesDataService id="mv1" flattenData="true"
                  targetName="{ApplicationContext.getTargetName()}" 
                  targetType="{ApplicationContext.getTargetType()}" 
                  metricName="Load" columns="{['cpuUtil', 'cpuUser', 'cpuKernel']}"
                  timePeriod="{MetricCollectionTimePeriod.LAST_DAY}"
                  /> 
    </intg:services>
    <comp:Table id="mvTable" dataProvider="{mv1}" />

<ds:MetricValuesDataService id="procData" 
      flattenData="true"
      targetName="{appModel.target.name}" 
      targetType="{appModel.target.type}" 
      metricName="CPUProcessorPerf"
      columns="{['CPUIdle']}"
      timePeriod="REALTIME"
      interval="15" />

<components:InfoItem label="CPU(0) Idle %" 
value="{procData.result.getString('0','CPUIdle')}" />

var cpuPerf:Metric = 
            ApplicationContext.getTargetContext().getMetric("CPUPerf");
    var cpuPerfSel:MetricSelector = procMetric.getSelector( 
            ['system','idle', 'io_wait']);
    cpuPerfSel.getData(cpuDataHandler, MetricCollectionTimePeriod.CURRENT,
            page.getBatchRequest());

public function cpuDataHandler(cpuData:MetricResultSet,fault:ServiceFault):void
        {
        if(fault != null) return;   // handle this better!

        var dataPoint:TimestampMetricData = cpuData.results[0];
        var collectionTime:Date = dataPoint.timestamp;
        var idleTime:Number = dataPoint.data[0]['idle'];
        var systemTime:Number = dataPoint.data[0]['system'];
        var ioWaitTime:Number = dataPoint.data[0]['io_wait']; 
        }

8.11.2 Custom Data Source

In addition to the metric and SQL data sources (and service tags) that can be used to obtain data for charts, tables and other components, you can construct your own custom data source for these components. This is useful in situations where you want to obtain data from other MPCUI services and manipulate it before display. For example, to combine data from two metrics, filter the data in some way, or otherwise aggregate the data.Creating a custom data source requires the use of controller code to obtain the source data and then to manipulate it to create the data source. The custom data source provides the following important behavior:

• Set column descriptors for the data included in the data source to provide help to the UI component when displaying the data. The descriptor contains properties such as data type, and display label (for legends or column headers).

• Support multiple data points to enable the display of the data in a time-series chart.

• Support caching and modification of the data source allowing components to show updated data as information underlying the data source changes.

public function CustomDataSource(columns:Array, hasKey:Boolean=false, isTimeSeries:Boolean=false)

// execute a SQL query and then massage the data for display
                var query:SqlQueryService = new SqlQueryService('CPU_USAGE', 
                            [SqlQueryInput.createParam("TARGET_GUID", 
                            ApplicationContext.getTargetContext().guid)]);
                query.execute(cpuQueryHandler, page.getBatchRequest());
        }
        
        
        public function cpuQueryHandler(result:SqlQueryResultSet, 
                            fault:ServiceFault):void
        {
            
            if(fault != null || result.getError() != null) return;
            
                    cpuSqlData = new CustomDataSource([
                        new QueryColumnDesc("Processor", QueryColumnType.STRING), 
                        new QueryColumnDesc("Idle Percentage", QueryColumnType.DECIMAL),
                        new QueryColumnDesc("Used Percentage", QueryColumnType.DECIMAL)
                        ], true);
                    page.setModel("cpuSqlData", cpuSqlData);
      
            if(result.rows != null)
            {
                for(var r:int=0; r<result.rows.length; r++)
                {
                    var id:String = result.getString(r, 'CPU Number');
                    var idle:Number = result.getNumber(r, 'Idle %');
                    var used:Number = result.getNumber(r, 'Used %');
                    cpuSqlData.setRow("Processor #"+id, idle, used);
                }
            }           
        }
  

8.11.2.2 Binding the Data Source to a UI Component

In the page layout (for example, ProcessesPage.mxml), the data is bound to the UI component using the dataProvider property. In Example 8-14, note cpuSqlTable. This is a table that displays the data loaded into the cpuSqlData custom data source.

Example 8-14 Binding the Data Source to a UI Component

<mp:Region id="cpuUtilRegion" width="100%" height="100%" title="CPU Utilization" >     
  <mx:HBox width="100%" height="100%"> 
  <mp:LineChart id="cpuUtilChart" width="60%" height="100%" 
         dataProvider="{model.cpuChartData}" 
         legendLocation="right" showLegend="true" />
  <mp:Table id="cpuSqlTable" dataProvider="{model.cpuSqlData}" 
                                        width="40%" height="100%"/>
  </mx:HBox>      
</mp:Region>

Figure 8-7 shows what Example 8-14 displays.

Figure 8-7 Table Displaying Data Loaded into the cpuSqlData Custom Data Source

Description of "Figure 8-7 Table Displaying Data Loaded into the cpuSqlData Custom Data Source"

8.11.3 Packaged SQL and the Query Service

While the MPCUI framework provides access to the most useful data through either UI components or simplified services (such as the metric service), inevitably you must have access to other information stored in the Management Repository in a more unstructured form. The MPCUI framework provides a SQL query service for this access.

The SQL query service enables you to package SQL statements with your plug-in and then run the statements through a Web service and then bind that data to UI elements in your custom UI. The SQL query service does not provide an open-ended or scriptable API to the Management Repository as this would expose a potential security risk.

The SQL query service can only run SQL statements that have been deployed to the Management repository through the Enterprise Manager Extensibility Framework. This ensures that the statements can access EDK views only. This still provides you with a lot of flexibility and the ability to access data from your own views (for example, views generated from Enterprise Manager configuration data) along with Enterprise Manager partner EDK views.

You can encapsulate the query service entirely within the page code by using the SQLDataService tag. This tag allows the caller to specify the SQL to be processed and the parameters to be passed. This data service object can then be bound to a table or to other UI components that support it.

<intg:services>
      <ds:SQLDataService id="dbSummaryDS" queryID="DATABASE_SUMMARY" 
                    properties="{model.dbSummProp}" />      
    </intg:services>
    
            <t:Table id="dbSummaryTable" dataProvider="{dbSummaryDS}"> 
                <t:columns>
                    <mx:AdvancedDataGridColumn width="100" dataField="Name"/>
                    <mx:AdvancedDataGridColumn width="100" dataField="Status"/>
                    <mx:AdvancedDataGridColumn width="500" dataField="Database File Location"/>
                </t:columns>
            </t:Table>

Retrieving Individual Values From the SQL DataService

To reference a specific cell returned from SQLdataService for use within a component (such as Link or Label), the following type of reference is used:

<ds:SQLDataService id="ids" queryID="INSTANCE_INFO" 
                     properties="{props('TARGET_GUID',appModel.target.guid)}" />
 
      <components:InfoItem label="CPU Model" 
                     value="{ids.result.getString(0,'CPU Model')}" />   
                        

The reference to the data service is through dataService.result.getString(rowIndex,'column'), where rowIndex is the row returned from the query and column is the name of the column as specified in the original SQL query.

The query service can also be called from within a controller, providing much more flexibility in terms of how the data is manipulated before it is displayed. There are two APIs that provide access to the query service:

• SqlQuery interface

  The SqlQuery interface allows for a single SQL query to be processed, passing the bind variable and receiving a result set in return. The result set provides an interface quite similar to that of the JDBC ResultSet.

  Example 8-16 Using the SqlQuery API:

  var getInfoSvc:SqlQuery = new SqlQuery("GET_TARGET_INFO",
              [["TARGET", name],["TYPE", type]]);   // bind variables
       getInfoSvc.execute(getTargetInfoHandler);
  
   public function getTargetInfoHandler(resultSet:ResultSet, fault:ServiceFault):void
   {    
       var target:Target;            
       if(fault == null)
       { 
           if(resultSet != null && resultSet.getError() == null)
           {
               target.setGuid(resultSet.getBase64Binary(0, "TARGET_GUID"));
               target.setTypeMetaVer(resultSet.getString(0, "TYPE_META_VER"));
               
               var props:Array = new Array();
               for(var i:int=1; i<Target.NUM_PROPERTIES+1; i++)
                   props.push(resultSet.getString(0, "CATEGORY_PROP_"+i));
               target.setCatProperties(props);      
           }    
   }
  

• BulkSqlQuery interface

  The bind variables are referenced by name and correspond to the variables as represented in the packaged SQL statement:

  SELECT target_guid, type_meta_ver, category_prop_1, category_prop_2, 
               category_prop_3, category_prop_4, category_prop_5
       FROM mgmt_targets
       WHERE target_name = ?TARGET?
       AND target_type = ?TYPE? 
  

  When a number of queries can be processed in a single request, you can use the BulkSqlQuery interface. Each query must be added to the bulk query and when all queries to be processed have been added, the BulkSqlQuery.execute method is called and passed the result handler that will be called with the results.

  When a result handler for the SqlQuery is passed a single SqlQueryResultSet for the processed query, the result handler for the BulkSqlQuery is passed a BulkResultSet. Then it must retrieve the SqlQueryResultSet for each query using the request id specified when the query was added.

  A separate request id is required to support the case where the same query can be processed multiple times with different bind variables as part of the same bulk request.

  Example 8-17 Using the BulkSqlQuery API

  var guidParam:Array = [["TARGET_GUID", ApplicationContext.getTargetContext().guid]];
  
    var bulkQuery:BulkSqlQuery = new BulkSqlQuery();  
    bulkQuery.addQuery("INSTANCE_INFO", "INSTANCE_INFO", guidParam);      
    bulkQuery.addQuery("PROCESS_STATES", "PROCESS_STATES", guidParam);
    bulkQuery.addQuery("PROCESS_INFO", "PROCESS_INFO", guidParam);    
                                                           
    bulkQuery.execute(pageDataHandler, page.getBatchRequest()); 
  
  public function pageDataHandler(bulkResult:BulkResultSet, fault:ServiceFault):void
  {
    var info:SqlQueryResultSet = bulkResult.getResultSet("INSTANCE_INFO");
  

8.11.4 Working With Target Services

In addition to the services described previously, the MPCUI framework provides a number of other services that are an integral part of the Target object (oracle.sysman.emx.model.Target). When the MPCUI application is running, the ApplicationContext.getTargetContext() call returns the Target instance for the primary target.

You can construct other target instances for associated targets. In either case, use the following methods to obtain additional information for these targets through the MPCUI service layer.

var target:Target = ApplicationContext.getTargetContext();
     target.getTargetInfo(targetInfoHandler);


         public function targetInfoHandler(target:Target, fault:Fault):void

// get associated host 
    var target:Target = ApplicationContext.getTargetContext();
    var assocTypes:Array = [ AssociationDataService.HOSTED_BY ];
    target.getAssociatedTargets(assocTypes, assocHandler); 

        public function assocHandler(assocResult:GetAssociationsResult,
                                 fault:ServiceFault):void
        {
            var host:ManageableEntityComponent = 
                assocResult.getAssoc(AssociationDataService.HOSTED_BY);
            if(host != null) 
                page.setModel("relatedHost", host.name);
        }

var target:Target = ApplicationContext.getTargetContext();
     target.getMetricMetadata(metadataHandler);


 public function metadataHandler (target:Target,
        fault:Fault):void

var target:Target = ApplicationContext.getTargetContext();
       target.getAvailability(targetAvailHandler);


           public function targetAvailHandler(availInfo:AvailOvervieData,
                                 fault:Fault):void

8.11.5 Monitoring Service Request Performance

MPCUI includes a tracing service that enables you to monitor the performance of service requests made from the MPCUI code. This is useful when attempting to troubleshoot slow pages or to identify the amount of time spent processing the request in the Management server.

To enable service tracing:

1. Depending on your implementation, choose one of the following:

   • Flex-based UI

     1. Locate the html-template/data/mpCuiProperties.xml file. It is included in the project directories (if you are using the Demo Sample as a template).

     2. Add the following line to the mpCuiProperties.xml file:

        <traceEnabled>true</traceEnabled>
        

     3. Rebuild your application, and then launch it using the Flex Builder debugger or run option:

   • Metadata-only UI

     1. When running the MPCUI page in the console, ensure that the plug-in is deployed.

     2. Access the target home page associated with the plug-in.

     3. In the address box of the browser window, add the following to the end of the URL:

        &traceEnabled=true
        

     4. Press Enter to reload the page.

   The MPCUI application loads and the home page appears with the Activity Tracing dialog similar to Figure 8-8.

   The Activity Tracing dialog displays the set of pages accessed in the current session, and below each page the set of requests made to the Management Server.

   Figure 8-8 Activity Tracing Dialog

   
   Description of "Figure 8-8 Activity Tracing Dialog"
   
   

2. Expand or collapse the dialog using the controls in the upper right-hand corner. It continues to refresh while the MPCUI application is active.

   Note:

   When you select a service request in the top pane of the dialog, the Total Time (round trip) is shown as well as the time spent processing the request in the Management Server (Service Time).

3. In the details pane, click Show Item Details to view the body of the request and response messages sent between your application and the Management server.

8.11.6 Automated Polling of Service Requests

The MPCUI framework supports a limited subset of intervals (15, 30, 60, 90 seconds) so that requests can be grouped together to avoid a large number of requests to the Management Server.

The MPCUI framework starts and stops the polling of these requests automatically as each page or dialog appears or is removed (goes out of scope).

You cannot initiate a polling request that is persistent beyond the scope of a page or dialog.

8.11.7 Batching of Service Requests

In addition to the batching of polling requests, the MPCUI framework provides the ability to explicitly batch requests made at runtime from activity (page or dialog) controllers. Batching of requests is a good practice as it avoids additional round trips to the Management Server which slows the performance of your UI pages and adds additional overhead to the Management Server.

The most common opportunity to batch requests is as part of the activity initialization.

• For data services declared in the page layout (MXML file), the MPCUI framework will batch the requests for you.

• For service requests you make from your controller.init() method, you can pass the page's batch request to the service methods. The MPCUI framework calls the init() method after your page is loaded.

Example 8-18 is extracted from the HomePageController.as file in the Demo Sample. Note the instances of page.getBatchRequest() in the method. All requests made in this way will be performed over a single pass to the Management Server.

override public function init(pg:IActivity):void
  {   
    super.init(pg);                               
    page = pg as HomePage;                                                     

    var guidParam:Array = [["TARGET_GUID", 
            ApplicationContext.getTargetContext().guid]];            
    var bulkQuery:BulkSqlQuery = new BulkSqlQuery();          
    bulkQuery.addQuery("INSTANCE_INFO", "INSTANCE_INFO", guidParam);
    bulkQuery.addQuery("CPU_USAGE", "CPU_USAGE", guidParam);  
    bulkQuery.execute(queryResultHandler, page.getBatchRequest());

    // get processes metric to get process summary information
    var procMetric:Metric = ApplicationContext.getTargetContext()
            .getMetric("CPUProcessesPerf");
    var procSelector:MetricSelector = procMetric
            .getSelector(['ProcUser', 'ProcCPU', 'ProcCmd']);
    procSelector.getData(processesHandler, 
            MetricCollectionTimePeriod.CURRENT, page.getBatchRequest());    
            
    var cpuPerf:Metric = ApplicationContext.getTargetContext()
            .getMetric("CPUPerf");
    var cpuPerfSel:MetricSelector = cpuPerf.
            getSelector(['system', 'idle', 'io_wait']);
    cpuPerfSel.getData(cpuDataHandler, 
            MetricCollectionTimePeriod.REALTIME, page.getBatchRequest());           

    // get associated host 
    var target:Target = ApplicationContext.getTargetContext();
    var assocTypes:Array = [ AssociationDataService.HOSTED_BY ];
    target.getAssociatedTargets(assocTypes, assocHandler, 
            page.getBatchRequest());    
}

You can use batch requests elsewhere in controller code by creating a MultiServiceRequestor (batch request) and passing it to each request made. For example, suppose that in response to a button click in the page, two requests will be made to the Management Server to retrieve information. They could each be made separately (resulting in two trips to the server) as shown in Example 8-19:

var procMetric:Metric = ApplicationContext.getTargetContext()
            .getMetric("CPUProcessesPerf");
 var procSelector:MetricSelector = procMetric
            .getSelector(['ProcUser', 'ProcCPU', 'ProcCmd']);
 procSelector.getData(processesHandler, 
            MetricCollectionTimePeriod.CURRENT);    // 1st round trip

 var cpuPerf:Metric = ApplicationContext.getTargetContext()
            .getMetric("CPUPerf");
 var cpuPerfSel:MetricSelector = cpuPerf.
            getSelector(['system', 'idle', 'io_wait']);
 cpuPerfSel.getData(cpuDataHandler, 
            MetricCollectionTimePeriod.REALTIME);  // 2nd round trip        

Alternatively, you can combine the batch requests into a single batch request avoiding the additional round trip to the Management server as shown in Example 8-20:

var batchRequest:MultiServiceRequestor = new MultiServiceRequestor();
 
            var procMetric:Metric = ApplicationContext.getTargetContext()
            .getMetric("CPUProcessesPerf");
  var procSelector:MetricSelector = procMetric
            .getSelector(['ProcUser', 'ProcCPU', 'ProcCmd']);
  procSelector.getData(processesHandler, 
            MetricCollectionTimePeriod.CURRENT, batchRequest);    
            
  var cpuPerf:Metric = ApplicationContext.getTargetContext()
            .getMetric("CPUPerf");
  var cpuPerfSel:MetricSelector = cpuPerf.
            getSelector(['system', 'idle', 'io_wait']);
  cpuPerfSel.getData(cpuDataHandler, 
            MetricCollectionTimePeriod.REALTIME, batchRequest); 
 
  batchRequest.sendRequest();     // 1st and ONLY round trip!

8.12.1 Automation Services

One of the more powerful aspects of the MPCUI framework is the ability to provide access to administrative features through a UI customized to that purpose. The framework supports the processing of administrative tasks through the Enterprise Manager job system and Web services that provide access to the job system.

The MPCUI provides the following job services:

• Job.submit

• Job.runSynchronous

• JobExecution.getStatus

• JobExecution.getDetails

• JobExecution.stopJob

• JobExecution.deleteJob

• JobExecution.getJobDetailsURL

• RemoteOp.performOperation

var job:Job = new Job("backup", "MyBackup", null, 
                ApplicationContext.getTargetContext(), 
                [Job.jobParam("dsn", "AdminDS"), Job.jobParam("sql_cmd",stmt)], 
                 JobSchedule.IMMEDIATE);
  job.submit(jobSubmitHandler);
} 

private function jobSubmitHandler(exec:JobExecution, fault:Fault):void
{
       // using exec (JobExecution) can now get current status of job,
       // get step details, and start or stop the job
  var execId:JobExecutionId = exec.getExecutionId();
}

var job:Job = new Job("backup", "MyBackup", null, 
            ApplicationContext.getTargetContext(), 
            [Job.jobParam("dsn", "AdminDS"), Job.jobParam("sql_cmd",stmt)], 
            JobSchedule.IMMEDIATE);
    job.runSynchronous((jobRunHandler, 30); // 2nd param is timeout
} 

private function jobRunHandler(exec:SynchronousJobExecution, fault:Fault):void
{
    // using exec (SynchronousJobExecution) can get details about job execution;
    // this handler will not be called until the job completes, fails
    // or the timeout is reached
    var execId:JobExecutionId = exec.getExecutionId();
}

var task:Task = new Task("TTisql", null, [Job.jobParam("dsn", "AdminDS"), 
                        Job.jobParam("sql_cmd",stmt)]);
            task.execute(createTableHandler, 10);   // timeout is 10s
         }

        private function createTableHandler(result:SynchronousJobExecution, fault:Fault):void
        {        
            var status:JobStatus = result.getRunStatus();
            if(status == JobStatus.RUNNING)
            {
                // timed out while waiting for job... still running
            

private function submitHandler(exec:JobExecution, fault:Fault):void
{
    exec.getStatus(statusHandler);
}

private function statusHandler(status:JobStatus, fault:Fault):void
{
    if(status.getStatus() == JobStatus.FINISHED)

private function createTableHandler(result:SynchronousJobExecution, fault:Fault):void
 {        
     var status:JobStatus = result.getRunStatus();
     if(result != null && result.Status() == JobStatus.COMPLETED)
     {
         var steps:Array = result.getStepDetail();
         for(var i:int=0; i<steps.length; i++)
         {
             var detail:JobStepDetail = steps[i];
             proc.addDetailText(detail.output);
         }

private function submitJob():void
 {
     var params:Array = new Array();
     params.push(Job.jobParam("p0","p0value"));
     var job:Job = new Job(type, name, desc, ApplicationContext.getTarget(), params,Job.immediateSchedule()); 
     job.submit(submitHandler);
 }
 
 private function submitHandler(result:JobExecution, fault:Fault):void
 {
     if(fault == null && result != null)
     {
         // get the job status; calls the server
         result.getStatus(statusHandler);
     }
 }
 
 private function statusHandler(result:JobStatus, fault:Fault):void
 {
     if(fault == null && result != null)
     {
         if(result.getStatus() == JobStatus.COMPLETED)
         {
             // now can get job output details
             result.getJobExecution().getDetails(detailsHandler);
         }
     }
 }
 
 private function detailsHandler(result:JobExecutionDetails, fault:Fault):void
 {
     if(fault == null && result != null)
     {
         var steps:Array = result.getStepDetail();
         for(var i:int=0; i<steps.length; i++)
         {
             var detail:JobStepDetail = steps[i];
             proc.addDetailText(detail.output);
         }                
     }
}

private function stopJob(exec:JobExecution):void
 {
     // NOTE: the JobExecution must be a valid job context obtained from submitted a job
     exec.stopJob(stopJobHandler);
 }

 private function stopJobHandler(exec:JobExecution, fault:Fault):void
 {
     if(fault == null && exec != null)
     {
         // job was successfully stopped
 } 
 }

private function deleteJob(exec:JobExecution):void
 {
     // NOTE: the JobExecution must be a valid job context obtained from submitted a job            
     exec.deleteJob(deleteJobHandler);
 }

 private function deleteJobHandler(exec:JobExecution, fault:Fault):void
 {
     if(fault == null && exec != null)
     {
         // job was successfully deleted
     } 
 }  

var job:Job = new Job("backup", "MyBackup", null, 
                 ApplicationContext.getTargetContext(), 
                [Job.jobParam("dsn", "AdminDS"), Job.jobParam("sql_cmd",stmt)], 
                JobSchedule.IMMEDIATE);
                job.runSynchronous((jobRunHandler, 30, true); 

stage/agent/scripts

./stage/agent/scripts/process/kill_process.pl

var params:Array = [ 
            RemoteOp.param("%scriptsDir%/process/kill_process.pl"),
            RemoteOp.param(pid) ]; 
    var remoteOp:RemoteOp = new RemoteOp("perl", params);              
    remoteOp.performOperation(killProcessHandler);

private function killProcessHandler(remoteOp:RemoteOp, fault:Fault):void

/**
  * Check status; could be any number of problems some of which may result 
  * in step output, some of which (like missing creds) result in a non-successful 
  * run status but no step details.
  * 
  * result.getRunStatus() - the status of the job, refer to Constants.JOB_*_STATUS
  * result.getStepDetail().stepName/detail - name and output from each step in the job 
  * result.getJob() - the complete job Object, to reference parameters:
  *   result.getJob().parameter[0].paramName/paramValue[0]
  * 
  */
  if(remoteOp.result.status != Constants.JOB_COMPLETED_STATUS)
  {
    // job did *NOT* complete successfully
    var pid:String = remoteOp.getParameter(2).paramValue[0] as String;
    var msg:String = "Unable to successfully kill process ["+pid+
                "].  The status of the command was: " 
               +Util.getCatString(Util.JOB_STATUS, remoteOp.result.status)
               +"\nReturn Code: "+remoteOp.result.returnCode
               +"\nCommand Output: "+remoteOp.result.commandOutput;
    MessageAlert.show(msg, "Failed to Kill Process", Alert.OK);
   }
   else
   {
    // successful job execution; process was killed; can look at the
    // step details to get possible output from the job
    MpLog.debug("Command was successful: "
         +"\nReturn Code: "+remoteOp.result.returnCode
           +"\nCommand Output: "+remoteOp.result.commandOutput);       
    page.processesTable.refreshImmediate();    
   }                                    

8.12.2 Working With Credentials

The Enterprise Manager credentials model supports three different modes for performing operations that require credentials:

• Preferred Credentials

  Specific credentials are set for a target or all targets of a particular type. In this mode, the user does not select a set of credentials or provide credential values.

• Named Credential Set

  Sets of credentials are created for a target or all targets of a particular type, and each set is assigned a name. In this mode, the user is presented with a list of named sets and can select the set that they would use to perform the operation.

• Override Credentials

  In this mode, the user can supply credentials at runtime that are used to perform the operation.

var ccSvc:CheckPreferredCredsService = new CheckPreferredCredsService();
       ccSvc.getPreferredCredsInfo(ApplicationContext.getTargetName(), 
       ApplicationContext.getTargetType(), 
       'HostCreds', checkPrefCredsHandler);

public function checkPrefCredsHandler(result:CheckPreferredCredsResult, 
                        fault:ServiceFault):void
  {
    if(fault != null)
        MessageAlert.show(fault.faultDetail, "Error Checking Preferred Creds");
    else
    {
        var msg:String = "Checked for Preferred Credentials for 
               target("+ApplicationContext.getTargetName()+","+
               ApplicationContext.getTargetType()+" for set(HostCreds) 
               user("+ApplicationContext.getEmUser()+") \n"+
               "Global Set = "+result.globalSet+" Instance Set = "
                +result.instanceSet;
        MessageAlert.show(msg, "Check Preferred Creds Result");   
    }
}

var target:Target = ApplicationContext.getTargetContext();
  target.getCredentialSets(["HostCreds", "HostSampleCreds"], 
                credSetResultHandler);

var credTableData:ArrayCollection;
   if(creds.credSet != null)
   {
      credTableData = new ArrayCollection(creds.credSet);
      
      // check to see if there are sets for both types
      var hostFound:Boolean = false;
      var sampFound:Boolean = false;
      for(var c:int=0; c<creds.credSet.length; c++)
      {
         if(creds.credSet[c].credentialType == "HostCreds")
             hostFound = true;
         else if(creds.credSet[c].credentialType == "HostSampleCreds")
             sampFound = true;
      }
                
      var missingType:String = ( !hostFound ? "HostCreds" : 
                                    "HostSampleCreds" );
      var empty:CredentialSet = new CredentialSet();
      empty.credentialType = missingType;
      empty.name = "<No Sets Found>";
      empty.guid = "";     
      credTableData.addItem(empty);           
   }
   else
   {
      empty = new CredentialSet();
      empty.credentialType = "<No Credential Sets Defined>";
      empty.name = "";
      empty.guid = "";                
      credTableData = new ArrayCollection([empty]);
   }  

8.12.2.3 Reusable Credentials UI Components

MPCUI provides a credentials region that may be included in a page to allow the end user to interact with the Enterprise Manager credentials subsystem to view the set of credentials available and to select preferred, named, or override credentials when performing a task (job or remote operation).

Figure 8-9 Credentials Region

Description of "Figure 8-9 Credentials Region"

To include this region in a page, add the following MXML:

Example 8-28 Adding a Credentials Region

<credentials:CredentialsRegion id="credRegion" width="40%" height="100%" 
         title="Credentials" target="{ApplicationContext.getTargetContext()}" 
         credentialType="HostCreds" />     

From the page controller associated with the page, retrieve the settings applied by the end user to this region:

Example 8-29 Retrieving Selected Credential Information

public function getCredsEntered(event:MouseEvent):void
        {            
            var mode:String = page.credRegion.getMode();
            var msg:String = "Credential Option Selected: "+mode+"\n";
         
            var namedSet:String;
            var creds:Array;
            if(mode == CredentialsRegion.NAMED_MODE)
            {
                namedSet = page.credRegion.getNamedSet();
                msg += "Named Set Selected: "+namedSet;
            }
            else if(mode == CredentialsRegion.OVERRIDE_MODE)
            {
                try
                {
                    creds = page.credRegion.getOverrideCredentials();
                    for(var c:int=0; c<creds.length; c++)
                        msg += "Field:"+creds[c].label+", "+creds[c].value+"\n";
                }
                catch(e:Error)
                {
                    msg += "Error Entering Credentials:\n";
                    msg += e.message;
                }
            }
            else
            {
                // preferred selected... 
            }
            MessageAlert.show(msg, "Credentials Entered");                   
        }       

In Example 8-29, note that the mode determines if the user selected preferred, named, or override credentials. Depending on the mode, the named set can be retrieved (CredentialsRegion.getNamedSet()) or the override credentials can be retrieved (CredentialsRegion.getOverrideCredentials()).

8.13.1 Defining Regions

The Enterprise Manager UI style guides recommends that you organize the information on the page into regions. A region is a visual box with a title that can be expanded and collapsed. For example, in Example 8-30, each of the rows could be split up into separate regions rather than more vertical containers:

<mx:VBox height="100%" width="100%">
      <!-- 1st row -->
      <mx:HBox height="33%" width="100%">
          <components:Region height="100%" width="50%" title="Row 1 Region 1" > 
          </components:Region>       
          <components:Region height="100%" width="50%" title="Row 1 Region 2" >
          </components:Region>             
      </mx:HBox>
      
      <!-- 2nd row -->
      <mx:HBox height="33%" width="100%">      
          <components:Region height="100%" width="50%" title="Row 2 Region 1" > 
          </components:Region>       
          <components:Region height="100%" width="50%" title="Row 2 Region 2" >
          </components:Region>                         
      </mx:HBox>
      
      <!-- 3rd row -->
      <mx:HBox height="33%" width="100%">
          <components:Region height="100%" width="50%" title="Row 3 Region 1" >
          </components:Region>       
          <components:Region height="100%" width="50%" title="Row 3 Region 2" > 
          </components:Region>                              
      </mx:HBox>                
  </mx:VBox>

Example 8-32 results in a display similar to Figure 8-10. You can use each of the regions to contain other UI components (such as tables and charts) to display meaningful information. For more detailed examples, see the examples in the Demo Sample included in the Extensibility Development Kit.

Figure 8-10 Regions

Description of "Figure 8-10 Regions"

8.14.1 Availability Region

The availability region displays the availability of the target for the period specified in the AvailabiltyRegion tag daySpan property. It shows a segmented bar that shows details of the target availability (such as outages) over that same period:

<avail:AvailabilityRegion width="25%" height="100%" daySpan=”1”/>

Figure 8-11 Availability Region

Description of "Figure 8-11 Availability Region"

8.14.2 Incidents and Problems Region

The incidents region shows the set of open incidents for the current target and all related targets. It provides the option to filter the list of displayed incidents. The only necessary settings for the region are the size (width/height):

<events:IncidentRegion width="50%" height="100%"/>

Figure 8-12 Incidents and Problems

Description of "Figure 8-12 Incidents and Problems"

8.14.3 Job Summary Region

The jobs summary region displays the count of jobs by status.

<jobs:JobSummaryRegion width="20%" height="100%" />

Figure 8-13 Job Summary

Description of "Figure 8-13 Job Summary"

8.14.4 Credentials Region

For information about reusable credentials UI components, see Section 8.12.2.3, "Reusable Credentials UI Components".

8.15.1 Line Chart

Typically, the line chart displays information over time (often referred to as a time-series chart). Therefore, it lends itself to the display of metric information either historically or in real-time. The chart includes properties for specifying the metricName and metricColumns (an array) that should be shown in the chart and a timePeriod property that can be set to show historical data or real-time sampled data. When timePeriod is set to "REALTIME", the chart manages an automatic polling request for you and updates the chart data as new samples arrive.

<components:Region title="CPU Load" width="75%" height="100%" >
    <charts:LineChart id="cpuload" width="100%" height="100%"
                 metricName="Response"
                 metricColumns="['Load']"
                 timePeriod=”REALTIME” interval=”15” />
    <components:Link label="Show History" 
           click="{invokeActivity('metricHistory'))}" />   
 </components:Region> 

Figure 8-14 Example of a Line Chart

Description of "Figure 8-14 Example of a Line Chart"

<c:LineChart id="hchart" timePeriod="REALTIME" 
              showLegend="true" legendLocation="top"

8.15.2 Area Chart

The area chart is similar to the line chart and has the same attributes. It displays data in the same way as LineChart. The showCumulativeLine property controls the display of an area chart. For most area charts, this property should be included in set to “true” to show a stacked or cumulative area chart. Otherwise, the area chart overlays the fill areas for each series included in the chart.

<charts:AreaChart id="cpuutil" width="100%" height="100%" 
          metricName="CPUProcessorPerf" 
          metricColumns="{['CPUIdle']}"
          timePeriod="LAST_DAY" />

8.15.3 Bar (Horizontal) Chart

The bar chart exposes the same properties as the column chart both for visible attributes and for specifying control over the data source:

<charts:BarChart id="spaceChart" timePeriod="CURRENT" 
          width="100%" height="100%" 
          groupBy="byKey" 
          metricName="MSSQL_Database" 
          metricColumns="{['spaceavailable']}" />   

Figure 8-15 Bar Chart

Description of "Figure 8-15 Bar Chart"

8.15.3.1 Grouping Bars

The groupBy property (available for bar and column charts) enables you to organize data by key or by column. The default (by column) applies when the data set does not include keys.

For example, assume you have the following data set where the User column is treated as the key to the data:

User	Logins	Errors
Jones	23	12
Smith	30	4
Shah	27	20

In Example 8-33, the groupBy property is set to byColumn. This creates two groups of columns, one for each data column, with all three keys appearing in each group as displayed in Figure 8-16.

Example 8-33 Group By Column

<mp:BarChart id="userBarChart" 
               dataProvider="{model.userData}" 
               showLegend="true"
               groupBy="byColumn"
               />

Figure 8-16 Group By Column

Description of "Figure 8-16 Group By Column"

In Example 8-34, the groupBy property is set to byKey. This creates three groups, one for each key, with both columns (the data items) appearing in each group as displayed in Figure 8-17.

Example 8-34 Group by Key

<mp:BarChart id="userBarChart" 
                        dataProvider="{model.userData}" 
                        showLegend="true"
                        groupBy="byKey"
                        />

Figure 8-17 Group By Key

Description of "Figure 8-17 Group By Key"

8.15.4 Column (Vertical Bar) Chart

The column chart is a vertical bar chart and exposes the same properties as the bar chart both for visible attributes and for specifying control over the data source:

<charts:ColumnChart id="bchart" timePeriod="LAST_DAY" 
          width="100%" groupBy="byKey" 
          metricName="CPUProcessorPerf" metricColumns="{['CPUIdle']}"/>

Figure 8-18 Column Chart

Description of "Figure 8-18 Column Chart"

8.15.5 Pie Chart

In the following example, the code constructs a pie chart by specifying the metric name and metric columns. The MPCUI framework performs the necessary requests to obtain information from the Management Server and populates the values in the chart.

<charts:PieChart id="memChart" 
       targetName="{appModel.target.name}" 
       targetType="{appModel.target.type}" 
       metricName="MemoryPerf" 
       metricColumns="{model.memoryColumns}"
       timePeriod="LAST_DAY" 
       labelPosition="none" />    

Figure 8-19 Pie Chart

Description of "Figure 8-19 Pie Chart"

8.16.1 Data Service

Example 8-35 maps the table to the MetricDataService by specifying the metricName and metricColumns. You do not have to specify the headerText attributes for the columns because it will be filled with the metric column labels. You can override these labels if required.

<c:Table id="processesTable" width="100%" height="100%"
              metricName="CPUProcessesPerf"
              metricColumns="['ProcUser', 'ProcCPU', 'ProcCmd']"
              timePeriod="REALTIME"
              interval="30"
              >
    <c:adminElements>               
        <mx:Button id="killProcessButton" label="Kill Process" 
                click="controller.killProcess(event)"/>
    </c:adminElements>                
    <c:columns>
      <mx:AdvancedDataGridColumn width="50" dataField="key" />
      <mx:AdvancedDataGridColumn width="100" dataField="ProcUser" />
      <mx:AdvancedDataGridColumn width="80" dataField="ProcCPU" />
      <mx:AdvancedDataGridColumn width="400" dataField="ProcCmd" />
    </c:columns>                
</c:Table>     

Figure 8-20 Data Service

Description of "Figure 8-20 Data Service"

8.16.2 Custom Data Provider

In Example 8-36, the data for the table is loaded in the controller, and mapped to the page model processInfoData item. The processInfoData is an array of objects (of any type). The dataField property specified for each column identifies the public property that will be displayed in each column. In this case, the dataField name will also be used as the headerText. You can supply the headerText property to override this label.

<tbl:Table id="processInfoTable" dataProvider="{model.processInfoData}">
    <tbl:columns>
            <mx:AdvancedDataGridColumn width="100" dataField="Process ID"/>
            <mx:AdvancedDataGridColumn width="250" dataField="User"/>
            <mx:AdvancedDataGridColumn width="100" dataField="Database"/>
            <mx:AdvancedDataGridColumn width="100" dataField="Status"/>
            <mx:AdvancedDataGridColumn width="250" dataField="Command"/>
            <mx:AdvancedDataGridColumn width="100" dataField="CPU Time"/>
            <mx:AdvancedDataGridColumn width="100" dataField="Memory Usage"/>
    </tbl:columns>
</tbl:Table>

8.16.3 Getting Selected Rows

The rows currently selected in the table can be obtained by looking at the selectedRows property of the table. This property is an array of selected rows, where each row is a Dictionary object that contains data in the row keyed by the column name. If the row is based on a custom data source, then the row will be whatever object was mapped into the table data source.

var process:Dictionary = page.processesTable.selectedRows[0];
 

If the table is set to allow single selection, then the selectedRows array includes a single entry only (or none if no row is selected).

8.17.1 Dialog Registration

To make a dialog available to be displayed using the invokeActivity method, you must register it as an activity as part of the Integration class. In Example 8-37, note the following:

• id attribute: The ID is used to reference this dialog from other activities within the application. It must be unique across all activities included in the application.

• dialogClass attribute: The dialogClass attribute is a reference to the MXML class that extends Dialog and that is the implementation for this dialog.

inputParams are optional, but they enable the dialog to be reused in situations where input parameters are required and you want to pass an object as context directly from the MXML using the bean directive. The MPCUI framework maps the input object parameters to the dialog parameters.

If you do not define inputParams as part of the dialog definition, then any input data required by the dialog (such as any custom properties) would have to be set in ActionScript and the dialog shown using the Dialog.show method.

<intg:DialogActivityDef id='metricHistory' label='Metric History' 
dialogClass='{MetricHistoryDialog}' >
            <intg:inputParams>
                <intg:InputParam name='targetName'/>
                <intg:InputParam name='targetType'/>
                <intg:InputParam name='metric'/>
                <intg:InputParam name='columns'/>
                <intg:InputParam name='period'/>
                <intg:InputParam name='title'/>
            </intg:inputParams>
        </intg:DialogActivityDef>

Figure 8-21 Metric History Dialog

Description of "Figure 8-21 Metric History Dialog"

8.17.2 Displaying a Dialog and Waiting for Close Events

If the dialog includes some state that is required when the dialog closes, then a close handler can be passed to the invokeActivity method. This handler is called with the CloseEvent. This handler identifies which button was pressed to close the dialog and retrieves the dialog object itself to retrieve information from it.

public function showCpuMetricDetails(event:MouseEvent):void
     {
        var bean:Bean = new Bean("targetName", page.appModel.target.name, 
                   "targetType", page.appModel.target.type, 
                   "metric", page.cpuutil.metricName, "columns",page.cpuutil.metricColumns, 
                   "period", "REALTIME", "title", "Metric Details (Current)");
        page.invokeActivity("metricDetails", bean, metricDialogClosed);
     }

   public function metricDialogClosed(event:CloseEvent):void
   {
        MpLog.debug("Metric Details Dialog Closed");
        var button:int = event.detail; // Alert.YES, Alert.NO, Alert.OK etc…
        var metDetailsDialog:MetricDetailsDialog = event.currentTarget 
                as MetricDetailsDialog;
   }

In Example 8-38, the metricDialogClosed function is passed to invokeActivity. When the dialog closes, the method is called and passed a CloseEvent. From this event, the currentTarget property contains the dialog itself, and the detail property indicates which button was pressed to close the dialog.

8.18.1 Train Definition Example

Example 8-39 provides a definition of train and Figure 8-22 shows the train.

<intg:TrainActivityDef id='addNewUserEmbeddedTrain' label='Add New User'>
 <intg:stepActivities>
  <mx:Array>
   <intg:TrainStepActivityDef id='anuStep1' label='User Info' pageClass='{trainSamp.S1_UserInfo}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
   <intg:TrainStepActivityDef id='anuStep2' label='Expiry' pageClass='{trainSamp.S2_Expiry}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
   <intg:TrainStepActivityDef id='anuStep3' label='Credentials' pageClass='{trainSamp.S3_Credentials}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
   <intg:TrainStepActivityDef id='anuStep4' label='Schedule' pageClass='{trainSamp.S4_Schedule}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>
   <intg:TrainStepActivityDef id='anuStep5' label='Notifications' pageClass='{trainSamp.S5_Notifications}' pageControllerClass='{trainSamp.NotificationsTrainStepController}'/>
   <intg:TrainStepActivityDef id='anuStep6' label='Confirmation' pageClass='{trainSamp.S6_Confirm}' pageControllerClass='{trainSamp.AddNewUserTrainStepController}'/>                
  </mx:Array>
 </intg:stepActivities>
</intg:TrainActivityDef>

Figure 8-22 Train Example

Description of "Figure 8-22 Train Example"

8.18.2 Train Controller

The train controller is used to managed state kept across all pages in the train and respond to changes in the train (movement between steps) and respond to the train completing when the user clicks either the Finish or Cancel button.

8.18.3 Train State

State may be maintained in the Train model using the Train.model property. This property is a dynamic property that can be used to hold any information appropriate to the train. Individual pages can store their own state in their own model properties and may also access information stored in the train model.

8.18.4 Train Events

Each train step controller can implement the init and destroy methods that are called when the step starts or stops. The step can do either of the following:

• Perform a step-specific processing step

• Access the train and allow it to process higher level logic

The train controller can also be called when the train ends (Finish or Cancel) by adding a listener function for the train done event:

// register a listener for the train complete event, this may be a cancel or finish.
 train.addEventListener(TrainEvent.TRAIN_EVENT, trainDone);

The listener (trainDone in Example 8-40) can inspect the train state and determine if processing should continue or not. It can choose to direct control to some other activity (page) or can set the train back to another step:

public function trainDone(event:TrainEvent):void
{
// train cancel/finish button was pressed, so caller can now validate
// the train (look at the model).  The caller has the various options indicated below.
var train:Train = event.target as Train;

if(train.model["isComplete"])
{
  // want to end the train, but go somewhere else (otherPage is a page id)
  train.endTrain("otherPage");
else
{
  // go back to train at a certain step
  train.controller.setStepById("step2");
}

8.25.1 About Guided Discovery

The guided discovery flow provides you with the ability to add targets and associations to Enterprise Manager by running discovery scripts on selected Management Agents and calling service APIs to add the appropriate entities. This process is driven from a user interface wizard (train) and can use information supplied by the end user to guide the process. It is up to you to determine (based on your specific requirements) the information required from the end user during this process. For examples, see the plug-in samples in the EDK (demo_hostsample and demo_hostsystem). For more information about discovery scripts, see Chapter 11, "Defining Target Discovery".

The services typically used during guided discovery include the following:

• TargetInfo services to retrieve Management Agents and targets, for example, for target existence or target properties

• AssociationInfo services to retrieve existing associations

• Discovery service to run discovery scripts on selected Management Agents

• TargetManagement services to create or delete targets

• AssociationManagement services to create or delete associations

For more information about these services, see Section 8.25.5, "Using Discovery Service", Section 8.25.6, "Using Target Information Services", and Section 8.25.7, "Using Target Management Services".

8.25.2 Supporting Guided Discovery

To add guided discovery to a plug-in, ensure that the following directories contain the required files:

• plugin_stage/discovery

  • Scripts that will be executed from the guided discovery flow. These scripts might include multiple targets and associations. For more information about discovery scripts, see Section 11.3, "Creating the Discovery Script".

  • customdiscover.lst file. This file must include one line for each discovery script to be provided with the plug-in. Each entry must reference a discovery category, which is a unique identifier that will be used to identify the script to be executed when calling the discovery service. The following entry shows a discovery category (DHS_DISC) that is used to refer to the demo_hostsample_discovery.pl script during the guided discovery flow.

    DHS_DISC|demo_hostsample_discovery.pl
    

• plugin_stage/oms/metadata/discovery

  Discovery metadata file (plugin_discovery.xml). For more information about the discovery metadata file and an example of the discovery XML, see Section 11.2, "Creating Discovery XML". For guided discovery, there are a number of attributes that must be specified correctly to allow your guided discovery to be registered correctly.

  • <DiscoveryModule name="DemoHostSample">

    This is the unique name for the discovery module and must match the module name used to register the discovery SWF in the MPCUI metadata file.

  • <NlsValue>Discover Demo Host Sample Targets</NlsValue>

    This is the label that appears in the Target Types list on the Add Targets Manually page of the Cloud Control console.

    <CustomDiscoveryUI>
       <LaunchADF>
         <DestOutcome>goto_core-mpcustomdiscovery-page</DestOutcome>
       </LaunchADF>
    </CustomDiscoveryUI>
    

    This must be exactly the same in your discovery metadata file. It ensures that the guided discovery UI that you built and included in your plug-in will be launched.

• plugin_stage/oms/metadata/mpcui

  • discovery.swf

    Similar to the MPCUI application created for a target home page, the guided discovery UI is constructed as a Flex application.

  • MyMpcui.swf

    In addition to the discovery SWF, the MPCUI metadata file must include an entry to register the discovery SWF with the appropriate discovery module.

    Example 8-46 SwfFiles Tag From MPCUI Metadata File for Flex-based UI

    <SwfFiles>
        <Swf is_homepage="true">HostSample.swf</Swf>
        <Swf discovery_module="DemoHostSample">HostSampleDiscovery.swf</Swf>
    </SwfFiles>
    

    The <Swf discovery_module="DemoHostSample">HostSampleDiscovery.swf</Swf> entry shows a discovery SWF being registered with the discovery module that was registered in the discovery metadata. This UI is launched when this discovery module is selected by the user in the Add Targets Manually page in the Cloud Control console.

8.25.3 Constructing the Guided Discovery User Interface

The guided discovery UI is built using the MPCUI features for constructing a Flex UI. The UI components, such as regions, buttons, tables, dialogs, and so on are used to construct a user interface to guide the user through the process of adding new targets to Enterprise Manager. For information about adding these UI components, see the relevant sections of this chapter, such as Section 8.16, "Defining Tables" or Section 8.17, "Defining Dialogs".

<?xml version="1.0" encoding="utf-8"?>
<mp:MpDiscoveryApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
                           xmlns:mp="http://www.oracle.com/mpcui"  
    backgroundColor="#EFF3F7" preloader="oracle.sysman.emx.MpPreloader" >
    <mx:Script>
        <![CDATA[      
            import discovery.DiscoveryInteg;
            override public function getIntegrationClass():Class 
                return discovery.DiscoveryInteg; }
        ]]>
    </mx:Script>    
</mp:MpDiscoveryApplication>

<mp:PageActivityDef id='discoHomePg' label='Discovery Console' pageClass='{discovery.DiscoveryTrainPage}' pageControllerClass='{discovery.DiscoveryTrainPageController}' isDefaultPage="true" />
<mp:TrainActivityDef id='discoTrain' label='Discover New Targets'>
    <mp:stepActivities>
        <mx:Array>
            <mp:TrainStepActivityDef id='selAgentsStep' shortLabel="Select Agents" label='Add Demo Host System Target: Select Agents' pageClass='{discovery.train.SelectAgentsStep}' pageControllerClass='{discovery.train.DiscoveryTrainStepController}'/>
            <mp:TrainStepActivityDef id='selHostSysStep' shortLabel="Select System" label='Add Demo Host System Target: Select Demo Host System' pageClass='{discovery.train.SelectHostSystemStep}' pageControllerClass='{discovery.train.DiscoveryTrainStepController}'/>
            <mp:TrainStepActivityDef id='selTargetsStep' shortLabel="Configure Targets" label='Add Demo Host System Target: Configure Targets' pageClass='{discovery.train.SelectTargetsStep}' pageControllerClass='{discovery.train.DiscoveryTrainStepController}'/>
            <mp:TrainStepActivityDef id='confTargetsStep' shortLabel="Confirm Changes" label='Add Demo Host System Target: Confirm Changes' pageClass='{discovery.train.ConfirmChangesStep}' pageControllerClass='{discovery.train.DiscoveryTrainStepController}'/>
            <mp:TrainStepActivityDef id='finTopo' shortLabel="Summary" label='Add Demo Host System Targets: Apply Changes' pageClass='{discovery.train.FinalizeTopoStep}' pageControllerClass='{discovery.train.DiscoveryTrainStepController}'/>
        </mx:Array>
    </mp:stepActivities>
</mp:TrainActivityDef>

8.25.4 Structure of the Discovery Application

The discovery application is often a single page that either has a train embedded in it, or that displays dialogs to obtain information from the end user to guide the discovery process. The steps of the guided discovery flow depends on the requirements, but often involve the following:

1. Determine on which Management Agents to run a discovery script

2. Run the discovery script

3. Process the results of the discovery script, adding additional information provided by the end user

4. Call APIs to add or delete targets

One important consideration about guided discovery is that it can be used to update the topology of existing composite targets as well as discover new targets. In the case of the sample plug-in (demo_hostsystem), the guided discovery UI allows the user to add new system targets, but also allows the user to add or remove members from an existing system.

This use case also illustrates the requirement to use Enterprise Manager APIs to query for the set of existing targets known to Enterprise Manager to compare the set with information returned from the discovery script to identify which targets are already managed by Enterprise Manager and which are not. For example, the result might be a list of new targets that should be added and a list of other targets that no longer exist in the managed configuration and must be removed from Enterprise Manager.

This scenario also illustrates that the discovery application might also be integrated with the custom UI built for the target home page. This provides the user with the ability to update the configuration of an existing composite target directly from the composite target home page.

See the HostSystemConfiguration page in the demo_hostsystem sample plug-in for an example of using discovery UI from within a target home page.

8.25.5 Using Discovery Service

The Discovery service is used to run a discovery script included with your plug-in. For a description of your plug-in requirements to support discovery, see Section 8.25.2, "Supporting Guided Discovery".

Example 8-49 (included in the demo_hostsystem sample plug-in in the DiscoveryTrainStepController) shows calling the discovery service (TargetFactory.discoverTargets). This service includes an addRequest method that can be called multiple times to process discovery on multiple Management Agents if required.

Each call to the addRequest method is passed the following along with the handler that will be called with the results of the discovery script:

• Request ID

  A unique identifier (assigned by you) associated with that particular request which will enable you to retrieve the specific results associated with that request.

• Agent

  the Management Agent Target that the discovery should be run against

• Plug-in ID

  The plug-in ID associated with the discovery to be run. A plug-in can include multiple discovery modules and categories.

• Discovery category

  The discovery category. This must map to a discovery script through an entry in the discover.lst file included in the agent part of the plug-in.

/**
 * when doing discovery, the service will accept multiple requests to be
 * processed at the same time.  this would typically be the case if multiple
 * agents were involved in the process, but could also be if different discovery
 * categories (scripts) were to be processed.
 *
 * the discovery request includes the following elements:
 *     requestId   a unique identifier associated with that particular request 
 *                 that will allow you to retrieve the specific results associated
 *                 with that request.
 *     agent       the agent Target that the discovery should be run against
 *     pluginId    the pluginId associated with the discovery to be run; a plug-in
 *                 can include multiple discovery modules and categories
 *     discCat     the discovery category; this must map to a discovery script via 
 *                 an entry in the discover.lst file included in the agent part of 
 *                 the plugin
 *     params      parameters that are to be passed to the discovery script
 * 
 * Note on discoveryModule - in addition to the pluginId, the discovery UI is 
 * passed the discovery module associated with this discovery pass.  If you've  
 * chosen to implement multiple types of discovery operations from a single 
 * discovery UI you may retrieve thediscoveryModule to determine in what context
 * the UI was launched.
 */

var requestId:String = "DiscReq1";
var pluginId:String = ApplicationContext.getPluginId();
var discoveryCategory:String = "DHSYSTEM_DISC";
discSvc.addRequest(requestId, agent, pluginId, discoveryCategory, params); 

TargetFactory.discoverTargets(discSvc, discoverResultsHandler);

The discovery results handler, declared as follows, is passed a fault object and the discovery results.

public function discoverResultsHandler(disc:Discovery, fault:ServiceFault):void

If a fault did not occur during processing of the discovery script, then the fault object will be null. The discovery object passed to the handler includes an Array of the DiscoveryRequest objects constructed by calling the addRequest method. Each request includes the properties specified (such as agent, category, and so on) and also includes a DiscoveredTargets object. The DiscoveredTargets object includes the list of targets returned from the discovery script that was run on the target Management Agent for the specified request. For more information about discovery scripts, see Section 11.3, "Creating the Discovery Script" and for information about the discovery objects returned by the DiscoveryService, see the API documentation in the EDK.

8.25.6 Using Target Information Services

During the discovery process it is often necessary to obtain target information such as a list of agents or the set of targets of a particular type. The target information service provides a number of APIs that can be used for such purposes. This section provides an overview of these services. For additional information, see the API documentation in the EDK and for examples of their use, see the demo_hostsystem sample plug-in.

• TargetFactory.getAgents

  The getAgents API enables you to retrieve a set of Management Agents that can be used to perform discovery. You can filter the list by specifying selection properties (Array of TargetProperty) such as selecting all the Management Agents running on a Windows host.

• TargetFactory.getTargets

  Use the getTargets API to retrieve a list of targets specifying any number of selection criteria including hosts, target types, managed status, or metadata version. Each item is specified as a list of possible values and the request can include one or more selection criteria.

• Target.getSystemMembers

  Use the getSystemMembers API to retrieve the list of system member targets. These are targets that are included in the system through the systemStencil. For information about the system targets, see the Oracle Enterprise Manager Cloud Control Extensibility Programmer's Guide:

  http://www.oracle.com/pls/em121/homepage
  

• Target.getCompositeMembers

  Use the getCompositeMembers API to retrieve the list of composite member targets. Composite members are those included in a composite (or system target) through containment associations. For information about composite targets, see the Oracle Enterprise Manager Cloud Control Extensibility Programmer's Guide:

  http://www.oracle.com/pls/em121/homepage
  

8.25.7 Using Target Management Services

The target management services provide you with the ability to create or delete targets or associations. In the case of target management, associations can also be passed as part of the target definition and the associations are added as part of the process of adding the target itself. This section provides an overview of these services. For additional information, see the API documentation in the EDK and for examples of their use, see the demo_hostsystem sample plug-in.

• TargetFactory.createTargets

  Use the createTargets API add targets to Enterprise Manager. The process of adding targets to Enterprise Manager forces the deployment of the necessary plug-in to the Management Agents associated with each target. The request to this API is a list of Target objects, each of which must, at a minimum, specify a name, type, and agent. Typically, target instance properties (if used for this target type) can also be specified.

• TargetFactory.deleteTargets

  Use the deleteTargets API to remove targets from Enterprise Manager. The request to this API is a list of Target objects. Removing a target from Enterprise Manager should be done with care as deleting the target is not reversible and it removes all target, metric, and configuration history.

• Target.createAssociations

  Use the createAssociations API to add associations between the specified target and another target. Associations can be created in this way when creating them by using derived associations or by using the system stencil. In all cases, the association must be associated with a corresponding allowed pairs definition. For more information, see Chapter 10, "Using Derived Associations".

• Target.deleteAssociations

  Use the deleteAssociations API to delete associations between the specified target and other targets.

8.26.1 Add Logging to your Code

Use the logging facility (MpLog) to log messages from your code.

While logging can be useful in situations where diagnostics are necessary, it has a cost in terms of code size and overhead. Therefore, use logging with care.

Perform logging by calling one of several MpLog methods (such as debug, info, error, or fatal). The methods accept a message string and an optional list of parameters that must be substituted.

To substitute parameters, indicate the parameter location using {#} format:

MpLog.debug("The metric {1} was not found for the target {2}.", metricName, targetName);

The message generated for this log statement appears in the following log output:

2011-04-22 11:10:17 [MpCui] DEBUG The metric CPU was not found for the target MYHOST

The level (info, debug, error, fatal) allows the user to enable log output for different classes of messages.

• By default, all error and fatal messages are sent to the log output location.

• The info and debug level messages are only sent if these levels are explicitly enabled.

Furthermore, you can direct the messages for each level to different output locations. There are three possible log locations:

• FLASHLOG: messages are sent to the Flash log (requires a debug Adobe Flash Player)

• EMLOG: messages are sent to the Enterprise Manager application logs

• CONSOLE: messages are sent to a small window displayed at the bottom of the MPCUI display

8.26.2 Options for Capturing Log Output

The options for capturing log output depend on your implementation:

• Running MPCUI From Adobe Flash Builder

• Running MPCUI from Enterprise Manager Console

8.26.2.2 Running MPCUI from Enterprise Manager Console

After the plug-in is deployed, the settings for logging are detected from the HTTP request. The default setting is FATAL,FLASHLOG;ERROR,FLASHLOG.

The end user can modify the settings as follows:

1. Append the following to the URL in the address bar of the browser:

   &loglevel=ALL,FLASHLOG
   

2. You can substitute ALL,FLASHLOG with any valid logging settings, such as ERROR,CONSOLE and so on.

3. For diagnostic situations, add the following to the end of the URL:

   &loglevel=ALL,CONSOLE
   

4. Refresh the page to see the page and all log messages in the console window similar to Figure 8-28

Figure 8-28 Viewing Log Messages

Description of "Figure 8-28 Viewing Log Messages"

8.27.1 Developing MPCUI with Flex SDK and Apache Ant

If Flex Builder is not available, then install Adobe Flex SDK and use Ant to build the SWF file for your plug-in as follows:

1. Download and install Apache Ant from the following website:

   http://ant.apache.org
   

   1. Set the ANT_HOME environment variable to the location where Apache Ant is installed.

   2. Include $ANT_HOME\bin in the PATH environment variable of your command shell.

   3. Set the ANT_OPTS environment variable to -Xmx512m.

2. Download and install Flex SDK version 3.5:

   • Download the Flex SDK 3.5 ZIP file from the following website:

     http://download.macromedia.com/pub/flex/sdk/flex_sdk_3.5.zip
     

   • Download the Flex 3.5 Data Virtualization Components for Flex Builder ZIP file from the following website:

     http://download.macromedia.com/pub/flex/sdk/datavisualization_sdk3.5.zip
     

   • Download the Flex 3.5 Automation Libraries for Flex Builder ZIP file from the following website:

     http://download.macromedia.com/pub/flex/sdk/automation_sdk3.5.zip
     

     Note:

     When you are adding the automation libraries to the SDK directory, they must be expanded into the FLEX_HOME/frameworks directory, and not in the FLEX_HOME directory.

3. Edit the demo_hostsample\mpcui\build.xml file.

   Update the FLEX_HOME property so location points to the location of the Flex SDK installation.

4. Build the HostSample.swf file:

   1. cd demo_hostsample\mpcui

   2. ant

      Entering this command builds the demo_hostsample\mpcui\bin-debug\HostSample.swf file.

8.27.2 Developing MPCUI in Adobe Flash or Flex Builder

This section describes the process to follow when building a Flex application using the MPCUI libraries and Adobe Flash Builder. These steps assume the use of the sample application provided with the EDK referred to as the Demo Host Sample (or demo_hostsample). As with many development activities it is often easiest to start with a working example to understand how the provided APIs work and how to use them to accomplish higher-level use cases.

To simplify the process for developing your custom UI, build and run the Flex application from Adobe Flash Builder without having to redeploy the plug-in to Enterprise Manager after each change. When running from Adobe Flash Builder, your UI will not have access to the other Enterprise Manager features and pages available to the console, but you will be able to exercise your UI to ensure that it is functioning correctly before deploying it as part of your plug-in.

demo_hostsample
    html-template/data/demo_hostsample_menu.xml           
    mpcui/src
          HostSample.mxml            The application definition, must extend 
                                     MpApplication and implement the single 
                                     method "getIntegrationClass"
          HostSampleInteg.mxml       The integration class, defines the set of
                                     pages, dialogs, trains, etc. that make up
                                     the application
          HomePage.mxml              The target homepage, contains the layout of
                                     the UI for the homepage
          HomePageController.as      The controller for the HomePage, includes 
                                     the methods that load data for the page
                                     and respond to events from the page
          ProcessesPage.mxml
          ProcessesPageController.as
          CredentialsPage.mxml
          CredentialsPageController.as
          AvailabilityDialog.mxml
          MetricHistoryDialog.mxml

8.27.3 Setting Up an Adobe Flash Builder Project for MPCUI

This section assumes you are using Adobe Flash Builder 4.5 but includes notes for Adobe Flash Builder 3 users.

To set up an Adobe Flash Builder project, you can create an empty project or import the demo_hostsample project in to Adobe Flash Builder to use as a template. If you are importing the demo_hostsample project, then compete the steps in Section 8.27.3.1, "Before You Begin". Otherwise, proceed to Section 8.27.3.2, "Creating an Adobe Flash Builder Project".

8.29.1 Accessibility Options in Enterprise Manager

Enterprise Manager provides the end user with the ability to set options for accessibility including a screenreader option. The MPCUI framework is aware of these settings and makes them available to you in your Flex code (see the oracle.sysman.emx.util.AdaSettings in the API reference).

Typically you do not have to check for these settings because MPCUI automatically renders accessible components when the end user sets their account to require an accessible user interface. Among other things, this replaces charts with an accessible view of the same data.

8.29.2 Summary of Critical Issues

When constructing an accessible MPCUI Flex application, consider the following items:

• Enable accessibility

  Add the accessible flag to the compiler settings.

  For more information, see the Adobe Best Practices and the settings in the demo_hostsample example plug-in

• Use MPCUI Pages, dialog and components

  These components include accessibility support.

  For more information, see Section 8.29.3, "Using MPCUI Components".

• Set Tab Order of Components

  Sets the reading and tab order for all components.

  For more information, see Section 8.29.4, "Controlling Reading and Tabbing Order".

• Set Name and Description

  For components that require additional text description (such as images).

  For more information, see Adobe Best Practices.

• Avoid the use of or provide accessible equivalents for drag-and-drop, audio, and decorative content.

  For more information, see Adobe Best Practices.

• Avoid conveying information using color

  For more information, see Adobe Best Practices.

• Do not add menus to the Flex Application.

  Use the Enterprise Manager Target menu.

  For more information see this guide.

• Avoid using non-accessible Flex components

  For a list of accessible components, see Adobe Best Practices.

8.29.3 Using MPCUI Components

Because the MPCUI framework provides components that include accessibility support beyond the base Flex components, use the MPCUI version of those components. In addition to the specific components listed in Table 8-2, the application should include only MPCUI top-level activities such as Page, Dialog, or Train. Implement your application based on the MpApplication base class. Table 8-2 provides a list of important components included in the MPCUI framework:

8.29.4 Controlling Reading and Tabbing Order

While Flex provides support for determining the reading and tabbing order of components included in the application, it does not work well for complex layouts that include multiple regions and pages. To ensure that the application provides a tab order that make sense, set the order within each page or dialog.

The MPCUI framework provides a means of setting the tab order. Use this method instead of setting the tabIndex of each property. Do not set the tabIndex of the components included in your pages, but use the tabOrder property of the page or dialog.

To use the tabOrder property, you must assign a unique ID to every component included in the Page. All Flex and MPCUI components support the id property. Example 8-51 shows a Page declaration that includes the tabOrder property.

<mp:Page label="Home Page" 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:mp="http://www.oracle.com/mpcui"    
    tabOrder="{[ summaryRegion, statusRegion, currentStatus, statusSince, availability, 
            configurationRegion, cpuModel, cpuPer, currentLoad, osVersion, relatedHost, 
            installedSoftware, jobSummary, 
            reportsRegion, allReports, hostPerfReport, 
            currentLoadRegion, cpuLoadRegion, cpuload, showCpuHistory,
            processSummaryRegion, numUsers, numProcesses,
            resourcesRegion, cpuUtilRegion, cpuutil, 
            processorRegion, processorChart, showProcessorHistory,
            memoryRegion, selMemChart, memChart,
            eventsRegion
            ]}"  
    defaultComponent="{currentStatus}"
    >

    <!-- First Column, 25% width of page, two regions stacked vertically -->
    <mx:HBox width="100%" height="100%">
        <mx:VBox width="25%" height="100%" > 
            <mp:Region id="summaryRegion" title="Summary" height="50%" width="100%" >
                <mp:InnerRegion id="statusRegion" title="Status" height="40%" width="100%" >
                    <mp:InfoDisplay width="100%" height="100%">
                        <!-- reference to the AvailDataService -->
                        <mp:InfoItem id="currentStatus" label="Current Status" value="{ads.currentStatus}" image="{ads.currentStatusIcon}" 
                            click="invokeActivity(Constants.PAGE_AVAILABILITY, bean(Constants.P_TARGET_NAME, appModel.target.name, 
                            Constants.P_TARGET_TYPE, appModel.target.type));" /> 
                        <mp:InfoItem id="statusSince" source="{ads.statusSinceItem}"  />                                    
                        <mp:InfoItem id="availability" label="Availability %" value="{NumberFormat.formatNumber(ads.availPercent,1)}%" destination="availDialog" />                                     
                    </mp:InfoDisplay>
                </mp:InnerRegion>

The tabOrder property is an array of the component ids included in the page that must be included in the tabbing or reading order.

For more information, see the demo_hostsample sample application and the API reference document.