Maximo 7.x Launch In Context Guidelines

Launch in Context 1

Launch In Context Guidelines

Launch in Context 2

1 Introduction __________________________________________________________________3

1.1 Disclaimer _____________________________________________________________________ 3

1.2 Abbreviations Used Throughout This Document______________________________________ 3

1.3 Types of OMP Integration ________________________________________________________ 3

2 Launch in Context _____________________________________________________________4

2.1 Preparing the External Application_________________________________________________ 4

2.2 Defining the Launch Entry________________________________________________________ 5

2.3 Associating a Launch Entry with a Sigoption_________________________________________ 5

2.4 Associating a Sigoption with a Menu Item ___________________________________________ 8

2.5 Associating a Condition with a Sigoption ___________________________________________ 12

2.6 URL Processing Information _____________________________________________________ 14

Launch in Context 3

1 Introduction This document provides guidelines for PMP development specific to Operational Management Product (OMP) integration using Launch in Context. A general understanding of Maximo, MBOs and the Maximo Integration Framework is required. Descriptions of Maximo components mentioned in this document can be found in the IBM Tivoli Change and Configuration Management Database Release 7.1 Integration Guide.

1.1 Disclaimer No Warranty SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED, IBM MAKES NO

WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,

THE IMPLIED WARRANTIES OR CONDITIONS OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT,

REGARDING THE SAMPLE CODE INCLUDED IN THIS DOCUMENT. IBM DOES NOT PROVIDE ANY

TECHNICAL SUPPORT FOR THIS SAMPLE CODE.

1.2 Abbreviations Used Throughout This Document

CI – Configuration Item GUID – Globally Unique IDentifier ITIC – IBM Tivoli Integration Composer LIC – Launch in Context MBO – Maximo Business Object MEA – Maximo Enterprise Adapter framework OMP – Operational Management Product PMP – Process Manager Product Sigoption – Signature Option (Maximo access rights) TADDM – Tivoli Application Discovery and Dependency Manager UI – User Interface

1.3 Types of OMP Integration

OMP Integration from an application can be implemented in multiple ways: 1. LIC – Launch in Context – A Process Manager (PMP) application can be configured to invoke

a Launch Entry that will open an OMP application window and pass data such as CI information.

2. IM – Integration Module – A Process Manager (PMP) application/escalation/workflow can be configured or coded to call an Integration Module which will then invoke an OMP-provided service. This invocation can be implemented totally as a background process (no user interaction) via a WorkFlow or Escalation process. It may also be initiated from the UI by a user via a Pushbutton or Menu Action. In either case, the service invocation may provide a response that can be processed by the PMP.

Launch in Context 4

2 Launch in Context The Launch in Context (LIC) framework lets you launch an external application’s user interface, passing the context of the source application to the target application. To set up a Launch in Context, you must:

1. Prepare the external application 2. Define a Launch Entry 3. Associate a Launch Entry with a Sigoption 4. Associate the Sigoption with a UI Control 5. Associate a Condition with the Sigoption to restrict Launch Entry visibility based on the

application data (optional) LIC is not intended to be used as a way to launch from one Maximo application to another Maximo application. The Maximo UI framework provides capabilities to support this. Note: the current design does not support returning any information from the launched application to the original application.

2.1 Preparing the External Application

Many external applications will already have a web-based console that you can launch using a URL in a web browser. The console may be a Servlet, a Portal, or a Java WebStart console. These are the types of consoles supported by Maximo’s LIC framework. To handle a full Launch in Context, the external application’s console must have the ability to “land in context”, meaning that you can pass data on the URL of the console that tells the console what screen to show. For example, the TADDM web console lets you pass the name of a view and the GUID of a CI to show in that view. If the external application does not have a “land in context” feature, you will either need to add one, or simply launch to some standard start page within that console. You will need to understand the format of the external console’s URL and the data it needs to “land in context” so you can create your Launch in Context Console URL within Maximo. Ideally the external application will also support Single Sign-On. For example, if you configure your Maximo and TADDM servers correctly, users can launch the TADDM web console from Maximo without having to log in again. When running Maximo from within the WebSphere Application Server (WAS), it is not difficult to enable Single Sign-On with any other application that is also running within WAS, using LTPA tokens. That setup is beyond the scope of this document; it is covered in the WebSphere Application Server documentation. (Search the WAS InfoCenter for “Single Sign-On.”) If the external application does not support Single Sign-On, the user will usually have to log in again the first time they launch the external console. Normally the user’s web browser stores authentication information after that initial login, so he or she does not need to log in repeatedly when doing multiple launches.

Launch in Context 5

2.2 Defining the Launch Entry

Maximo includes a Launch in Context application to support the entry and maintenance of Launch Entries. A Launch Entry can also be created via XML using the MEA-provided object structure (MXLAUNCH) that supports inserting/updating/querying of Launch Entries. Defining the Launch Entry includes identifying the Launch Entry’s Name, URL, OMP product/version and target window. The OMP product and version identify if the launch is specific to a specific OMP product name and version. The URL can include substitution variables. The target window identifies whether the launch will occur within a new browser window or within the current browser. Additionally, a Launch Entry can include Launch Context properties that limit its usage to certain applications and content.

• A Launch Entry can be assigned one or more context Resource Objects (MBOs) that will limit the Launch Entry’s usage to applications that support the same objects. This restriction is implemented at the time a Launch Entry is associated with a UI control using the Application Designer. The Application Designer application will limit the selection of the Launch Entry based on the MBO that is associated with the Application and the MBO(s) in the Launch Context list of the Launch Entry.

• A Launch Entry’s usage can also be limited by the Resource Classification of the data being processed. Multiple objects within Maximo support the Classification attribute. For those objects that have this attribute, the Classification value in the Launch Context can be used to limit the display of the Launch Entry. For example, if a Launch Entry tied to the CI application had a Launch Context with a Classification value of ‘Computer System’, then within the CI application, the Launch Entry would appear only for those CIs where the classification value equals ‘Computer System’. For CIs that do not have this classification value, the Launch Entry would not be visible on the UI. This restriction is implemented by using a Maximo Condition Java class. Out of the box Conditions have been provided to support this functionality. See “Associating a Condition with a Sigoption” for more details.

2.3 Associating a Launch Entry with a Sigoption

After a Launch Entry is created, it needs to be assigned to a Maximo Application and a Sigoption so it will surface within the Application.

Launch in Context 6

Do this by using the Application Designer under the Configuration menu. Within the Application Designer do the following:

1. Find the application you need to add your Launch Entry to, and select it. Be sure you are on the Workspace tab

2. From the Select Action menu, pick Add/Modify Signature Options.

3. In the Add/Modify Signature Options dialog, click New Row. 4. Name your option (ie.VPHYSTOPO ) and give it a description. This description is what the

users will see in the menu.

Launch in Context 7

5. Maximize the Advanced Signature Options section. 6. In the Advanced Signature Options section, check the radio button "Associate to launch entry

to enable launch in context".

Launch in Context 8

7. Click the magnifying glass next to the Launch Entry Name field, and select the entry name you created in the Launch Entry application. Click the OK button.

8. Click OK in the Add/Modify Signature Options dialog, 9. Save your changes in the Application Designer.

2.4 Associating a Sigoption with a UI Control

10. Stay in the Application Designer. From the Select Action menu, pick Add/Modify Select Action Menu.

11. Click New Row, and fill in: a. Element Type: OPTION b. Key Value: Enter the Sigoption name, such as VPHYSTOPO. c. Header Description (optional): Enter a description of the UI control. d. Position: Enter the relative position of the new menu item in the Select Action menu.

Menu items with lower position numbers display above those with higher position numbers.

Launch in Context 9

e. Subposition: Enter 0 for a first level menu, or a value greater than 0 for a second-level menu item.

f. Visible: Leave this checked. g. Tabs: Select MAIN, unless the Launch Entry does not need any variables from the

MBO, in which case you can select ALL to display it on all tabs. h. (You can also fill in image and access key, but they are optional.)

12. Click on OK, then Save the application in the Application Designer.

If you want a toolbar button instead/in addition to the drop down action menu, repeat (4) but pick Add/Modify Toolbar Menu in step 10 instead.

13. Go to the Security > Security Groups application to give users access to the new Launch Entry.

Launch in Context 10

14. Select a user group that should have access to the Launch Entry UI control. Pick EVERYONE if everyone should have access to it. If you want to give access to multiple groups, you will need to repeat this process for each of the groups.

15. Go to the Applications tab. 16. Select the application you want to modify in the upper table. (You can expand the table filter

and use it to find what you need.) 17. Find the option (such as VPHYSTOPO) in the lowest table. (You can use the filter from the

table header here too.) 18. Check Grant Access next to the option.


19. Click Grant Listed Options for This Application, confirm in the popup, and Save your changes

in the Security Groups application.

20. Sign Out from Maximo and exit your browser window. (Changes will not be seen until you sign in using a new browser window.)

21. Sign In as a user that is member of the group that has been given access. 22. Go to the application you modified and verify that the menu item works.


2.5 Associating a Condition with a Sigoption

A Maximo Condition Class is provided to hide Launch Entry menu items if the Launch Entry is configured such that:

1. the current MBO’s classification does not have a match with the Launch Entry’s Classification value (this applies to any MBO that has a Classification attribute)

2. the CI does not have a relationship to the OMP configured on the Launch Entry (this applies to Launch Entries that are tied to the CI or ACTCI MBOs

3. the Console URL requires a CI GUID or an OMP relationship (because it includes one of these tags: {ciguid}, {sourcetoken}, or {reportinghostname}), and the current MBO does not have a CI GUID or an OMP associated with it.

The condition class provided is: psdi.iface.app.launch.LaunchCICondition. It is already in the application server’s class path, so you don’t need to do anything special to use it. NOTE: Due to a current design limitation, when this class file is used for a Conditional Expression, a manual SQL update of the condition is required to set the Condition’s ‘Expression’ attribute equal to the name of the Launch Entry (values are case sensitive). The intent is to correct this limitation in a future release or patch. An example of this SQL script is in the “Sample Database Scripts” section of this document. (See “Create a Conditional Expression for a Sigoption.”) Below is an example of a TADDM Launch Entry Conditional Expression defined in the Conditional Expression Manager application. The “Expression” attribute is read-only in the application, so we set that value to the name of the Launch Entry using an SQL script. You can set the rest of the Conditional Expression’s attributes using this application. As an alternative to the Java class, you can set the Conditional Expression Type to “EXPRESSION” and enter an SQL expression in the Expression field. The Expression field is editable when you set the Type to “EXPRESSION.” If the SQL expression evaluates to “true” at runtime, the Launch Entry will be displayed; otherwise the security framework will hide it.


To associate the Conditional Expression to the Sigoption, go to the Security Groups application and select the appropriate Group and then move to the Application tab and select the application. At the bottom of the window is the list of Sigoptions for the application. Choose the applicable Sigoption, and click on the Go To menu arrow to assign a Conditional Expression to it. If you need to create the Conditional Expression, you can choose “Go To Conditional Expression Manager,” create the new Conditional Expression there, and select “Return With Value” at the top of the screen. Otherwise, you can choose “Select Value” to select an existing Conditional Expression, as shown below. There are many Conditional Expressions out of the box, so you will probably need to use the filter fields to search for yours, as shown below. Click on the Save button in the Security Groups application after you select your Conditional Expression.


2.6 URL Processing Information

The Console URL can include any MBO attribute from the application’s MBO using the format ‘{mbo attribute}’. If your application has a value in a child MBO (in relation to the application MBO), you can include that value in your URL in one of two ways:

1. Create a non-persistent attribute on the application MBO and copy the value from the child to the application MBO in your application code. Then use the non-persistent attribute name in your URL.

2. Create a relationship (maxrelationship) between the parent and child MBO, and reference the relationship name in the URL, as in ‘{relationship name.child attribute}’.

Below is a URL example with two MBO attribute substitutions: https://{PMRELOMPRLN.HOSTNAME}:9045/tcWebUI/interaction-handler?actionId=viewId&objectId={OMPDEPLOYMENTID}

The Integration framework provides OMP-specific logic only when the Launch Entry has an OMP name configured, and the application MBO has a value in its CIGUID attribute. The OMP-specific logic can perform the following substitutions in the Console URL:

1. {reportinghostname}: If this value is in the Console URL, the Integration framework will find an OMP/CI relationship for the given CIGUID, where the OMP has the same product name and version as the one configured in the Launch Entry. Then it will retrieve the hostname of that OMP server and fill it in as the reporting hostname.

2. {sourcetoken}: If this value is in the Console URL, the Integration framework will find an OMP/CI relationship for the given CIGUID, where the OMP has the same product name and version as the one configured in the Launch Entry. Then it will retrieve the sourcetoken attribute from that relationship and fill it in as the source token.

NOTE: the CIGUID attribute must be part of the main application MBO (not a child MBO) for

reporting hostname or source token substitution. If needed, you can copy the CIGUID from the child

MBO to the main MBO in your application code. Also, in the Actual CI MBO (ACTCI), the CIGUID

attribute is replaced by the GUID attribute, but the substitutions work the same way.

If the logic to retrieve the reporting hostname or source token for the CI/OMP combination retrieves multiple records, a dialog will pop up, and the user will have to select the specific OMP server before launching the application. This will occur when a CI is managed by multiple OMPs. There is no support for returning values from the launched application to the Maximo application where the launch was initiated.

2.7 Using the MXLAUNCH Object Structure and XML Import

2.7.1 Sample XML

<?xml version="1.0" encoding="UTF-8"?>


<SyncMXLAUNCH xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.ibm.com/maximo">

<MXLAUNCHSet>

<MAXLAUNCHENTRY>

<CHANGEBY>amfred</CHANGEBY>

<CONSOLEURL>http://$taddmWebLaunchHostname$:$taddmWebLaunchPort$/cdm/servlet/LICSe

rvlet?default.port=$taddmServerPort$&default.server=$taddmServerHostname$&

graph=physicalinfrastructure&guid={guid}</CONSOLEURL>

<DISPLAYNAME>Actual CI - View Physical Topology</DISPLAYNAME>

<LAUNCHENTRYNAME>TADDM PHYSICAL VIEW</LAUNCHENTRYNAME>

<TARGETWINDOW>TADDM</TARGETWINDOW>

<MAXLECONTEXT>

<CHANGEBY>amfred</CHANGEBY>

<INCLUDECHILDCLASS>0</INCLUDECHILDCLASS>

<RESOURCECLASS></RESOURCECLASS>

<RESOURCETYPE>ACTCI</RESOURCETYPE>

</MAXLECONTEXT>

</MAXLAUNCHENTRY>

</MXLAUNCHSet>

</SyncMXLAUNCH>

In this sample XML, you can see that we are creating one MAXLAUNCHENTRY (a Launch Entry) and one child MAXLECONTEXT (a Launch Context assigned to the Launch Entry). We have provided the Console URL, Display Name, Launch Entry Name, and Target Window for the Launch Entry. For the Launch Context, we set “Include Child Classifications” to 0, meaning false. Resourceclass is blank, meaning that we don’t care with the MBO’s classification is. Resourcetype is ACTCI, meaning that this Launch Entry should be used with applications where the main MBO is ACTCI. (The Actual CI application uses the ACTCI MBO.) Our installer substitutes the values between dollar signs, like $taddmWebLaunchHostname$, with their actual values before we import the XML, so by the time you start using Maximo, those values have already been updated. The values in curly braces, like {guid}, are filled in at runtime. See the URL Processing Information section for details.

2.7.2 Importing the XML

You can import these MXLAUNCH XML files from the Maximo UI. To do this, you create an Enterprise Service and use the Data Import feature. The IBM Tivoli Change and Configuration Management Database Release 7.1 Integration Guide explains how to do this in the chapters entitled “Creating Adapters, Services, and Channels” and “Synchronous Inbound Integration Processing.” Details about how the XML files are formatted are in the “Integration XML Content” and “Integration Schemas” chapters.


2.8 Sample Database Scripts

Here are some examples of DB2 scripts that may be useful, especially if you need to understand which Maximo database tables are updated. Use the Maximo UI to do your configuration wherever possible, to avoid errors. These scripts are based on the Release 7.1.0 code, and the tables may change slightly over time.

1. Create a Launch Entry named “TADDM PHYSICAL VIEW”. The English (EN) description is “Actual CI – View Physical Topology”. Portnumber is not used in this release. This is a Console URL the for TADDM application, so it launches into the browser target window named “TADDM”. It does not require that the CI be associated with any OMP servers. (TADDM does not count as an OMP server.) insert into maxlaunchentry ( maxlaunchentryid, launchentryname, displayname, langcode, hasld, portnumber, consoleurl, targetwindow, ompproductname, ompversion, changeby, changedate, rowstamp) values (MAXLAUNCHENTRYSEQ.nextval, 'TADDM PHYSICAL VIEW', Actual CI - View Physical Topology ', 'EN', 0, null, 'http://$taddmWebLaunchHostname$:$taddmWebLaunchPort$/cdm/servlet/LICServlet?default.port=$taddmServerPort$&default.server=$taddmServerHostname$&graph=physicalinfrastructure&guid={guid}', 'TADDM', null, null, 'MAXIMO', sysdate, maxseq.nextval);

2. Add a Launch Context (the ACTCI MBO) to a Launch Entry insert into maxlecontext ( maxlecontextid, launchentryname, resourcetype, resourceclass, changeby, changedate, includechildclass, rowstamp) values (MAXLECONTEXTSEQ.nextval, 'TADDM PHYSICAL VIEW', 'ACTCI', null, 'MAXIMO', sysdate, 0, maxseq.nextval);

3. Create a Sigoption (VPHYSTOPO) for a Launch Entry (2 insert statements: 1 to create the sigoption and one to assign it to a Launch Entry using a sigoptflag) insert into sigoption (app, optionname, description, esigenabled, visible, alsogrants, alsorevokes, prerequisite, sigoptionid, langcode, hasld, rowstamp) values ('ACTUALCI', 'VPHYSTOPO', 'Physical', 0, 1, null, null, null, SIGOPTIONSEQ.nextval, 'EN', 0, maxseq.nextval); insert into sigoptflag (sigoptflagid, optionname, app, flagname, value, rowstamp) values (SIGOPTFLAGSEQ.nextval, 'VPHYSTOPO', 'ACTUALCI', 'LAUNCHENTRY', 'TADDM PHYSICAL VIEW', maxseq.nextval);

4. Create a Select Action Menu Item on the MAIN tab for a the VPHYSTOPO Sigoption insert into maxmenu (menutype, moduleapp, position, subposition, elementtype, keyvalue, headerdescription, url, visible, image, accesskey, tabdisplay, maxmenuid, rowstamp) values


('APPMENU', 'ACTUALCI', 410, 3, 'OPTION', 'VPHYSTOPO', null, null, 1, null, null, 'MAIN', MAXMENUSEQ.nextval, maxseq.nextval);

5. Create a Conditional Expression for a Sigoption a. Create an SQL Conditional Expression (VACTCINUM) for the Launch Entry named

“TADDM PHYSICAL VIEW” insert into condition (conditionid, conditionnum, type, expression, classname, description, rowstamp) values (CONDITIONSEQ.nextval, 'VACTCINUM', 'EXPRESSION', 'actcinum is not null', null, 'Condition for the TADDM Physical Topology View', maxseq.nextval);

b. Create a Java Class Conditional Expression (TADDMPHYS) for the Launch Entry named “TADDM PHYSICAL VIEW” insert into condition (conditionid, conditionnum, type, expression, classname, description, rowstamp) values (CONDITIONSEQ.nextval, 'TADDMPHYS', 'CLASS', 'TADDM PHYSICAL VIEW', 'psdi.iface.app.launch.LaunchCICondition', 'Condition for the TADDM Physical Topology View', maxseq.nextval);

c. Add a Conditional Expression (TADDMPHYS) for a Sigoption (VPHYSTOPO) in the ACTUALCI application. Also give the security group SYSADMIN access to the UI controls (menu items, buttons, etc.) that are associated with the sigoption. insert into applicationauth (groupname, app, optionname, applicationauthid, conditionnum, rowstamp) values ('SYSADMIN', 'ACTUALCI', 'VPHYSTOPO', APPLICATIONAUTHSEQ.nextval, 'TADDMPHYS', maxseq.nextval);

6. Update the credential mapper classname to psdi.iface.omp.TestCredentialMapper update maxpropvalue set propvalue='psdi.iface.omp.TestCredentialMapper' where propname='mxe.int.credentialmapperclassname' and servername='COMMON';

Maximo 7.x Launch In Context Guidelines

Software

Transcript of Maximo 7.x Launch In Context Guidelines