Tivoli Service Automation Manager V7.2.4 Extensions Guide

Transcript

Tivoli Service Automation Manager Version 7.2.4 Extensions Guide
 SC34-2658-04 Tivoli Service Automation Manager Version 7.2.4 Extensions Guide
 SC34-2658-04 Note Before using this information and the product it supports, read the information in “Notices” on page 281. Edition notice This edition applies to IBM Tivoli Service Automation Manager Version 7 Release 2 Modification Level 4 (program number 5724–W78), available as a licensed program product, and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC34-2658-03 and any previous versions. Order publications through your IBM representative or the IBM branch office serving your area. Publications are not stocked at the addresses given below. Address comments on this publication to: IBM Deutschland Research and Development GmbH IBM Systems and Technology Group Systems Software Development Dept. 2705, Bldg. 71032-16 Schoenaicher Str. 220 71032 Boeblingen Germany FAX (Germany): 07031 16 4240 FAX (other countries): (+49) 7031 16 4240 Make sure to include the following in your comment or note: v Title and order number of this book v Page number or topic related to your comment When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright IBM Corporation 2011, 2013. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Tables . . . . . . . . . . . . . . . ix Preface . . . . . . . . . . . . . . . xi Who should read this information . . . . . . . xi Support information . . . . . . . . . . . xii Getting technical training. . . . . . . . . xii Searching knowledge bases . . . . . . . . xii Searching the Internet . . . . . . . . . xii Using IBM Support Assistant . . . . . . xii Finding product fixes . . . . . . . . . xiii Getting email notification of product fixes xiii Contacting IBM Software Support . . . . . xiii Setting up a software maintenance contract xiv Determine the business impact . . . . . xiv Describe the problem and gather background information . . . . . . . . . . . . xv Submit the problem to IBM Software Support xv Chapter 1. Overview . . . . . . . . . 1 Chapter 2. Main concepts of Tivoli Service Automation Manager. . . . . . 3 Tivoli Service Automation model . . . . . . Tivoli Service Automation Templates and instances Tivoli Service Automation Manager structural service . . . . . . . . . . Manager process model . . . . . . . . . . . Manager services for users 3 4 5 5 Chapter 3. Describing a Tivoli Service Automation Manager solution . . . . . 7 Tivoli Service Request Manager extension points . Self-service extension points . . . . . . . . Maximo Enterprise Adapter and REST extension points . . . . . . . . . . . . . . . . 8 . 8 . 9 Chapter 4. Self-service user interface extension points . . . . . . . . . . 11 Extending the self-service user interface . . . . . Merging offerings with multiple extensions . . . Setting up your development environment . . . Setting up Eclipse IDE . . . . . . . . . Verifying Eclipse installation and importing the projects . . . . . . . . . . . Installing Eclipse and importing the projects . . . . . . . . . . . . . Configuring the build environment . . . . Setting up quickdeploy with public key authentication . . . . . . . . . . Setting up quickdeploy with password authentication . . . . . . . . . . Writing an extension for branding . . . . . . Modifying the branding of the logon screen Loading a customized CSS sheet for the logon screen . . . . . . . . . . . © Copyright IBM Corp. 2011, 2013 11 12 12 12 13 13 14 14 16 17 17 18 Changing the logon screen image . . . . Changing the logon screen heading . . . Changing the logon screen brand logo . . Modifying the branding of the main screen . . Loading a customized CSS sheet for the main screen . . . . . . . . . . . Modifying the main screen heading text . . Modifying the main screen brand logo . . Modifying the branding of offerings . . . . Extending the offering panels . . . . . . . Changing widget values . . . . . . . . Setting default values . . . . . . . . Hiding and showing widgets . . . . . . Hiding widgets . . . . . . . . . . Hiding groups of widgets . . . . . . Making widgets read only . . . . . . Adding widgets and event handlers . . . . Adding custom widgets . . . . . . . Adding custom event handlers . . . . . External HTML file content . . . . . . Employing REST calls in the extensions . . . Example REST queries. . . . . . . . Using REST queries in widgets . . . . . Extending the wizard offerings . . . . . . . Changing the appearance of a wizard page . . Setting the title of a wizard page . . . . Setting the description of a wizard page . . Hiding and showing widgets on a wizard page . . . . . . . . . . . . . . Changing widget values on a wizard page . . Setting default values for widgets on a wizard page . . . . . . . . . . . Adding custom widgets and event handlers to a wizard page . . . . . . . . . . . Adding custom widgets to a wizard page Adding custom event handlers on a wizard page . . . . . . . . . . . . . . Making REST calls on a wizard page . . . Validating a wizard page before further navigation . . . . . . . . . . . . Setting a wizard page as optional . . . . . Adding a page in the wizard . . . . . . Removing a page from the wizard. . . . . Globalizing extensions . . . . . . . . . . Testing and deploying extensions . . . . . . Testing your extension: quickdeploy . . . . Removing your extension. . . . . . . . Running quickundeploy . . . . . . . Disabling your extension manually . . . Deploying your extension: rebuild and deploy Rebuilding custom_web.war . . . . . . Deploying custom_web.war . . . . . . Migrating and upgrading your extensions . . . Migrating your extension . . . . . . . . Upgrading Tivoli Service Automation Manager with an installed extension . . . . 18 19 20 21 21 22 22 23 24 25 26 26 27 28 28 29 30 31 32 34 34 37 38 39 40 40 41 43 44 44 45 46 47 47 48 48 49 50 51 52 53 53 54 54 55 55 56 57 57 iii API reference for the self-service user interface Global API functions . . . . . . . . Add Server to Project . . . . . . . . Create Project with Server . . . . . . Create Project from Saved Image . . . . Modify Server Resources . . . . . . . Modify Reservation. . . . . . . . . Register Image . . . . . . . . . . Other API capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . 58 58 62 69 76 78 80 81 85 Chapter 5. Defining services in Tivoli Service Automation Manager . . . . . 87 Working with service definitions . . . . . . . 87 Creating a service definition . . . . . . . . 87 Creating a service definition from an existing service definition . . . . . . . . . . . 88 Changing the status of an existing service definition . . . . . . . . . . . . . . 89 Defining the data model - the topology of a service 89 Creating a service topology model for a new service definition . . . . . . . . . . . 89 Defining a service topology node type . . . . 90 Adding nodes to a service topology model . . . 91 Using topology nodes with variable cardinality . . . . . . . . . . . . . 92 Setting default cardinality for a variable service topology node . . . . . . . . . 93 Configuring cardinality definition for a variable service topology node . . . . . . 93 Configuring selection for a variable service topology node . . . . . . . . . . . 94 Adding an attribute to a service topology node 94 Using the auto-numbering feature for service topology node attributes . . . . . . . . 95 Defining management plans of a service. . . . . 95 Creating a management plan from advanced workflows . . . . . . . . . . . . . . 96 Introducing advanced workflow nodes . . . 96 Defining the advanced workflow . . . . . 97 Defining the management plan in the service definition . . . . . . . . . . . . . 98 Extending a management plan using extension nodes . . . . . . . . . . . . . . . 98 Creating a workflow with an extension node 99 Adding extensions to workflows . . . . . 99 Consuming data from the topology in management plans . . . . . . . . . . 100 Defining the iteration of a task node. . . . 100 Providing the data context . . . . . . . 101 Mapping data into the input container 102 Mapping data from the output container 104 Data mapping expression language . . . 104 Error handling in management plans . . . 107 Structure and syntax of error handling rules 108 Removing error handling rules . . . . . 109 Starting management plans from other services 110 Generic subworkflow reference . . . . . . 114 The PMRDPAPPSR approval process . . . 114 Scheduler workflows . . . . . . . . . 114 Generic editing workflows . . . . . . . 115 iv Tivoli Service Automation Manager V7.2.4 Extensions Guide Starting Tivoli Provisioning Manager workflows . . . . . . . . . . . . 116 Generic email notification workflow . . . . 117 Writing custom code to run a management plan 118 Public class com.ibm.ism.pmzhb.runbook.task.api.TaskAPIFactory 118 Method detail . . . . . . . . . . 119 Public interface com.ibm.ism.pmzhb.runbook.task.api.TaskAPI 120 Method detail . . . . . . . . . . 120 Public interface com.ibm.ism.pmzhb.runbook.task.api.InputContainer and OutputContainer. . . . . . . . . 121 public interface com.ibm.ism.pmzhb.runbook.task.api.InOutContainer 121 Using the Service Automation Request application to debug management plans . . . 123 Describing the Service Automation Request application . . . . . . . . . . . . 124 Describing the Container Mappings tab 124 Describing the Log tab . . . . . . . 125 Describing the Workflows tab . . . . . 125 Describing the VSRPARAMS tab . . . . 126 Making management plans available through Service Request Manager . . . . . . . . . 126 Creating a classification for a new service offering . . . . . . . . . . . . . . 127 Creating an offering and adding it to the offering catalog. . . . . . . . . . . . 127 Linking offerings to management plans . . . 128 Applying server side validations to offerings 129 Associating lookups with offerings . . . . 129 Creating a domain to use with a classification attribute . . . . . . . . . . . . . 131 Updating service definitions with parts of other service definitions . . . . . . . . . . . . 131 The service update package . . . . . . . 131 Building a service update package from a service definition . . . . . . . . . . . 132 Deploying a service update package on a service definition . . . . . . . . . . . 132 Deploying a service update package on a service deployment instance . . . . . . . 133 Exporting service definitions and related data . . 134 Exporting a service definition structure from a Tivoli Service Automation Manager environment. . . . . . . . . . . . . 134 Transferring service update package structures 136 Exporting a service update package structure from a Tivoli Service Automation Manager environment. . . . . . . . . . . . 136 Importing a Tivoli Service Automation Manager migration package. . . . . . . . . . . 138 Chapter 6. Security . . . . . . . . . 139 Defining roles in Tivoli Service Automation Manager . . . . . . . . . . . . . Creating a role in Tivoli Service Automation Manager . . . . . . . . . . . . Creating a service catalog . . . . . Creating a security group . . . . . . . 139 . . . . 139 . 140 . 140 Assigning a service catalog to a security group . . . . . . . . . . . . . Assigning signature options to a security group . . . . . . . . . . . . . Providing reassignment authorization to a security group . . . . . . . . . . Assigning users to a security group . . . Verifying the security group . . . . . Signature options . . . . . . . . . . Reusing existing users and groups from LDAP Identifying users and groups in LDAP . . Adding users to policy security groups in LDAP . . . . . . . . . . . . . Enabling security group synchronization using VMMSYNC . . . . . . . . . Configuring a security group . . . . . Assigning users to customers . . . . . Verifying users and groups . . . . . . Policy level security groups . . . . . . Data restriction and customer objects . . . Identifying the MBO of the resource object . Extending the Cloud Customer Administration for a resource assignment . . . . . . . Configuring data restriction for the resource . Investigating other functions in the self-service user interface for cloud level users . . . . . 141 . 141 . . . . 142 142 142 143 145 . 145 . 145 . . . . . . . 146 146 147 147 147 148 148 . 149 . 149 . 150 Chapter 7. Advanced workflow references. . . . . . . . . . . . . 151 Workflow overview . . . . . . . . . . . Advanced Workflow Component . . . . . . Advanced Workflow Components Web Services Applications that are used with Workflow . . . . Workflow design process . . . . . . . . . Business process analysis . . . . . . . . Process analysis . . . . . . . . . . Workflow processes and user responsibilities Elements of workflow processes . . . . . . Person records . . . . . . . . . . . Person groups and workflow assignments Roles and role records . . . . . . . . Communication templates . . . . . . . Substitution variables in communication templates . . . . . . . . . . . . . Notifications. . . . . . . . . . . . Escalations and action groups . . . . . . Escalation points . . . . . . . . . . Record routing . . . . . . . . . . . Synonym statuses . . . . . . . . . . Examples of workflow processes . . . . . . Example of a purchase requisition business process . . . . . . . . . . . . . Example of a service request business process Example of a work order business process Configuring for Workflow . . . . . . . . . Configuration prerequisites . . . . . . . . Configuring administrator e-mail notifications Security permissions for workflow processes Working with Actions . . . . . . . . . . Actions and Workflow . . . . . . . . . Actions and escalations . . . . . . . . . 151 152 152 152 154 155 156 156 157 157 158 159 159 160 161 161 162 163 163 164 164 165 167 169 169 169 170 170 171 171 Action types. . . . . . . . . . . . . Custom actions . . . . . . . . . . . . Creating action records . . . . . . . . . Creating action groups . . . . . . . . . Creating actions specific to Workflow . . . . Creating actions specific to escalations . . . . Duplicating actions . . . . . . . . . . Deleting actions . . . . . . . . . . . View Action Log . . . . . . . . . . . Add or modify an image . . . . . . . . Synchronize parameters . . . . . . . . . Configurable parameter mapping. . . . . . Parameter mappings in the Action application Input parameter mappings . . . . . . . Output parameter mappings . . . . . . Automation Scripts application . . . . . . Workflow Designer and Workflow Designer (Advanced) . . . . . . . . . . . . . . Creating workflow processes . . . . . . . Adding nodes and connection lines to the canvas. . . . . . . . . . . . . . Using Workflow Designer application . . Using Workflow Designer (Advanced) application . . . . . . . . . . . Designing workflows with Workflow Designer canvas. . . . . . . . . . . . . . . Workflow Designer toolbar . . . . . . . Process nodes . . . . . . . . . . . Connection lines . . . . . . . . . . Designing workflows with Workflow Designer (Advanced) canvas . . . . . . . . . . Objects and Workflow processes . . . . . Workflow Designer (Advanced) toolbar . . Process nodes . . . . . . . . . . . Connection lines . . . . . . . . . . Using Workflow Designer (Advanced) application . . . . . . . . . . . . Adding attachments to workflows . . . Classifying workflows . . . . . . . Setting Launch on Demand for a workflow. . . . . . . . . . . . Setting the Go To Instance for a workflow Using the Workflow Instances tab . . . Enabling logging . . . . . . . . . Setting node properties . . . . . . . . . Specifying the properties of connector actions Specifying the properties of condition nodes Specifying the properties of interaction nodes Specifying the properties of manual input nodes . . . . . . . . . . . . . . Specifying the properties of subprocess nodes Specifying the properties of task nodes . . . Specifying the properties of wait nodes. . . Setting workflow processes to automatically initiate. . . . . . . . . . . . . . . Setting processes to not auto-initiate . . . . . Duplicating workflow processes . . . . . . Activating and viewing workflow processes . . . Workflow validation process . . . . . . . Validating workflow processes . . . . . Enabling workflow processes . . . . . . . Contents 171 172 173 174 174 175 175 175 176 176 177 177 178 178 181 182 183 183 184 184 184 185 185 187 188 192 193 193 194 194 199 200 200 201 201 202 202 203 203 205 205 207 208 208 210 211 211 211 212 212 213 213 v Activating workflow processes . . . . . . Disabling workflow processes . . . . . . . Viewing workflow assignments from a Workflow-enabled application . . . . . . . Viewing workflow history from a Workflow-enabled application . . . . . . . Viewing workflow specifications from a workflow-enabled application . . . . . . . Viewing workflow action logs from a workflow-enabled application . . . . . . . Viewing a Workflow Map . . . . . . . . Modifying workflow processes . . . . . . . Creating a process revision . . . . . . . . Synchronizing active workflow processes . . . Viewing synchronized processes . . . . . . Adding workflow support to applications . . . Adding toolbar buttons for active workflow processes . . . . . . . . . . . . . Modifying toolbar buttons for active workflow processes . . . . . . . . . Deleting workflow processes . . . . . . . Exporting and importing workflow processes Workflow Administration and Workflow Administration (Advanced). . . . . . . . . Workflow Administration . . . . . . . . Workflow Administration (Advanced) . . . . Using the List tab . . . . . . . . . . Using the Workflow tab . . . . . . . . Using the Assignments tab . . . . . . . Using the History tab . . . . . . . . Using the Map tab . . . . . . . . . Using the Logs tab . . . . . . . . . Using the Specifications tab . . . . . . Stopping instances of workflow processes . . . Deleting assignments . . . . . . . . . . Reassigning workflow assignments . . . . . Completing assignments. . . . . . . . . Sending reassignment notifications . . . . . Workflow/Inbox Assignments portlet . . . . Configuring the Workflow Inbox . . . . . Workflow Launcher . . . . . . . . . . . Developing Custom Actions . . . . . . . . Parameter metadata . . . . . . . . . . Parameter Mappings XML . . . . . . . . Convenience routines for data mappings . . . Sample Jython Script . . . . . . . . . . Troubleshooting and Support . . . . . . . . Known problems, work-arounds, and limitations Error when stopping a workflow with email specified . . . . . . . . . . . . . Internet Explorer 7 sometimes crashes when launching Workflow Designer or Workflow Designer (Advanced) . . . . . . . . . Right-clicking on ILOG Canvas Stop node shows a "Java Applet Window" entry . . . Internet Explorer 7: Hidden Form Missing error in Workflow Designer (Advanced) . . Internet Explorer 7: security exception when launching Workflow Designer (Advanced). . Advanced Workflow Components Messages . . . vi 214 214 215 215 215 216 216 216 217 217 217 218 219 219 220 220 220 220 221 221 222 222 222 222 223 223 223 224 224 224 225 225 225 226 227 227 231 233 234 235 235 235 235 235 236 236 236 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 8. Network extensions . . . . 241 Prerequisites. . . . . . . . . . . . . . Running network provisioning actions . . . . . Overview of network extensions . . . . . . . The network data model . . . . . . . . . Linking network configuration instances to Data Center Model objects . . . . . . . . . . Network APIs . . . . . . . . . . . . . Network management plans and extension nodes Modifying the network configuration of a customer . . . . . . . . . . . . . . Modifying the network configuration of a project. . . . . . . . . . . . . . . Overwriting network provisioning parameters Tivoli Provisioning Manager extensions . . . The Virtual Server Template (VST) of a server . . Virtual Server Template (VST) properties . . . Virtual Server Template (VST) enhancements to support IPv6 provisioning . . . . . . . . IPv6 network environment . . . . . . . Sample scenarios . . . . . . . . . 241 241 241 242 242 244 244 246 247 247 249 249 249 250 251 251 Chapter 9. Storage extensions . . . . 253 Introducing storage extensions . . . . . . Setting additional attributes for storage extensions Storage attributes . . . . . . . . . . Predefined values for the SRCATTRNAME attribute of the PMRDPVSRPARM object . Extensions for the cloud storage pool . . . . Storage entities . . . . . . . . . . . Predefined storage interfaces . . . . . . Predefined data elements for the PMRDPSTORPOOL Maximo Business Object . Cloud storage pool extensions . . . . . . Defining a cloud storage pool extension . Example . . . . . . . . . . . Storage extension nodes . . . . . . . . . Extensions for the Create Project management plan . . . . . . . . . . . . . . Configuring storage extensions . . . . The Create Project workflows . . . . . Extensions for the Cancel Project management plan . . . . . . . . . . . . . . Configuring storage extensions . . . . Purging modes . . . . . . . . . . The Cancel Project workflows . . . . . PMRDPADPEX workflow . . . . . PMRDPRRSTX workflow . . . . . PMRDPRRSTF workflow . . . . . . 253 254 . 254 . . . . 254 256 257 257 . . . . . 258 258 258 259 261 . 261 . 262 . 262 . . . . . . . 263 264 265 265 266 266 267 Chapter 10. The metering framework 269 Metering framework components. . . . . . Using workflows to write meter records . . . The meter task . . . . . . . . . . . Meter parameters . . . . . . . . . Enabling the meter task . . . . . . . . The meter action . . . . . . . . . . The meter service . . . . . . . . . . Querying meter records using the REST API . . . . . . . 269 269 270 270 271 272 272 273 Calculating the activity time for reserved resources . . . . . . . . . . . . The PMRDPMETER meter table . . . . The PMRDPMETERSEARCH meter table . . . . . 273 . 274 . 275 Chapter 11. Managing conflicting Tivoli Service Automation Manager Extension offerings . . . . . . . . . 277 Adding a new offering . . . . . . . . . Adding an extension on top of other extensions Naming conventions to simplify manual merging of extensions . . . . . . . . . 277 277 . 278 A C E H J. M P R S T V W X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 284 284 284 284 285 285 286 286 287 287 287 288 Appendix. Accessibility features . . . 279 Trademarks and Service Marks . . . . 289 Notices . . . . . . . . . . . . . . 281 Index . . . . . . . . . . . . . . . 291 Glossary . . . . . . . . . . . . . 283 Contents vii viii Tivoli Service Automation Manager V7.2.4 Extensions Guide Tables 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. Global API functions for the self-service user interface apply to the following class: . . . . 58 Global API functions for the self-service user interface . . . . . . . . . . . . . 58 Global API functions for dialogs apply to the following offerings: . . . . . . . . . . 58 Global API functions for dialogs . . . . . 59 Global API functions for wizards apply to the following offerings: . . . . . . . . . . 60 Global API functions for wizards . . . . . 61 Project Details wizard page. . . . . . . . 62 Requested Image wizard page . . . . . . 63 Server Details (optional) wizard page.. . . . 64 Install Software wizard page. . . . . . . 66 Network Segment Selection wizard page. 66 Other Settings (optional) wizard page. . . . 67 Summary wizard page. . . . . . . . . 67 Project Details wizard page. . . . . . . . 69 Requested Image wizard page . . . . . . 70 Server Details (optional) wizard page.. . . . 71 Install Software wizard page. . . . . . . 73 Network Segment Selection wizard page. 73 Other Settings (optional) wizard page. . . . 74 Summary wizard page. . . . . . . . . 74 Create Project from Saved Image page . . . 76 Modify Server Resources fields, capabilities and available arguments. . . . . . . . . 78 Modify Reservation fields, capabilities, and possible arguments . . . . . . . . . . 80 General wizard page . . . . . . . . . 81 Resources page . . . . . . . . . . . 82 Network Configuration page . . . . . . . 83 Platform Settings page . . . . . . . . . 84 Other common capabilities that support offerings . . . . . . . . . . . . . 85 Input Parameter Mapping: . . . . . . . 103 VSR Parameter: . . . . . . . . . . . 103 Resulting Container Mapping: . . . . . . 103 © Copyright IBM Corp. 2011, 2013 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. Input Parameter Mapping: . . . . . . . VSR Parameter: . . . . . . . . . . . Resulting Container Mapping: . . . . . . Node selection expression details . . . . . Describing the columns in the Container Mappings tab . . . . . . . . . . . Describing the columns in the Log tab Describing the columns in the Workflows tab Describing the columns in the VSRPARAMS tab . . . . . . . . . . . . . . . Specification attributes . . . . . . . . . . . . . . . . . . . . . . . . Types of nodes and guidelines for connection lines . . . . . . . . . . . . . . Input parameters . . . . . . . . . . Output parameters. . . . . . . . . . Description of management plans and network extension nodes. . . . . . . . Network parameters . . . . . . . . . Subnet parameters . . . . . . . . . . Default route parameters. . . . . . . . Domain Name Service (DNS) parameters Properties in the VST . . . . . . . . . IPv6 properties in the VST . . . . . . . Storage attributes . . . . . . . . . . Predefined values for the SRCATTRNAME attribute . . . . . . . . . . . . . Storage entities in cloud storage pool administration . . . . . . . . . . . Predefined storage interfaces . . . . . . Data elements . . . . . . . . . . . Relationships . . . . . . . . . . . Meter parameters . . . . . . . . . . Meter methods . . . . . . . . . . . Time frames, boundaries, and values The PMRDPMETER table . . . . . . . The PMRDPMETERSEARCH meter table 103 103 103 105 124 125 126 126 129 143 195 227 229 244 247 248 248 248 250 250 254 255 257 257 258 258 270 272 273 274 275 ix x Tivoli Service Automation Manager V7.2.4 Extensions Guide Preface This publication documents how to build new or extend existing solutions in the areas of cloud computing or IT service management using IBM® Tivoli® Service Automation Manager. Who should read this information This information is intended for the following: v Service teams completing customization for Tivoli Service Automation Manager deployments. v Service teams building extensions for Tivoli Service Automation Manager. v Advanced engineers for customers. What's new in this release This release of Tivoli Service Automation Manager offers a set of new features and enhancements to the existing functions. Currency Support for new management server operating systems: v System x: Red Hat Enterprise Linux 6.2 Support for new administrative workstation operating systems: v System x: Red Hat Enterprise Linux 6.2 Support for new hypervisor operating systems: v KVM on system x: Red Hat Enterprise Linux 6.2 v VMControl 2.4.1.1 Guest operating systems: KVM on System x: v Red Hat Enterprise Linux 6.2 & 6.3 Out of Band toleration for VMware datastore selection VMware feature support: v Allow VMs with more than 8 vCPUs v Tolerate Storage VMotion See also the IBM Integrated Service Management Library for Tivoli Service Automation Manager extensions to expand the capabilities of the product at: https://www-304.ibm.com/software/brandcatalog/ismlibrary/ search#rc=TivoliServiceAutomationManager:Tivoli%20Service%20Automation %20Manager. For example, an extension is available that adds z/VM 6.2 support for System z and zEnterprise for this release. © Copyright IBM Corp. 2011, 2013 xi Support information You can find support information for IBM products from a variety of sources. v “Getting technical training” v “Searching knowledge bases” v “Contacting IBM Software Support” on page xiii Getting technical training Information about Tivoli technical training courses is available online. Go to http://www.ibm.com/software/tivoli/education/. Searching knowledge bases If you have a problem with Tivoli Service Automation Manager, search through one of the many available knowledge bases. You can begin with the IT Service Management Information Center at http://publib.boulder.ibm.com/infocenter/tivihelp/v10r1/index.jsp. Searching the Internet If you cannot find an answer to your question in the IT Service Management information center, search the Internet for the latest, most complete information to help you resolve your problem. To search multiple Internet resources, go to the IBM Tivoli Support website. From there, you can search a number of resources, including: v IBM technotes v IBM downloads v IBM Redbooks® If you still cannot find a solution to the problem, you can search forums and newsgroups on the Internet for the latest information to help you resolve it. Using IBM Support Assistant At no additional cost, you can install on any workstation the IBM Support Assistant, a stand-alone application. You can then enhance the application by installing product-specific plug-in modules for the IBM products that you use. The IBM Support Assistant helps you gather support information when you need to open a problem management record (PMR), which you can then use to track the problem. The product-specific plug-in modules provide you with the following resources: v Support links v Education links v Ability to submit problem management reports For more information, see the IBM Support Assistant Web site at http://www-01.ibm.com/software/support/isa/. xii Tivoli Service Automation Manager V7.2.4 Extensions Guide Finding product fixes A product fix might be available from the IBM Software Support website. About this task Check the website to determine which fixes are available for your product. Procedure 1. Find the Tivoli Service Automation Manager product at http://www.ibm.com/ software/tivoli/products/. 2. Click the Support Pages link for the product. 3. Click Fixes for a list of fixes for your product. 4. Click the name of a fix to read the description and download the fix. Getting email notification of product fixes You can get notifications about fixes and other news about IBM products. Procedure 1. From the support page for any IBM product, click My support in the upper-right corner of the page. 2. Optional: If you have not registered, click Register in the upper-right corner of the support page to set up your user ID and password. 3. Sign in to My support. 4. On the My support page, click Edit profiles in the left navigation pane, and scroll to Select Mail Preferences. Select a product family and check the appropriate boxes for the type of information you want. 5. Click Submit. 6. For email notification for other products, repeat steps 4 and 5. Contacting IBM Software Support You can contact IBM Software Support if you have an active IBM software maintenance contract and if you are authorized to submit problems to IBM. About this task Before you contact IBM Software Support, follow these steps: Procedure 1. Set up a software maintenance contract. 2. Determine the business impact of your problem. 3. Describe your problem and gather background information. What to do next Then see “Submit the problem to IBM Software Support” on page xv for information on contacting IBM Software Support. Preface xiii Setting up a software maintenance contract To be able to submit a problem to IBM, you need to have a software maintenance contract. The type of contract that you need depends on the type of product you have. Procedure v For IBM distributed software products (including, but not limited to, Tivoli, Lotus®, and Rational® products, as well as IBM DB2® and IBM WebSphere® products that run on Microsoft Windows or UNIX operating systems), enroll in IBM Passport Advantage®: – Enrolling online: Go to the Passport Advantage Web page at http://www.ibm.com/software/lotus/passportadvantage/, click How to enroll, and follow the instructions. – Enrolling by Telephone: For the telephone number for your country, go to the IBM Software Support Handbook webpage at http:// www14.software.ibm.com/webapp/set2/sas/f/handbook/contacts.html and click Contacts. v For IBM eServer™ software products, you can purchase a software maintenance agreement by working directly with an IBM marketing representative or an IBM Business Partner. For more information about support for eServer software products, go to the IBM Technical support advantage webpage at http://www.ibm.com/servers/eserver/techsupport.html. What to do next If you are not sure which type of software maintenance contract you need, call 1-800-IBMSERV (1-800-426-7378) in the United States. For a list of support telephone numbers for your location, go to the Software Support Handbook page at http://www14.software.ibm.com/webapp/set2/sas/f/handbook/contacts.html. Determine the business impact When you report a problem to IBM, you are asked to supply a severity level. In order to provide this information, understand and assess the business impact of the problem you are reporting. xiv Severity 1 Critical business impact: You are unable to use the program, resulting in a critical impact on operations. This condition requires an immediate solution. Severity 2 Significant business impact: The program is usable but is severely limited. Severity 3 Some business impact: The program is usable with less significant features (not critical to operations) unavailable. Severity 4 Minimal business impact: The problem causes little impact on operations, or a reasonable circumvention to the problem has been implemented. Tivoli Service Automation Manager V7.2.4 Extensions Guide Describe the problem and gather background information When explaining a problem to IBM, it is helpful to be as specific as possible. Include all relevant background information so that IBM Software Support specialists can help you solve the problem efficiently. To save time, know the answers to these questions: v What software versions were you running when the problem occurred? v Do you have logs, traces, and messages that are related to the problem symptoms? IBM Software Support is likely to ask for this information. v Can the problem be recreated? If so, what steps led to the failure? v Have any changes been made to the system? For example, hardware, operating system, networking software, and so on. v Are you currently using a workaround for this problem? If so, be prepared to explain it when you report the problem. Submit the problem to IBM Software Support You can submit the problem to IBM Software Support online or by telephone. Online Go to the IBM Software Support Web site at http://www.ibm.com/ software/support/probsub.html. Enter your information into the appropriate problem submission tool. By Telephone For the telephone number to call in your country, go to the contacts page of the IBM Software Support Handbook at http:// www14.software.ibm.com/webapp/set2/sas/f/handbook/contacts.html. If the problem that you submit is for a software defect or for missing or inaccurate documentation, IBM Software Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. If a workaround is possible, IBM Software Support provides one for you to implement until the APAR is resolved and a fix is delivered. Preface xv xvi Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 1. Overview IBM Tivoli Service Automation Manager helps automate the management of IT services in an IT Service Management (ITSM) environment. It provides the data for the different management phases of ITSM and the required building blocks to automate the management processes for IT services. By providing these functions, Tivoli Service Automation Manager can also be applied to cloud computing environments where a high level of ITSM automation is required to reach cloud scale efficiencies. Tivoli Service Automation Manager uses the concept of service definitions to capture real-world IT services. Service definitions are structured templates to instantiate and manage services. The structural definition of a service is the data context for the different phases of ITSM. Service definitions contain information about management processes that are tailored for a particular type of service. The structural and process models feed into the various stages of the service life cycle. For more details on the structural and process models, see the “Tivoli Service Automation Manager structural service model” on page 3 and “Tivoli Service Automation Manager process model” on page 4 sections. During the service design phase, these service definitions are created as templates of IT services. Details about the later phases of the service management cycle are also added. For example, service definitions provide templates of management processes to instantiate new services in the service transition phase, or to manage services in the service operation phase. When the templates are instantiated during the service transition phase, Tivoli Service Automation Manager uses service deployment instances to provide a view of instances of a service. First, the actual layout of a service is captured at a particular point in time. Then, templates of management processes that are applicable to a given instance of a service are provided. These management process templates can then be used to automate the implementation phase of changes to services in the service operation phase. Using service deployment instances, Tivoli Service Automation Manager adds value to related ITSM processes by providing data for the concrete structure of a service at any point in time. As a result, Tivoli Service Automation Manager automatically obtains the implementation part of ITSM processes using its management process templates. © Copyright IBM Corp. 2011, 2013 1 2 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 2. Main concepts of Tivoli Service Automation Manager The IBM Tivoli Service Automation Manager model and concepts are aligned to the IT Service Management (ITSM) service life cycle. When users build solutions for specific IT services using Tivoli Service Automation Manager, a basic sequence of steps must be followed. These steps are associated with a specific set of Tivoli Service Automation Manager elements. When the design of a service is complete, offerings are created and published to service catalogs so that users can request the implementation of new services. When a user request is received, new service deployment instances are built based on the model that is captured in the associated service definitions. These service deployment instances are used by Tivoli Service Automation Manager to deploy and manage services. The Tivoli Service Automation Manager service automation model comprises two major parts: v The structural model of a service. The structural model describes what the service to be managed looks like. v The process model of a service. The process model defines which processes can be run on the service. Tivoli Service Automation Manager structural service model The structural model of the Tivoli Service Automation Manager service defines all the components that make up a service and the relationships between them. The model has physical components and logical components. Physical components are usually software or hardware components. Logical components are domain-specific constructs, such as a WebSphere cluster as a group of application server instances; or a specific messaging queue in an Enterprise Service Bus (ESB) environment. For each component, the type and set of attributes that are required for a particular service are contained in the structural model. The term service topology model is also used to describe a service. The model objects that represent the components of the service are called service topology nodes. The level of abstraction used in a service topology model depends on the scope of the managed service. For example, a model for automating the management of WebSphere clusters contains elements such as WebSphere nodes and application server instances, or logical entities such as cells and clusters. In most cases, the model cannot handle elements at or below the operating system layer; these elements are taken as a prerequisite. The main managers of a WebSphere service are WebSphere architects and specialists. These people are the target audience for the service automation model that is managing WebSphere clusters. Service topology models that manage pools of servers, can contain elements such as LPARs, network adapters, or storage partitions as physical components and © Copyright IBM Corp. 2011, 2013 3 operating systems and operating system resources as logical components of a service. The main audience for the description of a service is server and operating system administrators. The structural model of a service that is managed with the product can contain both components that are actively managed and components that are not modified by Tivoli Service Automation Manager, but are still structural components of a modeled service. For example, the database management system (DBMS) used by a WebSphere cluster can be a component that is provided and maintained by vendor-acquired software, or peer service, but is not created or altered by any management action that is completed as part of the WebSphere cluster service. However, this DBMS is still part of a WebSphere cluster service topology. The DBMS provides access to configuration attributes of the component that might be required, for example, to configure a connection from WebSphere to the database. This DBMS also indicates that a particular DBMS server is used by a particular WebSphere service, enabling specific impact analysis. Tivoli Service Automation Manager process model The process model defines all the management processes that can be run on the service described in the structural model. In particular, the process model defines the processes that are subject to automation through Tivoli Service Automation Manager. This part of the service model does not define any concrete processes for services. Instead, it defines a process model from which concrete instances of executable processes can be created at a later stage. The process model contains process templates for various stages of the service life cycle. For example, it contains process definitions to implement new services, and in most cases, it also contains process definitions for modifying services that are previously deployed. For the larger IBM service management picture, the process model for any specific service can plug-in to various ITSM processes. For example, the Tivoli Service Automation Manager process model with the associated structural model of a service can feed into the planning and assessment phase of a change management process and lead to more automated and faster processing of the change. In addition, the concrete process steps that can be generated from the process model provide content to implement a change. Using the self-service virtual server provisioning service as an example, management plans can: v Create virtual servers in a project. The servers model a service instance deployed in the product. v Modify servers, for example, by adding additional hardware to the servers. v Deprovision all virtual servers and free up hardware resources when a service is decommissioned. Processes that are defined in the process model are called management plans. Management plans are implemented using advanced workflow technology. Using graphics, advanced workflows model processes in a control flow. The management task node works with the advanced workflow technology to integrate the control flow into the topology by using iterative definitions, data mapping rules, and error handling rules. 4 Tivoli Service Automation Manager V7.2.4 Extensions Guide Related reference: “Network management plans and extension nodes” on page 244 Network extension nodes are used for all types of management plans. Templates and instances When services are automated using Tivoli Service Automation Manager, both structural and operational services are defined on a template level. A service definition is a template for similar service instances that are deployed. Service definitions contain topology templates that provide the data model for the service in Tivoli Service Automation Manager. A service definition also contains management plans that define the process for creating, managing, and deleting the service. Based on these templates, instances of a particular deployment of a service are created and managed through Tivoli Service Automation Manager. For example, use the template of a service to manage a pool of VMware virtual servers that are operating several instances of a service. One instance might be used to manage servers for the development team of a project, and another one for the test team.Tivoli Service Automation Manager uses the term service deployment instance for an instance of a managed service that is created from a service definition. Tivoli Service Automation Manager services for users Tivoli Service Automation Manager's artifacts are created and maintained using Tivoli's process automation engine applications and the administrative user interface that are shipped with the product. The administrative user interface is also used to configure service instances such as creating new service deployment instances from service definitions or modifying services that are previously deployed. These applications are not targeted to users, but to technical experts such as service designers and administrators. The service management functions implemented by Tivoli Service Automation Manager are provided in the form of service offerings that are requested by users of the offering catalog interface. Service offerings and the offering catalog interface are provided by the Tivoli Service Request Manager® (SRM) component. Service offerings can also be accessed through external user interfaces, such as the self-service user interface. When a user requests a service from the SRM offering catalog, a flow of tasks occurs. These tasks are shown in the next figure. Chapter 2. Main concepts of Tivoli Service Automation Manager 5 End user Self-service user interface Maximo Enterprise Adapter / REST Service Request Manager Tivoli Service Automation Manager Service offerings Offering presentation Offering "XYZ" Service definitions Service deployment instances The flow can be described as: 1. Users select an entry for a specific offering from the offering catalog. 2. Users enter a set of parameters to process the request. 3. When the user submits the catalog request, it is processed by a workflow that triggers a request for Tivoli Service Automation Manager to create a service deployment instance or modify an existing one. As an alternative to the SRM offering catalog UI, service offerings are also presented in an external self-service user interface. The external self-service user interface does not bypass SRM completely; it replaces the presentation layer of SRM, which means that there is no direct access to the product APIs. Instead a simplified request API for service offerings is used. Consequently, when the service automation functions in IBM Tivoli Service Automation Manager are presented to users in a more abstract, service-oriented way, additional artifacts must be created. Service offerings and presentations must be defined in SRM and extensions to the external self-service UI must also be defined. In most cases, these artifacts do not have to be defined. Tivoli Service Automation Manager includes a set of artifacts for building and customizing solutions. It is not necessary to create or modify the whole chain of artifacts shown in the previous figure for every extension scenario. In many cases, only individual modifications to some of the existing artifacts are necessary. 6 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 3. Describing a Tivoli Service Automation Manager solution The main component of each service automation solution is a service definition. A service definition is the first artifact you create when you are building a solution. Next, you instantiate the service and design the control flow for the process using the advanced workflow designer. You can also reuse some of the generic workflows that are provided with IBM Tivoli Service Automation Manager product. When you use Tivoli Service Automation Manager to create a service automation solution, or to extend an existing one, you must modify several extension points. Each of these extension points are specific to the underlying implementation component. Tivoli Service Request Manager (SRM) is the user-facing component inside Tivoli's process automation engine that presents services to users in an offering catalog. Tivoli Provisioning Manager is the engine that drives automated actions in the managed environment. The self-service user interface can be used as a more flexible way of providing service offerings. The Maximo® Enterprise Adapter (MEA) serves as the bridge between the outside components and the internal components of Tivoli's process automation engine. In the following figure, the high-level extension points that are required to build a service automation solution are numbered. 4 Self-service user interface Dojo / HTML Tivoli's Process Automation Engine 5 Maximo Enterprise Adapter / REST Object structures / services 3 Service Request Manager Offerings / Service requests 1 Tivoli Service Automation Manager Service definitions / Management plans 2 Tivoli Provisioning Manager / Automation Provisioning workflows Tivoli's Process Automation engine Base framework © Copyright IBM Corp. 2011, 2013 7 Related tasks: “Creating a service definition” on page 87 The main component of each service automation solution is a service definition. service definition consists of two major parts: a service topology model that captures the structure of the automated service and a process model that consists of management plans for creating instances of a service. A service definition is also important when completing extensions to an existing solution. Related reference: “Starting Tivoli Provisioning Manager workflows” on page 116 With Tivoli Service Automation Manager, you can start Tivoli Provisioning Manager workflows using the PMZHBRTPM advanced workflow. Tivoli Service Request Manager extension points The Service Request Manager (SRM) offering catalog is a simple interface that presents offerings to users who request services. Before you can present a service through SRM, you must classify it. Classifications contain service-specific attributes. The requester of a service must specify these or any other attributes that affect the associated back-end service. You can then create a service offering based on this classification. Service offerings define some properties that are not functional, such as price in an offering catalog. They also provide technical definitions by assigning values to specification attributes for the associated service implementation. For example, the offering designer defines specification attributes for the service definition and the management plan. Predefined values are also passed on to Tivoli Service Automation Manager. The SRM offering also includes a set of defined parameters. You must determine how these parameters, which are a subset of the specification attributes for the associated service implementation, are displayed. Finally, an offering can be made available in multiple offering catalogs. These catalogs can be defined for different users or groups, which means that a certain set of offerings can be made available to one group and another set of offerings can be made available to another group. Self-service extension points The REST interface acts as a bridge between the self-service user interface and the internal components of Tivoli's process automation engine. These components are: Tivoli Service Automation Manager, SRM and Tivoli Provisioning Manager. The self-service user interface can be modified for new Tivoli Service Automation Manager solutions. Users can create their own offerings in SRM. These offerings can be added to offering catalogs and displayed in the self-service user interface. The self-service user interface provides a specialized panel to display the main parameters for each offering. These parameters can be modified in this panel. All the attributes for a particular offering are displayed in the self-service user interface. Table type attributes for an offering are not shown in the self-service user interface. Each attribute has a corresponding input field on the self-service user interface. If additional interfaces are required for particular offerings, the self-service user interface can be extended with new panels in the form of JavaScript Dojo classes. 8 Tivoli Service Automation Manager V7.2.4 Extensions Guide Maximo Enterprise Adapter and REST extension points Components outside Tivoli's process automation engine can access services and data inside Tivoli's process automation engine using the Maximo Enterprise Adapter. The Maximo Enterprise Adapter also includes the Representational State Transfer (REST) interface. Users can access data stored in complex Maximo Business Objects from the REST interface. MBOs can be created by using the Maximo Enterprise Adapter inside Tivoli's process automation engine. Tivoli Service Automation Manager includes object structures for a number of use cases, such as those implemented in the self-service user interface. If the internal structure of Tivoli Service Automation Manager is not changed and special object relationships are not accessed by external components, this extension point is not affected. Chapter 3. Describing a Tivoli Service Automation Manager solution 9 10 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 4. Self-service user interface extension points You can extend the self-service user interface to meet your own needs. Extending the self-service user interface You can personalize the self-service user interface to meet your corporate standards and requirements using an API (application programming interface). About this task In Tivoli Service Automation Manager Version 7.2.2, you can customize the user interface with an API. The approach has several advantages: v Upgrades or migration do not affect your customized changes. The extensions are kept in a separate war file called custom_web.war. This file is not modified by Tivoli Service Automation Manager upgrade installers to prevent losing customer extensions. v You do not need advanced JavaScript skills and extensive knowledge of the product code to modify the user interface. v It is officially supported. The API interfaces have been thoroughly tested and documented for the exact purpose of writing customer extensions. If you use them and run into problems, it is easy to get support and fixes. The self-service interface extensibility API is designed to support two areas: v Branding You can adjust the look and feel of the user interface to your corporate standards in terms of colors and style. It is possible to load custom CSS rules for certain parts of the product, replace some images (logos) with customer logos, and change welcome messages and other headings. v Extending existing offerings Some of the offerings are API-enabled, that is, they provide a set of capabilities that can be used by customer extensions. The capabilities range from branding through changing default values, hiding values or widgets, making widgets read only, connecting widget events to custom event handlers and finally, adding custom sections that contain user-defined widgets. You can find a complete reference to all API-enabled offerings with their widgets and capabilities in “API reference for the self-service user interface” on page 58. You develop the extensions on a local development environment and test them by deploying the extension to a Tivoli Service Automation Manager management server that acts as a test environment. When the extension is ready for production, build the custom_web.war file, copy it to the Tivoli Service Automation Manager administrative console, and rebuild (redeploy) the MAXIMO.ear file on the production environment. © Copyright IBM Corp. 2011, 2013 11 Merging offerings with multiple extensions The JavaScript extension API only supports one extension class per offering. If an extension is installed for a particular offering, you cannot install a second extension for that offering unless the extensions are merged. Before you begin ITEMNUM is the database parameter that contains the offering ID. When you are naming extension files, use the ITEMNUM.js pattern, for example: A.js. About this task To merge two extensions: Note: The following extensions, files, and classes are for example purposes only. Procedure 1. Put the first extension in its own file, for example, put extension x into x.js. 2. Put the second extension in a separate file, for example, put extension y into y.js. 3. Write a class called A.js to import the previous extensions: x.js and y.js. Results A.js calls the appropriate functions from x and y separately. Function names inside the x and y modules do not have to change. Setting up your development environment To write the self-service user interface extensions, you first must set up and configure your environment. To set up your development environment, you must perform the following procedures: 1. Set up the Eclipse IDE development environment. 2. Configure your build environment. Setting up Eclipse IDE The custom_web.zip file on the Tivoli Service Automation Manager installation medium contains two predefined projects for Eclipse IDE. v custom_web - project, which contains the actual extensions. v custom_web_build, which is a tool project that contains build scripts for test and deployment. You must import the two project files into the local directory, and then, into Eclipse. Procedure 1. Insert the Tivoli Service Automation Manager installation medium into your local DVD drive. If you have the medium as an ISO image, mount the image locally. 2. Navigate to: v 12 Windows [Drive:\]TSAMBASE723\samples\UI Tivoli Service Automation Manager V7.2.4 Extensions Guide UNIX v [/mountpoint/]TSAMBASE723/samples/UI 3. Copy the file custom_web.zip to your local hard disk. What to do next If you already have Eclipse installed proceed to “Verifying Eclipse installation and importing the projects.” If not, proceed to “Installing Eclipse and importing the projects.” Verifying Eclipse installation and importing the projects: If you already have Eclipse IDE installed, check the requirements, and import the predefined Eclipse projects into the application. Before you begin 1. Ensure that the following features of Eclipse are installed: v Eclipse Java™ Development Tools v Eclipse IDE for JavaScript Developers 2. Ensure that the J2EE version of a full Eclipse release is installed. Supported Eclipse IDE for Java EE Developers releases are: v Ganymede v Galileo v Helios 3. Ensure that Apache Ant in Eclipse is at version 1.8.0 or newer. If not, download the latest version at http://ant.apache.org. Procedure 1. Using Eclipse IDE, create a workspace. 2. Select File > Import > General > Existing Projects into Workspace. 3. Click Select archive file and browse for custom_web.zip, which you copied in step 3 in the previous section. 4. Click Finish to import the projects. Installing Eclipse and importing the projects: Install the latest version of Eclipse IDE for Java EE Developers, and import the predefined Eclipse projects into the application. Procedure 1. Open http://www.eclipse.org/downloads, and download the most recent Eclipse IDE for Java EE Developers package. Note: Ensure that Apache Ant in Eclipse is at version 1.8.0 or later. If not, download the latest version at http://ant.apache.org. 2. Extract the package to a directory of your choice. 3. Start the application and create a workspace. 4. Select File > Import > General > Existing Projects into Workspace. 5. Click Select archive file and browse for custom_web.zip, which you copied in step 3 in the previous section. 6. Click Finish to import the projects. Chapter 4. Self-service user interface extension points 13 Configuring the build environment There are two ways to deploy the extensions. You can either rebuild the whole MAXIMO.ear file, or use the quickdeploy feature. Full deployment: One way to deploy the custom_web.war file extension to your management server is to copy the war file to the administrative console and rebuild and redeploy the MAXIMO.ear file. This procedure can take a considerable amount of time, therefore, only perform full deployment when your extension is finished and ready for the installation on a production system. This procedure is described in more detail in “Testing and deploying extensions” on page 51. quickdeploy: When you develop an extension for the user interface, you usually introduce small changes to the code and test them immediately as part of rapid development test cycle. To avoid a time-consuming full redeployment of the MAXIMO.ear file, your development environment provides a feature called quickdeploy. quickdeploy assumes that only the actual custom_web.war file, already deployed to the target management server, and its contents (javascript, html, css, or other files), must be replaced. This is accomplished by remotely copying the contents to the location of the deployed custom_web.war file within the application server. The contents of the file do not have to be loaded by the application server class loader. Before you begin Because the underlying technology for transferring the extension to the target management server relies on SSH (Secure Shell), the management server must have the following service up and running: v sshd listening on the default port 22. About this task You can transfer the extensions to the management server using public key authentication (preferred), or with password authentication. The procedures for these two methods are described in detail in the subsequent sections. Setting up quickdeploy with public key authentication: Set up your build environment to transfer the extensions by using the public key authentication method. Procedure 1. Generate a secure key pair for your client: a. Generate an RSA or DSA key pair from putty (http://www.putty.org) or a similar key tool. b. When using putty, use puttygen, a key generator program included in the putty installation. Select either SSH-2-RSA, or SSH-2-DSA with a number of bits between 64 - 2048 (1024 by default). c. Ensure that the public key is in an OpenSSH-compatible format. When you use puttygen, copy the key from the text field to an id_dsa.pub or id_rsa.pub file, depending on the cryptographic method selected. 14 Tivoli Service Automation Manager V7.2.4 Extensions Guide Note: Ensure that you are storing the key in OpenSSH-compatible format. Do not click Save public key to ensure that you are not using putty proprietary format. Instead, copy and paste the public key from the text field to a new file and name this file id_dsa.pub or id_rsa.pub. d. Save the private key to a file called id_dsa or id_rsa (depending on the cryptographic method selected) without extension. Note: Ensure that you are storing the key in OpenSSH-compatible format. Do not click Save public key to ensure that you are not using putty proprietary format. Instead, in the Conversions menu, select Export OpenSSH key. e. Place both the private and the public key into the keys folder of the custom_web_build project in Eclipse. The keys folder in your custom_web_build project now contains the following files: v id_ - the private key v id_.pub - the public key 2. Establish a trusted connection to the management server: a. Copy the public key file to the target management server. b. On the target management server, add the contents of the public key to the authorized_keys file in your home directory: cd ~/.ssh cat /path/to/public/key/id_.pub >> authorized_keys 3. Edit the build.properties file in the custom_web_build project in the following way: v sshUser - Set to your user name on the target management server. v v v v v Important: This user must be the owner of the WebSphere application server process. The default is tioadmin. sshUsePwd - Comment this line out. (Do not set it to no). sshUseKey - Set to yes. sshKeyFile - Set to keys/id_. sshKeyPassphrase - Set the passphrase for your key (only if you have set one during key creation). targetHost - Set to the host name of the target management server. If you have not installed Tivoli Service Automation Manager with default settings for WebSphere, you might need to change the following properties: v WAS_HOME - Set to the installation directory of WebSphere. v SERVER_NAME - Set to the name of the application server that runs Maximo. v CELL_NAME - Set to the WebSphere cell that hosts your application server. 4. To test your setup, run the quickdeploy ant task from the build.xml: a. b. c. d. e. In the custom_web_build project, right-click build.xml. Select Run as > Ant build. In the Targets tab, clear the rebuild check box and select quickdeploy. In the Name field, change the text to quickdeploy. Click the Classpath tab and click User Entries. f. Click Add JARs.... g. Drill down to custom_web_build/lib/jsch-0.1.42.jar, and select jsch-0.1.42.jar. Chapter 4. Self-service user interface extension points 15 h. Click OK. The contents of the extension are copied over to the management server, and show up in the user interface the next time you open it. Note: The initial version of the custom_web project is only a sample that is to be filled with actual content. It does not change anything if not modified. What to do next Optionally, repeat step 4 on page 15 to perform the following ant tasks: v quickundeploy - Removes your extension from the application server. v rebuild - Builds a new custom_web.war file for deployment in productive environments. For more information about using these functions, see “Testing and deploying extensions” on page 51. Setting up quickdeploy with password authentication: Set up your build environment to transfer the extensions by using the password authentication method. Using password authentication is not recommended because it poses a security risk. The password is stored in clear text within the build.properties file. Procedure 1. Edit the build.properties file in the custom_web_build project in the following way: v sshUser - Set this parameter to your user name on the target management server. Important: This user must be the owner of the WebSphere application server process. The default is tioadmin. v sshPwd - Set to your password. v sshUsePwd - Set to yes. v sshUseKey - Comment this line out. (Do not set it to no). v targetHost - Set to the host name of the target management server. If you have not installed Tivoli Service Automation Manager with default settings for WebSphere, you might need to change the following properties: v WAS_HOME - Set to the installation directory of WebSphere. v SERVER_NAME - Set to the name of the application server that runs Maximo. v CELL_NAME - Set to the WebSphere cell that hosts your application server. 2. To test your setup, run the quickdeploy ant task from the build.xml: a. In the custom_web_build project, right-click build.xml. b. Select Run as > Ant build. c. In the Targets tab, clear the rebuild check box and select quickdeploy. d. In the Name field, change the text to quickdeploy. e. Click the Classpath tab and click User Entries. f. Click Add JARs.... g. Drill down to custom_web_build/lib/jsch-0.1.42.jar, and select jsch-0.1.42.jar. 16 Tivoli Service Automation Manager V7.2.4 Extensions Guide h. Click OK. The contents of the extension are copied over to the management server, and show up in the user interface the next time you open it. Note: The initial version of the custom_web project is only a sample that is to be filled with actual content. It does not change anything if not modified. What to do next Optionally, repeat step 4 on page 15 to perform the following ant tasks: v quickundeploy - Removes your extension from the application server. v rebuild - Builds a new custom_web.war file for deployment in productive environments. For more information about using these functions, see “Testing and deploying extensions” on page 51. Writing an extension for branding After you configure your build environment, start modifying the branding of the Tivoli Service Automation Manager self-service user interface. You can change colors, style, and images on the application to align it to your corporate standards. About this task The current Tivoli Service Automation Manager extensibility API supports three kinds of modifications: v Branding of the logon screen v Branding of the application v Branding of specific offerings For each of them, different API calls are possible. The following sections explain in detail how to change the branding of your Tivoli Service Automation Manager installation. Modifying the branding of the logon screen Modify the logon panel of the application, so that the users see a custom image, logo, and heading. Before you begin Ensure that Tivoli Service Automation Manager is up and running, and that the user interface is visible. Procedure 1. Switch to your development environment. 2. Using Eclipse, open the custom_web project in the workspace. 3. Navigate to WebContent > js > custom > tsam > dijit. 4. Open the Login.js and LoginError.js files. What to do next Depending on what you want to modify, proceed to one of the following topics. Chapter 4. Self-service user interface extension points 17 Loading a customized CSS sheet for the logon screen: Load your own CSS sheet to customize the logon panel. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamLoadCSS function. 3. Include the context root in the URL: /custom. 4. Omit the WebContent folder in the URL. Example The following code examples load the default login.css sheet that cascades on the default Tivoli Service Automation Manager styles. The first example is from the login.js file. dojo.provide("custom.tsam.dijit.Login"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.Login"); dojo.declare("custom.tsam.dijit.Login", [ibm.tivoli.simplesrm.srm.dijit.Login], { tsamCustomInit: function() { this.tsamLoadCSS("/custom/js/custom/tsam/dijit/themes/login.css"); }, }); The following code is from the LoginError.js file. dojo.provide("custom.tsam.dijit.LoginError"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.LoginError"); dojo.declare("custom.tsam.dijit.LoginError", [ibm.tivoli.simplesrm.srm.dijit.LoginError], { tsamCustomInit: function() { this.tsamLoadCSS("/custom/js/custom/tsam/dijit/themes/login.css"); }, }); Changing the logon screen image: By default, there is an automation robot image at the logon screen. You can replace this image with any other of your choice. Procedure 1. Edit the tsamCustomInit function. 2. Use the function tsamSetLoginImage. 3. Specify the correct image dimensions (width and height). The image is best displayed when 60 pixels in width and 120 pixels in height. 4. Include the context root in the URL: /custom. 5. Omit the WebContent folder in the URL. 6. Optional: Specify alt-text for the image (a text displayed if the image could not be loaded). 18 Tivoli Service Automation Manager V7.2.4 Extensions Guide Example The following code examples load an image called loginMascot.png for Login and LoginError. The image is displayed next to the logon and password text fields. dojo.provide("custom.tsam.dijit.Login"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.Login"); dojo.declare("custom.tsam.dijit.Login", [ibm.tivoli.simplesrm.srm.dijit.Login], { tsamCustomInit: function() { this.tsamSetLoginImage(60,120,”login”,”/custom/js/custom/tsam/dijit/themes/images/loginMascot.png”); }, }); The following example code is for LoginError. dojo.provide("custom.tsam.dijit.LoginError"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.LoginError"); dojo.declare("custom.tsam.dijit.LoginError", [ibm.tivoli.simplesrm.srm.dijit.LoginError], { tsamCustomInit: function() { this.tsamSetLoginImage(60,120,”login”,”/custom/js/custom/tsam/dijit/themes/images/loginMascot.png”); }, }); Changing the logon screen heading: You can modify the title heading on the logon screen to display a custom text. Procedure 1. Edit the tsamCustomInit function. 2. Use the function tsamSetLoginHeading with the text that you want to display. Tip: v Do not use lengthy headings. The space on the panel is designed for 15-25 characters. v Using fixed strings in the user interface extension code is not advisable. Instead, use standard Dojo globalization means to load strings from different locales. If you still prefer to hard-code non-English strings into your extension, make sure that the extension js file is UTF-8 encoded. Since JavaScript source files are usually ANSI-encoded, you must convert them to UTF-8 to insert special characters. Example The following code example changes the default heading Service Automation Manager to MyCompany Cloud Services: dojo.provide("custom.tsam.dijit.Login"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.Login"); dojo.declare("custom.tsam.dijit.Login", [ibm.tivoli.simplesrm.srm.dijit.Login], { tsamCustomInit: function() { Chapter 4. Self-service user interface extension points 19 this.tsamSetLoginHeading(”MyCompany Cloud Services”); }, }); The following example code is for LoginError. dojo.provide("custom.tsam.dijit.LoginError"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.LoginError"); dojo.declare("custom.tsam.dijit.LoginError", [ibm.tivoli.simplesrm.srm.dijit.LoginError], { tsamCustomInit: function() { this.tsamSetLoginHeading(”MyCompany Cloud Services”); }, }); Changing the logon screen brand logo: You can display your corporate logo or any other image on the logon screen. About this task Before Tivoli Service Automation Manager Version 7.2.2, there was a Tivoli logo on the logon screen. In version 7.2.2, the logo was replaced with a transparent icon of equal size. You can replace this icon with any other image. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamSetLoginLogo function. 3. Specify the correct image dimensions (width and height). The preferred image size is 42 pixels in width and 22 pixels in height, and the width-height ratio is 2:1. 4. Include the context root in the URL: /custom. 5. Omit the WebContent folder in the URL. 6. Optional: Specify alt-text for the image (a text displayed if the image could not be loaded). Example The following code example loads a logo image called loginLogo.png, which is displayed in the upper-left part of the logon panel. dojo.provide("custom.tsam.dijit.Login"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.Login"); dojo.declare("custom.tsam.dijit.Login", [ibm.tivoli.simplesrm.srm.dijit.Login], { tsamCustomInit: function() { this.tsamSetLoginLogo(42,22,”logo”,”/custom/js/custom/tsam/dijit/themes/images/loginLogo.png”); }, }); The following example code is for LoginError. dojo.provide("custom.tsam.dijit.LoginError"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.LoginError"); dojo.declare("custom.tsam.dijit.LoginError", 20 Tivoli Service Automation Manager V7.2.4 Extensions Guide [ibm.tivoli.simplesrm.srm.dijit.LoginError], { tsamCustomInit: function() { this.tsamSetLoginLogo(42,22,”logo”,”/custom/js/custom/tsam/dijit/themes/images/loginLogo.png”); }, }); Modifying the branding of the main screen You can customize the appearance of the main screen with the application to align it with your corporate branding. Before you begin Ensure that Tivoli Service Automation Manager is up and running, and that the user interface is visible. Procedure 1. Switch to your development environment. 2. Using Eclipse, open the custom_web project in the workspace. 3. Navigate to WebContent > js > custom > tsam > dijit. 4. Open the SimpleSrmApp.js file. What to do next Depending on what you want to modify, proceed to one of the following topics. Loading a customized CSS sheet for the main screen: Load your own CSS sheet to customize the main screen. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamLoadCSS function. 3. Include the context root in the URL: /custom. 4. Omit the WebContent folder in the URL. Example The following code example loads the Custom_SimpleSrmApp_Tundra.css sheet, which cascades on the Tivoli Service Automation Manager default styles: dojo.provide("custom.tsam.dijit.SimpleSrmApp"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp"); dojo.declare("custom.tsam.dijit.SimpleSrmApp", [ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp], { tsamCustomInit: function() { this.tsamLoadCSS("/custom/js/custom/tsam/dijit/themes/Custom_SimpleSrmApp_Tundra.css"); }, }); Chapter 4. Self-service user interface extension points 21 Modifying the main screen heading text: You can customize the title of the main screen. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamSetBrandHeading function. Tip: v Your brand name can be much longer than the brand heading on the logon screen. A length between 25-35 characters is preferred. v Using fixed strings in the user interface extension code is not advisable. Instead, use standard Dojo globalization means to load strings from different locales. If you still prefer to hard-code non-English strings into your extension, make sure that the extension js file is UTF-8 encoded. Since JavaScript source files are usually ANSI-encoded, you must convert them to UTF-8 to insert special characters. Example The following code example changes the default brand Service Automation Manager to MyCompany on the upper-left part of the main screen, next to the Tivoli brand logo: dojo.provide("custom.tsam.dijit.SimpleSrmApp"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp"); dojo.declare("custom.tsam.dijit.SimpleSrmApp", [ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp], { tsamCustomInit: function() { this.tsamSetBrandHeading(”MyCompany”; }, }); Modifying the main screen brand logo: You can change the logo that is displayed next to the heading. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamSetBrandLogo function. 3. Specify the correct image dimensions (width and height). The preferred image size is 42 pixels in width and 22 pixels in height, and the width-height ratio is 2:1. 4. Include the context root in the URL: /custom. 5. Omit the WebContent folder in the URL. 6. Optional: Specify alt-text for the image (a text displayed if the image cannot be loaded). Example The following code example loads a logo image called brandLogo.png that is displayed instead of the Tivoli logo in the upper-left part of the application. 22 Tivoli Service Automation Manager V7.2.4 Extensions Guide dojo.provide("custom.tsam.dijit.SimpleSrmApp"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp"); dojo.declare("custom.tsam.dijit.SimpleSrmApp", [ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp], { tsamCustomInit: function() { this.tsamSetBrandLogo(42,22,”logo”,”/custom/js/custom/tsam/dijit/themes/images/brandLogo.png”); }, }); Modifying the branding of offerings You can load custom a CSS sheet to modify the style of specific offerings. Before you begin Ensure that Tivoli Service Automation Manager is up and running and that the user interface is visible. Procedure 1. Find and note the offering name: a. On the management server, log on to the Tivoli Service Automation Manager administrative interface as the catalog user. b. Select Go To > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify and select it. d. Take note of the offering ID (ITEMNUM). The pattern for the basic Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the custom_web project in the workspace. 4. Navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a file with the same name as the offering ID: PMRDP_nnnnA_72.js. The following example presents the skeleton for the PMRDP_0201A_72 offering (Create Project with VMware Servers): dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { }, tsamCustomDestroy: function() { }, }); 6. Load your custom CSS sheet: a. Edit the tsamCustomInit function and use the tsamLoadCSS function. b. Edit the tsamCustomDestroy function use the tsamUnloadCSS function. Important: Ensure that you implement the tsamCustomDestroy function and call the tsamUnloadCSS function correctly, otherwise the CSS sheet stays active for other offerings as well. c. Include the context root in the URL: /custom. Chapter 4. Self-service user interface extension points 23 d. Omit the WebContent folder in the URL. Example The following code example loads the Custom_Tundra.css sheet, which cascades on the self-service user interface default styles when the offering is loaded. The CSS sheet is replaced when a different offering is loaded. In the sample, the extension applies to the PMRDP_0201A_72 offering (Create Project with VMware Servers). dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { this.tsamLoadCSS("/custom/js/custom/tsam/dijit/themes/Custom_Tundra.css"); }, tsamCustomDestroy: function() { this.tsamUnloadCSS("/custom/js/custom/tsam/dijit/themes/Custom_Tundra.css"); } }); Tip: If you want to apply the same branding to all offerings, use the extension point of the application and load the appropriate CSS rules there. Extending the offering panels Each offering panel, or request, in the self-service interface consists of a group of widgets that can be customized in many ways. You can also add new widgets to the panels. Note: Ensure that the offering name does not contain any special characters other than a dollar sign "$" and underscore "_". If it does, you must change the name before you can customize the offering. About this task The Tivoli Service Automation Manager extensibility API supports extending the existing offerings with: v Changing widget values – Setting default values v Hiding and showing widgets – Hiding widgets – Hiding groups of widgets – Making widgets read-only v Adding widgets and event handlers – Adding custom widgets – Adding custom event handlers The following sections demonstrate in detail how to customize the existing Tivoli Service Automation Manager offering panels. 24 Tivoli Service Automation Manager V7.2.4 Extensions Guide Related tasks: “Creating an offering and adding it to the offering catalog” on page 127 If features are opened through the Service Request Manager offering catalog, you must create an offering to show these features in the service catalog. After creating the offering, add it to the catalog, so that users can request it. Changing widget values Add a set of default values to be displayed on widgets when the request panel is opened. Before you begin Ensure that your Tivoli Service Automation Manager is up and running and that the user interface is visible. About this task It is advisable that you extend the offerings by first duplicating the original offering and extending the duplicate. In this way, if you ever need to install any upgrades to the original offering, the extended offering will not be overwritten. Procedure 1. Find and note the offering name: a. On the management server, log on to the Tivoli Service Automation Manager administrative interface as the catalog user. b. Select Go To > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify and select it. d. In the Select Action menu, click Duplicate an Offering. e. Take note of the duplicated offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. Example The following code example shows the file skeleton for offering PMRDP_0201A_72. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { }, tsamCustomDestroy: function() { }, }); Chapter 4. Self-service user interface extension points 25 What to do next Proceed to the following task to define default values. Setting default values: Set default values so that a request always starts with a specific value. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetField and tsamCall functions. 3. Call the setValue capability, or other valid capabilities. Example In the following code example, the function tsamGetField gets a reference to a field that provides API capabilities for the Project Name text field on the Create Project with VMware Servers offering panel. In the field, the setValue capability is called, and it sets a default value for that text field. The default value is set to DefaultProject. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var pn = this.tsamGetField(„Project Name”); pn.tsamCall(„setValue”, „DefaultProject”); }, }); Hiding and showing widgets You can hide specific widgets or groups of widgets on the panels or make them read only. Before you begin Ensure that your Tivoli Service Automation Manager is up and running and that the user interface is visible. About this task It is advisable that you extend the offerings by first duplicating the original offering and extending the duplicate. In this way, if you ever need to install any upgrades to the original offering, the extended offering will not be overwritten. Procedure 1. Find and note the offering name: a. On the management server, log on to the Tivoli Service Automation Manager administrative interface as the catalog user. b. Select Go To > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify and select it. d. In the Select Action menu, click Duplicate an Offering. 26 Tivoli Service Automation Manager V7.2.4 Extensions Guide e. Take note of the duplicated offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. What to do next Depending on what you want to change, proceed to one of the following tasks. Hiding widgets: If you do not want the user to see particular information, you can hide a widget in the request panel. Note: Even if you hide the widget in the self-service user interface panels, any values defined on the widget are still submitted in the service request. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetField and tsamCall functions. 3. Call the setDisplay capability or other valid capabilities. Example In the following code example, the function tsamGetField gets a reference to a field that provides API capabilities for the Project Description text field on the Create Project with VMware Servers offering panel. In the field, the setDisplay capability is called. This capability sets a visibility value for that text field. Three values are available: none Hides the widget. inline Displays the widget without any formatting. block Displays the widget by reformatting it with a line-break. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var pd = this.tsamGetField(„Project Description”); pd.tsamCall(„setDisplay”, „none”); }, }); For an overview of available fields and capabilities, refer to “API reference for the self-service user interface” on page 58. Chapter 4. Self-service user interface extension points 27 Hiding groups of widgets: Hide whole groups of widgets at once instead of hiding them one by one. Note: Even if you hide the widget in the self-service user interface panels, any values defined on the widget are still submitted in the service request. About this task The Tivoli Service Automation Manager extensibility API provides fields that group sets of widgets thematically, but act as a single reference. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetGroup and tsamCall functions. 3. Call the setDisplay capability or other valid capabilities. Example In the following code example, the function tsamGetGroup gets a reference to a group field that provides API capabilities for the entire Software section of the Create Project with VMware Servers offering panel. The section contains a number of widgets. When a capability is called, each widget in the group is called. On the field group, the capability setDisplay is called. This capability sets a visibility value for that field group. The value is set to none, which means the entire Software section is invisible. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var sg = this.tsamGetGroup(„Software”); sg.tsamCall(„setDisplay”, „none”); }, }); For an overview of available fields and capabilities, refer to “API reference for the self-service user interface” on page 58. Making widgets read only: Make your widgets read only so that the user can see them but is not able to modify values. Procedure 1. Edit the tsamCustiomInit function. 2. Use the tsamGetField and tsamCall functions. 3. Call the setReadOnly capability, or other valid capabilities. Example In the following code example, the function tsamGetField gets a reference to a field providing API capabilities for the Project Team list on the Create Project with VMware Servers offering panel. In the field, the setReadOnly capability is called. 28 Tivoli Service Automation Manager V7.2.4 Extensions Guide This capability sets a boolean value to either enable or disable the field. The value is set to true, which means that the field is read only. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var pt = this.tsamGetField(„Project Team”); pt.tsamCall(„setReadOnly”, true); }, }); For an overview of available fields and capabilities, refer to “API reference for the self-service user interface” on page 58. Adding widgets and event handlers Add your own widgets and event handlers to enhance the functionality of a Tivoli Service Automation Manager offering. Before you begin Ensure that your Tivoli Service Automation Manager is up and running and that the user interface is visible. About this task It is advisable that you extend the offerings by first duplicating the original offering and extending the duplicate. In this way, if you ever need to install any upgrades to the original offering, the extended offering will not be overwritten. Procedure 1. Find and note the offering name: a. On the management server, log on to the Tivoli Service Automation Manager administrative interface as the catalog user. b. Select Go To > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify and select it. d. In the Select Action menu, click Duplicate an Offering. e. Take note of the duplicated offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. What to do next Depending on what you want to add, proceed to one of the following tasks. Chapter 4. Self-service user interface extension points 29 Adding custom widgets: You can use the extensibility API to add custom widgets that enhance the functionality of an offering. The container for these widgets is called custom section. You can add as many custom sections to a panel as needed. The contents of a custom section can either be directly coded into your extension or can be contained in an external HTML file. For more information on creating a separate HTML file, see “External HTML file content” on page 32. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetHtml and tsamAddCustomSection functions. Example The following code example uses the tsamGetHtml function to load an external HTML into a reference variable, and uses this reference as input for the tsamAddCustomSection function: dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var html = this.tsamGetHtml(„/custom/html/example.html”); this.tsamAddCustomSection(„mySection”, html); }, }); Three parameters are possible for tsamAddCustomSection: v The first parameter of this function identifies the section for further referencing. The section identifier must be unique. v The second parameter defines the contents of the custom section. It can either be a reference to an HTML file or a string that contains HTML elements. v The third parameter is optional. The parameter contains all CSS classes that apply to the custom section. If no value is specified, "input_row_short" is assumed by default. If you have your own CSS classes, you can load them by using the tsamLoadCSS function and add them to the default input_row_short class. The following example is an external HTML file, example.html that is loaded by the JavaScript. For more information, see “External HTML file content” on page 32.

Goes into service request!
30 Tivoli Service Automation Manager V7.2.4 Extensions Guide Apple Banana Cherry

Adding custom event handlers: Connect your own event handlers to both existing widgets and your own custom section widgets. About this task Connecting event handlers to widgets entails subscribing to events that occur on a widget, for example, a mouse click or a value change. When the event happens, the system calls your local event handler (an arbitrary JavaScript function in the extension). Note: Your event handler function might not be the only one subscribing to a specific event. New subscriptions are added to a list of subscribers, all of which are called in the order of their subscription. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetField and tsamConnect functions. Example In the following code example, the function tsamGetField gets a reference to the API field responsible for the Project Name text field. Then it subscribes local function _onChangeProject to the onChange event of the field. As a result, whenever the user enters information or changes the value of the text field, _onChangeProject is called. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var pn = this.tsamGetField(„Project Name”); this.tsamConnect(pn, „onChange”, this, „_onChangeProject”); }, _onChangeProject: function() { //modify as required }, }); v The first parameter is the source object, which can either be a field reference obtained by tsamGetField or a real widget reference obtained by tsamGetSectionWidget. v The second parameter is the event name, which can be any valid Document Object Model event. v The third parameter is the context in which an event handler is called. If the handler is a local function, it must be set to this. v The fourth parameter is the name of the local handler function to be called. Chapter 4. Self-service user interface extension points 31 The following code example adds a custom section to an offering that contains a text box. A text box reference is then obtained by using the tsamGetSectionWidget function. The widget is identified by its name attribute. Then, with the tsamConnect function, the custom text box is connected to _onChangeCustom, a custom local event handling function. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var html = this.tsamGetHtml(„/custom/html/example.html”); this.tsamAddCustomSection(„mySection”, html); var textBox = this.tsamGetSectionWidget(„mySection”, „VST_ATTR”); this.tsamConnect(textBox, „onChange”, this, „_onChangeCustom”); }, ` _onChangeCustom: function() { //modify as required } }); v The first parameter identifies the custom section from which you want to retrieve the widget reference. It must have the same name as the one in the section you previously added with the tsamAddCustomSection function. v The second parameter identifies the widget whose name attribute matches the parameter within that section. The following example is an external HTML file example.html that is loaded by the JavaScript. For more information, see “External HTML file content.” External HTML file content: Learn more about defining custom widgets and event handlers in the external HTML file. The content for the custom HTML file used to provide the offerings is not fully formed HTML. The and tags are omitted, because the custom section is actually a

in the panel markup. The API automatically supplies the

tags, which serve as a container for custom sections. Tip: Although it is possible for the user to supply the

tags, it is not recommended because double

tags are then created in the code as a result:

If you want to use more complex sections or structures in your section insert them into a markup, as shown in the following example. You can also place the widget code in nested

elements. It is possible to add simple HTML input elements such as , or , and to use Dojo widgets, because the HTML content is parsed by the Dojo parser when the custom section is created. 32 Tivoli Service Automation Manager V7.2.4 Extensions Guide Note: If you want to change the widgets in your extension code later on, you must use Dojo widgets instead of simple HTML input elements. HTML element attributes dojotype Identifies the Dojo widget class used for an element. Learn more about Dojo types at http://dojotoolkit.org/api/ . name Specifies the unique name of an element. The name is used as a key for storing the element value with the Tivoli Service Automation Manager in the virtual server template, software resource template, or service request. storeAt Determines where the value of an element is stored. The value can be stored in: v Custom service request - storeAt="CUSTOM" - If the extension points of the advanced workflow are used, this value is submitted to the subservice request that is launched as the advanced workflow extension. v Virtual server template - storeAt="VST" - Useful when dealing with virtual servers. v Software resource template - storeAt="SRT" - Useful when dealing with software packs or products. v Service request - storeAt="SR" or omitted - The default value, useful when you need the service request directly. Remember: The service offering must support this attribute, that is, the attribute must exist on the Specifications tab of the offering. required Determines if the value of this element is mandatory to submit the request. Possible values are true and false. If this attribute is omitted, the value is determined based on the name attribute. If the storeAt attribute is set to SR or was omitted, Tivoli Service Automation Manager correlates the "Mandatory" flag of the offering attribute that has the same name, for example: In this example, the required attribute is determined from the value of the "Mandatory" flag of the offering attribute "OFFERING_ATTR". Note: The required attribute does not work on dijit.form.TextBox elements, use dijit.form.ValidationTextBox instead. Example HTML content

Goes into service request!
Apple Chapter 4. Self-service user interface extension points 33 Banana Cherry

Employing REST calls in the extensions You can use REST queries in your extensions, to make specific information show up in your own widgets or to enrich the existing widgets of the offering panels. About this task REST (Representational State Transfer) is a way of communicating between systems by using standard HTTP methods such as GET, PUT, or POST. In Tivoli Service Automation Manager, it is used to exchange information between the self-service user interface and the Service Automation Manager core engine. Tivoli Service Automation Manager exposes REST data using the Maximo REST servlet. The data that is exposed is called object structures. An object structure is a view of a specific database entity that is used to query its attributes and relationships to other entities. The entity does not have to be a database table; it can also be a view that is only an aggregation of several other tables. Usually, the object structure does not expose all possible attributes of an entity for the sake of low network traffic impact. Using the REST API to query information from the core engine, in combination with adding custom widgets and event handling, allows you to extend the functionality of the self-service user interface to a large extent. You can use the storeAt attribute in custom widgets, which allows you to choose the destination for data input from the panel. This enables you to dynamically extend the Tivoli Provisioning Manager workflows to accept new parameters in either software resource templates or virtual server templates, without having to change the existing offering definition. For a detailed reference on the REST API, refer to “API reference for the self-service user interface” on page 58. Example REST queries: Learn more about the REST queries available in the self-service user interface. The following example query is a simple HTTP GET request. The assumption is that the session has already been authenticated, which in the context of the self-service user interface extensions, is always true. https://machine:9443/maxrest/rest/os/PMRDPRSR?_format=json&_compact=1 The query consists of four parts: machine:9443 Machine name and port. maxrest/rest/os REST servlet location. PMRDPRSR Object structure name. ?_format=json&_compact=1 Additional filtering and formatting parameters. 34 Tivoli Service Automation Manager V7.2.4 Extensions Guide In this example query no filtering was used, so the result for the object structure PMRDPRSR (service requests) is as follows: { "QueryPMRDPRSRResponse": { "rsStart": 0, "rsCount": 123, "rsTotal": 123, "PMRDPRSRSet": { "SR": [ { "AFFECTEDDATE": "2004-06-18T14:18:00+02:00", "AFFECTEDEMAIL": "[email protected]", "AFFECTEDPERSON": "LIBERI", "CHANGEBY": "WILSON", "CHANGEDATE": "2005-02-02T08:38:28+01:00", "CLASS": "SR", "DESCRIPTION": "Request for OS upgrade to Windows XP", "ORGID": "EAGLENA", "OWNER": "CALDONE", "PLUSPADDRISCHANGED": false, "PLUSPPOREQ": false, "REPORTDATE": "2004-06-18T14:18:47+02:00", "REPORTEDBY": "LIBERI", "REPORTEDEMAIL": "[email protected]", "REPORTEDPHONE": "(617) 555-9087", "REPORTEDPRIORITY": 2, "SITEID": "BEDFORD", "STATUS": "QUEUED", "STATUSDATE": "2005-02-02T08:38:28+01:00", "TICKETID": "1001", "TICKETUID": 2 }, { "AFFECTEDDATE": "2004-06-18T14:29:00+02:00", "AFFECTEDEMAIL": "[email protected]", "AFFECTEDPERSON": "WINSTON", "CHANGEBY": "WILSON", "CHANGEDATE": "2005-02-02T08:40:06+01:00", "CLASS": "SR", "DESCRIPTION": "Conference room is too hot", "ORGID": "EAGLENA", "OWNERGROUP": "TIER1", "PLUSPADDRISCHANGED": false, "PLUSPPOREQ": false, "REPORTDATE": "2004-06-18T14:29:16+02:00", "REPORTEDBY": "WINSTON", "REPORTEDEMAIL": "[email protected]", "REPORTEDPHONE": "(617) 555-4079", "REPORTEDPRIORITY": 2, "SITEID": "BEDFORD", "STATUS": "QUEUED", "STATUSDATE": "2005-02-02T08:40:06+01:00", "TICKETID": "1002", "TICKETUID": 3 }, (...) You can filter for specific criteria, for example, only service requests for a certain user called WINSTON. In this case, the query URL is: https://machine:9443/maxrest/rest/os/PMRDPRSR?_format=json&_compact=1&REPORTEDBY=WINSTON The response changes accordingly, with the value for rsCount changed from 123 to 2: Chapter 4. Self-service user interface extension points 35 { "QueryPMRDPRSRResponse": { "rsStart": 0, "rsCount": 2, "rsTotal": 2, "PMRDPRSRSet": { "SR": [ { "AFFECTEDDATE": "2004-06-18T14:29:00+02:00", "AFFECTEDEMAIL": "[email protected]", "AFFECTEDPERSON": "WINSTON", "CHANGEBY": "WILSON", "CHANGEDATE": "2005-02-02T08:40:06+01:00", "CLASS": "SR", "DESCRIPTION": "Conference room is too hot", "ORGID": "EAGLENA", "OWNERGROUP": "TIER1", "PLUSPADDRISCHANGED": false, "PLUSPPOREQ": false, "REPORTDATE": "2004-06-18T14:29:16+02:00", "REPORTEDBY": "WINSTON", "REPORTEDEMAIL": "[email protected]", "REPORTEDPHONE": "(617) 555-4079", "REPORTEDPRIORITY": 2, "SITEID": "BEDFORD", "STATUS": "QUEUED", "STATUSDATE": "2005-02-02T08:40:06+01:00", "TICKETID": "1002", "TICKETUID": 3 }, { "ACTUALFINISH": "2004-10-05T15:14:32+02:00", "AFFECTEDDATE": "2004-10-05T15:13:00+02:00", "AFFECTEDEMAIL": "[email protected]", "AFFECTEDPERSON": "WINSTON", "CHANGEBY": "WILSON", "CHANGEDATE": "2004-10-05T15:14:41+02:00", "CLASS": "SR", "CLASSSTRUCTUREID": "1202", "DESCRIPTION": "Reset windows password", "OWNERGROUP": "TIER1", "PLUSPADDRISCHANGED": false, "PLUSPPOREQ": false, "REPORTDATE": "2004-10-05T15:13:01+02:00", "REPORTEDBY": "WINSTON", "REPORTEDEMAIL": "[email protected]", "REPORTEDPHONE": "(617) 555-4079", "REPORTEDPRIORITY": 2, "STATUS": "RESOLVED", "STATUSDATE": "2004-10-05T15:14:32+02:00", "TICKETID": "1095", "TICKETUID": 143 } ] } } } You can also add comma-separated values to the filter parameter: https://machine:9443/maxrest/rest/os/PMRDPRSR?_format=json&_compact=1&REPORTEDBY=WINSTON,LOU The result is the union set of all service requests that have been reported by either WINSTON or LOU. 36 Tivoli Service Automation Manager V7.2.4 Extensions Guide Using REST queries in widgets: Use the REST queries to make the input data from the Maximo server display in the widgets. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamRestGetObjectStructure function. Example The following code example creates a custom section containing a drop-down list box. The list is filled by using a REST query for all service requests submitted by user WINSTON: dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var html = this.tsamGetHtml(„/custom/html/example.html”); this.tsamAddCustomSection(„mySection”, html); var dropdown = this.tsamGetSectionWidget("mySection", "SR_ATTR"); var params = {}; params.REPORTEDBY = "WINSTON"; var deferred = this.tsamRestGetObjectStructure("PMRDPRSR", params); deferred.addCallback(function(result) { for( var i in result.QueryPMRDPRSRResponse.PMRDPRSRSet.SR) { var theSR = result.QueryPMRDPRSRResponse.PMRDPRSRSet.SR[i]; dropdown.addOption({value: theSR.TICKETID, label:theSR.DESCRIPTION, item: null}); } }); } }); v The first parameter of tsamRestGetObjectstructure is the name of the object structure to query. v The second parameter is a map of filter parameters. If omitted, no filter is applied. The example.html file content: The return value of tsamRestGetObjectstructure is a dojo.deferred, which requires the definition of a callback function.tsamRestGetObjectStructure is an asynchronous function, and it does not return results immediately. The function retrieves data via an HTTP GET request over the network which might take some time. Therefore, the caller must provide a callback function, which is called on data arrival. The preceding example uses an anonymous callback function, which is a commonly used pattern designed for this purpose, but you a named function can also be used. The function must take one parameter result which contains the query results of the tsamRestGetObjectstructurecall. Important: The structure of the results depends on the object structure that has been used. In this case, PMRDPRSR was queried, so the result is an array of service request objects. You can find the structure of other object queries by manually calling the query in the web browser and looking at the results: Chapter 4. Self-service user interface extension points 37 { "QueryPMRDPVRPR1Response": { "rsStart": 0, "rsCount": 1, "rsTotal": 3, "PMRDPVRPR1Set": { "PMRDPVRP": [ { "CEC_HOST_PLATFORM_ID": 0, "DUALVIO_MODE": false, "HYPERVISOR_TYPE": "Xen", "HYPER_THREAD_SUPPORT": false, "IS_ENABLED": false, "MAXVCPU": 8, "MAX_CPU_UNITS": 40, "MAX_MEM_MB": 8192, "NAME": "Xen Local Disk", "NO_IMAGES_VALUE": false, "NO_ODD_VCPU": true, "NO_SERVERS_VALUE": false, "ORDER": 0, "PMRDPVRPID": 1, "PTOVCPUFACTOR": 1.0, "PVID_MODE": false, "RESOURCE_HOST_ID": 0, "SMI_BLOCKIPADDRESSONEXIT": false, "SMI_MAXIMUMSAVEDIMAGESPERUSER": 0, "SMI_UNLIMITED_IMAGES": true, "TPFILEREPOSITORY_ID": 0, "TPSERVER_ID": 0, "TPSERVER_IMAGE_REPO_ID": 0, "TPSPAREPOOL_ID": 0 } ] } } } This query example uses a different object structure, PMRDPVRPR1, to query Tivoli Service Automation Manager resource pools. The response is similar to the previous query (PMRDPRSR), only the naming has changed. In the extension, such query response would translate to: result.QueryPMRDPVRPR1Response.PMRDPVRPR1Set.PMRDPVRP where PMRDPVRP is an array of all results. To get the hypervisor type of the first pool, for example, you can access the data in the following way: var hvType = result.QueryPMRDPVRPR1Response.PMRDPVRPR1Set.PMRDPVRP[0].HYPERVISOR_TYPE; Extending the wizard offerings You can modify or extend existing wizard offerings for Tivoli Service Automation Manager self-service user interface. About this task The current self-service user interface extensibility wizard API supports extending existing wizard offerings with: v Changing the appearance of a wizard page – Setting the title of a wizard page – Setting the description of a wizard page – Hiding and showing widgets on a wizard page 38 Tivoli Service Automation Manager V7.2.4 Extensions Guide - Hiding individual widgets on a wizard page - Hiding groups of widgets on a wizard page - Making widgets on a wizard page read only – Setting a wizard page as optional v Changing widget values on a wizard page – Setting default values for widgets on a wizard page – Restricting or locking values on a wizard page v Adding custom widgets and event handlers to a wizard page – Adding custom widgets to a wizard page – Adding custom event handlers to widgets on a wizard page – Making REST calls on a wizard page – Validating a wizard page before further navigation v Adding a page to the wizard v Removing a page from the wizard Changing the appearance of a wizard page You can set a title and a description of a wizard page, or make a page optional. Moreover, you can hide specific widgets or groups of widgets on a wizard page, or make them read only. Before you begin Ensure that yourTivoli Service Automation Manager installation is up and running, and that the user interface is visible. Procedure 1. Find and note the offering name: a. On the management server, log on to the Maximo user interface as the catalog user. b. Select Go to > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify. d. Take note of the offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. Example The following code example shows the file skeleton for offering PMRDP_0201A_72: dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { }, Chapter 4. Self-service user interface extension points 39 tsamCustomDestroy: function() { }, }); What to do next Depending on what you want to change, proceed to one of the following tasks. Setting the title of a wizard page: You can add a title to a page on your wizard. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage and tsamCall functions. 3. Call the setTitle capability. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The setTitle capability is called on that page. This capability sets a title value for the page. The title value is set to DefaultTitle. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); page.tsamCall(“setTitle”, “DefaultTitle”); }, }); Setting the description of a wizard page: You can add your own description for a page on your wizard. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage and tsamCall functions. 3. Call the setDesc capability. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The setDesc capability is called on the page. This capability sets a description value for that page. The description value is set to DefaultDesc. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { 40 Tivoli Service Automation Manager V7.2.4 Extensions Guide var page = this.tsamGetPage(“Page ProjectDetails”); page.tsamCall(“setDesc”, “DefaultDesc”); }, }); Hiding and showing widgets on a wizard page: On a wizard page, you can hide specific widgets or groups of widgets, or make them read only. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamGetField and tsamCall functions. 4. Call capabilities that are valid on the fields. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The page then gets a reference to a field that provides API capabilities for the Project Description field on the Page ProjectDetails page. The setDisplay capability is called in the field. This capability sets a visibility value for that text field. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); var pn = page.tsamGetField(“Project Description”); pn.tsamCall(“setDisplay” “none”); }, }); Hiding widgets on a wizard page: To keep some unnecessary information from the user, hide a widget on a wizard page. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamGetField and tsamCall functions. 4. Call the setDisplay capability, or other valid capabilities. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The page then gets a reference to a field that providesAPI capabilities for the Project Description field on the Page ProjectDetails page. In the field, the setDisplay capability is called. This capability sets a visibility value for that text field. Three values are available: Chapter 4. Self-service user interface extension points 41 none Hides the widget. inline Displays the widget without any formatting. block Displays the widget by reformatting it with a line-break. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var pd = this.tsamGetField(„Project Description”); pd.tsamCall(„setDisplay”, „none”); }, }); For an overview of available fields and capabilities, refer to “API reference for the self-service user interface” on page 58. Hiding groups of widgets on a wizard page: On a wizard page, you can hide whole groups of widgets at once instead of hiding them one by one. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamGetGroup and tsamCall function. 4. Call the setDisplay capability, or other valid capabilities. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The page then gets a reference to a group field that provides API capabilities for the entire Software section on the wizard page. The section contains a number of widgets. Any capability called on it results in a call to each of the widgets in the group. In the field group, the setDisplay capability is called. This capability sets a visibility value for that field group. The value is set to none, which means the entire Software section is invisible. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page SoftwareInstall”); var pn = page.tsamGetGroup(“Software”); pn.tsamCall(“setDisplay” “none”); }, }); 42 Tivoli Service Automation Manager V7.2.4 Extensions Guide Making widgets on a wizard page read only: On a wizard page, make your widgets read only so that the user can see them, but is not able to modify any values. Procedure 1. 2. 3. 4. Edit the tsamCustomInit function. Use the tsamGetPage function. Use the tsamGetField and tsamCall functions. Call the setReadOnly capability, or other valid capabilities. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The page then gets a reference to a field that provides API capabilities for the Project Team menu on the Page ProjectDetails wizard page. In the field, the setReadOnly capability is called. This capability sets a boolean value to either enable or disable the field. The value is set to true, which means the field is read only. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); var pn = page.tsamGetField(“Project Team”); pn.tsamCall(“setReadOnly” true); }, }); Changing widget values on a wizard page On a wizard page, you can modify widget values by setting default values and locking or restricting them. Before you begin Ensure that yourTivoli Service Automation Manager installation is up and running, and that the user interface is visible. Procedure 1. Find and note the offering name: a. On the management server, log on to the Maximo user interface as the catalog user. b. Select Go to > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify. d. Take note of the offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. Chapter 4. Self-service user interface extension points 43 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. What to do next Depending on what you want to change, proceed to one of the following tasks. Setting default values for widgets on a wizard page: Set default values so that a wizard page always starts with a specific value. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamGetField and tsamCall functions. 4. Call the setValue capability, or other valid capabilities. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The page then gets a reference to a field that provides API capabilities for the Project Name text field on the wizard page. In the field, the setValue capability is called. This capability sets a default value for that text field. The default value is set to DefaultProject. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); var pn = page.tsamGetField(“Project Name”); pn.tsamCall(“setValue” “DefaultProject”); }, }); Adding custom widgets and event handlers to a wizard page Add your own widgets and event handlers to a wizard page to enhance the functionality of a Tivoli Service Automation Manager offering. Before you begin Ensure that yourTivoli Service Automation Manager installation is up and running, and that the user interface is visible. Procedure 1. Find and note the offering name: a. On the management server, log on to the Maximo user interface as the catalog user. b. Select Go to > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify. d. Take note of the offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 44 Tivoli Service Automation Manager V7.2.4 Extensions Guide 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. What to do next Depending on what changes you want to introduce, proceed to one of the following tasks. Adding custom widgets to a wizard page: You can use the extensibility API to add custom widgets to a wizard page to enhance the functionality of an offering. The container for such widgets is called a custom section. You can add as many custom sections to a page as needed. The contents of a custom section can either be directly coded into your extension or are contained in an external HTML file. For more information about creating a separate HTML file, see “External HTML file content” on page 32. Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamGetHtml and tsamAddCustomSection functions. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The example uses the tsamGetHtml function to load an external HTML document into a reference variable, then uses the reference as an input for the tsamAddCustomSection function. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); var html = this.tsamGetHtml(„/custom/html/example.html”); page.tsamAddCustomSection(„mySection”, html, „input_row_short”); }, }); v The first parameter of this function identifies the section for further referencing. The section identifier must be unique. v The second parameter defines the contents of the custom section. This parameter can either be a reference to an HTML file, as in the preceeding example, or a string containing HTML elements directly. v Optional: The third parameter contains all CSS classes that apply to the custom section. If you have your own CSS classes, you can load them by using the Chapter 4. Self-service user interface extension points 45 tsamLoadCSS function, and add them to the default input_row_short class. The string then is input_row_short myOtherClass. Adding custom event handlers on a wizard page: On a wizard page, you can connect custom event handlers to both existing Tivoli Service Automation Manager widgets and your own custom section widgets. About this task Connecting event handlers to widgets means subscribing to events that occur on a widget, for example, a mouse click or a value change. When the event happens, the system calls your local event handler (an arbitrary JavaScript function in the extension). Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamGetField and tsamConnect functions. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The page then gets reference to a field to which the event handler is attached. The code example gets a reference to the API field responsible for the Project Name text field. Then it subscribes local function _onChangeProject to the onChange event of the field. As a result, whenever the user enters information or changes the value of the text field, _onChangeProject is called. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); var pn = page.tsamGetField(“Project Name”); this.tsamConnect(pn, „onChange”, this, „_onChangeProject”); }, _onChangeProject: function() { //modify as required }, }); 46 Tivoli Service Automation Manager V7.2.4 Extensions Guide Making REST calls on a wizard page: Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Use the tsamRestGetObjectStructure function. Example The following code example creates a custom section on a wizard page that contains a menu. The menu is filled by using a REST query for all service requests reported by user WINSTON. The return value of tsamRestGetObjectstructure is dojo.deferred, and it requires the definition of a call-back function. dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); var html = this.tsamGetHtml(„/custom/html/example.html”); page.tsamAddCustomSection(„mySection”, html, “input_row_short “); var dropdown = page.tsamGetSectionWidget("mySection", "SR_ATTR"); var params = {}; params.REPORTEDBY = "WINSTON"; var deferred = this.tsamRestGetObjectStructure("PMRDPRSR", params); deferred.addCallback(function(result) { for( var i in result.QueryPMRDPRSRResponse.PMRDPRSRSet.SR) { var theSR = result.QueryPMRDPRSRResponse.PMRDPRSRSet.SR[i]; dropdown.addOption({value: theSR.TICKETID, label:theSR.DESCRIPTION, item: null}); } }); } }); v The first parameter of tsamRestGetObjectstructure is the name of the objectstructure to query. v The second parameter is a map of filter parameters. If this parameter is omitted, no filters are applied. The following example is an external HTML file example.html that is loaded by the JavaScript. For more information, see “External HTML file content” on page 32. Validating a wizard page before further navigation: Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage function. 3. Call the setValidate capability. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. On the page, capability validate is called. Their capability validates the wizard page by calling the JavaScript method, as specified in the third argument, before navigating further in the wizard. Chapter 4. Self-service user interface extension points 47 dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); page.tsamCall(“setValidate”, this, “_isProjectNameEmpty”); }, _isProjectNameEmpty: function(){ // check if the Project Name field is empty and return true } }); Setting a wizard page as optional Procedure 1. Edit the tsamCustomInit function. 2. Use the tsamGetPage and tsamCall functions. 3. Call the isOptional capability. Example In the following code example, function tsamGetPage gets a reference to a page that provides API capabilities for the Page ProjectDetails page on the Create Project with Vmware Servers wizard. The isOptional capability is called on the page. This capability sets a boolean value to set the page as an optional page. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page ProjectDetails”); page.tsamCall(“isOptional”, “true”); }, }); Adding a page in the wizard You can add pages to your wizard. Before you begin Ensure that yourTivoli Service Automation Manager installation is up and running, and that the user interface is visible. Procedure 1. Find and note the offering name: a. On the management server, log on to the Maximo user interface as the catalog user. b. Select Go to > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify. d. Take note of the offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 48 Tivoli Service Automation Manager V7.2.4 Extensions Guide 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. 6. Edit the tsamCustomInit function. 7. Use the tsamCreateCustomPage function. 8. Use the tsamAddPage function. Example In the following code example, function tsamCreateCustomPage gets a reference to a new page that provides API capabilities for the Page Custom page on the Create Project with Vmware Servers wizard. The values of the title, description, and contents of the new page are all set. The page is then added to the wizard to a location specified by the user. dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamCreateCustomPage(“Page Custom”); page.tsamCall(“setTitle”, “CustomPage Title”); page.tsamCall(“setDesc”, “CustomPage Description”); var html = this.tsamGetHtml(„/custom/html/example.html”); page.tsamAddCustomSection(„mySection”, html, „input_row_short”); this.tsamAddPage(page, 3); }, }); Removing a page from the wizard You can remove pages from your wizard. Before you begin Ensure that yourTivoli Service Automation Manager installation is up and running, and that the user interface is visible. Procedure 1. Find and note the offering name: a. On the management server, log on to the Maximo user interface as the catalog user. b. Select Go to > Service Request Manager Catalog > Offerings. c. Using the Description filter, search for the offering that you want to modify. d. Take note of the offering ID (ITEMNUM). The pattern for the Tivoli Service Automation Manager offerings is PMRDP_nnnnA_72, where nnnn is the numeric identifier. 2. Switch to your development environment. 3. Using Eclipse, open the workspace. 4. Open the custom_web project and navigate to WebContent > js > custom > tsam > dijit > request. Chapter 4. Self-service user interface extension points 49 5. Create a new file with the same name as the ID of the offering, for example PMRDP_nnnnA_72.js. 6. Edit the tsamCustomInit function. 7. Use the tsamGetPage function. 8. Use the tsamRemovePage function. Example dojo.provide("custom.tsam.dijit.request.PMRDP_0201A_72"); dojo.require("ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72"); dojo.declare("custom.tsam.dijit.request.PMRDP_0201A_72", [ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72], { tsamCustomInit: function() { var page = this.tsamGetPage(“Page OtherSettings”); this.tsamRemovePage(page); }, }); Globalizing extensions You need to globalize the extension if you are planning to deploy it in a multi-language environment. About this task User interface extensions make use of the standard Dojo globalization features. These features require little coding. The following procedure describes how to implement globalization in the extensions. Procedure 1. Import the Dojo globalization functionality into your extension. 2. Load your resource bundle containing the localized strings which you want to use. 3. Use the resource bundle as a replacement for the hard-coded strings in your code. Remember: v If you call dojo.requireLocalization (custom.tsam.dijit, uiStringTable), Dojo searches for an nls folder in the custom/tsam/dijit package in your extension. It then tries to load the uiStringTable.js file corresponding with the locale that is set in the Web browser. The locale is another subdirectory of nls, which must contain the same uiStringTable.js file, but with translated contents. v Always use this.customStringTable as a variable for your local resource bundle. Never use this._uiStringTable or this._requestStringTable because the original resource bundle from Tivoli Service Automation Manager will be overwritten. Example The following example demonstrates how to set the heading of the logon page using globalization: dojo.provide("custom.tsam.dijit.Login"); dojo.require("ibm.tivoli.simplesrm.srm.dijit.Login"); 50 Tivoli Service Automation Manager V7.2.4 Extensions Guide //Step 1: import the dojo localization functionality dojo.requireLocalization("custom.tsam.dijit", "uiStringTable"); dojo.declare("custom.tsam.dijit.Login", [ibm.tivoli.simplesrm.srm.dijit.Login], { tsamCustomInit: function() { //Step 2: load the resource bundle into a variable this.customStringTable = dojo.i18n.getLocalization("custom.tsam.dijit", "uiStringTable"); //Step 3: use the resource bundle as a replacement for hard strings this.tsamSetLoginHeading(this.customStringTable.LoginHeading); }, }); This example requires the following additional files to be present in your custom_web project: v js/custom/tsam/dijit/nls/uiStringTable.js (default, English) v js/custom/tsam/dijit/nls/de/uiStringTable.js (German) v js/custom/tsam/dijit/nls/es/uiStringTable.js (Spanish) v js/custom/tsam/dijit/nls/fr/uiStringTable.js (French) v js/custom/tsam/dijit/nls/it/uiStringTable.js (Italian) v js/custom/tsam/dijit/nls/ja/uiStringTable.js (Japanese) v js/custom/tsam/dijit/nls/ko/uiStringTable.js (Korean) js/custom/tsam/dijit/nls/pt-br/uiStringTable.js (Portuguese / Brazilian) js/custom/tsam/dijit/nls/ru/uiStringTable.js (Russian) js/custom/tsam/dijit/nls/zh/uiStringTable.js (Chinese) js/custom/tsam/dijit/nls/zh-tw/uiStringTable.js (Traditional Chinese) v v v v You can add more locales if necessary. The mentioned locales are supported by Tivoli Service Automation Manager. A resource bundle, uiStringTable.js, has the form of a JavaScript map or associative array: { LoginHeading: „My Login Heading”, AnotherToken: „Some other text” } What to do next Test your extension using the quickdeploy functionality, as described in “Testing your extension: quickdeploy” on page 52. Testing and deploying extensions Test the extension on your running test environment, or deploy it to your production environment. The development environment provides three useful features for testing and deploying your extensions: v quickdeploy: Copies the contents to the location of the deployed custom_web.war file within the application server. v quickundeploy: Removes your extension from the application server. Chapter 4. Self-service user interface extension points 51 v rebuild: Builds a new custom_web.war file for deployment in productive environments. Before you begin Check whether your local development environment has been set up in the following way: v The running Eclipse workspace contains the custom_web and custom_web_build projects. v The custom_web project contains your extension code: – JavaScript for extending the user interface. – Optional: CSS sheets for branding. v The custom_web_build project is configured for the quickdeploy Ant call. About this task Configure Ant targets quickundeploy and rebuild in the custom_web_build project. Important: Select only one build target for each Ant build configuration. Procedure 1. In Eclipse, select Run > External tools > External tools and configurations.... 2. Select the quickdeploy Ant build. 3. Click the Duplicate icon. 4. When a new item, quickdeploy(1), is created, rename it to quickundeploy. 5. Click the Targets tab and: a. Clear the quickdeploy check box. b. Select the quickundeploy check box. 6. Open the Classpath tab and: a. Ensure that the Ant Home points to the correct Ant version, that is, version 1.7.1 or later. b. Ensure that the jsch-0.1.42.jar library is in the class path. 7. Repeat steps 1 to 6 with the rebuild value to configure the rebuild target. Results You now have three build targets: quickdeploy, quickundploy, and rebuild. Testing your extension: quickdeploy Use quickdeploy to quickly update the running custom_web.war application with the latest JavaScript, HTML, and CSS content. quickdeploy remotely copies and overwrites the WebContent folder in your Tivoli Service Automation Manager test environment. The process does not affect the content of the Maximo Administrative Console. Note: v Overwriting files in deployed web applications leads to runtime errors when done with server-side components such as Java code. It works for JavaScript / Dojo source only because that code is not run on the server but transferred to the client first. Updating Java server-side code almost always requires you to restart the application server, because the class loader must be re-initialized. 52 Tivoli Service Automation Manager V7.2.4 Extensions Guide v Executing actions that rebuild and redeploy the Maximo.ear file always result in overwriting the extensions that were installed using quickdeploy. Ensure that you have built your extension to a custom_web.war file and copied it to the Maximo administrative console before executing any of the following actions: – Uninstalling and reinstalling the Tivoli Service Automation Manager – Installing Maximo or Tivoli Service Automation Manage fix packs – Installing Maximo or Tivoli Service Automation Manager test fixes – Upgrading Maximo or the Tivoli Service Automation Manager Before you begin v Ensure that the Tivoli Service Automation Manager test environment is up and running. v Ensure that the build.properties file located in your local custom_web_build project is configured, and that there are no problems with connectivity between your computer and the Tivoli Service Automation Manager test environment. Procedure 1. In Eclipse, select Run > External Tools > External Tools Configurations.... 2. Select quickdeploy, and click Run. 3. Test whether your extension works: v Close all web browser sessions on the target system, and restart your browser. v Reload the page or clean the browser cache, or both. Results Your extensions are visible in the self–service user interface. Removing your extension Depending on whether you want to remove the extension on your test environment, or on the production environment, different procedures apply. The quickundeploy feature removes all content from the WebContent folder, ensuring that no offering extensions are left. Because Tivoli Service Automation Manager depends on the existence of a deployed custom_web.war web module in its deployment descriptor, you should not use the quickundeploy feature on your production environment and delete the extension. Instead, disable it manually. If you are working on your test environment, proceed to “Running quickundeploy.” If you are working on the production environment, proceed to “Disabling your extension manually” on page 54 Running quickundeploy: Use the quickundeploy feature on your test environment to delete the contents of the WebContent folder. Before you begin v Ensure that the Tivoli Service Automation Manager test environment is up and running. v Ensure that the build.properties file located in your local custom_web_build project is configured, and that there are no problems with connectivity between your computer and the Tivoli Service Automation Manager test environment. Chapter 4. Self-service user interface extension points 53 Procedure 1. In Eclipse, select Run > External Tools > External Tools Configurations.... 2. Select quickundeploy, and click Run. 3. Test whether your extension works: v Close all web browser sessions on the target system, and restart your browser. v Reload the page or clean the browser cache, or both. Results The extension is no longer available. Disabling your extension manually: Learn how to deactivate an extension on the Tivoli Service Automation Manager production environment. About this task Tivoli Service Automation Manager depends on the existence of a deployed custom_web.war web module in its deployment descriptor. Because of that, you should not use the quickundeploy feature on your production environment and delete the extension. Instead, you can disable it manually. Procedure 1. Rename the extended offering file in the WebContent folder, so that the Tivoli Service Automation Manager cannot locate it. For example, for extension PMRDP_0201A_72, change the string to ___PMRDP_0201A_72 in the js file and rename the js file itself. 2. Rebuild and redeploy the custom_web.war file as described in “Deploying your extension: rebuild and deploy.” 3. Verify that the extension has been disabled by clicking on the offering icon in the user interface. Results The offering extension is disabled in the production environment. For example, when you click the PMRDP_0201A_72 offering panel, the plug-in searches for PMRDP_0201A_72 in the custom.tsam namespace, and when it cannot locate it, the next namespace in the hierarchy is searched. Deploying your extension: rebuild and deploy When you finish developing and testing your extensions, you must permanently deploy them to the production environment so that they are not overwritten when you reinstall or upgrade Tivoli Service Automation Manager. About this task quickdeploy changes the content of deployed web modules on the application server only, not on the Maximo administrative console. If the Maximo.ear file is rebuilt, which happens during reinstallation or upgrade of Tivoli Service Automation Manager, any extension installed with quickdeploy is overwritten. You must use the Maximo administrative console to rebuild and deploy your extension in the production environment to ensure that your changes are saved permanently. 54 Tivoli Service Automation Manager V7.2.4 Extensions Guide These tasks are described in the following sections. Rebuilding custom_web.war: Use the rebuild Ant target to rebuild the custom_web.war file so that it contains your extensions. Before you begin Ensure that your Tivoli Service Automation Manager production environment is up and running. Procedure 1. In Eclipse, select Run > External tools > External tools and configurations.... 2. Select rebuild, and click Run. The build directory of your custom_web_build project now contains a new file: custom_web.war. Tip: Back up the custom_web.war file before overwriting it. 3. Log on to the Maximo administrative console, and copy custom_web.war file to the applications/SimpleSRM folder. Depending on the operating system of the Maximo administrative console, the default directory is: v Windows v UNIX C:\IBM\SMP\maximo\applications\SimpleSRM /opt/IBM/SMP/maximo/applications/SimpleSRM What to do next Proceed to the next section and deploy the custom_web.war file on your production environment. Deploying custom_web.war: After you rebuild the custom_web.war file, you must deploy it to the production environment. Procedure 1. Ensure that the Tivoli Service Automation Manager productive environment is running. If it is not running, start MXServer. 2. Run the following set of commands to rebuild the maximo.ear file: v Windows cd C:\IBM\SMP\deployment buildmaximoear.cmd v UNIX cd /opt/IBM/SMP/maximo/deployment ./buildmaximoear.sh 3. Deploy the Maximo.ear file by running the following command: ${maximo_home}/jacl/solutions/DeployApplication.bat MAXIMO ${maximo_home}/deployment/ default/maximo.ear For example: v Windows cd C:\IBM\SMP\jacl\solutions DeployApplication.bat wasadmin wasadminpwd MAXIMO ctgNode01 MXServer c:\IBM\SMP\maximo\deployment\default\maximo.ear maximo_host webserver1 Chapter 4. Self-service user interface extension points 55 v UNIX cd /opt/IBM/SMP/jacl/solutions ./DeployApplication.sh wasadmin MAXIMO ctgNode01 MXServer /opt/IBM/SMP/maximo/deployment/default/maximo.ear maximo_host webser 4. Test if your extension works: v Close all web browser sessions on the target system, and restart your browser. v Reload the page and/or clean the browser cache. Results Your custom extensions are visible on the self-service user interface. Migrating and upgrading your extensions Learn how to migrate or upgrade Tivoli Service Automation Manager without losing the already implemented extensions. Before you begin In the process of upgrading or reinstalling Tivoli Service Automation Manager, the Maximo.ear file is rebuilt and redeployed, which results in overwriting the extensions installed with quickdeploy. Ensure that you have built your extension to a custom_web.war file, copied and deployed it to the Maximo administrative console as described in “Deploying your extension: rebuild and deploy” on page 54. About this task The custom_web.war file is a container for client-only code, which makes it possible to migrate its contents easily, as opposed to server-side JavaScript code. Important: The user interface extension depends on a specific version of the Tivoli Service Automation Manager self-service user interface extensibility API. Therefore, it is advisable that you store the custom_web.war file in the same place as other artifacts or extensions developed for this Tivoli Service Automation Manager version. For example, if you have written extension workflows for Tivoli Provisioning Manager, or added new offerings to your Tivoli Service Automation Manager installation, these artifacts are extracted from the Maximo database for migration scenarios. Migration packages generated by Maximo Migration Manager are highly dependent on the Process Manager Product version installed at the time of packages creation. Maximo supports installing migration packages only on a target system with the same Process Manager Product version as the source system. 56 Tivoli Service Automation Manager V7.2.4 Extensions Guide Migrating your extension Learn how to migrate custom extensions when migrating Tivoli Service Automation Manager. Procedure 1. Ensure that the same version of the Process Manager Product has been installed on both the source and the target system: v Base Services v Service Request Manager v Tivoli Provisioning Manager v Tivoli Service Automation Manager 2. Complete migration steps specific to the Tivoli Service Automation Manager, such as: v Importing migration manager packages v Importing other extension artifacts, such as: – Tivoli Provisioning Manager workflows – Java classes – Maximo workflows 3. Copy the custom_web.war file on your Maximo administrative console to: v Windows C:\IBM\SMP\maximo\applications\SimpleSRM UNIX /opt/IBM/SMP/maximo/applications/SimpleSRM v 4. Rebuild and redeploy Maximo.ear, as described in “Deploying your extension: rebuild and deploy” on page 54. Upgrading Tivoli Service Automation Manager with an installed extension Learn how to upgrade Tivoli Service Automation Manager without affecting your installed extensions. Procedure 1. On the Maximo administrative console, back up the following file: v Windows v UNIX C:\IBM\SMP\maximo\applications\SimpleSRM\custom_web.war /opt/IBM/SMP/maximo/applications/SimpleSRM/custom_web.war 2. Using the installer, upgrade Tivoli Service Automation Manager. 3. When the process is finished, verify that the custom_web.war file on the Maximo administrative console was not modified. Note: By default, the Tivoli Service Automation Manager installer recognizes customer extensions and does not modify them. The custom_web.war file is redeployed during the installation process If the file was modified: a. Rename the file, for example custom_web.war_orig. b. Copy the backup file into the same directory. c. Redeploy the extension as described in “Deploying your extension: rebuild and deploy” on page 54. Chapter 4. Self-service user interface extension points 57 API reference for the self-service user interface This section provides reference information for the self-service user interface extensibility API. Global API functions This section lists the global API functions that are applicable to the entire self-service user interface. These functions are called when the user interface is loaded. Table 1. Global API functions for the self-service user interface apply to the following class: Class in Tivoli Service Automation Manager Class in custom extension ibm.tivoli.simplesrm.srm.dijit.SimpleSrmApp custom.tsam.dijit.SimpleSrmApp Table 2. Global API functions for the self-service user interface Function name Function description Function parameters tsamAddStatusProjectMapping () {string}offItemNum By using this function, you can add a status to an offering. The statuses that are permitted are based on the offerings. The particular projects that can be selected are based on their status for the particular offering. For example, if the offering is Cancel Project, the projects that are available for selection are current {string}enStatus and future projects, the canceled projects are not shown. So if you write an extension calling this function, and set the Cancel Project offering and decommissioned as arguments, decommissioned project becomes available for selection because the decommissioned status is then permitted for the Cancel Project offering. For new or duplicate offerings, specify the status that can be selected by calling this function. Only one status can be specified for each call, if more than one status is specified, call the API once for each status. The ITEMNUM of the offering where mapping is added. This parameter must match the file name of the offering on the self-service user interface without the .js extension. The status string that is not translated, for example: DECOMMISSIONED and DRAFT. The functions vary for dialogs and wizards: Table 3. Global API functions for dialogs apply to the following offerings: 58 Offering name Offering class in Tivoli Service Automation Manager Cancel Project ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0218A_72 custom.tsam.dijit.request.PMRDP_0218A_72 Add Server from Saved Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0248A_72 custom.tsam.dijit.request.PMRDP_0248A_72 Tivoli Service Automation Manager V7.2.4 Extensions Guide Offering class in custom extension Table 3. Global API functions for dialogs apply to the following offerings: (continued) Offering name Offering class in Tivoli Service Automation Manager Offering class in custom extension Create Project from Saved Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0249A_72 custom.tsam.dijit.request.PMRDP_0249A_72 Modify Reservation ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0219A_72 custom.tsam.dijit.request.PMRDP_0219A_72 Modify Server Resources ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0251A_72 custom.tsam.dijit.request.PMRDP_0251A_72 Remove Server ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0253A_72 custom.tsam.dijit.request.PMRDP_0253A_72 Remove Saved Images ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0250A_72 custom.tsam.dijit.request.PMRDP_0250A_72 Create Server Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0245A_72 custom.tsam.dijit.request.PMRDP_0245A_72 Restore Server from Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0246A_72 custom.tsam.dijit.request.PMRDP_0246A_72 Start Server ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0255A_72 custom.tsam.dijit.request.PMRDP_0255A_72 Stop Server ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0256A_72 custom.tsam.dijit.request.PMRDP_0256A_72 Restart Server ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0257A_72 custom.tsam.dijit.request.PMRDP_0257A_72 Reset Server Password ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0258A_72 custom.tsam.dijit.request.PMRDP_0258A_72 Install Software ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0400A_72 custom.tsam.dijit.request.PMRDP_0400A_72 Table 4. Global API functions for dialogs Function name Function description Function parameters tsamAddCustomSection () Adds a custom html section

to the extension. {string} sectionId The ID attribute for this section. Must be unique. To prevent name conflicts, always use the prefix tsam. {string or object} htmlData The inner html data to use as contents in this section. Can be obtained by tsamGetHtml(). {string} className (optional) The class attribute for this section. Describes one or more CSS classes to style this section. The section is internally registered for easier usage. tsamGetSectionWidget () Returns a reference to a {string} sectionId widget that was created in a custom html section. The widget returned is a full-fledged dojo widget and {string} widgetName can be used as such. tsamRemove CustomSection () Removes a custom html section in this extension. The custom section that contains the required widget. Must be created via tsamAddCustomSection(). The name of the required widget. Defined using the html-attribute name. Reference or Null. Return parameter is Reference if the widget was found. Otherwise, it is Null. {string} sectionId The ID of the section to remove. The section must have been created using tsamCreateCustomSection(). Chapter 4. Self-service user interface extension points 59 Table 4. Global API functions for dialogs (continued) Function name Function description Function parameters tsamGetField () {string} fieldName Retrieves a field class for a specific offering widget. The field can be used to call capabilities upon. The capabilities are provided by the field class and may be restricted by the offering that is being extended. The name of the required field, as exposed by the offering API. tsamGetGroup () {string}groupName Retrieves a set of field classes for a specific offering API. The group is identified by a group name. Any capability call on the group will be invoked on every group member. The name of the required group, as exposed by the offering API. tsamConnect () Wrapper function for dojo.connect(). Accepts either plain dojo widgets that were retrieved from a call to tsamGetSectionWidget() or accepts the instances of Tivoli Service Automation Manager field class that were retrieved from calls to tsamGetField(). source The source of the event. Can be a widget or field class. event The event to subscribe to. For example, onClick, onChange, or else. context The context object on which the function method can be called. method The method to call on the context. Table 5. Global API functions for wizards apply to the following offerings: 60 Offering name Offering class in Tivoli Service Automation Manager Create User ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0231A_72 custom.tsam.dijit.request.PMRDP_0231A_72 Create Team ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0235A_72 custom.tsam.dijit.request.PMRDP_0235A_72 Create Project with VMware Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0201A_72 custom.tsam.dijit.request.PMRDP_0201A_72 Create Project with POWER LPAR Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0202A_72 custom.tsam.dijit.request.PMRDP_0202A_72 Create Project with z/VM Linux Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0204A_72 custom.tsam.dijit.request.PMRDP_0204A_72 Create Project with KVM Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0205A_72 custom.tsam.dijit.request.PMRDP_0205A_72 Create Project with POWER LPAR Servers via IBM Systems Director VMControl ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0206A_72 custom.tsam.dijit.request.PMRDP_0206A_72 Add VMware Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0211A_72 custom.tsam.dijit.request.PMRDP_0211A_72 Add POWER LPAR Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0212A_72 custom.tsam.dijit.request.PMRDP_0212A_72 Add z/VM Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0214A_72 custom.tsam.dijit.request.PMRDP_0214A_72 Add KVM Servers ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0215A_72 custom.tsam.dijit.request.PMRDP_0215A_72 Tivoli Service Automation Manager V7.2.4 Extensions Guide Offering class in custom_web Table 5. Global API functions for wizards apply to the following offerings: (continued) Offering name Offering class in Tivoli Service Automation Manager Offering class in custom_web Add POWER LPAR Servers via IBM Systems Director VMControl ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0216A_72 custom.tsam.dijit.request.PMRDP_0216A_72 Register VMware Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0222A_72 custom.tsam.dijit.request.PMRDP_0222A_72 Register POWER LPAR Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0223A_72 custom.tsam.dijit.request.PMRDP_0223A_72 Register z/VM Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0220A_72 custom.tsam.dijit.request.PMRDP_0220A_72 Register KVM Image ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0224A_72 custom.tsam.dijit.request.PMRDP_0224A_72 Register VM Image via IBM Systems Director VMControl ibm.tivoli.simplesrm.tsam.dijit.request.PMRDP_0226A_72 custom.tsam.dijit.request.PMRDP_0226A_72 Table 6. Global API functions for wizards Function name Function description Function parameters tsamGetPage () Retrieves a page of a wizard. {string} pageName The name of the required page, as exposed by the offering API. Return parameter tsamPage. Returns parameters Page, Class, Object. tsamCreateCustomPage () tsamAddPage () Creates a new Custom page with the page name that is passed as a parameter. {string} pageName The name of the required page, as exposed by the offering API. Adds a new custom page to the wizard. {object} page Page to be added to the Wizard, as exposed by the API. {numeric} index Index at which the page needs to be inserted. Return parameter tsamPage. Returns parameters Page, Class, Object. tsamRemovePage () Removes Page from a Wizard. Currently only an optional page can be removed from the wizard. {Object} page Page to be removed from the Wizard, as exposed by the API. tsamSetLeftButtonProps () Sets properties for the left button shown in the wizard. {String} labelValue Label to be shown on the button. {boolean} isEnabled Boolean value that decides whether the button is shown and enabled, or disabled. The left button allows the user to perform a resource availability check against the server at any time and independent of the currently selected wizard step. The left button is only used in Create Project and Add Server offerings. The API capability allows to either change the label on the button or to disable it. Chapter 4. Self-service user interface extension points 61 Add Server to Project Lists fields and capabilities available within the Add Server to Project wizard. Each table represents one of Add Server to Project wizard pages. Note: You can access pages and fields from a custom extension, either by using tsamGetPage() code phrase to visualize a wizard page or by using TsamGetField() code phrase to visualize a field. For example, tsamGetPage(“Page ProjectDetails”) opens the Project Details wizard page. See Arguments for custom extension access columns for more possible arguments. Table 7. Project Details wizard page. Field Type Project Details page Project Name label Label Project Name list box FilteringSelect For the whole Project section 62 All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Arguments for Possible custom extension Capability Values access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid Any other text setDisplay Invalid "Project Name Label" setValue Valid One of the existing Project Names "Project Name" setDisplay Invalid setReadOnly Valid Group Tivoli Service Automation Manager V7.2.4 Extensions Guide “Page ProjectDetails” Boolean true or false "Project" Table 7. Project Details wizard page. (continued) Field Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid The whole Project details section ProjectDetails setDisplay Valid none, block, or inline setReadOnly Valid Boolean true or false hideDetail Valid Label Arguments for Possible custom extension Capability Values access "Project Details" Status Name Description Type StartDate EndDate TeamAccess addDetail Valid name and value pair getDetail Valid Label Status Name Description Type StartDate EndDate TeamAccess Table 8. Requested Image wizard page Field Type Requested Image page Resource Group Label Used to Reserve Resources label All Capabilities defined on the wizard page or fieldClass Capability allowed for the Possible field: Valid or Capability Invalid Values setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid Any text setDisplay Valid none, block, or inline Arguments for custom extension access “Page RequestedImage” "Resource Group Label" Chapter 4. Self-service user interface extension points 63 Table 8. Requested Image wizard page (continued) Field Type All Capabilities defined on the wizard page or fieldClass Resource Group Used to Reserve Resources list box FilteringSelect setValue Valid setDisplay Valid setReadOnly Valid Image to be Deployed label Label setValue Valid setDisplay Valid Image to be Deployed grid table ItemChooserGrid setDisplay Valid setReadOnly Valid Number of Servers to be Provisioned label Label setValue Valid Any text setDisplay Valid none, block, or inline NumberSpinner Number of Servers to be Provisioned number spinner Capability allowed for the Possible field: Valid or Capability Invalid Values Arguments for custom extension access "Resource Pool" "Image Grid Heading" "Image Selection" setValue "Server Quantity Label" "Server Quantity" setDisplay setReadOnly Table 9. Server Details (optional) wizard page. Field Type Server Details (optional) page All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Possible Capability Values setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Arguments for custom extension access "Page ServerDetails" CPU section The whole CPU section TsamField setDisplay Valid "CPU" Modify the number of CPUs PopUpButton setDisplay Valid "CPU Button" setReadOnly Valid button 64 Tivoli Service Automation Manager V7.2.4 Extensions Guide Virtual CPU slider ResourceSlider Physical CPU ResourceSlider slider setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid "Virtual CPU Slider" "Physical CPU Slider" Memory section The whole Memory section TsamField setDisplay Valid "Memory" Modify memory PopUpButton setDisplay Valid "Memory Button" setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid button Memory slider Swap CPU slider ResourceSlider ResourceSlider "Memory Slider" "Swap Slider" Disk section The whole Disk section TsamField setDisplay Valid "Disk" Modify disk space PopUpButton setDisplay Valid "Disk Button" setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid button Disk slider The whole Resources section ResourceSlider Group "Disk Slider" "Resources" Chapter 4. Self-service user interface extension points 65 Table 10. Install Software wizard page. Field Type Additional Software (optional) page Select Software to Install panel Software SelectionPanel Capability allowed for All Capabilities the field: defined on the wizard Valid or page or fieldClass Invalid Possible Capability Values setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setDisplay Valid setReadOnly Valid Arguments for custom extension access "Page InstallSoftware" "Software Selection" Table 11. Network Segment Selection wizard page. Field Network Configuration page 66 Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Arguments for Possible Capability custom extension Values access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Tivoli Service Automation Manager V7.2.4 Extensions Guide "Page NetworkSegments" Table 12. Other Settings (optional) wizard page. Field Type Other Settings (optional) page Monitoring Agent to be installed checkbox Checkbox All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Possible Capability Values Arguments for custom extension access setTitle Valid Any text "Page OtherSettings" setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setChecked Valid true or false setReadonly Valid "Install Monitoring" Table 13. Summary wizard page. Field Summary page Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Possible Invalid Capability Values Arguments for custom extension access setTitle Valid Any text "Page Summary" setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Chapter 4. Self-service user interface extension points 67 Table 13. Summary wizard page. (continued) Field Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Possible Invalid Capability Values Project Details section ProjectDetails setReadOnly Valid setDisplay Valid hideDetail Valid Arguments for custom extension access "Summary Project Details" "Status" "Name" "Description" "Type" "StartDate" "EndDate" "TeamAccess" "TotalServers" "ActiveServers" addDetail Valid name or value pair getDetail Valid "Status" "Name" "Description" "Type" "StartDate" "EndDate" "TeamAccess" "TotalServers" "ActiveServers" Server Details column TsamField setDisplay Valid "Summary Server Details" Server Details value TsamField setDisplay Valid "Summary Server Value" CPU Details column TsamField setDisplay Valid "Summary CPU Details" Virtual CPU Detail row TsamField setDisplay Valid "Summary VCPU Row" Physical CPU Detail row TsamField setDisplay Valid "Summary PhysicalCPU Row" Memory Details column TsamField setDisplay Valid "Summary Memory Details" Main Memory Detail row TsamField setDisplay Valid "Summary Memory Row" Swap Memory Detail row TsamField setDisplay Valid "Summary SwapMemory Row" Disk Details column TsamField setDisplay Valid "Summary Disk Details" Disk Detail row TsamField setDisplay Valid "Summary Disk Row" 68 Tivoli Service Automation Manager V7.2.4 Extensions Guide Create Project with Server Lists fields and capabilities available within the Create Project with Server wizard, and provides more specific information necessary to personalize the wizard. Each table represents one of Create Project with Server wizard pages. Note: You can access pages and fields from a custom extension. Use tsamGetPage() code phrase to visualize a wizard page or TsamGetField() code phrase to visualize a field. For example, tsamGetPage(“Page ProjectDetails”) opens the Project Details wizard page. See Arguments for custom extension access columns for more possible arguments. Table 14. Project Details wizard page. Field Type Project Details page Project Name label Label Project Name text box TextField Group: Project Name label and Project Name Group Team to Grant Access label Label Team list box FilteringSelect Group: Team Label and Team Name Group Capability allowed for All Capabilities defined the field: on the wizard page or Valid or fieldClass Invalid Possible Capability Values Arguments for custom extension access “Page ProjectDetails” setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid Any other text setDisplay Valid setValue Valid setDisplay Valid "Project Name Label" "Project Name" "Project Name" setValue Valid setDisplay Valid setValue Valid One of the existing Team Names setDisplay Valid none, block, or inline setReadOnly Valid Boolean true or false "Project Team Label" "Project Team" "Project Team" Chapter 4. Self-service user interface extension points 69 Table 14. Project Details wizard page. (continued) Field Capability allowed for All Capabilities defined the field: on the wizard page or Valid or fieldClass Invalid Type Project Label Description label setValue Valid setDisplay Valid Description of the Project text box setValue Valid setDisplay Valid TextField Possible Capability Values "Project Description Label" "Project Description" Group Group: Project Description label and Project Description Date and Time Arguments for custom extension access "Project Description" ReservationDate setDisplay Valid setStartDate Valid setEndDate Valid setEndDateOption Valid restrictDuration Invalid "Reservation Date" forever, duration or until Group The whole general section: ProjectNameGroup and ProjectTeamGroup, Project DescriptionGroup, and ReservationDate "General" Table 15. Requested Image wizard page Field Requested Image page 70 Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Possible Capability Invalid Values Arguments for custom extension access setTitle Valid Any text “Page RequestedImage” setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Tivoli Service Automation Manager V7.2.4 Extensions Guide Table 15. Requested Image wizard page (continued) Capability allowed for the field: Valid or Possible Capability Invalid Values Field Type All Capabilities defined on the wizard page or fieldClass Resource Group Used to Reserve Resources label Label setValue Valid Any text setDisplay Valid none, block, or inline Resource Group Used to Reserve Resources list box FilteringSelect setValue Image to be Deployed label Label Image to be Deployed grid table Valid Arguments for custom extension access "Resource Group Label" "Resource Pool" setDisplay Valid setReadOnly Valid setValue Valid Any text setDisplay Valid none, block, or inline ItemChooserGrid setDisplay Valid "Image Grid Heading" "Image Selection" setReadOnly Valid Label Number of Servers to be Provisioned label setValue Valid Any text setDisplay Valid none, block, or inline NumberSpinner Number of Servers to be Provisioned number spinner setValue "Server Quantity Label" "Server Quantity" setDisplay setReadOnly Table 16. Server Details (optional) wizard page. Field Type Server Details (optional) page Capability allowed for All Capabilities defined the field: on the wizard page or Valid or Possible fieldClass Invalid Capability Values setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Arguments for custom extension access "Page ServerDetails" CPU section The whole CPU section TsamField setDisplay Valid "CPU" Chapter 4. Self-service user interface extension points 71 Modify the number of CPUs PopUpButton setDisplay Valid setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid "CPU Button" button Virtual CPU slider Physical CPU slider ResourceSlider ResourceSlider "Virtual CPU Slider" "Physical CPU Slider" Memory section The whole Memory section TsamField setDisplay Valid "Memory" Modify memory PopUpButton setDisplay Valid "Memory Button" setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid button Memory slider Swap CPU slider ResourceSlider ResourceSlider "Memory Slider" "Swap Slider" Disk section The whole Disk section TsamField setDisplay Valid "Disk" Modify disk space PopUpButton setDisplay Valid "Disk Button" setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid button Disk slider 72 ResourceSlider Tivoli Service Automation Manager V7.2.4 Extensions Guide "Disk Slider" Table 17. Install Software wizard page. Field Type Install Software (optional) page Select Software to Install panel Software SelectionPanel All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Arguments for Possible custom extension Capability Values access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setDisplay Valid setReadOnly Valid "Page InstallSoftware" "Software Selection" Table 18. Network Segment Selection wizard page. Field Network Segment Selection page Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Possible Capability Arguments for custom Invalid Values extension access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name "Page NetworkSegments" Chapter 4. Self-service user interface extension points 73 Table 19. Other Settings (optional) wizard page. All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Possible Capability Values Arguments for custom extension access setTitle Valid Any text "Page OtherSettings" setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Save Image on Checkbox Exit checkbox setChecked Valid true or false "Save Image On Exit" setReadonly Valid Keep Image on Checkbox Exit checkbox setChecked Valid true or false "Keep Image" setReadonly Valid Monitoring Agent to be installed checkbox setChecked Valid true or false "Install Monitoring" setReadonly Valid Field Type Other Settings (optional) page Checkbox Table 20. Summary wizard page. Field Summary page 74 Type All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Possible Capability Values Arguments for custom extension access setTitle Valid Any text "Page Summary" setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name Tivoli Service Automation Manager V7.2.4 Extensions Guide Table 20. Summary wizard page. (continued) Capability allowed for the field: Valid or Invalid Field Type All Capabilities defined on the wizard page or fieldClass Project Details section ProjectDetails setReadOnly Valid setDisplay Valid hideDetail Valid Possible Capability Values Arguments for custom extension access "Summary Project Details" "Status" "Name" "Description" "Type" "StartDate" "EndDate" "TeamAccess" "TotalServers" "ActiveServers" addDetail Valid name or value pair getDetail Valid "Status" "Name" "Description" "Type" "StartDate" "EndDate" "TeamAccess" "TotalServers" "ActiveServers" Server Details column TsamField setDisplay Valid "Summary Server Details" Server Details value TsamField setDisplay Valid "Summary Server Value" CPU Details column TsamField setDisplay Valid "Summary CPU Details" Virtual CPU Detail row TsamField setDisplay Valid "Summary VCPU Row" Physical CPU Detail row TsamField setDisplay Valid "Summary PhysicalCPU Row" Memory TsamField Details column setDisplay Valid "Summary Memory Details" Main Memory Detail row TsamField setDisplay Valid "Summary Memory Row" Swap Memory Detail row TsamField setDisplay Valid "Summary SwapMemory Row" Disk Details column TsamField setDisplay Valid "Summary Disk Details" Chapter 4. Self-service user interface extension points 75 Table 20. Summary wizard page. (continued) Field Type All Capabilities defined on the wizard page or fieldClass Disk Detail row TsamField setDisplay Capability allowed for the field: Valid or Invalid Valid Possible Capability Values Arguments for custom extension access "Summary Disk Row" Create Project from Saved Image Lists fields and capabilities available within the Create Project from Saved Image wizard. Note: You can access fields from a custom extension by using tsamGetField() code phrase. See Arguments for custom extension access column for possible arguments. Table 21. Create Project from Saved Image page Capability allowed for the field: Valid or Invalid Field Type All Capabilities defined on the wizard page or fieldClass General heading Label setValue Valid setDisplay Valid setDisplay Valid setValue Valid setDisplay Valid setValue Valid setDisplay Valid setValue Valid One of the existing Team Names setDisplay Valid none, block, or inline setReadOnly Valid true or false setValue Valid setDisplay Valid Description of TextField the Project text box setValue Valid setDisplay Valid Date and Time ReservationDate setDisplay Valid setStartDate Valid setEndDate Valid setEndDateOption Valid restrictDuration Valid Project Name label Project Name text box TextField Team to Grant Access label Label Team list box FilteringSelect Project Description label 76 Label Tivoli Service Automation Manager V7.2.4 Extensions Guide Possible Capability Values Arguments for custom extension access Any other text "General Heading" "Project Name Label" "Project Name" "Project Team Label" "Project Team" "Project Description Label" "Project Description" "Reservation Date" forever, duration, or until Table 21. Create Project from Saved Image page (continued) Capability allowed for the field: Valid or Invalid Field Type Resource Group Used to Reserve Resources list box FilteringSelect setValue Valid setDisplay Valid setReadOnly Valid Save Image grid table ItemChooserGrid setDisplay Valid setReadOnly Valid Save Image on Checkbox Exit checkbox setChecked Valid setReadonly Valid Keep Image on Exit checkbox Checkbox setChecked Valid setReadonly Valid Monitoring Agent to be installed checkbox Checkbox setChecked Valid setReadonly Valid Group: Project Name label and Project Name Group "Project Name" Group: Team Label and Team Name Group "Project Team" Group: Team Label and Team Name Group "Project Team" Group: Project Description label and Project Description Group "Project Description" Group The whole general section: Project NameGroup and Project TeamGroup, Project DescriptionGroup, and ReservationDate Possible Capability Values Arguments for custom extension access All Capabilities defined on the wizard page or fieldClass "Resource Pool" "Saved Image Restore Grid" true or false "Save Image On Exit" true or false "Keep Image" true or false "Install Monitoring" "General" Chapter 4. Self-service user interface extension points 77 Modify Server Resources Lists fields and capabilities available within the Modify Server Resources request, and provides more specific information necessary to personalize the request. Note: You can access fields from a custom extension by using tsamGetField() code phrase. See Arguments for custom extension access column for possible arguments. Table 22. Modify Server Resources fields, capabilities and available arguments. Field Type All Capabilities defined on the wizard page or fieldClass Project Name label Label setValue Valid Any other text setDisplay Invalid none, block, or inline setValue Valid setDisplay Invalid setReadOnly Valid setDisplay Valid none, block, or inline setReadOnly Valid Boolean true or false hideDisplay Valid Label Project Name list DropDownSelect box Project Details section Project DetailsLite Capability allowed for the field: Valid or Invalid Arguments for Possible Capability custom extension Values access "Project Name Label" "Project Name" "Project Details" Status Name Description Type StartDate EndDate TeamAccess addDetail Valid setValue Valid setDisplay Valid Select Server grid ItemChooserGrid table setDisplay Valid setReadOnly Valid the whole Resources section: CPU, Memory, and Disk TsamField setDisplay Valid "Resources Selector" The whole CPU section TsamField setDisplay Valid "CPU" setReadOnly Valid setDisplay Valid setReadOnly Valid Select Server to modify resources label Label PopUpButton Modify the number of CPUs button 78 Tivoli Service Automation Manager V7.2.4 Extensions Guide name and value pair "Select Server Label" "Server Chooser Grid" "CPU Button" Table 22. Modify Server Resources fields, capabilities and available arguments. (continued) Field Type All Capabilities defined on the wizard page or fieldClass Virtual CPU slider ResourceSlider setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setDisplay Valid setReadOnly Valid setDisplay Valid setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setDisplay Valid setReadOnly Valid setDisplay Valid setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid getValue Valid setDisplay Valid setReadOnly Valid setDisplay Valid setReadOnly Valid Physical CPU slider ResourceSlider The whole Memory section TsamField Modify memory PopUpButton Capability allowed for the field: Valid or Invalid Arguments for Possible Capability custom extension Values access "Virtual CPU Slider" "Physical CPU Slider" "Memory" "Memory Button" button Memory slider ResourceSlider Swap CPU slider ResourceSlider The whole Disk section TsamField Modify disk space PopUpButton "Memory Slider" "Swap Slider" "Disk" "Disk Button" button Disk slider Check Resources Check resources button ResourceSlider TsamField Button "Disk Slider" "Check Availability" "Check Availability Button" Chapter 4. Self-service user interface extension points 79 Modify Reservation Lists fields and capabilities available within the Modify Reservation wizard. Note: You can access fields from a custom extension by using tsamGetField() code phrase. See Arguments for custom extension access column for possible arguments. Table 23. Modify Reservation fields, capabilities, and possible arguments Field Type All Capabilities defined on the wizard page or fieldClass Project Name label Label setValue Valid Any other text setDisplay Invalid none, block, or inline Project Name list box DropDownSelect setValue Valid setDisplay Invalid setReadOnly Valid setDisplay Valid none, block, or inline setReadOnly Valid Boolean true or false hideDetail Valid Label Project Details section Project DetailsLite Capability allowed for the field: Valid or Invalid Arguments for Possible custom extension Capability Values access "Project Name Label" "Project Name" "Project Details" Status Name Description Type StartDate EndDate TeamAccess Date and Time ReservationDate addDetail Valid setDisplay Valid setStartDate Valid setEndDate Valid setEndDateOption Valid name and value pair "Reservation Date" forever, duration, or until restrictDuration Valid Group For the group: Project Name label, and Project Name and Project details 80 Tivoli Service Automation Manager V7.2.4 Extensions Guide "Project” Register Image Lists fields and capabilities available within the Register Image wizard. Each table represents one of Register Image wizard pages. Note: You can access pages and fields from a custom extension. Use tsamGetPage() code phrase to visualize a wizard page or TsamGetField() code phrase to visualize a field. For example, tsamGetPage("Page General") opens the General wizard page. See Arguments for custom extension access columns for more possible arguments. Table 24. General wizard page All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Arguments for Possible custom extension Capability Values access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid Any other text setDisplay Invalid none, block, or inline setValue Valid setDisplay Invalid Image Label Description label setValue Valid setDisplay Valid Image Description text box TextArea setValue Valid setDisplay Valid Resource Pool label Label setValue Valid setDisplay Valid Resource Pool list box FilteringSelect setValue Valid One of the existing Team Names setDisplay Valid none, block, or inline setReadOnly Valid Boolean true or false setValue Valid setDisplay Valid setValue Valid setDisplay Valid setReadOnly Valid Field Type General page Name of Virtual Server Image label Label Name of Image text box TextField Discovered Image label Label Discovered Image list box DropDownSelect "Page General" “Image Name Label” "Image Name" “Image Desc Label” "Image Desc" "ResourcePool Label" "ResourcePool" "Discovered Image Label" "Discovered Image" Chapter 4. Self-service user interface extension points 81 Table 25. Resources page Field Type Resources page Resources label Minimum label Label Label All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Possible Capability Values Arguments for custom extension access setTitle Valid Any text "Page Resources" setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid setDisplay Valid setValue Valid setDisplay Valid setValue Valid setDisplay Valid “Resources Heading” "Minimum Heading" Recommended label Label Number of VCPUs row TsamField setDisplay Valid "NumOfVCPUs Row" Number of VCPUs label Label setValue Valid setDisplay Valid "NumOfVCPU Label" the minimum value for Number of VCPUs NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid the recommended value for Number of VCPUs NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid Amount of PCPUs row TsamField setDisplay Valid "AmtOfPCPUs Row" Amount of PCPUs label Label setValue Valid setDisplay Valid "AmtOfPCPU Label" the minimum value for Amount of PCPUs NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid the recommended value for Amount of PCPUs NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid 82 Tivoli Service Automation Manager V7.2.4 Extensions Guide "Recommended Heading" "NumOfVCPU" "Rec_NumOfVCPU" "AmtOfPCPU" "Rec_AmtOfPCPU" Table 25. Resources page (continued) Field Type All Capabilities defined on the wizard page or fieldClass Amount of Memory row TsamField setDisplay Valid "AmtOfMemory Row" Amount of Memory label Label setValue Valid setDisplay Valid "AmtOfMemory Label" the minimum value for Amount of Memory NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid the recommended value for Amount of Memory NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid Disk Space Size row TsamField setDisplay Valid "DiskSpace Row" Disk Space Size label Label setValue Valid setDisplay Valid "DiskSpace Size Label" the minimum value for Disk Space Size NumberSpinner setValue Valid setDisplay Valid setReadOnly Valid setValue Valid setDisplay Valid setReadOnly Valid All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Arguments for Possible custom extension Capability Values access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid the recommended value for Disk Space Size NumberSpinner Capability allowed for the field: Valid or Invalid Possible Capability Values Arguments for custom extension access "AmtOfMemory" "Rec_Amt OfMemory" "DiskSpace Size" "Rec_DiskSpace Size" Table 26. Network Configuration page Field Type Network Configuration page Network Configuration label Label setDisplay Valid Network tab NetworkAnnotation setDisplay Valid "Page Network" “Network Configuration Heading” "Network Tab" Chapter 4. Self-service user interface extension points 83 Table 27. Platform Settings page Field Type Platform Settings page VMware Settings label Label VMware Settings Tsam VMwareSettings 84 All Capabilities defined on the wizard page or fieldClass Capability allowed for the field: Valid or Invalid Arguments for Possible custom extension Capability Values access setTitle Valid Any text setDesc Valid Any text setOptional Valid Boolean true or false setValidate Valid JavaScript method name setOnFinish Valid JavaScript method name setOnLoad Valid JavaScript method name setValue Valid setDisplay Valid setValue Valid Parameters: (fieldElement, Value). fieldElement values to be passed as “Family”, “Installed”, “Version”, “ProductKey”. setReadOnly Valid Parameters: (fieldElement, Value). fieldElement values to be passed as “Family”, “Installed”, “Version”, “ProductKey”. setDisplay Valid Parameters: (fieldElement, Value). fieldElement values to be passed as “Family”, “Installed”, “Version”, “ProductKey”. Tivoli Service Automation Manager V7.2.4 Extensions Guide "Page Platform" "PlatformSettings Heading" "Platform Settings" Other API capabilities Lists other common capabilities that support various offerings. Table 28. Other common capabilities that support offerings Capability name Capability description Supported offerings addDetail For the HTML element created, this function returns the document object model (DOM) node with the required detail added. Add Server from Saved Image Cancel Project Remove Server Remove Server from Image Start Server Restart Server Stop Server Reset Server Password Install Software Chapter 4. Self-service user interface extension points 85 86 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 5. Defining services in Tivoli Service Automation Manager To define or change a IBM Tivoli Service Automation Manager solution, you must complete certain tasks. Working with service definitions The main component of each service automation solution is a service definition. With Tivoli Service Automation Manager, you can create and modify service definitions. You can also change the state of service definitions and export them. Creating a service definition The main component of each service automation solution is a service definition. service definition consists of two major parts: a service topology model that captures the structure of the automated service and a process model that consists of management plans for creating instances of a service. A service definition is also important when completing extensions to an existing solution. About this task Some of the steps are optional depending on the design of your service definition. If you select incorrect options, it can cause errors when you run management plans later. You can always come back to this procedure during the design phase of the service, and adapt the settings appropriately. Procedure 1. In the administrative UI, click Go To > Service Automation > Service Definitions. 2. Click the Service Definition tab to create a service definition. The Service Definitions panel opens. icon. 3. On the toolbar, click the New Service Definition 4. In the Service Definition ID field, enter a unique identifier for your service definition. 5. In the Name field, enter a name for your service definition. 6. In the Description field, enter a useful description for your service definition. 7. Optional: Enter a different owner in the Owner field if you want to change the owner of the service definition. The default owner of the service definition, is the user you logged in with. The owner of a service definition has specific privileges: for example, the owner can modify the service definition. 8. Optional: In the Default User Group field, select a default group of users for service instances created from the service definition. Whenever a service instance is created from the service definition, the default user group is set for the service instance. Users in this group have access to options such as starting management plans. 9. Optional: The Service Group and Service fields, link the new service definition or add it to a specific service group in the service catalog. © Copyright IBM Corp. 2011, 2013 87 For example, Tivoli Service Automation Manager service definitions can belong to an IT Infrastructure Automation service group. 10. On the toolbar, click the Save Service Definition definition. icon to save the service What to do next Define the structural model, by defining the service topology template and process model. Related concepts: Chapter 3, “Describing a Tivoli Service Automation Manager solution,” on page 7 The main component of each service automation solution is a service definition. A service definition is the first artifact you create when you are building a solution. Next, you instantiate the service and design the control flow for the process using the advanced workflow designer. You can also reuse some of the generic workflows that are provided with IBM Tivoli Service Automation Manager product. Related reference: “Starting Tivoli Provisioning Manager workflows” on page 116 With Tivoli Service Automation Manager, you can start Tivoli Provisioning Manager workflows using the PMZHBRTPM advanced workflow. Creating a service definition from an existing service definition Create a Tivoli Service Automation Manager service definition by duplicating an existing one. The new service definition initially contains the same definitions as the original one, that is, it is the base service definition which can then be modified. About this task You can edit the new service definition. You can add parameters to topology nodes, and add or change management plans. The following steps describe how to create a service definition from an existing one. Procedure 1. In the administrative UI, click Go To > Service Automation > Service Definitions. 2. Click the List tab. 3. Put your cursor in one of the search fields, such as the Service Definition ID field, and press Enter. A list of Tivoli Service Automation Manager service definitions opens. 4. Select the service definition you want to use as the base for your new service definition by clicking the Service Definition ID or Name. The service definition opens in the main Service Definition panel. 5. From the Select Action menu, select the Duplicate Service Definition. A new copy of the service definition that contains all the information from the original service definition is created. 6. In the Service Definition ID and Name fields, enter a service definition identifier and a name. 7. On the toolbar, click the Save Service Definition 88 Tivoli Service Automation Manager V7.2.4 Extensions Guide icon. The new service definition is in the design state, which means it can be edited. When all modifications are applied, set it to the approved state. Changing the status of an existing service definition You can edit existing service definitions. For example, you can add new parameters to the service topology model or add or change management plans. About this task A service definition must be in the design state to be editable. If it is in the approved state, return it to the design state to edit it. The following steps describe how to change the state of a service definition. Procedure 1. In the administrative UI, click Go To > Service Automation > Service Definitions. 2. Click the List tab. 3. Put your cursor in one of the search fields, such as the Service Definition ID field, and press Enter. A list of Tivoli Service Automation Manager service definitions opens. 4. Select the service definition you want to change by clicking the specific Service Definition ID or Name. The selected service definition opens in the main Service Definition panel. icon to change the status. 5. On the toolbar, click the Change Status 6. In the Change Status window, select Design from the Status list. 7. In the Memo field, provide a short description about why you are changing the status. The service definition is now in the design state. Defining the data model - the topology of a service The structural model of a Tivoli Service Automation Manager service includes all the components that make up a service, and the relationships between these components. The model has physical components and logical components. Physical components are usually software or hardware components. Logical components are domain-specific constructs. For each component, the type and a set of attributes that are required for a particular service are contained in the structural model. Tivoli Service Automation Manager also uses the term service topology model for this description of a service. The model objects that represent the components of the service are called service topology nodes. The level of abstraction used in a service topology model is dependent on the scope of the managed service. Creating a service topology model for a new service definition The service topology structural model includes single components that make up your service environment and relationships. Before you begin A service definition must be created, and it must be in the design state, before you can create a service topology model for that service definition. Chapter 5. Defining services in Tivoli Service Automation Manager 89 Procedure 1. In the administrative UI, click Go To > Service Automation > Service Definitions. 2. Click the List tab. 3. Put your cursor in one of the search fields, such as the Service Definition ID field and press Enter. A list of Tivoli Service Automation Manager service definitions opens. 4. Select the service definition you want by clicking the specific Service Definition ID or Name. The selected service definition opens in the main Service Definition panel. 5. Click the Service Topology tab. Basic information about the service definition topology model opens. The name of the service topology is currently set to a default placeholder and no nodes exist within the topology model. 6. To edit the service topology, click the double arrows next to the Service Topology Name field, and select Go to Service Topologies to switch to the Service Topologies application. 7. Enter a useful name and description for your service topology. The topology model is flagged as a template, see the Is Template check box because the service topology model belongs to a service definition. 8. On the toolbar, click the Save Topology icon to save. Defining a service topology node type To define a service topology node type, create a classification. A classification defines a set of attributes, their data types, and descriptions. The classification can be applied to a set of topology nodes. Before you begin Create a classification before creating a topology node. Procedure 1. In the administrative UI, click Go To > Administration > Classifications. icon to create a classification. 2. On the toolbar, click the New Classification 3. In the Classification field, enter an identifier for the classification, for example MYNODECLASS. The identifier is a short alphanumeric string. The string must be unique for a Tivoli Service Automation Manager server. Include the purpose for the classification when you are entering the identifier for it. For a specific service definition or group of service definitions, enter a classification identifier with a common prefix. For example, if you are developing service definitions for managing WebSphere Process Server systems, start all your classifications for service topology node types with the prefix WPS. 4. When you leave the Classification field, a system message opens asking if you want to add the new classification. Click Yes. 5. Enter a useful description for the classification. The description is a default description for any service topology nodes to which the classification is later applied. 6. Optional: Clear the Generate Description check box. If you leave this check box selected, all the attributes and their values are put into the description of the object to which a classification is applied. It can 90 Tivoli Service Automation Manager V7.2.4 Extensions Guide make the description difficult to read. Clear this check box and later users can decide what the description of the object is. 7. Ensure that the new classification is a subclassification of the Tivoli Service Automation Manager root topology node classification. The new classification must be applied to Tivoli Service Automation Manager service topology node objects. Inherit from the classification PMZHBWTNC, which is shipped as part of the product. You can also define a new topology node type by extending any existing classification to become a sub classification of PMZHBWTNC. Your new node type now inherits all attributes from the existing node type and you can then define additional attributes on top. a. Click the double arrows next to the Parent Classification field, and chooseSelect Parent Classification from the list. b. In the Select Parent Classification window, locate the PMZHBWTNC classification. c. To make your classification a direct child of this classification, click the blue box to left to the classification identifier. To extend any existing node type, expand the PMZHBWTNC classification tree. Locate the classification you want to extend and click the blue box. When you have selected the appropriate parent classification and saved your new classification, there are some new entries in the Use With table. The new entries define the type of objects that can be applied to the classification. The important entries are for the objects with the PMZHBWTNC type, that is, the Tivoli Service Automation Manager service topology node object that is inherited from the PMZHBWTNC base classification. The new node type is defined, you can now add attributes to the classification. These attributes define the attributes of topology nodes. The classification is applied to the topology nodes at a later time. 8. Click New Row in the Attributes table. 9. Enter the name of the attribute. Attribute names are global and can be shared across multiple classifications. If the attribute does not exist, you are prompted to create it, specify a description and a data type. Adding nodes to a service topology model You can add nodes to a service topology model to extend the data of the structural service model. Before you begin A service definition must be created with its service topology model. Procedure 1. In the administrative UI, click Go To > Service Automation > Service Definitions and open the required service definition. 2. Click the Service Topology tab. 3. To access the service topologies, click the double arrows next to the Service Topology Name field and select the Go to Service Topologies option. 4. In the Topology Nodes table, click Add Node. 5. In the Name field, enter a name. 6. Enter a description for the node. Chapter 5. Defining services in Tivoli Service Automation Manager 91 7. Set the type of the node by applying a classification (a classification is created earlier in the process). Click the double arrows next to the Classification field and select Classify from the list. The Classify window opens, listing the classifications that can be applied to Tivoli Service Automation Manager service topology node objects. 8. Locate the required classification, and click the blue box next to it. When the classification is selected, it is applied to the topology node. All attributes that are defined for the classification are added to the Specifications table for the node. Some attribute fields and model settings are updated in the Topology Nodes table. 9. In the Specifications table, enter values for individual attributes. These values serve as default values when you are creating service deployment instances from a service definition. The first node is created. 10. To add another node, in the Topology Nodes table, click Add Node. 11. Enter a name for the node. 12. Enter a description for the node. 13. To apply a classification, click the double arrows next to the Classification field and select Classify from the list. 14. Locate the required classification, and click the blue box next to it. There are two nodes defined in the service topology model, but there is no relationship between the two nodes. Look at the Parent Node Name column in the Topology Nodes table: the column is empty for both nodes. 15. To add the missing relationship, make one node a parent and the other node a child. In the details section, click the double arrows next to the Parent Node ID of the node you are making the parent. 16. Select the Select Value option. Select a parent topology node out of the set of nodes that exist in the service topology model. 17. Click the other node. The parent-child relationship is created between the two nodes. 18. To check the parent-child relationship, look at Parent Node Name column of the Topology Nodes table. Results The definition of the sample topology model is completed. You can add more nodes to the model at a later time. Using topology nodes with variable cardinality You can have variable cardinality nodes in a service definition, which means that the number of topology nodes can vary depending on the input from the management plan. For example, if a service definition is based on a project that has servers, the number of servers in the project is unknown when the service definition is created. After the service instance is created, the number of servers is included in the service request. Additional servers can be added through another management plan at a later time. You can model the servers as variable cardinality topology nodes and create the server using the next settings. 92 Tivoli Service Automation Manager V7.2.4 Extensions Guide Setting default cardinality for a variable service topology node Specify a default number of nodes to be created when the service is deployed. About this task Note: Default cardinality settings for variable nodes are only checked if the service definition is configured to accept defaults. You must check whether the Accept Topology Customization Defaults check box is selected for your service definition. In the administrative user interface, click Go To > Service Automation > Service Definitions to access the Service Definitions application. Procedure 1. In the administrative user interface, access the service topology node editor. 2. Enter a maximum and minimum cardinality, or select the maximum cardinality unbounded check box or enter a default number in the Default Cardinality field. If you select the maximum cardinality unbounded check box, you are not setting any limit on the maximum number of nodes. For example, if you have two nodes for a new instance of a specific service, enter the value 2 in the Default Cardinality field. Default cardinality settings are only effective for the initial management plan of a service definition. When you are editing management plans where new nodes or sub trees are created in a service topology model, default cardinality settings are ignored. Configuring cardinality definition for a variable service topology node Instead of setting default cardinality for a variable service topology node, you can configure the number of topology nodes for a variable cardinality node created during the execution of a management plan. Define the name of an attribute for the service request specification so that it can hold the number of topology nodes that must be created. About this task Click the select value icon next to the Cardinality set by Request Attribute field. A list of asset attributes opens, select the attribute you want to use in the service request. This attribute holds the number of topology nodes that must be created. This feature works in a modification management plan if there is a requirement in the management plan to create the particular topology node. Related reference: “Making management plans available through Service Request Manager” on page 126 Service Request Manager offerings show management features in Tivoli Service Automation Manager service definitions. Chapter 5. Defining services in Tivoli Service Automation Manager 93 Configuring selection for a variable service topology node Similar to defining an attribute to set the cardinality of a topology node using a service request, a service request attribute can also be used to select a topology node during the execution of a management plan. The topology node selected, can then be addressed in a management task node to run an operation on the node. About this task Click the select value icon next to the Selectable by Request Attribute field. A list of all numeric asset attributes opens. Select the attribute you want to use in the service request to hold the topology node identifier of the topology node that is selected. This feature works in a modification management plan only, where a Select for Modification or Select for Deletion requirement exists in the management plan for the specific topology node. Adding an attribute to a service topology node You add attributes to service topology nodes when you extend the data of your structural service model. Procedure 1. In the administrative UI, click Go To > Administration > Classifications. 2. To find the classification that corresponds to the node type you want to extend, type search criteria into the Classification or Description fields under the List tab. 3. Select the required classification to open it in the main tab. When you extend a classification for a Tivoli Service Automation Manager service topology node type, do not add attributes to an existing classification. Create a subclassification and add attributes to it. All attributes in the original classification are inherited. 4. To create a sub classification from a particular classification, click New Row in the Children table. It lists the sub classifications of the particular classification. 5. In the Classification field, enter a unique identifier, for example MYWSAPPSRV. 6. After you have entered an identifier in the Classification field, you are asked whether you want to add the new classification; click Yes. 7. Enter a description. 8. To add attributes to your new sub classification, check that the sub classification of the primary classification can be opened in the Classifications application. Click the double arrows next to the Classification identifier in the Children table and select Move To ... from the list. 9. To add attributes to the new classification, click New Row on the Attributes table. 10. Define the details of the new attributes. You have now extended a classification by creating a sub classification. You can now go ahead and apply the new classification to a topology node in your service topology model. 11. . In the administrative UI, click Go To > Service Automation > Service Definitions. 12. Open your topology model in the Service Topologies application using the specific service definition in the Service Definitions application. 13. Locate the node you want to change in the Topology Nodes table and open the details section. 94 Tivoli Service Automation Manager V7.2.4 Extensions Guide 14. Click the double arrows next to the Classification field and select Classify. 15. Click Yes to continue. 16. In the selection window that opens, locate the sub classification you created previously and click the blue box next to it. The classification is applied to the topology node that contains the additional attributes defined in the classifications application. Note: If you select a classification which is not a subclassification of the currently applied one, Tivoli Service Automation Manager produces an error. Using the auto-numbering feature for service topology node attributes The Tivoli Service Automation Manager auto-numbering feature can be used by any alphanumeric specification attribute. It is used for the name of service topology nodes and to set additional properties on the topology node. To use this feature, add placeholder definitions with a specific syntax to the specific attributes of nodes within a service topology template. When nodes are deployed from the template, Tivoli Service Automation Manager interprets the definitions and applies a numbering algorithm. For example, when you assign different names to nodes, if one variable node exists, then several instances can be created from this variable node. To ensure, each of the instances have their own unique name, use the auto-numbering feature to call them NodeInstance01, NodeInstance02. The expression for this syntax is: NodeInstance${NodeInstanceNum:%02d} The syntax for the numbering placeholders is: ${[: System Configuration -> Platform Configuration -> Workflow Designer (Advanced). icon to create a workflow. 2. Click the New Process 3. Enter a name for the workflow, for example MYNEWWF and check the Object field is set to SR. 4. Add routes and nodes that are needed for the specific task that is being implemented. icon. 5. On the toolbar, click the Save Process 6. Enable the workflow before executing it, on the toolbar, click the Enable Process enables it. 7. icon. The system checks that the workflow is correct and then icon. On the toolbar, click the Activate Process Only one revision of a workflow can be active. Chapter 5. Defining services in Tivoli Service Automation Manager 97 Defining the management plan in the service definition Each service definition has one or more management plans, which are used to modify services created from the service definition. Before you begin Create a service definition in the design stage before defining your management plan. Procedure 1. In the administrative UI, click Go To > Service Automation > Service Definitions and open the specific service definition. 2. Click the Management Plans tab, on the toolbar, click the Add Management Plan icon. 3. In the Management Plan ID field, enter a unique management plan identifier, for example MODPLAN. The management plan identifier is set later in the appropriate workflow that is used to start the management plan. 4. Enter a name and a short description explaining the role of the management plan. 5. Define topology nodes for your management plan. Using topology requirements, the management plan creates new topology nodes or selects existing topology nodes to modify or delete them. Topology nodes can be referenced in task nodes using the Node Scope field. To define topology requirements for the management plan: a. Click Add Topology Requirements in the Topology Requirements table. b. Set the template node referenced by the requirement field, click the Select icon next to the Topology Node field. A list of nodes defined in Value the topology model for the current service definition opens. If the management plan is used to create a service instance, select the Is Initial check box. c. Set the type of requirement (creation, selection for modification, or selection for deletion) field. Extending a management plan using extension nodes Tivoli Service Automation Manager includes extension nodes inside advanced workflows. To add functions to their system, users and services teams can register their own workflows with these extension nodes . By adding extension nodes to Tivoli Service Automation Manager workflows, the supported extension nodes remain stable across fix pack releases. The investment into these extensions is protected because the extension nodes do not change. Related reference: “Network management plans and extension nodes” on page 244 Network extension nodes are used for all types of management plans. 98 Tivoli Service Automation Manager V7.2.4 Extensions Guide Creating a workflow with an extension node To extend a management plan using extension nodes, create a workflow with a subprocess node. Procedure 1. In the administrative UI, click Go To > System Configuration > Platform Configuration > Workflow Designer (Advanced). 2. Create a workflow or open an existing workflow. 3. Add a subprocess node. 4. Double-click the subprocess node to open its details. 5. In the Subprocess Behaviour section, select Use Extensions. 6. Click OK and save the workflow. What to do next Use the Workflow Process Extensions application to add multiple extensions. Proceed to “Adding extensions to workflows.” Adding extensions to workflows Extensions are existing workflows that have the same Object as the parent workflow. They are attached to any sub process node that use extensions. When you run the parent workflow, each extension added also runs depending on the Enabled, Priority, and Condition values selected. About this task Procedure 1. In the administrative UI, click Go To > System Configuration > Platform Configuration > Workflow Process Extensions. 2. The nodes, which can use extensions are listed in the Extensions Points table. Select one of these sub processes. 3. Extensions associated with this sub process are shown in the Extensions table. Click New Row to add a new extension. icon. 4. Under Process, click the Select Value 5. The workflows with the same Object as the extension you selected are opened. 6. Select one of the workflows. 7. Optional: Enter values for the Enabled, Priority, and Condition fields. If you select the Enabled check box, the extension workflow is set to run. Only an extension workflow which is enabled can run. If a priority is not assigned, extension workflows are executed in random order. If an extension workflow has a priority greater than zero, then it runs along with the other extension workflows in ascending numeric order, that is, an extension workflow with a priority 1 runs first, and an extension workflow with a priority 5 runs later. Finally, if a condition is supplied, only an extension workflow which satisfies its condition is run. icon. 8. Click the Save 9. Click Go To > System Configuration > Platform Configuration > Workflow Designer (Advanced). 10. Open the workflow that you opened in previous steps, and double-click the subprocess created in the “Creating a workflow with an extension node.” Chapter 5. Defining services in Tivoli Service Automation Manager 99 11. In the Extensions table, you can see the extensions created in the Workflow Process Extensions application. Consuming data from the topology in management plans The management task node is the core integration point between the advanced workflow technology on the one side, and the topology on the other side. Task nodes are used to interact with the topology. In a management task node, you can complete the these actions. v Iterate a set of affected and executing node pairs. To iterate a set of node pairs, use a node tag that corresponds to the nodes in the node pairs. The instance state is used to retrieve all nodes that match the node tag. For each of the affected and executing node pairs, an operation workflow is run. The operation workflow is called sequentially for each of the affected and executing node pairs. v Provide a data context for the operation workflow. You can use a mapping language to map data from the topology or the service request into an input container. The input container is a map of strings that is used for the actions and custom conditions in the operation workflow. The operation workflow is not aware of the structure of the topology of the service instance, which makes the operation workflow generic and reusable. For example, the generic Tivoli Provisioning Manager implementation that is described in the “Starting Tivoli Provisioning Manager workflows” on page 116 section is implemented as an operation workflow. It requires a workflow name and workflow parameters in the input container. The output container mappings map output data generated by the operation workflow back into the topology. v Specify error handling rules. Using error handling rules, you can identify errors using the message ID returned by the operation workflow and you can specify what happens when an error occurs. The actions you can complete on errors include skipping errors and continuing with the workflow. Defining the iteration of a task node Depending on the topology of the service instance, a task node can run the operation workflow multiple times. The operation workflow is executed for every valid combination of executing nodes and target nodes. You must use the node type, node scope and Topology Condition values in the administrative user interface to define the valid combinations for the task node. About this task Procedure 1. In the administrative UI, click Go To -> System Configuration -> Platform Configuration -> Workflow Designer (Advanced) and open a workflow. 2. Add a sub process node. 3. Double-click the subprocess node to open its details. 4. In the Subprocess Behaviour section, select Task Node. 5. In the Management Task Details , set the node tag and the node scope for both the executing and affected nodes. v The node tag refers to a topology node. By default it is the same as the classification identifier of the topology node. The node tag can be changed in the Service Topology Nodes application. v The node scope can be one of these values: New, All or Selected. When the node scope is set to New it is only the topology nodes created by the current 100 Tivoli Service Automation Manager V7.2.4 Extensions Guide management plan being executed that are taken into account. When the node scope is set to Selected, it is only the selected nodes that are taken into account. 6. Optional: In the Topology Condition field, enter a topology condition. 7. For every iteration of the task node and every operation workflow that is called or started, an executing and affected node is identified. In most cases, the node tag and node scope of the affected and executing nodes are the same. If so, Tivoli Service Automation Manager iterates over the affected nodes only. The algorithm that identifies the applicable combinations of the executing and affected nodes goes through these steps: a. Identify the set of affected nodes by checking the node tag and the node scope. b. The set of executing nodes is identified. c. The algorithm removes some combinations from the set of all possible combinations of affected and executing nodes using these rules. If there is no other executing node closer to the affected node in the topology, an executing node executes an operation workflow on an affected node. The distance from an executing to an affected node is the node distance from the executing node to the closest common parent node. If no common parent node exists the distance has no limits. d. For every combination of executing and affected nodes, the topology condition is checked. If the topology condition is empty or equal to true, the operation workflow is executed on the set of nodes. Example Sometimes one node must be used to run operations that affect another node. The executing node that must be used must be closer in the topology than the other nodes. For example, if the node tag and the node scope are the same for both the executing and affected nodes, then each affected node is also in the set of executing nodes. Since the distance between a node to itself is the smallest, all other combinations that are not allowed are removed. Another example is a service topology with virtual servers. Each virtual server must have a set of additional disks. When you are creating the management plan for these disks, you want to contact the virtual server to format each new disk. This example can be modeled as a topology where a project node serves as the root node for the virtual server nodes and the disk nodes have the virtual server node as the parent node. Then, specify the disk node tag as the affected node tag and set the node scope of the affected node to New. The executing node tag becomes the virtual server tag and the node scope is set to All. The algorithm in this case means that each new disk is an affected node and the virtual server that each disk is attached to is the executing node. The algorithm ignores the other virtual servers as there are too far away from the disk node. Providing the data context A management plan task node can run an operation workflow on each of the affected and executing node pairs in a set. The operation workflow needs data from both the affected and executing nodes and the current request. The operation workflow might want to pass data that is generated during the execution of the operation workflow to tasks executed during the execution of the management plan later. To help passing data to and from operation workflows, Tivoli Service Automation Manager provides input and output containers, and a mapping language to map data in to the input container and out from the output container. The input Chapter 5. Defining services in Tivoli Service Automation Manager 101 container is a structure, which is used to hold key-value pairs that are passed into the operation. The output container is a similar structure, which is used to hold data that is passed out from the operation. One input and output container exist for each iteration of a task node. A global input container that has a lifecycle of the execution of management plan also exists. When an operation workflow runs, it has direct access to its own input container only. Tivoli Service Automation Manager provides an expression language to fill the input container with data from the service request, the topology nodes, and the global input container. The output container maps data from the output container to the topology nodes or the global output container. For example, a topology has two virtual server nodes and a management plan whose advanced workflow has one task node that iterates over these virtual server nodes. The topology has three separate input containers and one global input container, which is available until the management plan terminates. The two separate input containers are created for each iteration of the management task over the vírtual server nodes. Mapping data into the input container: You can define a mapping on a management task node that maps data from various sources into the input container of the operation workflow. Procedure 1. In the administrative UI, open the details of a task node in the Advanced Workflow Designer application. 2. Click New Row in the Input Parameter Mappings table. 3. In the Parameter Name field, enter a parameter name The mapped value is available in the input container under this name. 4. Enter a mapping type. The mapping type defines how data is retrieved for that parameter. Valid mapping types are Constant, Expression, Request, and VSRParm. 5. Depending on the mapping type you selected, enter a value in the Constant Value or Mapping from Attribute field. If the mapping type is VSRParm, you define the parameter value in the Constant Value or Mapping from Attribute field by specifying the source type and source attribute name of the variable service request parameter. Define it in the following form: [Source Type].Src Attribute Name. If you put a wildcard character (*) at the end of the parameter name in the Mapping from Attribute field ([Source Type].Src Attribute*), all variable request parameters that match the wildcard pattern are searched. These parameters are then displayed in the input field under the parameter name, appended by the variable name part (suffix) of the request parameter. 6. If sensitive information such as a password is entered, it must be encrypted in the database. Select the Crypt check box. Example The following examples describe the various mapping definitions and corresponding values for mapping type VSRParm. 1. Mapping without using wildcards 102 Tivoli Service Automation Manager V7.2.4 Extensions Guide Table 29. Input Parameter Mapping: Parameter Name Mapping Type Constant Value or Mapping from Attribute Network_Segment VSRParm [NETWORK].PMRDP.NET.Segment_1 Table 30. VSR Parameter: Src Attribute Name Src Attribute Value PMRDP.Net.Segment_1 Management Segment Source Token Source Name Source Type 1 1 NETWORK Table 31. Resulting Container Mapping: Parameter Value Network_Segment Management Segment 1 2. Mapping by using wildcards Table 32. Input Parameter Mapping: Parameter Name Mapping Type Constant Value or Mapping from Attribute Network_Segment_* VSRParm [NETWORK].PMRDP.NET.Segment_* Table 33. VSR Parameter: Src Attribute Name Src Attribute Value Source Token Source Name Source Type PMRDP.Net.Segment_1 Management Segment 1 1 NETWORK PMRDP.Net.Segment_2 Customer Segment 1 1 NETWORK PMRDP.Net.Segment_3 Customer Segment 2 1 NETWORK Table 34. Resulting Container Mapping: Parameter Value Network_Segment_1 Management Segment 1 Network_Segment_2 Customer Segment 1 Network_Segment_3 Customer Segment 2 Chapter 5. Defining services in Tivoli Service Automation Manager 103 Mapping data from the output container: Define a mapping on a management task node that maps the data produced by the operation workflow in the topology or the global input container. Procedure 1. In the administrative UI, open the details of a task node in the Advanced Workflow Designer application. 2. Click New Row in theOutput Parameter Mappings table. 3. Enter a parameter name in the Parameter Name. The mapped value is looked up under this name in the output container. 4. Enter a mapping type. The mapping type for a parameter defines how data is retrieved for that parameter. Valid types are Affected Node, Expression, and Parent Container 5. Depending on the mapping type selected, enter a value in the Attribute field. If the mapping type is Expression, then the expression is estimated and any attributes that are found are updated with the mapped value. If the mapping type is Affected Node, then the value is stored in the specific attribute on the affected node. If the mapping type value is Parent Container, then the value is stored under the specific name in the global container. 6. If sensitive information such as a password is entered, it must be encrypted in the database. Select the Crypt check box. Data mapping expression language: The Tivoli Service Automation Manager data mapping expression language includes four parts which run in sequence. The language includes: 1. A topology node selection expression, which is mandatory. The topology node selection expression returns a set of topology nodes. A topology node action statement, which is optional. The topology node action statement retrieves related objects from the topology node, for example, it can go travel across relationships, or filter the set of topology nodes from an expression. 3. The property statement, which is mandatory. The property statement returns the value of a specific property on the object returned by the node action statement. 2. 4. The value computation expression, which is optional. The value computation expression estimates a boolean expression from the set of values, and counts the number of values returned. Value computation expressions are used in topology conditions. 104 Tivoli Service Automation Manager V7.2.4 Extensions Guide Topology node selection expression: Tivoli Service Automation Manager data mapping expressions begin with a set of topology nodes. You can use two methods to retrieve topology nodes in a mapping expression: the role method and the type method. Use the role method to retrieve the current affected or executing node of the operation. Use the type method to retrieve the nodes with a specific classification. Table 35. Node selection expression details Node selection expression Role It evaluates to the current affected node. <> It evaluates to the current executing node. The role method retrieves one topology node, the type method can retrieve many topology nodes. To use the type method, use the name of the classification in square brackets, for example, to retrieve all topology nodes with the PMRDPCLCVS classification, use [PMRDPCLCVS]. An example of the role method .PMRDPCLCVS_NAME retrieves the value of the specification attribute PMRDPCLCVS_NAME on the current affected node. <>.PMRDPCLCVS_NAME retrieves the value of the specification attribute PMRDPCLCVS_NAME on the current executing node. An example mapping using EXPRESSION for a parameter NAME [MyClassification].Name evaluates to NAME1: Peter, NAME2: Paul, and NAME3: Mary in the case where you have three topology nodes classified as MyClassification. [MyClassification].Name evaluates to Name: Peter in the case where you have only one topology node classified as MyClassification. Topology node action statement: The topology node action statement retrieves related objects from the topology node, for example, it can go travel across relationships, or filter the set of topology nodes from an expression. Using relationships: By using a specific node such as an executing or target node, you can go through relationships in the service topology model. You can then retrieve an attribute from the node using this relationship. This expression is useful to get parameters from other nodes near the executing node and target nodes. Starting with a specific node, for example the executing node of a task (‘<>'), append a relationship expression starting with the ‘− >' operator followed by a relationship name. Every topology model has two standard relationship names: the parent relationship, which points to the direct parent of a node, and the children relationship, which points to the direct child or children of a node. Note: A relationship expression always addresses another node. Starting from that node, you can find a relationship and then continue to find the next relationship and go through the complete topology model. For example, the expression: Chapter 5. Defining services in Tivoli Service Automation Manager 105 <>->PARENT->PARENT.MY_ATTR_NAME can find the parents parent of the executing node of a management plan task. Using node selector operators: You can easily identify the executing and affected nodes of a task because they are unique. You can identify other nodes using their type or by finding their relationships. If you cannot identify a node using the type operator or a relationship, then you can use special selection expressions to assess the attribute values of the node. For example, if there are multiple instances of the node, you can uniquely identify the node based on one of its attributes. A selection expression contains this syntax: {=""} is added directly to a node pointer such as a type-based node pointer. The attribute name can be the name of a specified attribute, or an attribute of the topology node object, for example: NAME. An example where a selection expression is useful is when you must select from multiple children in the children relationship of a node. In comparison to the parent relationship, which points to the only parent of a node, the children relationship can point to more than one child. As a result, you must define a selection criteria in which you uniquely identify one node. An example mapping using EXPRESSION for a parameter PORT [MyClassification]{Name=”Peter”}.SSH_PORT evaluates to Peter in the case where you have multiple topology nodes classified as MyClassification but you have one name only. Using the property statement: The property statement is required for a valid expression. An object is returned by the node action statement, the property statement then returns the value of a specific property in this object. Procedure 1. In the object, search for the property in the set of specifications. 2. Search for the property in the attributes of the object. 3. To use a property statement, add a dot and the name of the property to the topology node action statement. The value computation expression: Value computation expressions are not valid in the context of output parameter mappings. The value computation expression is a boolean expression based on a set of values. The value computation expression counts the number of values returned. These expressions are used in topology conditions. The >, <, <=, >=, !=, and= operators are supported for value computations. An example mapping with a value computation [MyClassification].SSH_PORT = 22 106 Tivoli Service Automation Manager V7.2.4 Extensions Guide v In the case where you have one topology node classified as MyClassification, whose SSH_PORT attribute is 22, then the result is true. v In the case where you have two topology nodes classified as MyClassification, with one SSH_PORT attribute equal to 22, and the other SSH_PORT attribute equal to 42, then the first result is true and the second result is false. Error handling in management plans A task node contains an error handling layer that wraps around the operation workflow. This layer uses a set of error handling rules to respond to particular errors. Error handling options include: ignoring certain errors in the operation workflow, retrying the operation workflow, interrupting the management plan so it can be manually worked on, and canceling the management plan. A task node can take either of two outgoing routes: the positive route or the negative route. If the task node follows the positive route, the management plan continues in the normal way. In this case, either the operation workflow has ended successfully or an error is ignored. If the task node follows the negative route, the management plan is canceled because of errors. Management plan activities that follow the negative route of a task node are error handlers. These activities include clean up procedures and diagnostic steps. They are called before the management plan ends. A task node calls the operation workflow through the error handling layer which responds to errors in these ways. v It runs the operation workflow for the same topology node pair again. v It ignores the error and continues running the operation workflow. The task node continues to the next topology node pair, or, if all topology node pairs are processed, the task node exits on the positive route. v It ignores the error and cancels the management plan. The task node stops the iteration on the topology node pairs and the management plan is canceled. The task node exits on the negative route. The output parameter mappings are not completed for the last iteration that caused the error. After, the management plan is stopped, the run book completion listener checks if the management plan is canceled, and then sets the service request and the state of the service instance. v The management plan is stopped so it can be manually worked on. It is stopped by an assignment for the Assignment Role. The Assignment Role is defined in the Management Task Details panel. The default value for the Assignment Role is PMZHBSSIO, which is a service deployment instance operator. An email notification is sent to all users sharing the Assignment Role. Assignments are displayed in the inbox portlet of the Maximo user interface. The assignments are opened in the Service Automation Requests application to analyze the details of the particular service request. When the assignment is routed, it opens a dialog that offers the error handling options previously described. Operation workflows communicate errors to the task node by stopping on the negative route and optionally returning an error code. The error handling layer inspects the error handling rules of the task node and handles the error accordingly. There are three types of rules. v The specific rule, which applies to a specific error code. v The default rule, which applies to all error codes. If there is no specific rule for the error code returned, then the default rule is applied. If the operation workflow does not return any error code, the default rule is also applied. v The implicit rule is predefined for every task node and it applies to all error codes. If no other matching rule exists, that is, no specific rule is defined for the Chapter 5. Defining services in Tivoli Service Automation Manager 107 error code and no default rule, then the implicit rule is applied. The implicit rule states that the management plan must be stopped by an assignment for the Assignment Role. If an operation workflow terminates on the negative route, it usually means that an error has occurred and the operation workflow can add error messages to the service request log to record the problem. If an operation workflow does not add any error message to the service request log, then the ERRORCODE is not specified. If an operation workflow adds one or more error messages to the service request log, then the last error message determines the ERRORCODE. The ERRORCODE is set to the message identifier of the last the error message. Structure and syntax of error handling rules If the operation workflow is disabled, error handling rules are defined in the Details dialog of a task node. If two or more rules are defined for the same error code, then the changes are not saved until this issue is resolved. Error handling rules include these attributes. v The On error message ID attribute defines the message identifier of the last error message that the operation workflow added to the service request log. If the On error message ID attribute is empty, then the message identifier is set for each error message. If the operation workflow does not add any error message to the service request log, the message identifier is also set. v After returning on the negative route of the operation workflow, the Maximum Number of Retries attribute defines the maximum number of times an operation workflow is tried using the specific On error message ID attribute. If the operation workflow is tried again, and returns with a different error, then the error handling layer searches for the rule that matches the new error code. The counter is set to the value of the Maximum Number of Retries for the new rule. If the default or implicit rules apply before and after the change of error code, then the counter is reset to the value of the Maximum Number of Retries of the default rule. v If the operation workflow is still producing an error after being tried for the last time, then the Assignment After Retries and Ignore After Retries If No Assignment attributes define the behavior. The Assignment After Retries attribute defines whether the management plan is stopped so it can be manually worked on. If it is stopped, an assignment for the Assignment Role is created. If the Assignment After Retries attribute is set N, then the Ignore After Retries If No Assignment attribute defines whether the error is ignored in the operation workflow. If the Ignore After Retries If No Assignment attribute is set to Y, then the task node exits on the positive route and the management plan continues in the normal way. Otherwise, the management plan is canceled and the task node is stopped on the negative route. If the Assignment After Retries attribute is set to Y, then the Ignore After Retries If No Assignment attribute is ignored. v After the management plan completes, the SR status on completion of management plan attribute defines the target state for the service request. During execution of a management plan, a number of error handling rules might have been applied. The last defined value for the SR status on completion of management plan attribute in the sequence of rules applied defines the final value of the SR status on completion of management plan attribute. If none of the rules that are applied can define a value for the SR status on completion of management plan attribute, then the service request is set to FAILED or RESOLVED depending on whether the management is canceled. v Message Group to set on the SR and Message Key to set on the SR attributes are optional. If the operation workflow ends with an error after being tried 108 Tivoli Service Automation Manager V7.2.4 Extensions Guide many times, then the message with the Message Group to set on the SR and Message Key to set on the SR attributes are added to the service request log. The message is also added if the error is ignored. An example of error handling rules There are two rules defined for a task node. Attributes with "attributes=" are not defined. Rule 1: (ERRORCODE=, SRSTATUS=, MAXRETRIES=0, ASSIGNMENTAFTERRETRIES=N, IGNOREAFTERRETRIES=N, MSG_GROUP=, MSG_KEY=) Rule 2: (ERROROCODE=CTJZH7799E, SRSTATUS=RESOLVED, MAXRETRIES=2, ASSIGNMENTAFTERRETRIES=N, IGNOREAFTERRETRIES=Y, MSG_GROUP=ctjzh, MSG_KEY=CTJZH7804E_DELETE_NOT_ALLOWED) Case 1: If the operation workflow returns with the CTJZH7799E error code, then Rule 2 applies. In this scenario, the Maximum Number of Retries attribute is set to 2 so the workflow is tried twice. If the operation workflow still returns with the same error after being tried twice, then the error message ctjzh.CTJZH7804E_DELETE_NOT_ALLOWED is logged. The target service request is set to RESOLVED, which is defined by SR status on completion of management plan. The task node is stopped on the positive route because the Ignore After Retries If No Assignment attribute is set to Y. The management plan continues in a normal way. Case 2: If the operation workflow fails with an error code other than CTJZH7799E, or if the operation workflow does not specify the error code using the addLogEntry method of the TaskAPI, then Rule 1 applies. In this scenario, according to Rule 1, the Maximum Number of Retries attribute is set to 1 so it is not tried again. The management plan is canceled and continues on the negative route of the task node because Ignore After Retries If No Assignment is set to N and Assignment After Retries is set to N. If Assignment After Retries is set to Y, then the management plan would be stopped by an assignment for the Assignment Role after the error occurred. Removing error handling rules You have to remove error handling rules which require inbox assignment. You also have to do it after every Tivoli Service Automation Manager fix pack installation as the error handling rules are created with it again. Procedure 1. In the Runbook, go to System Configuration > Platform Configuration > System Properties. 2. In the System Properties application, filter for the property pmzhb.rb.protection.disabled and set the global value to true. If there is no such property, add it by using the New Row button and set its global value to true. 3. Click Save. 4. Select the property, click the button on top of the page. 5. In the Live Refresh window that opens, click OK. 6. Go to System Configuration > Platform Configuration > Workflow Designer (Advanced). 7. Filter for PMRDPRUCRT (Create Project Runbook) and select the active version. Chapter 5. Defining services in Tivoli Service Automation Manager 109 8. In the Select Action menu, select Deactivate Process. 9. In the same menu, select now Disable Process. The check boxes Enabled? and Active? are cleared. 10. In the section below, right click the INSTALLSW and select Properties. 11. In Subprocess Node Properties, make sure that only Service Automation Task is selected. 12. In Error Handling Rules, check Ignore After Retries If No Assignment. Leave Assignment After Retries cleared. 13. Click the button on the left side above the New Row button. 14. Remove the error handling rules from the TPMINVOC and DELSOFTSTA nodes by repeating the previous steps. 15. In the Select Action menu, select Enable Process. 16. In the same menu, select now Activate Process. The check boxes Enabled? and Active? are checked. 17. Click Save. The error handling rule is now removed from the Runbook. Starting management plans from other services You can create custom services definitions to use your own service definitions and processes with Tivoli Service Automation Manager processes. Management plans provided with Tivoli Service Automation Manager are implemented as advanced workflows. Each advanced workflow contains a pre-defined set of extension points. You can use these extension points to plug your own specific workflows into the advanced workflows provided with Tivoli Service Automation Manager. From insideTivoli Service Automation Manager, a subset of these extension points can be used to call your management plans for service definitions. For example, when you create a project management plan you might want to add disks or software licensing. Then, when you cancel the project, you might want to remove the disks and licensing. The information about the type of disk, and the size of disk to use for the particular project must be stored in a data container within Tivoli Service Automation Manager. The next example, explains how to use an extension node to switch the context from a Tivoli Service Automation Manager service instance to your service instance. 110 Tivoli Service Automation Manager V7.2.4 Extensions Guide Data is processed with Management plans View configuration Tivoli Service Automation Manager Additional services Legend Service definitions included as part of Tivoli Service Automation Manager Service definition provided by users Management plans included as part of Tivoli Service Automation Manager and management plans provided by users Task node User service Task Figure 2. Extension nodes Each management plan provided by Tivoli Service Automation Manager defines extension points which can be used to plug into other workflows. Some of these extension points are EXTCSTART, EXTCSUCC and EXTCFAIL. EXTCSTART is the first extension node to plug into your management plan. EXTSUCC and EXTCFAIL are called at the end of the management plan after it is executed. To use custom service definitions in Tivoli Service Automation Manager, these prerequisites must be fulfilled: v You must use standard Service Request Manager tools, to define classifications and offerings, and to add the offerings to catalogs. v You must implement a new service definition using standard Tivoli Service Automation Manager tools so that you can create topologies and advanced workflows to implement the management plans and quota definitions. v You must identify the extension points in the Tivoli Service Automation Manager management plans where additional workflows can be plugged in. Chapter 5. Defining services in Tivoli Service Automation Manager 111 Your management plans are implemented in the same way as management plans provided by Tivoli Service Automation Manager. 1. Based on the classification of the service request, you must search for the required values to fill out the service request. Search for the values in any of these locations, the specified offering, the input parameters provided when starting the management plan or the service request parameters provided by the self-service user interface. The process of searching for values is completed by a Tivoli Service Automation Manager workflow called PMZHBRMPIV. 2. A service request is created using the PMZHBRMPIV workflow. 3. An escalation picks up the service request, and starts the management plan advanced workflow. 4. The advanced workflow run time executes the management plan advanced workflow, which in turn, runs the steps such as creating a service instance and other tasks. 5. The service request status is updated accordingly to reflect the results of running the management plan. 6. Your management plans, must follow the same structure as the workflows provided from Tivoli Service Automation Manager. There is one exception, no reservation is supported. A typical management plan completes approval business logic, Tivoli Service Automation Manager scheduler logic, the logic to create or select topology nodes and the management tasks specific to that plan. In Tivoli Service Automation Manager, there are two types of management plans. The initial management plan, which, is used to create a service deployment instance from a service definition, and the modification management plan, which, is executed on an existing service deployment instance. For each service definition one initial management plan exists, for example NEWPROJECT, and one, or many modification plans exist, for example, ADDSERVER, REMOVESERVER, and, CANCELPROJECT. The service instantiation subworkflow PMZHBSIWRB provided by Tivoli Service Automation Manager must be used to run the create project management plans. The subworkflow creates the service deployment instance, and topology nodes which the management plan can complete actions on. The modification subworkflow PMZHBSIMRB must be used for any modification management plan to select the appropriate topology nodes. This subworkflow selects the topology nodes which the management plan can complete actions on. The next figure is an example of a new project management plan. It shows the steps the project management plan must contain, so it can be executed by IBM Tivoli Service Automation Manager. 112 Tivoli Service Automation Manager V7.2.4 Extensions Guide STOP START APPROVAL MP1 SCHEDULER MP2 MPn INITIAL WORKFLOW STOP Legend MP Management Plan positive connection line negative connection line Figure 3. An example of a new project management plan To use the PMZHBSIWRB and PMZHBSIMRB subworkflows, this information must be provided as part of the service request specification: v The service definition number: PMRDPCLCPR_SERVICEDEFINITIONNUM is required for the PMZHBSIWRB subworkflow only. v The service definition revision: PMRDPCLCPR_SERVICEDEFINITIONREVISION is required for the PMZHBSIWRB subworkflow only. v The service deployment instance identifier: PMRDPCLCPR_SERVICEINSTANCEID is required for the PMZHBSIMRB subworkflow only. v The PMRDPCLVSRV_MPNUM management plan. For each extension point defined, you can use these extension points to run your management plan. An advanced workflow that defines at least one task node with these characteristics must be included. v The definition of PMZHBRMPIV as an operation workflow. v The definition of these management task mappings: – The PMRDPCLCPR_PROJECTNAME task mapping, which is a constant mapping that defines the project name or service instance. This parameter is required to run the create management plan advanced workflow. – The PMRDPCLCPR_DESCRIPTION task mapping, which is a constant mapping that defines the project description or service instance. This parameter is required to run the create management plan advanced workflow. – The mandatoryOFFERINGID for the offering is used. Chapter 5. Defining services in Tivoli Service Automation Manager 113 Generic subworkflow reference You can use generic workflows to help you create new workflows. The PMRDPAPPSR approval process Tivoli Service Automation Manager includes a sample sub workflow that implements an approval process called PMRDPAPPSR. This approval process is used by management plan developers for business approval in their processes, or as a template that is duplicated to implement customer-specific multi-stage approval processes. The PMRDPAPPSR process contains these properties. v Management plans skip approval if the pmzhb.enable.autoapproval system property is set to Y. Otherwise the approval process completes these actions: v – It changes the state of the service request state to waiting for approval. – It sends an email to all cloud and system administrators informing them that approval is pending. – It creates an inbox assignment for all cloud administrators informing them that approval is pending. – The assignee can use the self-service or administrative user interfaces to input the approval decision. – It sends an email to the original requestor of the service request informing them of the approval decision. – It stops on the black or red edge of a workflow depending on the approval decision. DITA When you are developing a management plan, it is advised to implement the PMRDPAPPSR approval process using an extension node. Then, if at any stage, you want to use a different approval process, you can do so without changing the management plan. Pre-condition The REQUESTOR field of the service request, must contain the administrative user ID of the user requesting the service so that email notification works. The state of the service request must be new, or, it must be in any other state, which, allows it to transfer to the waiting for approval state. Post-condition The PMRDPAPPSR process stops on the positive route if the approval decision is positive, or on the negative route if the approval decision is negative. Scheduler workflows The Scheduler workflow is called PMZHBSCHED. It implements these functions. Functions of the scheduler workflow v The Scheduler workflow delays executing the service request until after the date and time specified in the SR TARGETSTART attribute. As a result, scheduling requests such as create project requests are implemented. v This workflow puts a global lock on each service instance. This means, the workflow verifies that there is only one service request active for each service instance. 114 Tivoli Service Automation Manager V7.2.4 Extensions Guide The state of the service request must be Queued, or it must be in any other state that allows it to transfer to Queued. PMZHBSRSCHED changes the state of the service request to Queued. If the scheduling part is used, the TARGETSTART attribute must contain a date and time. If the TARGETSTART attribute is empty, the current date and time are used as defaults. The service request must have a pointer to the service definition and management plan that are being executed by this workflow. Set the PMRDPCLCPR_SERVICEDEFINITIONNUM and PMRDPCLCPR_SERVICEDEFINITIONREVISION service request attributes for the service definition, set the PMRDPCLCPR_SERVICEINSTANCEID attribute for the service instance, and finally set the PMRDPCLVSRV_MPNUM attribute for the management plan. Post-condition PMZHBSCHED always stops on the positive route. The state of the service request changes to In Progress. All workflows that depend on this workflow can be executed and used now. The state of the service request cannot change until all processing is finalized. The service request status can then be changed to its final state, which is Resolved. Generic editing workflows The PMZHBSIWRB, PMZHBSIMRB and PMZHBSIDRB workflows are used to create, delete, and modify topology nodes and service deployment instances. You can use the PMZHBSIWRB workflow to create a service instance for the management plan. You can use the PMZHBSIMRB workflow to modify this service instance, and you can use the PMZHBSIWRB workflow to delete this service instance. Pre-condition You must run the PMZHBSCHED scheduler workflow, before running any of these workflows. If you are using the PMZHBSIWRB workflow to create a service instance from a service definition that contains variable cardinality nodes, these nodes must have a default cardinality, or the service request must have an attribute whose name is specified in the Cardinality set by Request Attribute field for the node, and whose value is the number of nodes that must be created. If you are using the PMZHBSIMRB or PMZHBSIDRB workflows and the associated management plan has a topology requirement that is Selection, then the service request must have an attribute whose name is specified in the Selectable by Request Attribute field for the node and whose value is the topology node identifier of the selected node. Post-condition Specific topology nodes are selected so they can be modified and deleted. For the PMZHBSIWRB workflow, a service instance is created, with its state set to Transition. For the PMZHBSIDRB workflow, the state of the service instance is changed to Decommissioning. If the management plan is an initial management plan or a requirement to create a topology is configured on the management plan, new topology nodes are added. Chapter 5. Defining services in Tivoli Service Automation Manager 115 Starting Tivoli Provisioning Manager workflows With Tivoli Service Automation Manager, you can start Tivoli Provisioning Manager workflows using the PMZHBRTPM advanced workflow. To start a Tivoli Provisioning Manager workflow, you must pass the name of the workflow to the input container in the PMZHB_TPM_WORKFLOW_NAME container variable. Tivoli Provisioning Manager workflow input parameter variables names must match the names in the Tivoli Provisioning Manager workflow interface. Tivoli Provisioning Manager output parameters are stored with the same names as the ones used in the Tivoli Provisioning Manager workflow interface. Return values that are null are stored as empty strings. If the PMZHB_TPM_WORKFLOW_NAME_CHECK input container variable is not defined, then it is passed as Null. If the PMZHB_TPM_WORKFLOW_NAME_CHECK input container variable is set to yes, then all input parameters must be defined in the input container. If a required input variable is not defined in the input container, then an error message is written. If Null is passed, then an empty variable or a variable that contain spaces is defined. Examples using the Tivoli Provisioning Manager workflow definition SampleWorkflow1 For example, using this Tivoli Provisioning Manager workflow definition: workflow SampleWorkflow1(in inParm1, in inParm2, out outParm1, out outParm2) LocaleInsensitive the values that the input container requires are in inParm1, inParm2 and PMZHB_TPM_WORKFLOW_NAME. PMZHB_TPM_WORKFLOW_NAME must be the SampleWorkflow1 string. When the Tivoli Provisioning Manager workflow is finished, the values of outParm1 and outParm2 are available in the output container. SampleWorkflow2 For example, using this Tivoli Provisioning Manager workflow definition: workflow SampleWorkflow2 (in encrypted inParmEncrypted, out encrypted outParmEncrypted) LocaleInsensitive the input parameter inParmEncrypted, is passed to the Tivoli Provisioning Manager workflow encrypted. The result parameter outParmEncryptedis returned by the Tivoli Provisioning Manager workflow encrypted but it is stored in the output container decrypted. You can also pass parameters to input arrays in a Tivoli Provisioning Manager workflow. The array parameters in the input container must follow a naming convention to pass the parameters. All parameters must have a suffix that indicates the index of the array parameter. The suffix must start with 0 and is incremented by one for every array element added. SampleWorkflow3 For example, using this Tivoli Provisioning Manager workflow definition: workflow SampleWorkflow3 (in array inArray1, out array outArray2) LocaleInsensitive 116 Tivoli Service Automation Manager V7.2.4 Extensions Guide if the array outArray2 is filled with three elements: outArray2[0], outArray2[1], and outArray2[2], then there are three output variables: outArray20, outArray21, and outArray22 defined in the output container that contains the array element values. These Tivoli Provisioning Manager errors are handled by Tivoli Service Automation Manager. v Tivoli Provisioning Manager workflow is not found. v Tivoli Provisioning Manager workflow throws an exception. v v v v Tivoli Provisioning Tivoli Provisioning Tivoli Provisioning Tivoli Provisioning Java code. Manager Manager Manager Manager workflow workflow workflow workflow executes an invalid DCM query. detects a Python runtime error. throws a class not found exception. throws a Java exception called inside the If a failure occurs, Tivoli's process automated engine workflow logs an error message in the service request log and stops on the negative route of the workflow. If it is required, the caller then directs the error handling workflow and continues on the negative route of the workflow. Related concepts: Chapter 3, “Describing a Tivoli Service Automation Manager solution,” on page 7 The main component of each service automation solution is a service definition. A service definition is the first artifact you create when you are building a solution. Next, you instantiate the service and design the control flow for the process using the advanced workflow designer. You can also reuse some of the generic workflows that are provided with IBM Tivoli Service Automation Manager product. Related tasks: “Creating a service definition” on page 87 The main component of each service automation solution is a service definition. service definition consists of two major parts: a service topology model that captures the structure of the automated service and a process model that consists of management plans for creating instances of a service. A service definition is also important when completing extensions to an existing solution. Generic email notification workflow The workflow for email notification is called PMRDPRBNTU. It is used to send emails that contain information about the topology. This workflow is an extension of the general communication template feature that is available in the workflow actions. Pre-condition You must run an initial or modification workflow before running this email notification workflow. You can then access the topology from the email notification patterns. For the template you are using, the communication template identifier TEMPLATEID must be set in the CommunicationTemplateId attribute in the input container. The communication template must be valid and anyone receiving the template must have a valid email address. Post-condition This workflow always stops on the positive route. Any errors during processing, are written into the service instance and service request logs. Chapter 5. Defining services in Tivoli Service Automation Manager 117 Writing custom code to run a management plan You can write custom code to implement use cases that you cannot implement using the advanced workflow language or the generic workflows which are included as part of Tivoli Service Automation Manager. Write custom code using either Java classes or Jython scripts. If you are using Java classes to write custom code, you must set up a Java development environment. Java development environments have better support to write code efficiently. It is outside the scope of this guide to include details on how to setup, develop, and deploy custom Java classes in a Tivoli Service Automation Manager system. You are advised to contact IBM Services to implement Java classes. For the purposes of writing custom code here, you are advised to implement automation scripts using the Jython language. Jython scripts can be used to implement Tivoli's process automation engine actions. You can use the automation scripts application to create Jython scripts in Tivoli's process automation engine. See the “Automation Scripts application” on page 182 section for more details. When a task node runs an operation workflow, the workflow has access to additional data provided by the task node, for example the input and output containers. Tivoli Service Automation Manager includes a task API so you can access the input containers easily. For example, the next sample Jython code accesses task node artifacts. The Jython code creates a TaskAPI object using the TaskAPIFactory and the pre-defined scriptHome and wfinstance variables. It then accesses the input container and retrieves the PROJECTNAME and PARTNAME attributes from the input container. Finally the Jython code sets a parameter NAME in the output container. import com.ibm.ism.pmzhb.runbook.task.api.TaskAPIFactory api = com.ibm.ism.pmzhb.runbook.task.api.TaskAPIFactory.create (scriptHome, wfinstance) ic = api.getInputContainer() projectname = ic.getValue("PROJECTNAME") partname = ic.getValue("PARTNAME") oc = api.getOutputContainer() oc.setValue("NAME", projectname + "-" + partname) Related concepts: “Automation Scripts application” on page 182 The Automation Scripts application allows you to create and manage a library of Jython scripts. Public class com.ibm.ism.pmzhb.runbook.task.api.TaskAPIFactory Use the TaskAPIFactory to create TaskAPI objects using the parameters passed to an action or custom condition. 118 Tivoli Service Automation Manager V7.2.4 Extensions Guide Method detail: Create a TaskAPI using custom condition objects. create public static TaskAPI create(psdi.mbo.MboRemote main, java.lang.Object param) throws java.rmi.RemoteException, psdi.util.MXException Parameters main is the main Maximo Business Object for the custom condition. param is the parameter passed into CustomCondition.evaluateCondition(MboRemote, Object). Returns The return is the TaskAPI if one exists. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. create You can create a TaskAPI using ActionCustomClass objects. public static TaskAPI create(psdi.mbo.MboRemote main, java.lang.Object[] params) throws java.rmi.RemoteException, psdi.util.MXException Parameters main is the main Maximo Business Object for the custom condition. param is the parameter passed into ActionCustomClass.applyCustomAction(MboRemote, Object[]). Returns The TaskAPI if one exists. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. Chapter 5. Defining services in Tivoli Service Automation Manager 119 Public interface com.ibm.ism.pmzhb.runbook.task.api.TaskAPI Task API is the main API interface for action classes and custom condition classes that are used in management task workflows. Task API supports access to input and output containers and to the task context. Method detail: The getOutputContainer retrieves the output container for the current task. getOutputContainer OutputContainer getOutputContainer() throws java.rmi.RemoteException, psdi.util.MXException Returns The OutputContainer or Null , if the getOutputContainer is not used in the task context. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. getInputContainer getInputContainer retrieves the input container for the current task. InputContainer getInputContainer() throws java.rmi.RemoteException, psdi.util.MXException Returns The OutputContainer or Null , if the getOutputContainer is not used in the task context. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. getWFExtensionMBO getWFExtensionMBO retrieves the PMZHBSMWFEXT Maximo Business Object, which holds the data context for the operation workflow. psdi.mbo.MboRemote getWFExtensionMBO() throws java.rmi.RemoteException, psdi.util.MXException Returns The PMZHBSMWFEXT MboRemote object. 120 Tivoli Service Automation Manager V7.2.4 Extensions Guide Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. addLogEntry addLogEntry adds a localized log entry to the service instance log. void addLogEntry(java.lang.String msgGroup, java.lang.String msgKey, java.lang.Object[] params, java.lang.String logType) throws java.rmi.RemoteException, psdi.util.MXException Parameters msgGroup is the message group to use msgKey is the message key to use params are the parameters to use in the message logType is a string you can use to differentiate the source of the message Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. Public interface com.ibm.ism.pmzhb.runbook.task.api.InputContainer and OutputContainer The public interface com.ibm.ism.pmzhb.runbook.task.api.InputContainer and public interface com.ibm.ism.pmzhb.runbook.task.api.OutputContainer are used to extend the InOutContainer. These containers inherit all the InOutContainer methods. public interface com.ibm.ism.pmzhb.runbook.task.api.InOutContainer The public interface com.ibm.ism.pmzhb.runbook.task.api.InOutContainer is the common interface for both the input and output containers. Method detail getValue retrieves the value from the container. getValue java.lang.String getValue(java.lang.String attributeName) throws java.rmi.RemoteException, psdi.util.MXException Chapter 5. Defining services in Tivoli Service Automation Manager 121 Parameters attributeName is the search key. Returns The value that matches the search key or it returns Null if no value exists. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. setValue setValue sets a value in the container. void setValue(java.lang.String attributeName, java.lang.String alnValue) throws java.rmi.RemoteException, psdi.util.MXException Parameters attributeName is the key that must be set. alnValue is the value that must be set. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. setEncryptedValue setEncryptedValue sets an encrypted value in the input or output container. void setEncryptedValue(java.lang.String attributeName, java.lang.String alnValue) throws java.rmi.RemoteException, psdi.util.MXException Parameters attributeName is the key that must be used. alnValue is the value that must be used. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. 122 Tivoli Service Automation Manager V7.2.4 Extensions Guide getAllValues getAllValues retrieves all the values in the input or output containers in a map. This map is read-only. Any changes to this map results in an exception. java.util.Map getAllValues() throws java.rmi.RemoteException, psdi.util.MXException Returns The map containing all key-value pairs in the container. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. isEncryptedValue isEncryptedValue checks to see if the value is encrypted. boolean isEncryptedValue(java.lang.String attributeName) throws java.rmi.RemoteException, psdi.util.MXException Parameters attributeName is the key that must be checked. Returns It returns true if the value is encrypted, and it returns false if the value is not encrypted or does not exist. Throws java.rmi.RemoteException when RMI exceptions are thrown. psdi.util.MXException when Tivoli's process automation engine exceptions are thrown. Using the Service Automation Request application to debug management plans You can use the Service Automation Requests application to monitor the run time data of a management plan while it is being executed. About this task The Service Automation Requests application is only available in the context of a service deployment instance. Procedure 1. In the administrative UI, click Go To > Service Automation > Service Deployment Instances. Chapter 5. Defining services in Tivoli Service Automation Manager 123 2. Put your cursor in one of the search fields, the Service Deployment Instance field, and press Enter. A list of service deployment instances opens. 3. In the list of service deployment instances, select the service deployment instance associated with the management plan that you want to debug. 4. When you run a management plan, it produces a service request, click the Service Request tab to see all the service requests associated with the specific service deployment instance. 5. Select the service request you want to debug. 6. Click the double arrows next to the particular service request, and select Go To Service Automation Requests. Describing the Service Automation Request application The Service Automation Request application contains nine tabs. The Service Request, Related Records, Specifications, and the Requests tabs are copies of Tivoli's process automation engine Service Requests application. These tabs show general information that is associated with the service request generated in Tivoli's process automation engine. The Container Mappings, Log, Workflows and VSPParams tabs show additional information for debugging. Describing the Container Mappings tab: The Service Automation Request application contains nine tabs. The Container Mappings tab is one of these tabs. This tab includes information about debugging management plans and workflows. The Container Mappings tab The Container Mappings tab shows run time data for the container mappings defined in the advanced workflow. Use container mappings to find out what parameters are mapped into the input container. If a parameter is missing or has an unexpected value, check the Log tab for any warnings that occurred during the input container mapping. The tab is divided into two sections: the first section shows the input container mappings, the other section shows the output container mappings. Both sections contain the same type of information. The next table describes the information in the columns in these sections. Table 36. Describing the columns in the Container Mappings tab 124 Column name Description Task Identifier The Task Identifier is string separated by colons, it contains three elements: the name of the advanced workflow, the revision, and the name of the task node in the advanced workflow. Operation Name The Operation Name is the name of the operation in the task node where the container mapping is defined. Parameter Parameter is the key for the container mapping. Value Value is the runtime value for the container mapping. Current Affected Topology Node ID The topology node identifier that is affected at the current time. It is defined in the container mapping. Tivoli Service Automation Manager V7.2.4 Extensions Guide Table 36. Describing the columns in the Container Mappings tab (continued) Column name Description Current Affected Topology Node Name The topology node name that is affected at the current time. It is defined in the container mapping. Current executing Topology Node ID The topology node identifier that is executed at the current time. It is defined in the container mapping. Current executing Topology Node name The topology node name that is executed at the current time. It is defined in the container mapping. Describing the Log tab: The Service Automation Request application contains nine tabs. The Log tab is one of these tabs. It includes information about debugging management plans and workflows. The Log tab The log tab contains three tabs. These tabs, show the content of three different logs created during execution of an advanced workflow. Table 37. Describing the columns in the Log tab Column name Description Work Log The Work Log contains the localized messages that are written during processing of the service request. Communication Log The Communication Log contains all communications, that is, emails that are sent during processing. Service Automation Log The Service Automation Log contains traces that are not localized and are written during the processing of the service request. Describing the Workflows tab: The Service Automation Request application contains nine tabs. The Workflows tab is one of these tabs. It includes information about debugging management plans and workflows. Workflows In it's first section, the Workflows tab shows a list of the workflows executed with the specific management plan. For each workflow, the details section shows the history of the workflow, such as, when it was created by the workflow Tivoli's process automation engine execution run time. You can follow the nodes and route that the workflow passed through during execution. The next table describes the information in the columns in these sections. Chapter 5. Defining services in Tivoli Service Automation Manager 125 Table 38. Describing the columns in the Workflows tab Column name Description Workflow Description The Workflow Description is the description of the process that the workflow passed through. Workflow Node The Workflow Node is node inside the process that is passed through. Node desc The description of the workflow node. Action Type The action type. Action performed The action that is completed. Transaction date The timestamp for the execution time of the event. Describing the VSRPARAMS tab: The Service Automation Request application contains nine tabs. The VSRPARAMS tab is one of these tabs. It includes information about debugging management plans and workflows. VSRPARAMS This tab contains attributes for the variable service request parameters used for this service request. Some service requests do not use variable service request parameters so the contents might be empty. The next table describes the information in the columns in this tab. Table 39. Describing the columns in the VSRPARAMS tab Column name Description Src Attribute Name The source attribute name Src Attribute Value The source attribute value Source Token The source token Source Name The source name Source Type The source type Making management plans available through Service Request Manager Service Request Manager offerings show management features in Tivoli Service Automation Manager service definitions. For general descriptions of Service Request Manager, look at the Service Request Manager documentation at http://publib.boulder.ibm.com/infocenter/tivihelp/ v32r1/index.jsp?topic=/com.ibm. . To create an offering, complete these steps: v Create a classification for the new service offering. v Create an offering and add it to an offering catalog. 126 Tivoli Service Automation Manager V7.2.4 Extensions Guide Related tasks: “Configuring cardinality definition for a variable service topology node” on page 93 Instead of setting default cardinality for a variable service topology node, you can configure the number of topology nodes for a variable cardinality node created during the execution of a management plan. Define the name of an attribute for the service request specification so that it can hold the number of topology nodes that must be created. Creating a classification for a new service offering You can create a classification to classify a Service Request Manager service offering. After the classification is created, you can then define a service offering and apply the classification to it. This offering can then be added to a service catalog so that users can request it. Procedure 1. In the administrative UI, click Go To > Administration > Classification. The classification application opens. 2. Put your cursor in one of the search fields, such as the Classification field, and press Enter. A list of classifications opens. 3. Select the required Tivoli Service Automation Manager classification. 4. From the Select Action menu, select Duplicate Classification. 5. Enter a new classification name and change the attributes of the classification. Creating an offering and adding it to the offering catalog If features are opened through the Service Request Manager offering catalog, you must create an offering to show these features in the service catalog. After creating the offering, add it to the catalog, so that users can request it. Procedure 1. In the administrative UI, click Go To > Service Request Manager Catalog > Offerings. Define new offerings do not duplicate an existing one. 2. On the toolbar, click the Insert an Offering 3. In the Offering field, enter a name. icon to create an offering. Restriction: The offering name must not contain any special characters other than a dollar sign "$" and underscore "_". 4. In the Description field, enter a short description. 5. In the Item Set field, enter PMSCS1. In the Offering Type field, select Service Request. In the Service Group field, select SRVAUTOM. In the Service field, select VSERVER. In the Classification field, select the appropriate classification for the new offering using the Classify wizard. 10. In the Service Request Information area, edit these fields: a. Clear the Invoke Apply Response Plans Workflow Only check box. b. Select the Automatic Line Manager Approval check box. c. Clear the Automatic Fulfillment Manager Approval check box. 6. 7. 8. 9. Chapter 5. Defining services in Tivoli Service Automation Manager 127 d. Leave the Ticket Template field empty. e. Leave the Line Manager Approval Workflow field empty. f. In the Fulfillment Manager Approval Workflow field, enter the name of the advanced workflow. The offering then starts. 11. Click the Specifications tab. 12. In the Presentation area, configure the offering attributes. You can set the offering to one of these options: Mandatory, Hidden or Read only. Ensure that these settings are correct. 13. If you want to add an image, select Add/Modify Image from the Select Action menu on the toolbar. 14. Browse for an image and select it. icon on the toolbar. 15. Save the offering, click Save an Offering 16. Add the offering to other offering catalogs. Select Add Offering to Catalog from the Select Action menu on the toolbar. 17. On the toolbar, click the Change Status Active. icon and change the status to What to do next Assign the offering to the catalog of the roles that require the offering. See Tivoli Service Automation Manager Installation and Administration Guide for more information about existing security roles. Related concepts: “Defining roles in Tivoli Service Automation Manager” on page 139 With the current release of Tivoli Service Automation Manager, service providers can introduce new roles with new functions, for example: a role to use VMware specific offerings. Service providers can reuse existing roles and group management from LDAP. Service provider's can use their own group structure with Tivoli Service Automation Manager. Related tasks: “Extending the offering panels” on page 24 Each offering panel, or request, in the self-service interface consists of a group of widgets that can be customized in many ways. You can also add new widgets to the panels. Linking offerings to management plans A link between an offering and a management plan is created using specific attributes. The link is made between the offering, which models the type of request that the user submits, and the management plan that completes the request. To implement the management plan, the fulfillment manager approval workflow field must contain the name of the workflow. There are also five specification attributes that the offering must contain. 128 Tivoli Service Automation Manager V7.2.4 Extensions Guide Table 40. Specification attributes Specification attribute Description PMRDPCLCPR_PROJECTNAME This attribute must be present when creating a service instance. It includes the name for the service instance being created. This attribute is only required when the offering is used to create a service instance. PMRDPCLCPR_SERVICEDEFINITIONNUM The SDNUM of the service definition that is used to create a service instance. This attribute is only required when the offering is used to create a service instance. PMRDPCLCPR_SERVICEDEFINITIONREVISION The revision of the service definition which that is used to create a service instance. This attribute is only required when the offering is used to create a service instance. PMRDPCLCPR_SERVICEINSTANCEID The unique ID of the service instance that is used to run a management plan. This attribute is important if the editing management plans are executed on service instances that are previously created. If this attribute is populated, the service definition-related attributes are ignored. PMRDPCLVSRV_MPNUM This attribute specifies the management plan that is executed on a new or existing service instance. Applying server side validations to offerings If an offering contains an attribute with a TABLE data type, or is updated with new attributes that contain TABLE data types, then you must enable server side validations. Associating lookups with offerings To enable server-side validations, you must associate lookups with the attributes of an offering. About this task Note: The user-defined names that are used in these steps are for example purposes only. They are marked in italics. Attributes that contain the TABLE data type include this information: v An attribute name such as PMRDPCLCVS_ MPNUM. v A data type that is set to TABLE. v A Lookup Name that is defined in the lookup domain. v A Table Attribute, which you can select. Chapter 5. Defining services in Tivoli Service Automation Manager 129 v A Table Value, which you can select. Procedure 1. Create a domain called ssvl_pmzhbsmpln and select TABLE as the domain type. 2. Select an appropriate value for the OBJECT attribute. In this procedure, the value for the OBJECT attribute is pmzhbsmpln. 3. Using the Classification application, associate the ssvl_pmzhbsmpln domain with the PMRDPCLCVS_ MPNUM attribute. 4. Create a lookup name called ssv_pmzhbsmpln as an entry in the predefined lookup domain. To create the lookup name: a. In the administrative UI, click Go To > System Configuration > Platform Configuration > Application Designer. b. Export the Lookup.xml file and save it to a location on your computer. c. Add the ssv_pmzhbsmpln lookup name to the Lookup.xml file. The lookup name defines how attribute values with a TABLE data type are shown in the administrative user interface. This sample xml is updated with the ssv_pmzhbsmpln lookup name. The table id contains the ssv_pmzhbsmpln domain. The pmzhbsmpln object defined in step 2 contains two attributes: "MPNUM", and "description". These attributes are set in the dataattribute tag. d. Import the Lookup.xml file. 5. In the Lookup Name field, select the lookup name defined in step 4 for the offering. Results After the values are associated with the offering, the offering definition contains this information: v The attribute name, which is PMRDPCLCVS_ MPNUM. v The Data Type, which is set to TABLE. v The Lookup Name, which is set to ssv_pmzhbsmpln. v The Table Attribute, which is set to MPNUM. Related tasks: “Creating a domain to use with a classification attribute” on page 131 Your classification defines attributes that are shown to the user in the Service Request Manager offering catalog user interface. If these attributes provide the user with a list of values to select from, you must create a domain. You then assign the domain to the particular attribute of your classification. 130 Tivoli Service Automation Manager V7.2.4 Extensions Guide Creating a domain to use with a classification attribute Your classification defines attributes that are shown to the user in the Service Request Manager offering catalog user interface. If these attributes provide the user with a list of values to select from, you must create a domain. You then assign the domain to the particular attribute of your classification. About this task To create a domain, complete these steps: Procedure 1. In the administrative UI, clickGo To > System Configuration > Platform Configuration > Domains. The Domains application opens. 2. Click Add New Domain. 3. Select Add New ALN Domain. The ALN Domain window opens. 4. Enter a name for the domain and select values for the domain. 5. Click OK. 6. Next, add a new attribute to the classification and associate the attribute with the domain. In the administrative UI, click Go To > Administration > Classifications. The Classifications application opens. 7. Put your cursor in one of the search fields, such as the Classification field and press Enter. A list of classifications opens. 8. Open the classification. In the Attributes table, click New Row and add a new attribute to the classification. Add the newly created domain. Related tasks: “Associating lookups with offerings” on page 129 To enable server-side validations, you must associate lookups with the attributes of an offering. Updating service definitions with parts of other service definitions You can update a service definition or service deployment instance with parts of another service definition using service update package. The service update package If you change a service definition, for example, by adding attributes to topology nodes, these changes are applied to this particular service definition only. Any copies of the service definition are not changed. By using a service update package, you can apply the changes from the existing service definition to its copies. A service update package contains parts of a service definition which can be used to update other service definitions. It is a separate package which means that after it is defined and approved, it contains independent copies of management plans and topology nodes. Create the service update package manually by selecting the parts of a service definition that you want to go into the package. Service update packages can be created from approved service definitions only. You can apply service update packages to service definitions that are in the design state or to service deployment instances which are in the operation or maintenance state only. Chapter 5. Defining services in Tivoli Service Automation Manager 131 Building a service update package from a service definition You can build a service update package, which can include several management plans and topology nodes. The management plans and topology nodes are taken from the service definition that you use to build the service update package. Procedure 1. Create the service update package. a. In the Service Definitions application, click the List tab. b. Choose the service definitions you want in your service update package. c. In the Service Definitions application, click the Service Update Packages tab. d. Click Create Service Update Package. e. Enter a name, description, and owner for the service update package and click OK. 2. Refine the service update package. a. Go to the Start Center. b. Select the assignment called: TivSAM - : Refine Service Update Package from the inbox. All management plans and topology nodes that are part of the service update package are listed in the Define Service Update Package application. c. Choose the management plans and topology nodes by clicking the corresponding fields. d. To finish, click Route Workflow from the toolbar menu and click Complete an Assignment. 3. Approve the service update package. a. Select the assignment called: TivSAM - : Approve Service Update Package from the inbox. b. In the Service Update Package application, click Approve Service Update Package from the toolbar menu. c. To finish, click Route Workflow from the toolbar menu and click Complete an Assignment. Deploying a service update package on a service definition You can use this task to deploy a service update package on a service definition. Before you begin The service update package must be approved before you can deploy it on a service definition. Procedure 1. Select the service update package you want to deploy. a. Go to the Service Update Packages application: Go To > Service Automation > Service Update Packages. b. In the List tab, select the service update package. Information is displayed about the package, the information includes management plans and topology nodes that are contained in the package. c. Click the Service Definition Deployments tab. 2. Deploy the service update package. 132 Tivoli Service Automation Manager V7.2.4 Extensions Guide a. Click Deploy on Service Definitions. All the service definitions in the design state are listed. b. To choose service definitions from the list, select the corresponding check boxes. c. Click Deploy on Service Definitions. 3. Monitor the deployment process. a. Select the corresponding deployment entry under Service Update Package Deployments on Service Definitions. b. Click Refresh to monitor the deployment process. The status is set to Pending at the start of the deployment process. It then changes to In Progress, and finally to either Failed or Applied. c. Check the Messages section to see the results of the deployment. d. To refresh the panel, select Refresh page contents from the toolbar menu. Deploying a service update package on a service deployment instance Deploy a service update package on a service deployment instance. Before you begin The service update package must be approved before you can deploy it. Procedure 1. Select the service update package you want to deploy: a. Go to the Service Update Packages application: Go To > Service Automation > Service Update Packages. b. In the List tab, select the service update package. Information about the package is displayed, the information includes management plans and topology nodes contained in the package. c. Click the Service Instance Deployments tab. 2. Deploy the service update package: a. Click Deploy on Service Deployment Instances. All the service deployment instances that are in the Operational or Maintenance state are listed. b. Choose the service deployment instances from the list by selecting the corresponding check box. c. Click Deploy on Service Deployment Instances. 3. Monitor the deployment process: a. Select the corresponding deployment entry under Service Update Package Deployments on Service Definitions. b. Click Refresh to monitor the deployment process. The status is set to Pending at the beginning of the deployment process. It then changes to In Progress, and finally to either Failed or Applied. c. Check the Messages section to see the results of the deployment. d. To refresh the panel, select Refresh page contents from the toolbar menu. Chapter 5. Defining services in Tivoli Service Automation Manager 133 Exporting service definitions and related data Service definitions and their related structures can be exported from one Tivoli Service Automation Manager environment and imported into another. A service definition usually includes management plans, a monitoring definition, and a topology template. About this task Note: To manage the dependencies of multiple service definitions on a common data infrastructure, first package and transfer a library part, which contains the infrastructure, and then package and transfer the actual service definitions and related data. The source and target environments must be running the same Tivoli Service Automation Manager version. This task is a manual function. It is completed outside Tivoli Service Automation Manager using the Migration Manager application of the System Configuration module. The basic steps involved in the transfer are: Procedure 1. Select the migration groups. 2. Select the data to be exported. 3. Create the deployment package. 4. Distribute the package. 5. Deploy the package on the target system. Exporting a service definition structure from a Tivoli Service Automation Manager environment You can export a service definition, its service deployment instances, and topology node operations from one Tivoli Service Automation Manager environment to another Tivoli Service Automation Manager environment. About this task Procedure 1. For troubleshooting purposes: a. Click Go To > System Configuration > Platform Configuration > Logging b. Search for the integration logger. icon next to the Log Level c. Set the log level by clicking the select value field. Select DEBUG from the list. d. Select the Active check box to activate the logger. icon. e. On the toolbar, click the Save f. From the Select Action menu, select Apply Settings. 2. Check that all prerequisite structures are available in the target database by packaging them separately in a library part package. Import this package on the target system. These prerequisites might be shared by multiple service definitions. These items can be included in the library part package: v A DATADICTIONARY, which consists of domains. 134 Tivoli Service Automation Manager V7.2.4 Extensions Guide v A Business process management (BPM), which consists of actions and workflows. v A TSAM_TNOPS, which consists of topology node operations, job plans, classifications, and asset attributes. a. Open the Migration Manager application: Go To > System Configuration > Migration > Migration Manager. b. Create a package definition, enter a name and description. c. In the Migration Groups section, click New Row and select the TSAM_TNOPS migration group. d. Click Set Where Clause and specify what you want to include in the migration package for each object structure. For example: v Topology node operations (PMZHBWTNOP): opowner like 'PMRDP% v Classifications (CLASSSTRUCTURE): classificationid like 'PMRDP%' and parent='PMZHBWTNC' v Job plans (JOBPLAN): jpnum like 'PMRDP%' v Asset attributes (ASSETATTRIBUTE): assetattrid like 'PMRDP%' e. In the Migration Groups section, click New Row and select the DATADICTIONARY migration group. f. Click Set Where Clause and specify what you want to include in the migration package. For example: v domains (MAXDOMAIN): domainid like 'PMRDP% For any object structure that you do not want in your package, enter any condition that evaluates to false such as 1=2. g. If you want, add other migration groups. h. On the toolbar, click the Save icon. i. On the toolbar, click the Change Status definition. icon to approve the package j. From the Select Action menu, select Activate package definition. k. Click the Package tab. l. Click Create. 1) Select a processing action for the target system: replace First delete the existing content, then insert the new content in the database. addChange Adds the content or updates the existing content. 2) Enter some information about the package. 3) You might want to upload compiled sources, which can be any type of file to include in the package. 4) Click Continue and wait while the package is being created. m. Click the Distribution tab. n. From the Select Action menu, select Manage Targets and if it is necessary, add a new distribution target with a FILE type to the package. o. In the Distributions section, click New Row. p. Select the target. q. On the toolbar, click the Save icon. Chapter 5. Defining services in Tivoli Service Automation Manager 135 r. Click the Package tab and click Distribute. s. Select your distribution target and click OK. t. Click OK when the Processing Complete... message is displayed. A package archive file with .zip extension is in the distribution target directory. u. Move this file to the target system. v. Import the package on the target system. To complete this task, see the “Importing a Tivoli Service Automation Manager migration package” on page 138 section. 3. Repeat the previous procedure for all the service definitions associated with the TSAM_SVCD migration group and for all the service deployment instances associated with the TSAM_SVCI migration group . Any content that is referenced from these object structures must be present in the target system before the structures are imported. Transferring service update package structures You can transfer service updates package between Tivoli Service Automation Manager environments running the same version. First, export the service update package from one environment and then import it to the other. About this task For example, a service update package can be defined and approved in one environment, and applied onto a service definition or service deployment instance in another environment. The major portion of this manual process is completed outside Tivoli Service Automation Manager using the Migration Manager application of the System Configuration module. The service update package consists of: v Management plans v Topology template information Exporting a service update package structure from a Tivoli Service Automation Manager environment You can export a service update package and topology node operations from a Tivoli Service Automation Manager so that they can be imported into another Tivoli Service Automation Manager environment. About this task Procedure 1. For troubleshooting purposes: a. Click Go To > System Configuration > Platform Configuration > Logging b. Search for the integration logger. icon next to the Log Level c. Set the log level by clicking the select value field. Select DEBUG from the list. d. Select the Active check box to activate the logger. icon. e. On the toolbar, click the Save f. From the Select Action menu, select Apply Settings. 136 Tivoli Service Automation Manager V7.2.4 Extensions Guide 2. Check that all prerequisite structures are available in the target database by packaging them separately in a library part package. Import this package on the target system. These prerequisites might be shared by multiple service update packages. To complete this task see the“Exporting a service definition structure from a Tivoli Service Automation Manager environment” on page 134section. 3. Export the required service update package: a. Open Migration Manager, clickGo To > System Configuration > Migration > Migration Manager b. Create a package definition, enter a name and description. c. In the Migration Groups section, click New Row and select the TSAM_UPKG migration group. d. Click Set Where Clause and specify what you want to include in the migration package. For example, the PMZHBUPKG service update whose status is: select value from synonymdomain where domainid=’PMZHBUPKGSTATUS’ and maxvalue =’APPROVED’) and PACKAGENUM = ’1000’ Use either the PACKAGENUM or PACKAGEID attributes to specify which update package you want to export. Check that it is only service update packages whose status is approved that are exported. e. On the toolbar, click the Save icon. f. On the toolbar, click the Change Status definition icon to approve the package g. From the Select Action menu, select Activate package definition. h. Click the Package tab. i. Click Create. v Select a processing action for the target system: replace First delete the existing content, then insert the new content in the database. addChange Adds the content or updates the existing content. v Enter information about the package. v If you want, upload compiled sources of any file type to be included in the package. v Click Continue and wait while the package is being created. j. Click the Distribution tab. k. From the Select Action menu, select Manage Targets and if it is necessary, add a new distribution target with a FILE type to the package. l. In the Distributions section, click New Row. m. Select the target. n. On the toolbar, click the Save o. Click the Package tab. p. Click Distribute. icon. q. Select your distribution target and click OK. r. Click OK when the Processing Complete... message is displayed. A package archive file with .zip extension is in the distribution target directory. Chapter 5. Defining services in Tivoli Service Automation Manager 137 s. Move the package archive file to the target system. What to do next Import the package on the target system. Importing a Tivoli Service Automation Manager migration package You can import a migration package that was previously exported to another Tivoli Service Automation Manager environment. About this task Note: The two environments must be running the same Tivoli Service Automation Manager version. Procedure 1. In the target system environment, In the target system environment, Open the Migration Manager application: Click Go To > System Configuration > Migration > Migration Manager. 2. From the toolbar, click Upload Package, select the package, and click OK. 3. Click Deploy. 4. Check that you have a database backup so that you can restore the database in case errors occur during deployment. 5. Click Deploy. Enter your password and the reason for the change. 6. When the deployment is complete, go the specific application such as the Service Definitions application and select the imported component. 138 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 6. Security IBM Tivoli Service Automation Manager includes the following security mechanisms. Defining roles in Tivoli Service Automation Manager With the current release of Tivoli Service Automation Manager, service providers can introduce new roles with new functions, for example: a role to use VMware specific offerings. Service providers can reuse existing roles and group management from LDAP. Service provider's can use their own group structure with Tivoli Service Automation Manager. A detailed description of the following use cases is provided. v Steps to create a role in Tivoli Service Automation Manager. v Steps to reuse existing groups and users from LDAP in Tivoli Service Automation Manager. Related tasks: “Creating an offering and adding it to the offering catalog” on page 127 If features are opened through the Service Request Manager offering catalog, you must create an offering to show these features in the service catalog. After creating the offering, add it to the catalog, so that users can request it. Creating a role in Tivoli Service Automation Manager An example is used here, to create a role which can manage a project with a VMware hypervisor. Before you begin Understand the existing role model in Tivoli Service Automation Manager and be aware of the security model and data restrictions. In the following procedures, a role is equivalent to a security group. About this task The following steps are required to create a group in Tivoli Service Automation Manager: 1. Create a service catalog in Tivoli Service Automation Manager. 2. 3. 4. 5. 6. 7. Create a security group in Tivoli Service Automation Manager. Assign a service catalog and configure privileges for the security group. Grant signature options and configure permissions for the security group. Grant reassignment authorization to a security group. Assign users to a security group. Verify a security group. © Copyright IBM Corp. 2011, 2013 139 Creating a service catalog A service catalog defines the set of offerings that a new role can access. About this task Each role has its own catalog. You can be member of multiple roles, and, as a result, you have access to all offerings that are assigned to the roles in which you are a member. Note: A useful reference when you are completing this task is the service catalog Redbooks at http://www.redbooks.ibm.com/abstracts/sg247613.html Procedure 1. Log in to the administrative UI as PMSCADMUSR. 2. In the administrative UI, Go To > Service Request Manager Catalog > Catalogs icon. 3. To create a catalog, click the Insert a catalog 4. Enter a name and description, for example, enter VMWAREPA for the name, and Vmware project administrators for the description. 5. Select Add Multiple Offerings from the Select Action menu on the toolbar. 6. Select the offerings from the list, for example: Create Project for Vmware Servers, Add Server for Vmware Servers, Cancel Project, Modify Reservation, and Modify Server Resources. 7. To add the selected offerings to the catalog, click ADD. 8. To review the offerings added, click the Offerings tab. 9. Change the state of the catalog to active by selecting theChange Status from the Select Action menu on the toolbar. 10. Save the catalog and log out. Creating a security group Tivoli Service Automation Manager uses security groups to model the role and security model. A security group defines the permissions and privileges of the role. Users which are members of multiple security groups have permissions and privileges of all the security groups in which they belong. About this task Note: If you are using application server security and LDAP, the security group should be created within LDAP. The group can be synchronized withTivoli Service Automation Manager using the VMMSYNC cron task. Refer to the official Tivoli Service Automation Manager documentation at http://publib.boulder.ibm.com/ infocenter/tivihelp/v10r1/index.jsp?topic=%2Fcom.ibm.ccmdb.doc_7.1.1%2Finstall %2Ft_ccmdb_configcrontask.html for details on how to synchronize with LDAP. Procedure 1. In the administrative UI, click Go To > Security > Security Groups (SP). icon. 2. To create a security group, click the New Group 3. Enter a name and description, for example enter VMWAREPA for the name, and VMware Project Administrators for the description. 4. Select the Independent of Other Groups checkbox. 5. Save the security group. 140 Tivoli Service Automation Manager V7.2.4 Extensions Guide Related tasks: “Configuring a security group” on page 146 The procedure to configure an existing security group is the same as the procedure to create a security group. Assigning a service catalog to a security group A catalog is assigned to a security group to authorize the role for a set of offerings. You can assign multiple catalogs to a security group. All users who are members of the security group, have access to offerings in the self-service user interface. Procedure 1. In the administrative UI, click Go To > Security > Security Groups (SP). 2. Open the security group created in “Creating a security group” on page 140. 3. Click the Service Catalog tab and in the Authorized Catalogs section, click Add Row. 4. Click the double arrows next to the Catalog field, and choose Select Value. 5. Save the security group. Assigning signature options to a security group Signature options are used to improve usability in the self-service user interface. Signature options are related to the Tivoli's process automation engine application and can be authorized for each security group. In Tivoli Service Automation Manager, a Tivoli's process automation engine application, defines the signature options used in the self-service user interface. About this task Signature options can also be used to restrict web methods being called. The most important signature option is related to approval. Signature options enable the approval pod and authorize the group to call the approval web service. Procedure 1. In the administrative UI, click Go To > Security > Security Groups (SP). 2. Open the security group created in“Creating a security group” on page 140. 3. Click the Applications tab. 4. To search the applications, enter Cloud Web 2.0 Application in the Description field. 5. Select the Grant Access check box next to Read Access to Web 2.0 Service Requests option. 6. In the next section on this window, select access to the signature options of the application. 7. Save the security group. Related reference: “Signature options” on page 143 Signature options can be assigned to security groups. Chapter 6. Security 141 Providing reassignment authorization to a security group Group reassignment authorization permits a user to create a user for the group, that is, if a user has reassignment authorization to a group, the user can add new users to that group. Procedure 1. In the administrative UI, click Go To > Security > Security Groups (SP). 2. Open the security group created in.“Creating a security group” on page 140 3. Select Authorize Group Reassignment from the Select Action menu on the toolbar. 4. In the window that opens, click Select Users to select the users with grant option to the security group, for example, PMRDPCAUSR, PMRDPCSAUSR. 5. Click OK to add the users to the reassignment authorization table. 6. Click OK to close the window. 7. Save the security group. Assigning users to a security group Users who are members of a security group have permissions and privileges of that particular group. A user can be member of multiple groups, therefore, the permission and privileges can be shared across multiple groups. For example, if user A is in group X and is also in group Y, and user A has approval right from group X and no approval right from group Y, then user A has the right to approve. Procedure 1. In the administrative UI, click Go To > Security > Security Groups (SP). 2. Open the security group created in“Creating a security group” on page 140 3. Click the Users tab and click Select Users. 4. Select the users that are members of the security group, for example, PMRDPCSAUSR and click OK. 5. Save the security group. Verifying the security group Verifying the security group includes checking the new role is working properly and that all permissions and privileges provided are correct. The verification steps must be completed carefully to ensure that sensitive data is secure. Procedure 1. Log in to the self-service UI as the user with reassignment authorization, for example, PMRDPCAUSR. See step 4 in the“Providing reassignment authorization to a security group” procedure. 2. Go to the offering in Request a New Service > Virtual Server Management > Manage Users and Teams > Create User. 3. Enter the user details, for example, enter test for the User and enter maxadmin for the Password, click Next. 4. Select Cloud Customer Level Policy from the Security menu. 5. Select the Access checkbox next to the security group created in.“Creating a security group” on page 140 6. Click Next to enter the personal settings. 7. Click Next to enter regional settings. 8. Click Next to select at least one team submit request. 142 Tivoli Service Automation Manager V7.2.4 Extensions Guide Log out. Log in to the self-service UI as the new user created in step 3 on page 142. Go to Request a New Service > Virtual Server Management. Verify that only the offerings which are visible are added to the catalog in “Creating a service catalog” on page 140. 13. If the approval signature option is granted, verify that the approval pod is visible. 9. 10. 11. 12. Signature options Signature options can be assigned to security groups. List of options table Note: Other signature options are Tivoli's process automation engine defaults which are not used in Tivoli Service Automation Manager, so they can be ignored. Table 41. Option Description Comments ALLPRJ The group can view all projects using this option. Assign this option for administrative user groups, such as cloud administrator (CA) and cloud customer administrator. ALLSR The group can view all service requests using this option. Assign this option for administrative user groups, such as CA and cloud customer administrator. ALLTEAMS The group can view all teams Assign this option for using this option. administrative user groups, such as CA and cloud customer administrator. ALLUSERS The group can view all users using this option. Assign this option for administrative user groups, such as CA and cloud customer administrator. APPROVAL Approval features are provided with this option. Assign access to the approval panel and approval web service. APPROVALWS The WebService method for service request approval is provided with this option. The group can call the approval web service method. CLOUDLEVEL Use the group on the cloud level. The group can be used on the cloud level only. CUSTOMERLEVEL Use the group on the customer level. The group can be used on the customer level only. GRANTOPTION You can configure security groups in the create or modify user wizard. Assign this option to modify security group settings, for example, if you are editing personal information and passwords. MYAPPRPOD The Grant My Approval panel. Assign this option to make the pod visible in the self-service user interface. Chapter 6. Security 143 Table 41. (continued) Option Description Comments MYCUSTPOD The Grant My Customer panel. Assign this option to make the pod visible in the self-service user interface. MYPROJPOD The Grant My Project panel. Assign this option to make the pod visible in the self-service user interface. MYSRPOD The Grant My Service Request panel. Assign this option to make the pod visible in the self-service user interface. RAS_COMPARE_VMS RAS - The list all virtual servers available on a host platform: hypervisor and DCM view. Assign this option for administrative user groups, such as CA to start the RAS handler. RAS_DELETE_VMS RAS - Delete all virtual servers available on a host platform from DCM. Assign this option for administrative user groups, such as CA to start the RAS handler. RAS_FORCE_CLEANUP RAS - Remove all service deployment instance-related data. Assign this option for administrative user groups, such as CA to start the RAS handler. RAS_LIST_SDIRES Assign this option for RAS - The list of all service deployment instance backend administrative user groups, such as CA to start the RAS resources. handler. RAS_LIST_VMS RAS - The list of all virtual servers available on a host platform: hypervisor view. Assign this option for administrative user groups, such as CA to start the RAS handler. RAS_SR_STATUS RAS - Get the status of the service request. Assign this option for administrative user groups, such as CA to start the RAS handler. RAS_VALIDATE RAS - Validate the service deployment instance data consistency. Assign this option for administrative user groups, such as CA to start the RAS handler. READ Read access to the self-service This option is required to use user interface service signature options. requests. Related tasks: “Assigning signature options to a security group” on page 141 Signature options are used to improve usability in the self-service user interface. Signature options are related to the Tivoli's process automation engine application and can be authorized for each security group. In Tivoli Service Automation Manager, a Tivoli's process automation engine application, defines the signature options used in the self-service user interface. 144 Tivoli Service Automation Manager V7.2.4 Extensions Guide Reusing existing users and groups from LDAP An example of an existing group of LDAP users to manage a project with VMware hypervisor is provided here. Before you begin An administrator must know how to modify groups and users in LDAP/WebSphere. The host name and LDAP/Websphere server details are required to complete the following steps. About this task The following steps describe how an administrator uses existing groups and users in LDAP to work with Tivoli Service Automation Manager. Procedure 1. Identifying security groups and users in LDAP. 2. Adding users to policy security groups in LDAP. 3. Enabling security user and group synchronization using VMMSYNC. 4. Configuring security groups. 5. Assigning users to customers. 6. Verifying users and groups. Identifying users and groups in LDAP Identify the users and groups that must be synchronized from LDAP to Tivoli Service Automation Manager. About this task This example explains one group, which has one user, as a member of that group. The group that is being used here is the one created in “Creating a security group” on page 140. A user with a name called VMWAREPAUSR, is a member of the VMWAREPA group. Adding users to policy security groups in LDAP To define the level of authorization for a particular user, add a user to the policy security group. The administrator must decide whether the users are put on the cloud level policy or customer level policy. About this task For more information, see the security and data restriction at http:// publib.boulder.ibm.com/infocenter/tivihelp/v10r1/index.jsp?topic= %2Fcom.ibm.tsam_7.2.2.doc%2Fc_sp_data_segregation.html. Procedure 1. Log in to the LDAP/WebSphere host using the LDAP/WebSphere administrative account, for example: https://localhost:9043/ibm/console and user wasadmin. 2. Go to the cloud level policy group: PMRDPCLOUDPOLICY. a. Go to Users and Groups > Manage Group. b. In the Search for field, enter PMRDPCLOUDPOLICY and click Search c. Select the group. Chapter 6. Security 145 3. 4. 5. 6. 7. Select the Members tab. Click Add Users. Search for the users that must be added to the cloud level policy group. Select the users and click Add. Click OK in the group properties. 8. Repeat the previous steps, to add a user to the customer level policy group: PMRDPCUSTPOLICY. 9. Save your information. Enabling security group synchronization using VMMSYNC Tivoli's process automation engine and Tivoli Service Automation Manager provide a cron task called VMMSYNC which is used to synchronize the user, person, groups, and user-group memberships from LDAP into Tivoli Service Automation Manager. About this task The VMMSYNC cron task is described in the Service Request manager information center at http://publib.boulder.ibm.com/infocenter/tivihelp/v10r1/ index.jsp?topic=/com.ibm.srm.doc_7.1/installing/src/t_ccmdb_configcrontask.html. The following steps describe how to activate the VMMSYNC cron task in Tivoli's process automation engine. Procedure 1. In the administrative UI, Go To > System Configuration > Platform Configuration > Cron Task Setup 2. Search for the VMMSYNC cron task. 3. Select the VMMSYNC cron task. 4. If the cron task instance schedule is too slow or too fast, you might have to adjust it, to define how often the cron task should run. 5. Select the Active check box to activate the cron task instance. 6. Save the cron task. 7. On the toolbar, select Reload Request from the Select Action menu. 8. Select the cron task instance and click OK. In the details of the cron task instance, you can verify the last run time of the cron task. Configuring a security group The procedure to configure an existing security group is the same as the procedure to create a security group. About this task The security group exists and is synchronized from LDAP, so the “Creating a security group” on page 140 steps can be skipped. Related tasks: “Creating a security group” on page 140 Tivoli Service Automation Manager uses security groups to model the role and security model. A security group defines the permissions and privileges of the role. Users which are members of multiple security groups have permissions and privileges of all the security groups in which they belong. 146 Tivoli Service Automation Manager V7.2.4 Extensions Guide Assigning users to customers For the cloud level policy, the user must be assigned to the default customer PMRDPCUST. If the user is on the customer level policy, the user is limited to the customer associated with the user. Before you begin Ensure that the customer is registered with Tivoli Service Automation Manager, using the create customer offering. In this example, the default customer PMRDPCUST is selected to assign the user to all objects of the customer. About this task For each user, the following steps are mandatory to assign a user to a customer. Procedure 1. In the administrative UI, click Go To > Service Automation > Configuration > Cloud Customer Administration. 2. 3. 4. 5. 6. Search for the customers the user is assigned to, and select these customers. Click the Teams and User tab. Click Assign User and Person under the Users table. Select the users you want to assign to the customer. Click OK to assign the selected users to the customer. Verifying users and groups This task verifies that the synchronization and configuration of users and groups is successful. Procedure 1. Log in to the self-service UI as a new user, for example, as user PMRDPCAUSR and password maxadmin. 2. Go to Request a New Service > Virtual Server Management. 3. Verify that only the offerings which are visible are added to the catalog in “Creating a security group” on page 140. Policy level security groups Tivoli Service Automation Manager provides two policy level security groups: the cloud level policy security group and the customer level policy group. The cloud level policy group assigns access to the cloud, that is, users can access all customers. The customer level policy group assigns access to customer data only. Policy level groups are security groups in terms of Tivoli's process automation engine. They are configured using the Security Groups application. To access this application, in the administrative user interface, Go To > Security. Tivoli Service Automation Manager includes two default security groups which are registered in the following two system properties: v pmrdp.security.cloud.level.group v pmrdp.security.customer.level.group To access the previous system properties, in the administrative user interface, Go To > System Configuration > Platform Configuration > System Properties. Chapter 6. Security 147 Policy level security groups use data restrictions to restrict data to customers listed in the customer access list of a person. If a new customer object is added, you must add a new data restriction to the customer level group for that customer. The cloud level policy group also contains data restrictions for the service catalog to restrict access to offerings by cloud level users. Data restriction and customer objects With new services provided by Tivoli Service Automation Manager, security and multi-tenancy are important. For example, if a service requires new APIs and object structures, then the data must be separated between customers, that is, customer A cannot access the data for customer B. Tivoli Service Automation Manager includes customer objects which are provided by the service provider capabilities of Tivoli's process automation engine. If a data object is introduced as a customer object, a set of data restrictions is applied to each API call, to restrict access to the data object. For example, if a new service to enhance storage is introduced, using the self-service user interface a user can select a storage pool and request storage resources from that pool. The user can also mount storage resources for the servers in a project which are previously requested. You can use two methods to restrict data for the previous example, they are: 1. To grant access, storage pools can be assigned to customers. 2. Storage resources which are requested, must be restricted to separate data. An example for method 1 Assume that a storage pool called SP1 is configured and customers A, B, and C are selected, using the first method above, a service provider can assign SP1 to customers A and B, but not to customer C. In other words, customers A and B, can request data from SP1, but customer C cannot request data from SP1. An example for method 2 Assume that you have the first method applied, now customer A requests a storage resource called SR_A1 from the SP1 storage pool. The second method ensures that only customer A can access SR_A1, customers B, and C cannot access SR_A1. Identifying the MBO of the resource object The MBO that must be restricted, is the root MBO of the object structure exposed through the Representational State Transfer (REST) API. If the REST API call is requesting the storage pool, you must use the MBO of the storage pool object. For example in Tivoli Service Automation Manager, the MBO of the cloud server pool object is called PMRDPVRP and the MBO of the cloud storage pool is called PMRDPSTORPOOL. 148 Tivoli Service Automation Manager V7.2.4 Extensions Guide Extending the Cloud Customer Administration for a resource assignment Using the Cloud Customer Administration application, the administrative user can assign resources to a selected customer. To access the cloud customer administration application in the administrative user interface, Go To > Service Automation > Configuration > Cloud Customer Administration. In Tivoli Service Automation Manager, the cloud server pool, and the cloud storage pool can be assigned to a customer using the tab group on the Customers window. For each resource type, a separate table is shown which lists the assigned resources. If a new resource type is introduced, then a new table must be extended. You can use Tivoli's process automation engine extensibility functions to extend a new table. Other important points are: v Use the Database Configuration application to add two new relationships to the PLUSPCUSTOMER object. The new relationships can list the current resources assigned and the resources which are not assigned yet. v Use the Application Designer application, to extend the Cloud Customer Administration applications. v Copy and paste an existing tab and table and adapt the attributes for the new resource type. v Reuse the generic data bean implementation of the table. v Copy and paste the data from the existing multi-select dialog, and adapt the data attributes to the new resource type. v Reuse the generic data bean implementation for the dialog. Configuring data restriction for the resource To restrict access to certain types of resources, Tivoli Service Automation Manager provides a set of customer objects. The customer level policy group, whose default group is PMRDPCUSTPOLICY, lists data restrictions for customer objects. The security group contains a data restriction for each object. Some important requirements for data restrictions are: v The condition must select the resources which the user is requesting, so the user can trigger the condition through a REST API call. v A data restriction is an SQL condition applied in a select from where type statement. v In the condition, the variables: :user and :&personid& must be available to find which user is querying the data. v The Tivoli Service Automation Manager default configuration uses data restrictions which use the list of customers from the customer access list of a person. To access the customer list of a person: Go To > Administration > Resource > People (SP). v For the Rest API, use data restrictions with the QUALIFIED type where no application is defined. For more information, see http://www.redbooks.ibm.com/abstracts/ sg247891.html?Open. Chapter 6. Security 149 Investigating other functions in the self-service user interface for cloud level users With Tivoli Service Automation Manager, administrative users on the cloud level can act as substitutes for customers. For example, cloud level users can select a customer and work on behalf of that customer. When cloud administration users select a customer in the self-service user interface, Tivoli Service Automation Manager filters the queries for that customer. The offering panels show data for the selected customer only. Tivoli Service Automation Manager applies a filter statement to each REST query. If a new customer object is added, you must add an appropriate filter statement to each REST API call. Examples v A master image entry is a customer object that can be assigned to multiple customers. The REST call is added using this filter statement: &PLUSPCUSTOMER.CUSTOMER=. PLUSPCUSTOMER is a resource MBO relationship that lists the customers associated with the master image entry. The customers are selected from the customer selection box in the self-service user interface. An example of the master image entry is: https://:9443/maxrest/ rest/os/TPV02IMGLIBENTRYMSTR?_lid=maxadmin&_lpwd=maxadmin &PLUSPCUSTOMER.CUSTOMER=CUSTOMERA v Projects or teams are only associated with one customer. The filter statement is similar to this statement: &PLUSPCUSTOMER=. PLUSPCUSTOMER is the attribute in the resource MBO which is requested. It contains the customer name associated with the resource. An example of the persongroups team is: https://:9443/maxrest/ rest/os/ MBS_PERSONGROUP?_lid=PMRDPCAUSR&_lpwd=maxadmin&CLOUDTEAM=1 &PLUSPCUSTOMER=CUSTOMERA 150 Tivoli Service Automation Manager V7.2.4 Extensions Guide Chapter 7. Advanced workflow references The Workflow applications enable you to plan, design, build, test, implement, manage, and automate workflow processes. Related tasks: “Creating a management plan from advanced workflows” on page 96 Examples are used to explain how to create a management plan. Workflow overview You use the Workflow applications to plan, design, build, test, and manage workflow processes. Workflow provides a means of electronically reproducing business processes so that they can be applied to records. You can manage the movement of a record through a process from start to finish. You can instruct individuals to act on records, specify delegates when workers are unavailable, ensure that individuals act in a timely manner, and ensure that an audit trail exists for each record and process. Workflow is an integrated part of the software. Workflow processes and their supporting records are at the system level in a multisite implementation. Workflow processes can be used for all organizations and sites. You can design processes or subprocesses that are specific to an organization or specific to a site, through the use of logical branching. You can create a workflow process for any business object. Because all the applications are associated with Maximo business objects and can run a customer-developed Java class or script, you can build workflow processes for any application, including cloned and custom applications. Workflow handles assignments in a flexible manner. Assignees can receive notifications of assignments in their Workflow Inbox or in their e-mail inbox, eliminating the need for users to search for their assignments. Workers or administrators can reassign workflow tasks, stop a process instance, and remove a record from the control of Workflow. You can specify at what point in a process you want e-mail notifications generated. Delegates can be specified when workers are unavailable. A workflow process can run a program, such as a batch file or an .exe file, that is stored on a local server in the system directory. A workflow process for one type of record can launch a process for another type of record. For example, a service request can launch a process for an incident. A process can contain subprocesses. For example, for different subcategories of records, or records from different sites. When a process requires user interaction, the product can direct a user to a specific application, to a tab, or to an action. © Copyright IBM Corp. 2011, 2013 151 Advanced Workflow Component The Advanced Workflow Component that is installed with this product leverages the capabilities of the Action application to automate one or more steps in a Workflow process. Workflow automation or 'runbook automation' is used to refer to process automation capabilities for IT operations teams. The ability to automate processes is of utmost importance to all IT Operations organizations; the main goals being to reduce labor costs, and to reduce the risk of human error in performing intricate, tedious, and repetitive tasks. Workflows can be exposed to IT personnel who need to run repeatable procedures in several different contexts: v User- or tool-driven automation workflow procedures v Service flow-driven automation workflow procedures v Process-driven automation workflow procedures v Ticket-based automation workflow procedures v Web Services driven automation workflow procedures In the most simple of scenarios, run book automation provides straightforward value. Above and beyond simple documentation of the steps to perform, workflow-based automation provides for automation at two levels: sequencing the steps in the task and connecting tool-based automation to steps in the workflow. Actions provide access to a variety of built-in capabilities, including the ability to: v Initiate an application action v Change the status of a record v Execute a custom class or a specified executable program v Execute an automation script v Set the value of a field on a record Advanced Workflow Components Web Services Advanced Workflow Components comes with number of Web Services that help you automate your workflow processes. For more information, see the Advanced Workflow Components Web Services technote on the product support site: http://www.ibm.com/support/ Applications that are used with Workflow Workflow is used with other applications that directly or indirectly support its functionality. Actions Create and manage actions and action groups. Actions are associated with connection lines in a workflow process and are triggered by the routing that moves a record from one node to another. Automation Scripts Create jython scripts that serve as action implementations (similar to custom Java classes). As with custom Java classes, automation scripts can access information in Maximo business objects (MBOs) and interact with 152 Tivoli Service Automation Manager V7.2.4 Extensions Guide operational management products to perform a variety of operations (for example, install software, re-configure a device, or start a service). Communication Templates Create and manage templates that the system uses when generating e-mail messages. Workflow uses communication templates for notifications. Escalations Create and manage escalation processes. An escalation is a mechanism that can monitor time-sensitive records and key performance indicators, which can take actions or send notifications when a record reaches a defined escalation point. Workflow can use escalations with task assignments. Inbox/Assignments Setup Configure the Workflow Inbox on the Start Center of a user. People Create and manage records for individuals who are listed on records in any capacity. Workflow uses person records when generating assignments and notifications. Person Groups Create and manage records for groups of individuals. Workflow uses person group records when generating assignments and notifications. Roles Create and manage records for roles. All roles resolve to a person, person group, or e-mail address. All workflow assignments and notifications are made to roles. Workflow Administration View and modify assignments and active instances of workflow processes. Workflow Administration (Advanced) View and modify assignments and active instances of workflow processes. Information about active and inactive instances of workflow processes can also be viewed, including workflow assignments, workflow history, action logs and specification attribute information. Workflow Designer Create, view, and modify workflow processes. Workflow Designer (Advanced) Create, view, and modify workflow processes. Workflow Designer (Advanced) application provides a re-designed canvas for designing workflows and provides numerous new capabilities over Workflow Designer application. Workflows that were designed using the original Workflow Designer application can be managed using the Workflow Designer (Advanced) application. Workflow Inbox View and respond to workflow assignments. A workflow process routes assignments to users' inboxes. Workflow Launcher Exposes a library of re-usable workflows to the user for selection and invocation. Chapter 7. Advanced workflow references 153 Workflow design process Workflow processes can be designed to incorporate the most effective ways of completing business tasks. You can evaluate your current practices and determine how you can improve or standardize them before you design workflow processes. When you create a workflow process, the product directs records through paths that you specify. When you design a process, be sure to consider what can happen at each decision point and include all of the paths that a record can take. You could begin your workflow implementation with simple processes. You can always build in more complexity in a later revision. To design optimum workflow processes, consider the following guidelines: v Generic processes require less maintenance than highly specific ones. For example, you could modify roles that resolve to an individual more frequently than roles that resolve to a person group. v When designing processes, consider when you want the product to generate notifications. The product can generate notifications when the following events occur in a process: – A record reaches a decision point (node) – A record follows a specific path (connection line) in a process – Task assignments are made v When designing processes, consider how you want to handle null values. A process could reach a decision point that evaluates data on the record and that data could be missing from the record. v When a record takes the negative path, you can design the record so that it can be modified to take the positive path. You could also design the record to exit the process permanently. v If a record can go through a process again after it has been rejected, you can define a limit to the number of times a record can repeat the process. v Try to avoid having separate groups of nodes and connection lines that perform the same function at different points in a process. It is more efficient to reuse the same code through looping or through creating a subprocess. v Simple processes involving a limited number of nodes are easier to troubleshoot and maintain. If the number of nodes in your process grows too large, you could break down the process into subprocesses. v When writing Structured Query Language (SQL) statements, consider how the SQL syntax affects how the product interprets the statements. The following examples demonstrate the use of the colon in SQL statements: – ASSETNUM — (without a colon) Instructs the product to go to the database for the asset record – :ASSETNUM — (with a colon) Instructs the product to use the asset record in memory (the record currently on the window) 154 Tivoli Service Automation Manager V7.2.4 Extensions Guide Business process analysis Your business practices encompass how you manage your enterprise. You can start the analyses of your processes by collecting information about your enterprise. This information helps you to determine the types of processes that you could automate. Enterprise analysis Gather the following enterprise information to use when designing your workflow processes: v If you have an organizational chart, review your organizational chart to see how your enterprise is organized. v If your enterprise is multinational, list the languages that are required for your workflow processes. v Collect the business process flows that document the business units of your organization. If there are different process flows for the same organizations at various locations, gather those process flows. Compare the business practices at locations to find out if the differences are significant. v Review the standard operating procedures, such as the International Organization for Standardization (ISO) 9000 quality management or the ISO 14000 procedures. v Review the regulatory requirements for your industry and how they affect your business processes. v Review the policies that define who is responsible for creating budgets. v Review the policies that define financial approval limits and list the individuals who have the authority to approve spending. v Research the types of records at your enterprise that require approval. v Review the policies that define the levels of approval that are required for each type of record. Implementation analysis Gather the following implementation information for use when designing your workflow processes: v Determine the number of organizations and sites that exist for your enterprise. You create workflow processes at the system level. Find out if there are separate processes or subprocesses for different organizations or sites. v Find out if you use the Integration Framework to integrate with any external systems. v Determine if any Maximo product options have been purchased. v Research the applications that your enterprise has implemented. v Determine the types of records for which you use the software. v Find out if the system has been configured to generate records, such as inventory reorder records, preventive maintenance work orders, and scheduled payment invoices. v Determine if your implementation uses Start Centers that do not include the Workflow Inbox. If users cannot access the Inbox, you can design your workflow processes to send e-mail messages to notify users. Chapter 7. Advanced workflow references 155 Process analysis Information you collect about your processes can be formatted into a flowchart. A flowchart can help you to identify reusable elements, the beginning and the end of record life cycles, and the parts of the life cycle that can be managed by a workflow process. You could diagram your business process on paper, on a blackboard, or using a graphics software program to create a flowchart. Writing or diagramming a business practice helps you to analyze it. It also provides you with a map of your process flows that you can use when you create a workflow process. Your goal is to produce a detailed diagram that shows all of the routes that a record can take through your enterprise during its life cycle. Your research must include the following information: v The names and roles of the people who interact with records during a process v The processes that are used to manage specific records v The records that enter the process, and where the records go when they exit the process v The records that are managed during a process v The length of time it takes for a record to go through a process v The parts of your current process that are working well and should be kept v The parts of your current process that are not working well and should be changed or removed As you document your business process, make note of trouble spots, such as undocumented procedures, or different ways to complete the same task. Address these issues and refine your business processes before you create and implement a workflow process. Workflow processes and user responsibilities Workflow processes identify the people who create and who manage a record throughout its life cycle. Workflow processes also identify the types of records that are used. In workflow processes, assignments are made to roles that represent either a single user or a group of people. As you generate a list of persons associated with each process, consider whether you can create person groups for people with similar job responsibilities, levels of authority, and security clearances. To help you to identify the people, the roles, and the records that are involved in the workflow processes that you create, compile the following information: v Decide how people are going to be notified of workflow assignments. Users who are going to be assigned tasks must have user records. v Generate a list of the people who must be notified of the progress of a record. The product can send e-mail messages to notify specific users. It is more efficient to create person records for all individuals who receive notifications. v Identify the personnel who work on shifts. v Identify supervisors on person records for escalations and notifications. v Identify contract labor personnel if they are required to interact with a record in a workflow process. Identify which contract workers have both person records and labor records. v Specify the level of security that applies to individuals in different roles in your enterprise. Decide which applications and which actions personnel in each 156 Tivoli Service Automation Manager V7.2.4 Extensions Guide security group are allowed to view. When you design your security groups and workflow processes, you must ensure that users in a particular role have the security permissions they need to perform their assigned tasks. Elements of workflow processes You use workflow processes to create steps to guide records for your business processes. You use numerous elements when creating your workflow processes to achieve the business goals set out for your enterprise. Person records You use the People application to create, to modify, to view, and to delete records for individuals. The People application stores information about individuals, such as users, laborers, asset owners, and supervisors who receive workflow notifications. A person record is a record for an individual whose name could appear as a text field value. Workflow assignments are made to roles. All roles resolve to a person, to a person group, or to an e-mail address. The name of a person is used as the text field value in the Reported By field or in the Affected Person field on a service request, in the Supervisor field on a labor record, or in a Ship To field or Bill To Attention field on a purchasing record. You must create a person record for any individual who will be assigned tasks as part of a workflow process. When you create records in the Labor application and in the Users application, you must create a person record. Person records might have to be created for other individuals who do not have records in the Labor application or in the Users application. Person records that you create for use as part of workflow processes should contain values in the following fields: Supervisor The person who oversees or manages the individual. This information is used for escalations. Primary E-mail The E-mail address where notifications are sent. Primary Calendar The work calendar that the individual follows. This information is used when determining assignments and escalations. Primary Shift The shift that the individual works. This information is used when determining assignments and escalations. Workflow E-mail Notification The circumstances when the individual should receive e-mail notifications for task assignments. The default value is PROCESS. Workflow Delegate The person identifier of the individual designated to receive assignments when the primary individual is unavailable for an extended period of time (for example, on vacation or on sick leave) Chapter 7. Advanced workflow references 157 Delegate From and Delegate To The time period when workflow processes should route assignment to the delegate. If these fields are empty, all workflow assignments are routed to the delegate. Person groups and workflow assignments You use the Person groups application to specify that a group member for a specific organization or site be used when making workflow assignments. Workflow assignments are made to roles. Different workers can perform the same role on different shifts. Creating person groups for roles such as "supervisor" or "safety engineer" simplifies a workflow process. Creating person groups also reduces the need for revisions as individuals move in and out of roles. Workflow assignments are based on entries in the person group role record. If the Broadcast check box is selected on the role record, the task is assigned to all members of the person group. If the check box has not been selected, the product goes through the following steps to determine the appropriate role for the task: v The product checks for a person record with appropriate entries in the Calendar and Shift fields for the assignment, verifying the group members in the order specified by the Sequence field. If no sequence values are specified, the assignment is made to the first group member with an appropriate entry in the Calendar and Shift fields. The search logic depends on whether the workflow process is for an application at the site, the organization, or the system level. – If the application is at the site level, the first check is for person records where the value in the Use for Site field matches the site of the record in the workflow process. The next check is for person records where the value in the Use for Organization field matches the organization of the record in the workflow process. The third check is for person records where there is no value in either the Use for Site field or the Use for Organization field. – If the application is at the organization level, the product checks for person records where the value in the Use for Organization field matches the organization of the record in the workflow process. The next check is for person records where there is no value in either the Use for Site field or the Use for Organization field. – If the application is at the system level, the product checks for person records where there is no value in either the Use for Site field or the Use for Organization field. v If there is no person whose Calendar and Shift entries match the assignment, the product checks for a person record who is listed in the Site Default field. (This field is optional; you can specify a single site default per site.) v If no site default is specified, the product checks for a person record who is checked in the Organization Default field. (This field is optional; you can specify only a single organization default per organization.) v If no organization default is specified, the Group Default person is assigned. By default, the first person added to a person group becomes the group default, but you can modify this setting. 158 Tivoli Service Automation Manager V7.2.4 Extensions Guide Roles and role records You use the Roles application to create role records. A role is a function within a business. A role can represent a specific job title (such as a department manager), an assigned duty (such as a watch officer), a class file, and a data set. Workflow Inbox assignments and workflow notifications are always made to roles. All role records point to one or more person identifiers. Role records can also point to a table and column in the database that represent a person. When a role is encountered in a workflow process, it resolves the role to a person group or to an individual person record. You use roles when you create and configure the following workflow elements: v Communication templates (recipients) v Escalations v Negative connection lines (notifications) v v v v Positive connection lines (notifications) Manual Input nodes (notifications) Task nodes (assignments and notifications) Wait nodes (notifications) By using role records instead of person records for assignments and notifications, you can create generic workflow processes that require less maintenance as individuals move in and out of different roles within your company. Communication templates You use the Communication Templates application to create and to manage templates that generate e-mail messages about the status of workflow records. When you create a communication template, you can specify the following information: v The business object that the template can be used for v The applications where the template can be used v The address that the e-mail should be sent from v The address that replies should be sent to v The subject line of the message v The body of the message v One or more recipients of the message. You can send messages to roles, persons, person groups, and e-mail addresses, and you can specify whether each recipient should also receive a carbon copy (CC) or blind carbon copy (BCC) of the message. v Documents to include as attachments when the message is generated You can use substitution variables when creating the subject line and body of your message. When an e-mail is generated using that template, it replaces the substitution variables from the template with the corresponding values from the record. Chapter 7. Advanced workflow references 159 Substitution variables in communication templates A substitution variable is code that represents a column in the database related to the object specified in the Applies To field on the communication templates. When you use a substitution variable in the Subject or Message field and generate a notification, the variable is replaced with the database value for that column. You can use the Communication Templates application to modify communication templates without inactivating them. However, you cannot modify a communication template if it is in use on an escalation record or in an enabled or active workflow process. If you try to modify a communication template that cannot be modified, an error message is displayed. You can click the Detail Menu button next to the Subject and Message fields to select a field from the tables and related tables for the object specified in the Applies To field on the communication template. When you type a substitution variable manually, you type a colon (:), followed by the database column name (for example, :WONUM). v If the column is from the main database table for the object, the format is a colon (:) and the column name (for example, :WONUM). v If the column is from a database table related to the main object, the format is a colon (:), one or more relationship names separated by periods (.), and then the column name (for example, :ASSET.STATUS). Be sure to include a space before and after each substitution variable to ensure that the generated text is formatted properly. For example, if you were creating a communication template to notify the system administrator to create a new user record, your message might be similar to the following message: Subject — New employee Message — :FIRSTNAME :LASTNAME was hired on :HIREDATE . Please create a user record for this individual and e-mail them their user name and password at :EMAIL.EMAILADDRESS. When a communication template is used to generate a notification, it replaces the substitution variables with the corresponding values from the record that is generating the notification. A notification generated from the previous example might resemble the following notification: Subject — New employee Message — Julie Stickler was hired on 6/01/01. Please create a user record for this individual and e-mail them their user name and password at [email protected]. Note: To find out the column name for any field, place the cursor in the field and press Alt+F1. You see the table and column name associated with the field. If you are including a substitution variable for a nonrequired field, phrase the message so that it still makes sense to the reader if the field is null. 160 Tivoli Service Automation Manager V7.2.4 Extensions Guide Notifications You use the Workflow Designer or Workflow Designer (Advanced) application to create notifications. A notification is an email message that is generated by the progress of a record through a workflow process. The Workflow Designer or Workflow Designer (Advanced) application uses communication templates for notifications. You use the Communication Templates application to create and to manage the templates. When you create communication templates for workflow notifications, you specify roles as the recipients rather than persons or person groups. Many individuals come into contact with a record as it moves through its life cycle. Often these individuals need to know about the progress of a record. You can design your workflow process to generate notifications as required by your business process. Notifications can be made through e-mail or through a pager, providing that your paging system supports e-mail. You can configure the following workflow components to generate notifications: v Escalations v Negative connection lines v Positive connection lines v Manual input nodes v Task nodes v Wait nodes You cannot modify a communication template in the Workflow Designer or Workflow Designer (Advanced) application. You must create separate templates for your notification requirements. Escalations and action groups You use the Escalations application to create escalation records. An escalation is a mechanism for monitoring time-sensitive records. Escalations can take actions or send notifications when a record reaches a defined escalation point. Your Workflow administrator can specify that a task assignment has a time limit. If the assignment is not completed within the specified time limit, an escalation can be triggered for the record. Escalations help to get tasks completed on time and help to prevent work backlogs. Standard escalations do not exist. Your administrator creates custom escalation records that trigger a variety of actions and notifications. For example, an escalation might approve or cancel a record, or reassign a task assignment. An escalation might generate a reminder notification to the assignee regarding the task assignment, or send a notification to a supervisor that the assignee did not complete the assignment yet. Workflow uses escalations primarily with two objects: WFASSIGNMENT WFASSIGNMENT is an object associated with workflow task assignments. You can create escalations that monitor whether an assignee completes a task assignment within the specified time limit. If the task is not completed within the time limit, WFASSIGNMENT can trigger one or more actions. For example, by reassigning the task to a work group or by generating notifications to the supervisor. Chapter 7. Advanced workflow references 161 WFINSTANCE WFINSTANCE is an object associated with active instances of workflow processes. You can create escalations to monitor how long it takes a record to exit the control of a process. For example, if the process design includes one or more Wait nodes. Action groups An action group is a type of action record that includes multiple actions and a sequence to use when performing the actions. Escalations are always associated with action groups. You can associate an action group with an escalation in either of the following ways: v You can create action groups using the Actions application and then click Detail Menu next to the Action Group field on the Actions sub tab to associate the action group with the escalation. v You can create action groups in the Escalations application by clicking New Row on the Actions sub tab. When you create an action group in the Escalations application, the action group receives a generated name. The actions receive assigned sequence numbers. The sequence numbers are based on the order in which you add the actions to the group. Escalation points An escalation point defines the attributes of a record that trigger an action. You can define one or more escalation points for an escalation and specify one or more actions and notifications for each escalation point. You can create the following categories of escalation points: v Elapsed time since a past event — Compares the current date and time to the specified field that represents an event in the past. You can select from a list of DATETYPE fields on the record (for example, a Start Date on a workflow assignment, an Actual Start date on a work order, or a Status Date on a record that includes status). v Time until a future event — Compares the current date and time to the specified field that represents an event in the future (for example, a Renewal Date on a contract, a Due Date on an invoice, or a Target Finish date on a work order). v Condition — Condition without a time measurement. If you want to trigger the actions and notifications of an escalation based on a condition that does not have a time measurement, you can specify the condition in the Escalation Point Condition field. You also can use the Condition field to specify that the escalation point should be applied to only the subset of records specified by the condition 162 Tivoli Service Automation Manager V7.2.4 Extensions Guide Record routing Activating a workflow process indicates that the process is ready to have records routed through it. Before you activate a workflow, consider whether you want records to be routed into a process manually or automatically. A record can enter a workflow process by any of the following methods: v When you click the Route button on the toolbar. v When you select the Route Workflow action from the Select Action menu. v When you create and save a record, the record is routed into the workflow process. You can set one process per object to initiate automatically. v You can set workflow options in the Organizations application. These options specify that generated records should be routed into a particular workflow process. You can specify a workflow process to manage the following records: – Work orders that are generated from a preventive maintenance record – Purchase requisitions that are generated via the inventory reorder process – Purchase orders that are generated via the inventory reorder process – Work orders that are generated when a purchase order for a rotating asset is approved v A record can be routed from one workflow process to another in any of the following ways: – By means of an interaction node – By means of a subprocess node – By means of an WFINITIATE action specified on a connection line leaving a node v A record can be automatically routed into a process by means of an escalation action. v When creating a workflow process with the Workflow launcher application, a record is automatically created and routed into the process. Synonym statuses You can create synonym statuses if your business processes for record approvals or for status changes involve multiple steps for each approval or status change. For example, your business process might call for three different people to review a record before it is considered approved. There is a single status for waiting for approval and a single status for approved. You can create synonym statuses of waiting for approval that represent each of the preliminary approvals before the record is considered approved. You use the Domains application to add synonym values to a value list. For more information about creating synonym statuses, see the Domains Help for this product. Chapter 7. Advanced workflow references 163 Examples of workflow processes You can use the Workflow application to manage records used in a variety of business processes. The examples provided are basic because of the limited number of nodes that can be displayed. The examples illustrate some of the capabilities of the Workflow application and should not be used in a production environment. The product demonstration database includes workflow processes that display simple processes. Example of a purchase requisition business process You can create a workflow process to handle a purchase requisition. When you create a purchase requisition, your supervisor must approve it. When an approved purchase requisition reaches the purchasing department, a purchasing agent evaluates the record and then performs one of the following steps: v Rejects the requisition v Creates a request for quotation to receive bids for the purchase v Creates a purchase order from the requisition The record then exits the workflow process for the purchase requisition. For example, you can create a requisition such that if the total is less than $500, the requisition is routed to the purchasing department. If the requisition total exceeds $500, the requisition requires the approval of the department manager before it can be routed to the purchasing department. If the requisition total exceeds $1,000, the requisition requires the approval of a vice president before it can be routed to the purchasing department. If the requisition total exceeds $5,000, the requisition requires the approval of the chief financial officer before it can be routed to the purchasing department. The diagram that follows illustrates one way that you might map the preceding scenario. The nodes and the connection lines in this example are arranged so that they are easy to see at a glance, but they can be arranged differently. You could add or remove stop nodes, and the workflow process would still illustrate the same business process. Figure 4. Example of a purchase requisition workflow process 164 Tivoli Service Automation Manager V7.2.4 Extensions Guide Example of a service request business process A workflow process can be created to handle service requests. An enterprise uses the software for service desk functions. The enterprise has designed a workflow process that guides a service desk agent through the initial steps of the record management process. When a service desk agent takes an incoming telephone call, the agent creates a service request ticket to record the interaction. The enterprise has configured the database to require the agent to record the caller's name and telephone number. The agent also must type a short description of the service request. For example, a request for information, maintenance, and a classification for the service request. Depending on the type of service request, the agent also might type information about the asset or the location. When the agent saves the service request ticket, the product starts the service request workflow process. The Manual Input window opens with the following options: v I must type additional information regarding this service request. v I must type information about tickets or work orders related to this service request. v I must make an entry in the Work Log or Communications Log. v I have completed data entry for this ticket. Chapter 7. Advanced workflow references 165 If the agent requests to type more information, either the Service Request tab, the Related Records tab, or the Log tab display, depending on which option the agent selected. When the agent indicates the completion of data entry for a service request, the product evaluates the data on the record. If the agent has not provided asset or location data, the Manual Input window displays the following options: v Close ticket - informational call v Close ticket - unauthorized caller v Close ticket - misdirected call v Take no action If an asset or a location is specified on the record, the Manual Input window opens with the following options: v Take Ownership of ticket (Take Ownership action) v Assign Ownership of ticket (Assign Ownership action) v Create Incident record (Create Incident action) v Create Problem record (Create Problem action) v Create Change work order for an IT asset. (Create Change action) v Create Work Order for a non-IT asset. (Create Work Order action) v Take no action on this ticket. The following diagram illustrates one way that the preceding scenario might be mapped. Figure 5. Sample Service Request Workflow 166 Tivoli Service Automation Manager V7.2.4 Extensions Guide Example of a work order business process A workflow process can be created to handle a work order. An enterprise has configured the system to route all new preventive maintenance work orders that are generated through the preventive maintenance work order generation cron task into a workflow process. The first step is to evaluate the priority of the work order, as follows: v If the preventive maintenance work order is high priority or has a null value in the Priority field, it is routed to a work planner for immediate review and approval. v If the preventive maintenance work order has a low priority, it is routed to a Stop node and exits the process. All preventive maintenance work orders then go through a financial approval process. Work orders with an estimated total cost of less than $500 are automatically approved. The maintenance supervisor must review and approve work orders with an estimated total cost of more than $500. After a work order passes the financial approval process, it must be assigned to a work group, as follows: v If the preventive maintenance work order is for a vehicle, the system assigns it to the fleet maintenance group. Chapter 7. Advanced workflow references 167 v If the preventive maintenance work order is for a building or location, the system assigns it to the facilities maintenance group. v The system assigns all other preventive maintenance work orders to the maintenance group. After the system assigns the work order to a maintenance group, the work order exits the workflow process. The following diagram illustrates one way that you might map the preceding scenario. Figure 6. Example of a preventive maintenance work order workflow 168 Tivoli Service Automation Manager V7.2.4 Extensions Guide Configuring for Workflow The Workflow Designer and Workflow Designer (Advanced) applications require minimal configuration before you can create Workflow processes. Configuration prerequisites If you design and create Workflow processes, you must be familiar with the following tools, processes, and concepts: v The business processes for the enterprise v Applications that are involved in the workflow process, such as Asset Management applications, Change Management applications, and Provisioning applications. v Databases and data relationships v Structured query language (SQL) statements v SQL syntax required by your database Additionally, the Workflow Designer and Workflow Designer (Advanced) applications require a Java Virtual Machine (JVM) on the client workstation. If you do not have a JVM installed, the product cannot display the Workflow canvas. Eastern Asian languages For information about configuring the Workflow canvas to properly display Chinese and other Eastern Asian languages, see the System Administrator Guide for this product. Configuring administrator e-mail notifications During the installation process, you type an email address for the Workflow administrator. The administrator will receive system messages about errors. About this task Record the e-mail address for the Workflow administrator in the maximo.properties file. This file is located in the following directory:\applications\maximo\properties where is the directory into which you installed the product. Procedure 1. Using a text editor, open the maximo.properties file . 2. In the Workflow Related Properties section, locate the property named mxe.workflow.admin=. 3. Type or modify the e-mail address. For example: [email protected] 4. Save your changes. Chapter 7. Advanced workflow references 169 Security permissions for workflow processes If you design workflow processes, you must belong to a security group with security permissions. Users are not automatically granted access to workflow actions. An administrator must use the Security Groups application to grant users security permissions to workflow actions. The workflow actions appear in the Security Groups application when you add workflow support to an application. You can grant users access to actions before you activate a process. Additionally, you require security permissions for the following applications: v v v v v v v Actions Automation Scripts Communication Templates Escalations Inbox/Assignments Setup People Person Groups v Roles v Workflow Administration v Workflow Administration (Advanced) v Workflow Designer v Workflow Designer (Advanced) v Workflow Inbox (portlet) v Workflow Launcher If you or your group are responsible for testing workflow processes, you must have security permissions for other applications, depending on the processes that are being tested. Working with Actions An action is an event that is triggered when a record is found that meets the conditions defined by an escalation point, service level agreement, or Workflow process. Use the Actions application to create and manage actions and action groups that can be used with Workflow processes and to enable Workflow automation. Actions and action groups can also be used with escalations and service level agreements (SLA). Workflow automation is made possible by leveraging the capabilities of the Action application. You can create actions to: v Initiate an application action. v Change the status of a record. v Execute a custom class. v v v v 170 Execute a custom script. Execute a specified executable program. Execute a group of actions Set the value of a field on a record. Tivoli Service Automation Manager V7.2.4 Extensions Guide Actions and Workflow Workflow processes use actions to move records through a process and to trigger events, such as status changes. You define actions in the Actions application and then you reuse them in the Workflow processes that you create. You use actions when you create and configure the following Workflow elements: v Escalations v Negative connection lines v Positive connection lines v Interaction nodes v Manual input nodes Actions and escalations An escalation is a mechanism for monitoring time-sensitive records automatically, which can take actions or send notifications when a record reaches a defined escalation point. You create the actions that are associated with an escalation record in the Actions application. Action types When you create an action record, you specify the action type to help determine what kind of action to take when the action is encountered in a process. An action can be one of the following types: Application Action Used to specify that an application action be initiated. For this type of action, there must be values in the Object and Value fields. When creating an Application Action, you can specify one of the following actions if it is available for the specified object: v APPLYSLA — Apply the specified service level agreement. v v v v v v v Create Change — Create a change work order. Create Incident — Create an incident ticket. Create Problem — Create a problem ticket. Create Release — Create a release work order. Create SR — Create a service request ticket. Create WO — Create a work order. APPLYPS — Apply a Customer agreement v APPLYRP — Apply a Response Plan v WFACCEPT — Workflow auto-accept. Accepts the record and routes it to the positive path in the workflow process. v WFESCALATE — Escalate the record in the workflow process and reassigns the assignment to its escalation role. v WFINITIATE — Initiate a workflow process. This option requires a value in the Parameter/Attribute field. v WFREJECT — Workflow auto-reject. Rejects the record and routes it to the negative path in the workflow process. Chapter 7. Advanced workflow references 171 Change Status Used to specify that the status of a record will change. There must be a value in the Object field and a status in the Value field for this type of action. Custom Class Used to specify that a custom class file should run. There must be a value in the Object field and the name and path of a class file in the Value field for this type of action. Custom Script Used to specify that a custom Automation Script should be run. When an action type of Custom Script is selected, the application link associated with the Value attribute provides a link to the Automation Script application, allowing the user to select an existing script, or create a new one. Command Line Executable Used to specify that a program on the server should run. For this type of action, the name of a program file must be in the Value field. Action Group Used to specify that the system should run the sequence of actions that you specify in the Members table window. Set Value Used to specify that the system should set the value of a specified field. For this type of action, values are required in the Object, Value, and Parameter/Attribute fields. Custom actions Actions can be defined that invoke a custom implementation. A custom implementation can take one of two forms: v Custom java class v Custom script Both forms of custom implementation can access MBO data (and related data), as well as any application actions associated with the MBO. When an action type of Custom Class is specified, the name and path of a class file must be specified in the Value field. When an action type of Custom Script is specified, the application link associated with the Value attribute provides a link to the Automation Script application, allowing the user to select an existing Jython script, or create a new one. Related concepts: “Automation Scripts application” on page 182 The Automation Scripts application allows you to create and manage a library of Jython scripts. 172 Tivoli Service Automation Manager V7.2.4 Extensions Guide Creating action records You use the Actions application to create action records that can be used as part of an escalation, a service level agreement, or a workflow process. You can create different types of actions. Procedure 1. On the toolbar, click New Action. 2. In the Action Description field, type a description, or click Long Description to type additional information. 3. In the Type field, select a value from the menu of action types. The value in the Type field determines which fields on the action record you can edit, which fields are required, and the values that can be entered in those fields. 4. In the Value field, type a value that corresponds with the Action type you have selected. v If you are creating an Application Action type of action, click Detail Menu to select from the list of available actions. For this type of action, a value is required in the Object field. v If you are creating a Change Status type of action, type a status for the specified object. For this type of action, a value is required in the Object field. v If you are creating a Custom Class type of action, type the name and path of a class file in the Maximo directory. v If you are creating a Custom Script action, click Detail Menu to select from the list of available Automation Scripts, or go to the Automation Scripts application to create a new script. v If you are creating an Command Line Executable type of action, type the name and path of an executable file that exists on the server. v If you are creating a Action Group type of action, the Value field is read-only. v If you are creating a Set Value type of action, type the value to which you want the field set. You can click Detail Menu to use the SQL Expression Builder. For this type of action, values are required in the Object and Parameter/Attribute fields. If the value is a string it needs to be enclosed in single quotes. 5. Optional: In the Classification field, select a classification for the action. This is useful when selecting an action from a large library of actions in the Workflow Designer (Advanced) application. 6. If you are creating an Application Action, Change Status, or Set Value type of action, specify a value in the Object field. Specifying an Object is optional for Action Group, Custom Script, Custom Class, and Command Line Executable type actions. 7. If you are creating a Set Value type of action, specify a value in the Parameter/Attribute field. The Parameter/Attribute field contains a relationship tree containing relationships associated with the main object. 8. Optional: If you are creating a Change Status action, you can use the Memo field to add remarks regarding the status change. 9. Optional: If you are creating an action specifically for use with escalations or workflow, specify a value in the Accessible From field. Click Detail Menu to select an option and retrieve a value. 10. Click Save Action. Chapter 7. Advanced workflow references 173 Creating action groups You can create a Action Group type action containing two or more action records, and specify a sequence to use when the actions in the group are activated. About this task The following rules apply to action groups: v If you specify an object for the group, all members of the action group must be for the same object. v Group type actions cannot be members of an action group. When you create a Action Group action, the Value field, the Parameter/Attribute field, and the Memo field are all read-only. Procedure 1. On the toolbar of the Actions application, click New Action. If the Action field is empty, type a name for the role. 2. In the Action Description field, type a description, or click Long Description to type additional information. 3. In the Type field, select Action Group from the menu of action types. 4. Optional: In the Object field, type a value. 5. Optional: In the Classification field, select a classification for the action. This is useful when selecting an action from a large library of actions in the Workflow Designer (Advanced) application. 6. For actions created specifically for use with escalations or workflow, specify a value for the Accessible From field. Click Detail Menu to select an option and retrieve a value. 7. Click Select Members. You see a list of actions that exist for the specified object. If you do not specify an object, you see a list of action records that do not have a specified object. a. To select an action, check the Select Row check box. You can select more than one action. To cancel a selection, clear the check box. b. Click OK. Your selections are copied to the Members table window and sequence numbers are assigned to each action. 8. Optional: Modify the Sequence field to change the order in which the actions are initiated. 9. Click Save Action. Creating actions specific to Workflow You can create actions that are associated with a Workflow process. Workflow processes use actions to move records through a process and to trigger events, such as status changes. About this task You define actions once, and then reuse the actions when you create multiple Workflow processes. You use actions when you create and configure the following Workflow processes: escalations, negative connection lines, and positive connection lines, interaction nodes, and manual input nodes. 174 Tivoli Service Automation Manager V7.2.4 Extensions Guide Procedure 1. On the toolbar of the Actions application, click New Action. If the Action field is empty, type a name for the role. 2. Optional: In the Action Description field, type a description, or click Long Description to type additional information. 3. Optional: In the Object field, type a value. 4. Optional: In the Classification field, select a classification for the action. This is useful when selecting an action from a large library of actions in the Workflow Designer (Advanced) application. 5. In the Type field, select the type of action that you are creating. 6. In the Accessible From field, click Detail Menu to select Workflow. 7. Save your changes. Creating actions specific to escalations Procedure 1. In the Actions application, click New Action. 2. Optional: Provide a description of the action. 3. 4. 5. 6. Optional: Specify a value for object. Specify the type of action that you are creating. In the Accessible From field, select Escalation. Save your changes. Duplicating actions Use the Duplicate Action option from the Select Action menu in the Actions application to copy an existing action record. About this task You can duplicate an action if, for example, you wanted to create the same application action for two different objects. Once you duplicate an action record, you can then modify it as needed. Procedure 1. Go to System Configuration > Platform Configuration > Actions application, and display the record that you want to duplicate. 2. Click Select Action > Duplicate Action. Deleting actions You can delete an action record if it is no longer needed and if it is not being used by specific records or elements. About this task You cannot delete an action record if it is being used with any of the following records or workflow elements: v Escalations v Negative connection lines v Positive connection lines v Interaction nodes Chapter 7. Advanced workflow references 175 v Manual input nodes v Service level agreements Procedure 1. Go to System Configuration > Platform Configuration > Actions application, and display the record that you want to delete. 2. Click Select Action > Delete Action. View Action Log To see all of the log records that have been produced by invocations of the action, use the View Action Log option from the Select Action menu. Before you begin Logging for actions must be explicitly enabled. In the System Properties application: v To enable logging for all actions of Type=Custom Class, set the value for the system property rba.log.enableCustomActionLogging to 1. v To enable logging for all actions of Type=Custom Script, set the value for the system property rba.log.enableCustomScriptLogging to 1. Procedure 1. Go to System Configuration > Platform Configuration > Actions application, and select the record for which you want to see the action log records. 2. Click Select Action > View Action Log. Add or modify an image In the Actions application you can associate an image with an action. The image is displayed on positive or negative connectors that reference the action on the Workflow Designer (Advanced) canvas. Procedure 1. From the Select Action menu in the Actions application, click Add/Modify Image. The Add/Modify Image dialog is displayed. 2. Perform one of the following steps: v To delete the current image, click Delete. v To modify or add a new image, click Browse and select the file you want to use. Note: All images must be .jpg or .gif files. 3. Click OK. Results The image will be displayed where the action is used on connections lines in your Workflow process. Actions for which an image is not defined will display with the default action icon 176 . Tivoli Service Automation Manager V7.2.4 Extensions Guide Synchronize parameters For actions of type Custom Script, you can synchronize information that is configured on the Parameter Mappings tab in the Actions application with changes that have been made to the metadata in an automation script. About this task If the Synchronized flag is not set, use the Synchronize Parameters option from the Select Action menu to resynchronize, at which time you can update the configuration on the Parameter Mappings tab in the Actions application. The Synchronized flag is shown on the List tab and on the Parameter Mappings tab. Possible status values are NEW, DELETE, MODIFIED, and UNMODIFIED. A parameter is MODIFIED only if the MBO Type, Method Type, or Attribute Data Type values have changed in the metadata. The Relationship and Attribute values will not be overwritten, even if they have been modified in the metadata. Procedure 1. Go to System Configuration > Platform Configuration > Actions application, and display the record that you want to resynchronize and update. 2. Click Select Action > Synchronize Parameters. The table displays the changes to the Input Parameters and Output Parameters tables that are made if the changes in the metadata are accepted. 3. Click OK to apply the changes to the action and to mark the action as synchronized. 4. Press Cancel to leave the action parameters unchanged and to leave the action unsynchronized with the metadata. Related concepts: “Convenience routines for data mappings” on page 233 Convenience routines for obtaining Input parameters and setting Output parameters are used by the action implementation to shield it from the location of the Input and Output parameters. Related reference: “Parameter Mappings XML” on page 231 XML can be embedded in the source code to define input and output parameters for use with the parameter mapping function supported with actions. Configurable parameter mapping The ability to configure from where an action implementation gets its input parameters (and to where it stores its output parameters) helps facilitate the development of libraries of domain-oriented automation actions that can be applied in different scenarios, and which work with different object types (for example, workorders and tickets). This separation of business logic from the marshalling of input and output parameters, in the context of Workflow automation, makes it possible to plug the same action implementation into different workflows, without necessarily being constrained by the type of object processed by the workflow. For example, if an action requires three input parameters, and the three elements of data are available in a Change workorder as well as a Problem ticket, the same action implementation should be applicable to workflows designed to work with Chapter 7. Advanced workflow references 177 Change workorders as well as workflows designed to work with Problem tickets. This is also true for input parameters found in MBOs related to the workflow's primary object (for example, Change or Problem). The configurable parameter mapping approach for Action parameters has three elements: v Action implementations in the form of automation scripts define their input and output parameters as a form of metadata that is imbedded in the code. A simple XML representation is used for this metadata. v Convenience routines are available for automation scripts to 'get' input parameters from the primary MBO and related MBOs and to 'put' (or set) output parameters into attributes associated with primary MBO and related MBOs. These convenience routines rely on the parameter mapping configuration (defined in the action) to determine the relationship path to the parameters, for both inputs and outputs. v The Action application supports the configuration of the input and output parameter mappings for a given action. When an automation script action implementation is to be used in a new context where inputs and outputs must be marshalled from different locations, a new action is defined with possibly a different configuration for the parameter mappings. When defining a new action, and the reference to the custom script is specified, the metadata in the action implementation is used to pre-populate the rows in the Input and Output Parameter tables on the Parameter Mappings tab. The designer of the action can then complete the configuration of the Relationship and Attribute fields for each parameter defined in the Input and Output Parameter tables. Related concepts: “Convenience routines for data mappings” on page 233 Convenience routines for obtaining Input parameters and setting Output parameters are used by the action implementation to shield it from the location of the Input and Output parameters. Related reference: “Parameter Mappings XML” on page 231 XML can be embedded in the source code to define input and output parameters for use with the parameter mapping function supported with actions. Parameter mappings in the Action application While the specific input and output parameters used by an action implementation are defined in the source code metadata, the mapping of these parameters to specific MBO attributes or MBO sets is specified in the action definition. If an Action is associated with an script that contains metadata, then the 'Parameter Mappings' tab will be displayed in the Action application. Input parameter mappings For each input parameter defined in the metadata, a row is created in the Input Parameters table on the Parameter Mappings tab. For each row, the following read-only attributes are pre-populated when the automation script is selected: v Name – name of the input parameter. This is a required value, and will always be present. v Description – description of the input parameter. This is an optional value. v MBO Type – an optional value that specifies the type of MBO that must be defined in the last position in the user-specified Relationship field. When used, 178 Tivoli Service Automation Manager V7.2.4 Extensions Guide this places a restriction on the type of MBO that can be used as input to the action. For example, if MBO Type is set to "CI", then the following values in the Relationship field would be considered valid, or invalid: – WOCHANGE.CI (valid) – WOCHANGE.ASSET (invalid) v Attribute Data Type – A required value that specifies the expected data type of the attribute (or array of attributes) that is expected by the action. Attribute Type is applicable when Method Type is "Attribute" or "AttributeArray". For example, if Method Type=Attribute, and Attribute Type=INTEGER, then the attribute entered in the Attribute field must be of type INTEGER. v Method Type – A required value that specifies how the input data is being accessed by the action: – Attribute – The action is expecting a single attribute as input. – AttributeArray – The action is expecting an array of one or more attributes as input. – MBOSet – The action is expecting a MBO set as input. For each input parameter defined in the metadata, the following writeable attributes are available for configuring the "path" to each required input parameter. v Relationship – used to specify the relationship path to the input MBO, or MBO Set. – If the input MBO is the primary MBO that is associated with the action (or the workflow), then this field should be left blank. – If the input MBO is reached by a sequence of one or more relationships from the primary MBO, then a value must be specified in Relationship. – The "target", or rightmost MBO specified in the Relationship value, must match the MBO Type specification, if defined. – The relationship value can be entered into the Relationship field, or click on the Select Value icon after the Relationship field to use a the relationship navigation dialog to define the relationship path. v Attribute – used to specify the name of the attribute that is input to the action. – The specified attribute must be an attribute supported by the target MBO specified in the Relationship field. If the Relationship field is blank, the primary input MBO for the action is assumed, and the attribute must be supported by that MBO. – If Method Type is Attribute or Attribute Array, a value is required in this field. – If Method Type is MBOSet, then a value should not be specified in this field. – The data type of an attribute specified in this field must match the value specified in the Attribute Type field. – The attribute value can be entered into the Attribute field, or click on the Select Value icon after the Attribute field to use the attribute navigation dialog to select the attribute. The set of attributes displayed on the dialog is scoped to the attributes supported by the target MBO defined in the Relationship field v Override Value – used to supply a specific value to be returned as input to the action. At run-time, values specified in the Relationship and Attribute fields are ignored, and the value specified in Attribute Override is used as the input value. This field is only displayed if Attribute Data Type is UPPER, ALN, LOWER, INTEGER or SMALLINT. Clear this field to revert to use Relationship and Attribute. Chapter 7. Advanced workflow references 179 Note: When the input and output parameter tables are populated for an action, the values entered for Relationship and Attribute must pass validation before you can save the action. Examples The following examples describe different scenarios and corresponding values to use for Relationship and Attribute. 1. The primary MBO is WOCHANGE and the input attribute is CINUM: v Relationship=null v Attribute=CINUM 2. The primary MBO is WOCHANGE and the input attribute is the Description attribute associated with the Job Plan defined on the WOCHANGE: v Relationship=JOBPLAN v Attribute=DESCRIPTION 3. The primary MBO is WOCHANGE and the input consists of an array of OMPGUIDs that are associated with the set of CIs defined in the workorder: v Relationship=MULTIASSETLOCCI.CI.ACTUALCI v Attribute=GUID 4. The primary MBO is WOCHANGE and the input consists of a MBO Set of the CIs defined on the workorder: v Relationship=MULTIASSETLOCCI.CI v Attribute=null 5. The primary MBO is WOCHANGE and the input consists of a MBO Set of the specification attributes associated with the workorder: v Relationship=WORKORDERSPEC v Attribute=null The use of specification attributes as a way to configure additional attributes for MBOs is very convenient. Specification attributes are limited to three data types (alphanumeric, numeric and table domain). You can also define a filter in the path definition to identify a specification attribute, as shown in the following examples: 1. The primary MBO is WOCHANGE and the input consists of a MBO Set of the specification attributes associated with the workorder, where the name of the specification attribute is "capacity". Since the implementation for a specification attribute does not allow duplicates with the same ASSETATTRID for a given object, the MBO Set will contain 0 or 1 objects. v Relationship=WORKORDERSPEC[ASSETATTRID='CAPACITY'] v Attribute=null 2. The primary MBO is WOCHANGE and the input consists of an array of objects, the values obtained from the numvalue attribute associated with the filtered MBO set. Since the implementation for specification attributes does not allow duplicates with the same ASSETATTRID for a given object, an array will be returned with 0 or 1 objects: v Relationship=WORKORDERSPEC[ASSETATTRID='CAPACITY'] v Attribute=NUMVALUE 3. The primary MBO is WOCHANGE and the input consists of a MBO Set of the CIs where CINUM = the value of the CINUM attribute in the workorder: 180 Tivoli Service Automation Manager V7.2.4 Extensions Guide v Relationship=MULTIASSETLOCCI[CINUM=:cinum] v Attribute=null 4. The primary MBO is WOCHANGE and the input consists of a MBO Set of the CIs located in conference room 'conf200': v Relationship=MULTIASSETLOCCI[LOCATION='CONF200'] v Attribute=null 5. The primary MBO is WOCHANGE and the input consists of an array of objects containing CINUM values, filtered by the related MULTIASSETLOCCI MBOs where LOCATION='conf200' and further filtered by the related CI MBOs where the physical location is 'PITTSBURGH': - Relationship= MULTIASSETLOCCI[LOCATION='conf200'].CI[CILOCATION='PITTSBURGH'] - Attribute=CINUM Output parameter mappings For each Output Parameter mapping, a single attribute can be defined. For each output parameter defined in the metadata, a row is created in the Output Parameters table on the Parameter Mappings tab. MBO Sets and arrays cannot be defined as Output Parameters. For each row, the following read-only attributes are pre-populated when the automation script is selected: v Name – name of the output parameter. This is a required value, and will always be present. v Description – description of the output parameter. This is an optional value. v MBO Type – an optional value that specifies the type of MBO that must be defined in the last position in the user-specified Relationship field. When used, this places a restriction on the type of MBO that can be used as output to the action. For example, if MBO Type is set to "CI", then the following values in the Relationship field would be considered valid, or invalid: – WOCHANGE.CI (valid) – WOCHANGE.ASSET (invalid) v Attribute Data Type – A required value that specifies the expected data type of the attribute that is set as an output by the action. Attribute Data Type is always applicable for output parameters, since the only supported Method Type for output is Attribute. For example, if Attribute Data Type=INTEGER, then the Attribute entered in the Attribute field must be of type INTEGER. For each output parameter defined in the metadata, the following writeable attributes are available for configuring the "path" to each output parameter. v Relationship – used to specify the relationship path to the MBO with the output attribute – If the output MBO is the primary MBO that is associated with the action (or the workflow), then this field should be left blank. – If the output MBO is reached by a sequence of one or more relationships from the primary MBO, then a value must be specified in Relationship. – The "target", or rightmost MBO specified in the Relationship value, must match the MBO Type specification, if defined. – The relationship value can be entered into the Relationship field, or click on the Select Value icon after the Relationship field to use the relationship navigation dialog to define the relationship path. Chapter 7. Advanced workflow references 181 v Attribute – used to specify the name of the attribute that is output from the action. – The specified attribute must be an attribute supported by the target MBO specified in the Relationship field. – A value is always required in the Attribute field, since Method Type for output parameters is limited to Attribute. – The data type of an attribute specified in this field must match the value specified in the Attribute Data Type field. – The attribute value can be entered into the Attribute field, or click on the Select Value icon after the Attribute field to use the attribute navigation dialog to select the attribute. The set of attributes displayed on the dialog is scoped to the attributes supported by the target MBO defined in the Relationship field Note: When the input and output parameter tables are populated for an action, the values entered for Relationship and Attribute must pass validation before you can save the action. Examples The following examples describe different scenarios and corresponding values to use for Relationship and Attribute. 1. The primary MBO is WOCHANGE and the output parameter sets a value in CINUM: v Relationship=null v Attribute=CINUM 2. The primary MBO is WOCHANGE and the output parameter sets a numeric value in the numvalue attribute associated with the filtered WORKORDERSPEC MBO Set: v Relationship=WORKORDERSPEC[ASSETATTRID='capacity'] v Attribute=NUMVALUE Automation Scripts application The Automation Scripts application allows you to create and manage a library of Jython scripts. These scripts can be used to: v Create actions of Type=Custom Script, used anywhere a custom action can be used (for example, workflows, escalations, and so on). v Validate user input on Service Catalog Offerings application dialogs using Jython scripts. Parameter mapping metadata can be embedded in the script source, facilitating the development of re-usable actions, that can be configured for use in different object contexts (for example, workorders, tickets). The Actions tab in the Automation Scripts application provides a list of all actions that reference a particular script. This is useful when the script or its metadata is updated, thereby requiring actions that reference that script to be reconfigured. 182 Tivoli Service Automation Manager V7.2.4 Extensions Guide Related concepts: “Parameter metadata” on page 227 Parameter metadata embedded in a Jython script is used to define the inputs and outputs required by the implementation. “Convenience routines for data mappings” on page 233 Convenience routines for obtaining Input parameters and setting Output parameters are used by the action implementation to shield it from the location of the Input and Output parameters. “Writing custom code to run a management plan” on page 118 You can write custom code to implement use cases that you cannot implement using the advanced workflow language or the generic workflows which are included as part of Tivoli Service Automation Manager. Write custom code using either Java classes or Jython scripts. Related tasks: “Synchronize parameters” on page 177 For actions of type Custom Script, you can synchronize information that is configured on the Parameter Mappings tab in the Actions application with changes that have been made to the metadata in an automation script. Workflow Designer and Workflow Designer (Advanced) You use the Workflow Designer or Workflow Designer (Advanced) application to create workflow processes that reflect your business processes. A workflow process defines the actions and notifications that can occur at different points in a business process. Creating workflow processes About this task A workflow process consists of the header information for the record, the nodes, the connection lines, and the properties specified for the nodes and the connection lines. Procedure 1. On the toolbar of the Workflow Designer or Workflow Designer (Advanced) application, click New Process. 2. In the Process field, type a name for the process. 3. Optional: Type a description. 4. In the Object field, type a value or click Select Value and select an object. 5. Click Save Process. What to do next You are now ready to use the canvas to add nodes and connection lines and to configure the properties of each of the elements of the process. Note: The Workflow Designer (Advanced) applet stays synchronized with the Maximo server. If there is any question about the state of the workflow, save the workflow to re-synchronize the workflow with the Maximo server. Chapter 7. Advanced workflow references 183 Adding nodes and connection lines to the canvas You use the Workflow Designer or Workflow Designer (Advanced) application to create a workflow process by inserting nodes and connection lines on the Workflow canvas. Before you begin Select one of the following options to enable editing on a workflow: Options Step To create a workflow process Click New Process. To configure a process that is enabled and activated Select the process you want to revise and click Create Process Revision. Using Workflow Designer application: Procedure 1. On the Workflow Designer application toolbar, select Move/Add Nodes. 2. Drag a node onto the canvas. 3. To edit the properties of the node, double click the node, and edit the properties in the Node Properties window. 4. Repeat steps 2 and 3 to place other types of nodes onto the canvas. 5. To reposition nodes, drag the node you want to move. 6. On the Workflow Designer toolbar, select one of the following connection tools to create connection lines between nodes: a. Click Connect Nodes to add a positive connection line. b. Click Connect Nodes with a Negative Action to add a negative connection line. 7. Click a node and drag the line to another node. Lines must travel from one node to another node. The lines indicate the path for records to follow in the workflow process. The type of lines and the number of lines you can draw from each node varies depending on the type of node. 8. Click Save Process. What to do next After adding nodes and connection lines, the next step is to validate the process to ensure its structural integrity. Using Workflow Designer (Advanced) application: Procedure 1. On the Workflow Designer (Advanced) application toolbar, click the toolbar button for the node you want to add. 2. Click the location on the canvas where you want to place the node. 3. To edit the properties of the node, double click the node, and edit the properties in the Properties window, or right-click on the node and select Properties. 4. Repeat steps 2 and 3 to place other types of nodes onto the canvas. 5. To reposition nodes, drag the node you want to move to its new location. 6. On the Workflow Designer (Advanced) toolbar, select one of the following connection tools to create connection lines between nodes: 184 Tivoli Service Automation Manager V7.2.4 Extensions Guide a. Click the Positive Connection toolbar button connection line. b. Click the Negative Connection toolbar button connection line. to add a positive to add a negative The positive and negative connection buttons are 'sticky'. You can continue to connect nodes together, until you click a different toolbar button. You can click the connection toolbar button again to release the 'sticky' behavior and return to the selection tool. 7. Click the source node to start the connection, then click the target node to finish the connection, and draw the connection line between the two nodes. Lines must travel from one node to another node. The lines indicate the path for records to follow in the workflow process. The type of lines and the number of lines you can draw from each node varies depending on the type of node. 8. Click Save Process. What to do next After adding nodes and connection lines, the next step is to validate the process to ensure its structural integrity. Designing workflows with Workflow Designer canvas Using the Workflow Designer canvas you get a graphical view of a Workflow process that lets you see the process elements and how they are connected. The Workflow Designer application Canvas tab provides the tools and work space to create, view, and modify Workflow processes. Use the Workflow Designer canvas to drag and drop process nodes and add connection lines onto the canvas. The toolbar buttons provide visual indications of workflow application support and workflow process control. You use these icons to route workflow assignments and to complete workflow assignments. Workflow Designer toolbar The Workflow Designer application toolbar buttons provide visual indications of workflow application support and workflow process control. You use these icons to route workflow assignments and to complete workflow assignments. Route buttons When you add workflow support to an application, a Route button is added to the application toolbar. Two icons exist for the Route toolbar button, to indicate whether a record is being used in a workflow process. You can customize the Route buttons. If multiple processes exist for an application, you can create different buttons for each process. Icon File name Function nav_icon_route.gif Indicates that the application supports workflow. You can click the icon to route the current record into a process. Chapter 7. Advanced workflow references 185 Icon File name Function nav_icon_route_active.gif Indicates that the current record is under the control of one or more workflow processes. You can click this toolbar button to perform one of the following actions: v Complete a workflow assignment. v Route the record into another workflow process. You can customize the Route buttons. If multiple processes exist for an application, you can create different buttons for each process. Adding workflow toolbar buttons You can choose one toolbar button to represent all active workflow processes or add separate toolbar buttons for each active process. You can even indicate the order in which these toolbar buttons are displayed, based on your preferences and priorities. When multiple active processes exist for an object you have the following options: v Use a single toolbar button for all active workflow processes. The Start Workflow dialog box opens. Users can select a process from the menu of active processes in the dialog box. v Create separate toolbar buttons for each different, active process. Note: If you exceed the number of icons that can fit on the toolbar, users see a downward pointing arrow to indicate that a menu of options to choose from is available. To add a workflow toolbar button, complete the following steps: In the Workflow Designer application, display a process record.From the Select Action menu, select Edit Workflow GO Buttons . Applications that are associated with the object and support workflow are listed in the toolbar buttons for