IBM Cloud Orchestrator Version 2.4.0 Before using this information and the product it supports, read the information in Notices

IBM Cloud OrchestratorVersion 2.4.0.2

Content Development Guide

��

NoteBefore using this information and the product it supports, read the information in Notices.

Contents

Preface . . . . . . . . . . . . . . viiWho should read this information. . . . . . . vii

Chapter 1. Getting started with IBMCloud Orchestrator content . . . . . . 1Content packs . . . . . . . . . . . . . . 1Patterns . . . . . . . . . . . . . . . . 2Virtual images . . . . . . . . . . . . . . 2

Chapter 2. IBM Cloud Orchestratoroverview . . . . . . . . . . . . . . 3Architecture . . . . . . . . . . . . . . 3

Chapter 3. Installing and configuringIBM Process Designer . . . . . . . . 5

Chapter 4. Developing virtual systempatterns. . . . . . . . . . . . . . . 7

Chapter 5. Developing toolkit andapplication content . . . . . . . . . . 9Implementing workflow orchestration . . . . . . 9Managing business processes . . . . . . . . 10

Process application . . . . . . . . . . . 10Toolkit . . . . . . . . . . . . . . . 10Snapshot . . . . . . . . . . . . . . 11Business Process Definition . . . . . . . . 11Service . . . . . . . . . . . . . . . 11Participant group . . . . . . . . . . . 12Coach validation framework. . . . . . . . 12

Implementing extensions with IBM CloudOrchestrator . . . . . . . . . . . . . . 13

Implementing a custom operation for IBM CloudOrchestrator . . . . . . . . . . . . . 13Start a custom extension operation . . . . . 15Implementation of a human service as a UIextension . . . . . . . . . . . . . . 15

Implementation a Business Process Manager processas an extension . . . . . . . . . . . . . 16Best practices and guidelines . . . . . . . . 17Importing and exporting toolkits and processapplications . . . . . . . . . . . . . . 19

Importing toolkits . . . . . . . . . . . 19Exporting toolkits . . . . . . . . . . . 20

Business Process Manager security . . . . . . 20

Chapter 6. Importing using thecommand-line interface . . . . . . . 21

Chapter 7. Example scenarios forworkflow-based orchestration . . . . . 23Self-service offerings scenario . . . . . . . . 23

Event-triggered action scenario . . . . . . . . 26User action scenario . . . . . . . . . . . 29

Chapter 8. Automating the creation ofcategories, offerings, and user actions . 33Exporting using the catalogTool.sh tool . . . . . 37

Chapter 9. Publishing IBM CloudOrchestrator content to IBM CloudOrchestrator Catalog. . . . . . . . . 39

Appendix A. SCOrchestrator toolkit . . 41Configuration . . . . . . . . . . . . . 42Business objects . . . . . . . . . . . . . 42

OperationContext . . . . . . . . . . . 43Service Instance . . . . . . . . . . . . 44MetaData . . . . . . . . . . . . . . 44VirtualMachine . . . . . . . . . . . . 45NetworkInterface . . . . . . . . . . . 46Role . . . . . . . . . . . . . . . . 47Endpoint . . . . . . . . . . . . . . 47Service . . . . . . . . . . . . . . . 47CloudGroup . . . . . . . . . . . . . 48Parameter . . . . . . . . . . . . . . 50Hypervisor . . . . . . . . . . . . . 50HypervisorFilter . . . . . . . . . . . . 54

Services . . . . . . . . . . . . . . . 55General system services . . . . . . . . . 56Integration services . . . . . . . . . . . 58Cloud management services . . . . . . . . 67

Samples . . . . . . . . . . . . . . . 68

Appendix B. Scripting utilities toolkit 71File upload restrictions . . . . . . . . . . 71Business objects . . . . . . . . . . . . . 71Implementation services . . . . . . . . . . 75Sample processes . . . . . . . . . . . . 81Sample UIs . . . . . . . . . . . . . . 81Deprecated implementation services . . . . . . 82

Appendix C. Support IaaS toolkit . . . 83Generic IaaS REST call. . . . . . . . . . . 84OpenStack and Cloud API library in BusinessProcess Manager . . . . . . . . . . . . 85Get IaaS Regions . . . . . . . . . . . . 85Samples for the IaaS support toolkit . . . . . . 86Sample to create a tenant in OpenStack identityservice . . . . . . . . . . . . . . . . 87Sample to get a list of servers from OpenStackcompute service . . . . . . . . . . . . . 87Troubleshooting . . . . . . . . . . . . . 88

Appendix D. Email notification toolkit 89Business objects . . . . . . . . . . . . . 89

© Copyright IBM Corp. 2013, 2015 iii

Implementation services . . . . . . . . . . 90Sample processes . . . . . . . . . . . . 91Sample UI . . . . . . . . . . . . . . . 91

Appendix E. Support vSys classictoolkit . . . . . . . . . . . . . . . 93Business objects . . . . . . . . . . . . . 93Integration services . . . . . . . . . . . . 96User interface . . . . . . . . . . . . . 107

AJAX services . . . . . . . . . . . . 107Coach views. . . . . . . . . . . . . 107Human services . . . . . . . . . . . 108

Sample process services . . . . . . . . . . 111

Appendix F. Support vSys toolkit . . . 115Business objects . . . . . . . . . . . . 115Integration services . . . . . . . . . . . 116Deploy cloud service using advanced patterns . . 120

Appendix G. OpenStack CinderStorage Volumes toolkit . . . . . . . 121Installing and configuring . . . . . . . . . 121Toolkit scenarios . . . . . . . . . . . . 121

Creating new volumes . . . . . . . . . 122Attaching volumes . . . . . . . . . . 123Detaching volumes . . . . . . . . . . 124Deleting volumes . . . . . . . . . . . 124Managing volumes related to a virtual systeminstance . . . . . . . . . . . . . . 125

Toolkit developer's reference . . . . . . . . 126Environmental variables . . . . . . . . . 126Business objects . . . . . . . . . . . 126Human services . . . . . . . . . . . 127Coach views. . . . . . . . . . . . . 127Business processes. . . . . . . . . . . 128Integration services . . . . . . . . . . 129

Samples about how to use the available servicesand views . . . . . . . . . . . . . . 130Importing XML into IBM Cloud Orchestrator. . . 131Troubleshooting . . . . . . . . . . . . 132

Appendix H. Infrastructure as aService toolkit . . . . . . . . . . . 135Installing and configuring . . . . . . . . . 136

Customizing the installation packages of themanagement agents . . . . . . . . . . 138Making the toolkit writable. . . . . . . . 140Customizing the list of available flavors . . . 140Customizing the list of IBM Tivoli StorageManager policies and backup frequencies . . . 141Customizing the list of available IBM EndpointManager compliance groups . . . . . . . 141Customizing the YUM repository for thedeployed systems . . . . . . . . . . . 142Configuring an SMTP server in IBM CloudOrchestrator . . . . . . . . . . . . . 142

Toolkit scenarios . . . . . . . . . . . . 143Creating an offering to deploy a cloud service 143Decommissioning a cloud service. . . . . . 146

Deleting an offering to deploy a cloud service 146Deploying a cloud service . . . . . . . . 147Registering a management server configuration 147Unregistering a management serverconfiguration . . . . . . . . . . . . 148Modifying a management server configuration 148

Toolkit developer's reference . . . . . . . . 149Environmental variables . . . . . . . . . 149Business processes definitions . . . . . . . 149Human services . . . . . . . . . . . 150Coach views. . . . . . . . . . . . . 151Integration services . . . . . . . . . . 151General system services . . . . . . . . . 151

Samples about how to use the available servicesand views . . . . . . . . . . . . . . 151Troubleshooting . . . . . . . . . . . . 151

Appendix I. IBM Endpoint Managertoolkit . . . . . . . . . . . . . . 153Installing and configuring . . . . . . . . . 153Toolkit scenarios . . . . . . . . . . . . 154

Installing IBM Endpoint Manager agent on aprovisioned virtual machine . . . . . . . 154Registering unlinked virtual servers . . . . . 155Registering IBM Endpoint Manager server . . 156Unregistering IBM Endpoint Manager server 156Modifying an IBM Endpoint Manager server 157Deploy an IBM Endpoint Manager Fixlet Actionto a list of computers . . . . . . . . . . 157

Toolkit developer's reference . . . . . . . . 159Environmental variables . . . . . . . . . 160Business objects . . . . . . . . . . . 161Coach views. . . . . . . . . . . . . 164Human services . . . . . . . . . . . 165Business processes. . . . . . . . . . . 166General system services . . . . . . . . . 167Integration services . . . . . . . . . . 168

Samples about how to use integration services . . 172Configuring an SMTP server in IBM CloudOrchestrator . . . . . . . . . . . . . . 172Troubleshooting . . . . . . . . . . . . 172

Appendix J. IBM Endpoint Managerfor Patch Management toolkit . . . . 175Installing and configuring . . . . . . . . . 175Toolkit scenarios . . . . . . . . . . . . 176

Apply an IBM Endpoint Manager patch to thevirtual machines of a virtual system instance . . 176

Toolkit developer's reference . . . . . . . . 178Environmental variables . . . . . . . . . 178Human services . . . . . . . . . . . 178Coach views. . . . . . . . . . . . . 179General system services . . . . . . . . . 179

Samples about how to use the available servicesand views . . . . . . . . . . . . . . 179

Appendix K. IBM Endpoint Managerfor Software Distribution toolkit . . . 181Installing and configuring . . . . . . . . . 181Toolkit scenarios . . . . . . . . . . . . 182

iv IBM Cloud Orchestrator 2.4.0.2: Content Development Guide

Submitting an IBM Endpoint Manager softwaretask to a list of computers . . . . . . . . 182Deploying a cloud service with additionalsoftware . . . . . . . . . . . . . . 183

Toolkit developer's reference . . . . . . . . 185Business objects . . . . . . . . . . . 185Human services . . . . . . . . . . . 186Business processes. . . . . . . . . . . 187General system services . . . . . . . . . 188Integration services . . . . . . . . . . 188

Samples about how to use integration services . . 189Configuring an SMTP server in IBM CloudOrchestrator . . . . . . . . . . . . . . 189

Accessibility features for IBM CloudOrchestrator . . . . . . . . . . . . 191

Notices . . . . . . . . . . . . . . 193Programming interface information . . . . . . 195

Trademarks . . . . . . . . . . . . . . 195Terms and conditions for product documentation 195IBM Online Privacy Statement. . . . . . . . 196

Glossary . . . . . . . . . . . . . 197A . . . . . . . . . . . . . . . . . 197B . . . . . . . . . . . . . . . . . 198C . . . . . . . . . . . . . . . . . 198E . . . . . . . . . . . . . . . . . 198H . . . . . . . . . . . . . . . . . 198K . . . . . . . . . . . . . . . . . 198P . . . . . . . . . . . . . . . . . 199R . . . . . . . . . . . . . . . . . 199S . . . . . . . . . . . . . . . . . 199T . . . . . . . . . . . . . . . . . 199V . . . . . . . . . . . . . . . . . 199

Contents v

vi IBM Cloud Orchestrator 2.4.0.2: Content Development Guide

Preface

This publication documents how to author content for IBM® Cloud Orchestrator.

Who should read this informationThis information is intended for users and cloud administrators who build contentby using the IBM Cloud Orchestrator platform for their internal and widercommunity use.

© Copyright IBM Corp. 2013, 2015 vii

viii IBM Cloud Orchestrator 2.4.0.2: Content Development Guide

Chapter 1. Getting started with IBM Cloud Orchestratorcontent

IBM Cloud Orchestrator can be extended by providing different types of contentpackages to enable IBM Cloud Orchestrator to use the features that are deliveredby external software and infrastructure devices.

The different types of IBM Cloud Orchestrator content that you can create anddeploy in the cloud are explained here.

Content packsContent Packs provide the building blocks for orchestrations that run on theintegrated Business Process Manager platform in IBM Cloud Orchestrator.

Content Packs typically consist of a set of process applications and toolkits. Processapplications contain ready-to-use orchestrations and share library items from oneor more toolkits. Toolkits typically contain building blocks to be used by processapplications and other toolkits. They also provide sample processes and humanservices to demonstrate the usage of those building blocks.

IBM Cloud Orchestrator ships with a number of toolkits that provide buildingblocks related to pattern and image deployment, scripting support and offerings.These building blocks can be used to create new toolkits or process applications.See Chapter 5, “Developing toolkit and application content,” on page 9.

You can download additional content packs from the IBM Cloud OrchestratorCatalog. For information about installing the content packs, see Managing contentpacks.

Processes and human services contained in process applications or toolkits canthen be configured to be run in IBM Cloud Orchestrator in the following ways:

Self-service offerings

A self-service offerings is a process that is not related to any pattern orinstance. For example, add a user. To understand how to create aself-service operation, see the self-service offerings scenario. The offeringsare grouped into categories.

For more information about self-service offerings, see the following topics:v Designing self-servicev Using self-servicev Self-service offerings

Event-triggered action

Event-triggered actions are related to processes that are run as pre- andpost- operations during pattern deployment. For example, the operationcan be an automated approval process. To understand how to create anevent-triggered action in a real time scenario, see the event-triggered actionscenario.

For more information about event-triggered action, see the followingtopics:

© Copyright IBM Corp. 2013, 2015 1

https://www.ibm.com/software/brandcatalog/ismlibrary/cloudorchestratorcatalog

https://www.ibm.com/software/brandcatalog/ismlibrary/cloudorchestratorcatalog

v Event-triggered actionsv Making a process available as an orchestration action

User actions

A user action is a management extension for existing pattern instances, forexample, change a password.

For more information about user actions, see the following topics:v User actionsv Making a process available as an orchestration action

PatternsThe following items are patterns.

Virtual system patterns

A virtual system pattern is one or more virtual images and applicationsthat implement a deployment topology. The topology parts are defined byvirtual images, add-ons, and script packages. A virtual system pattern is atopology definition for repeatable deployment that can be shared.

See Chapter 4, “Developing virtual system patterns,” on page 7.

Virtual application patterns

Virtual application patterns are created to model virtual applications thatyou can deploy to the cloud. A virtual application is defined by a virtualapplication pattern. It is a complete set of operating system resources thatfulfill a business need, including web applications, databases, userregistries, messaging services, and transaction processes. Each virtualapplication pattern is associated with a pattern type. This pattern type is acollection of plug-ins that provide these resources and services for aparticular business purpose in the form of components, links, and policies.The pattern types, product extensions of the cloud system, and the types ofvirtual application that you build depend on the pattern types that youenabled.

Virtual imagesVirtual images provide the operating system and product binary files that arerequired to create a virtual system instance. Images can be extended to customizethe virtual images and the operating systems by adding script packages whichprovide additional functionality during provisioning time and software bundlesthat enhance the content of the image.

Software bundles

Software bundles contain and describe the software that is available for usewithin a virtual image. They include information about how to install thesoftware, prerequisites of the software, and parameters that are availablefor customizing the software. They combine the operating systemdefinition and custom software bundles to create virtual bundles that canbe provisioned in the cloud.

2 IBM Cloud Orchestrator 2.4.0.2: Content Development Guide

Chapter 2. IBM Cloud Orchestrator overview

IBM Cloud Orchestrator provides end-to-end service deployment acrossinfrastructure and operating system layers. It provides integrated IT capabilities fororchestration workflow automation and IT governance, resource monitoring, andcost management.

Your data center policies, process, and infrastructure can be integrated with thecloud in a consistent, flexible, and automated way, across various IT domains. Youcan define and implement business rules and IT policies with an intuitivegraphical tool. It helps you to connect the aspects of the different domains into aconsistent orchestration of automated tasks and human tasks.

ArchitectureIBM Cloud Orchestrator is built on OpenStack and common pattern modeling.Business Process Manager provides workflow modeling and runtime capabilities. Itis integrated so that event triggered automation provides the basis for cloud-centricworkflow enablement. The contents, toolkits, and other building blocks can befound, used, adapted, and shared in the IBM Cloud Orchestrator Catalog. For moreinformation about the IBM Cloud Orchestrator architecture, see Productarchitecture

Cloud Provisioning and Orchestration DevelopmentCollaboration Community

To evaluate future versions of this product, join the Development CollaborationCommunity. From the Cloud Provisioning and Orchestration DevelopmentCollaboration Community, you can use the hosted beta system and download thebeta code. The hosted system has the latest evaluation code. If you want toevaluate in your own environment, download the beta code.

You can learn how to develop orchestration and other content in this community.To access the community, go to https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=e5a54efe-3c9f-491b-af2a-e5400516b5aa.

.


https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=e5a54efe-3c9f-491b-af2a-e5400516b5aa




Chapter 3. Installing and configuring IBM Process Designer

You must install and configure Process Designer, one of the user interfaces forBusiness Process Manager to start with IBM Cloud Orchestrator content authoring.

Before you begin

This procedure describes the IBM Process Designer installation and configurationon a Windows operating system.

Procedure1. Install and configure IBM Cloud Orchestrator. See the Installing section of the

IBM Cloud Orchestrator information center. Business Process Manager isinstalled as a product component.

2. Install Process Designer on the Windows operating system on which youperform content development. See Installing IBM Process Designer in theBusiness Process Manager information center.

3. Configure Process Designer to connect with Business Process Manager:a. Edit C:\\Windows\system32\drivers\etc\hosts.b. On a new line, add the IP and host name (cs3-hostname) of the machine

where Business Process Manager is installed.c. Save the file.

4. Start Process Designer to develop content.


http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/topic/com.ibm.wbpm.imuc.doc/topics/tins_bpm_pcntr_wle.html


Chapter 4. Developing virtual system patterns

Virtual system patterns are topology definitions for repeatable deployment that canbe shared.

IBM provides several virtual system patterns that you can purchase and use.

Topic Link

For more information about creating andmanaging patterns

See Managing and deploying virtualpatterns.

For more information about pattern importthrough command line

See Chapter 6, “Importing using thecommand-line interface,” on page 21



Chapter 5. Developing toolkit and application content

You can develop toolkit and application content.

Implementing workflow orchestrationWorkflow orchestration is a Business Process Manager based extension to IBMCloud Orchestrator which consists of UI panels to collect additional data.

Workflow orchestration is optionally implemented by Business Process Managerhuman service and a Business Process Manager business process, which define thelogical flow of activities of the extension. The extension itself consists of the humanservice and the business process, which are developed with the standard BusinessProcess Manager designer. After development, it is registered as an extensionoperation in the Orchestration Actions or Self-Service Offerings of IBM CloudOrchestrator. After you register it, it is available in IBM Cloud Orchestrator.

The Business Process Manager-based extension types are:

Event-triggered actionsA custom operation that plugs into the existing programming flow at apredefined plug point or event. For example, the ‘Before provisioning’ or‘After provisioning ’ event is used during the deployment of a virtualapplication pattern or virtual system. This operation is used to extend thebasic capabilities of IBM Cloud Orchestrator management operations. Formore information, see Event-triggered actions.

User actionA custom action that you can run on a single image deployment, virtualsystem instance, or virtual application instance. These kinds of operationsimplement lifecycle management actions that extend the set of predefinedmanagement actions for service instances. For example, because the list ofpredefined operations does not include a system backup, it can beimplemented as an user action. For more information, see User actions.

Self-service offeringsA custom operation that is run in the context of the data center. Theseoperations are administrative operations that are used to automate theconfiguration and user operations. Self-service offering are used to enhancethe catalog of available services with more features. They are classified intodifferent categories. For more information about self-service offerings, seethe following topics:v Self-service offeringsv Designing self-servicev Using self-service


Managing business processesIBM Business Process Manager Standard is a comprehensive Business ProcessManagement offering. It gives you visibility and insight to manage businessprocesses. It offers tools and runtime environments for process design, execution,monitoring and optimization, and basic system-integration support.

The process application is the fundamental container for business processes andtheir components in Business Process Manager. It has a name and a unique tag(acronym) that can have a maximum length of seven characters. Business ProcessManager process applications and their related artifacts are stored within arepository, which is hosted and managed by the process center. Processapplications can be created either from the web interface of the process centerconsole or by using the Business Process Manager process designer tool.

Important: If you are a new user to Business Process Manager process designer,verify if you are granted access to the process center repository. The access can begranted either by using the Business Process Manager process designer tooling orthe Business Process Manager process center console. If you are an administratoruser, you can grant rights to other users:1. Go to the Admin tab > Manage Users.2. Click Add Users/Groups.3. In Add Users and Groups dialog, enter the first few letters of the user as a

search filter in the Search for Name panel.4. Select the user and click Add selected.

The user is granted access to the Process Center repository and can use the ProcessDesigner.

Process applicationA process application can contain one or more Business Process Definitions, whichrepresent a model, or template, of a business process that is run. The processapplication consists of the following definitions and activities:v Input and output variable definitionsv Business object data definitionsv User interface panel definitionsv Activities of the process that include the flow

The flow defines how the various activities of the process are orchestrated. When aprocess is started, an instance of the process is created from the process definitiontemplate.

ToolkitA toolkit is a container for Business Process Manager artifacts like Business ProcessDefinitions, Business Objects, Human Services, Coaches, and Business ProcessDefinitions. Toolkits are used to package reusable Business Process Managerartifacts as package content that can be used to build other Business ProcessDefinitions. But in contrast to a Process Application, a toolkit cannot be deployedto the Business Process Manager runtime environment as a stand-alone solution.Instead, the artifacts that are contained can be used as building blocks by otherProcess Applications, but must be declared as a dependency on the toolkit.Multiple Process Applications can have a dependency on the same toolkit andtoolkits can have also dependencies on each other. Toolkits and ProcessApplications can be exported as a .twx file. This file is transferred to other systems


that run the Business Process Manager Process Center, or it is published to the IBMCloud Orchestrator Catalog. You can download from the IBM Cloud OrchestratorCatalog and then import it into another Process Center. In IBM Cloud Orchestrator,do not use the option to export a toolkit or Process Application to a BusinessProcess Modeling Notation (BPMN) file.

SnapshotThe status of a Process Application or a toolkit can be captured by the ProcessDesigner tool or the web console of the Process Center. This snapshot defines aspecific version of the toolkit. It consists of all the related artifacts and their contentor state at the time when the snapshot is taken. The tip level is the most recentversion of a Process Application or toolkit. As a prerequisite, define a snapshot of aProcess Application for most of the management actions like export Processapplication or toolkit, archive, define a dependency on a toolkit.

Business Process DefinitionA Business Process Definition is a reusable model of a process that defines what iscommon to all runtime instances of that process model. Processes are graphicallymodeled in the Process Designer tool, which captures the flow of steps (activities).This graphical diagram represents activities in the process as boxes and linesconnect them to describe the flow of work. Each box represents an activity and islabeled with its description in the diagram. A Business Process Definition mustcontain a start event, an end event, at least one lane, and one or more activities.Lanes are used to segment the drawing canvas of a Business Process Definitioninto one or more horizontal sections. For example, when an activity (BusinessProcess Manager artifact) is added to the process diagram, its vertical positiondetermines the lane to which it belongs. Because each lane can be associated with arole, you can observe the association of an activity of a Business Process with therole. For each Business Process Definition that you create, you must declarevariables to capture the business data that is passed from activity to activity inyour process. Variables can be input to the process (input variables), output from acompleted process (output variables), or local variable (private variables).Related information:

http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.1/com.ibm.wbpm.main.doc/topics/cbpm_bpd.html

ServiceThe activities that are contained in the Business Process Definition describe theoverall flow of the process, but it does not capture the implementation of theprocess. Services are reusable implementations of activities in a Business ProcessDefinition. When a Business Process Definition starts, the services carry out therequired functions.

The following types of services are available in Business Process Manager:

Integration serviceUse an integration service when you want to integrate with an externalsystem. An integration service is the only type of service that can contain aJava or web service or REST integration.

General system serviceUse a general system service when you must coordinate other nestedservices or when you must manipulate variable data. General Systemservices cannot include Java, web service, or REST integrations directly.

Chapter 5. Developing toolkit and application content 11



Human serviceUse a human Service when you want an interactive service with UI panels(Coaches). Human Services generate human tasks in the Business ProcessManager Process Portal.

Ajax serviceUse an Ajax service when you want to include a control in a Coach toimplement dynamic data selection. For example, you can automaticallypopulate lists and complete edit boxes. An Ajax service can pull datadynamically from a connected data source such as a database.

Decision serviceUse a decision service when you want a condition to determine theimplementation.

Web serviceUse a Web service to implement a web service in Business ProcessManager.

Related information:

http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.1/com.ibm.wbpm.wle.editor.doc/modeling/topic/creating_services_B.html

Participant groupA participant group is used to represent a set of users in your organization orenterprise locally within an application. Participant groups can be found in theProcesses category within Business Process Manager Process Designer. Themembers of a Participant Group are local to the Business Process Application inwhich it is defined. In contrast, the Security Groups provide a global mechanism todefine groups.

Remember: A participant group is a logical group that does not exist outside ofthe concept of the Business Process Application in which it is defined.After a Business Process Application is installed on a Process Server in a differentenvironment, you must add or remove users in those groups. For thismanagement, use the Business Process Manager Process Admin Console.

Coach validation frameworkBusiness Process Manager includes a server side validation framework forvalidating coach data that is entered during run time. This feature simplifies thevalidation logic that identifies invalid user input and sends notifications duringrun time. Server script or a service defines the validation logic. Any service, otherthan Ajax service or a human service can be used as a validation service. Multiplecoaches in a human service flow can use the same validation service or serverscript. The coachValidation of type CoachValidation business object is a newsystem variable that contains information about validation errors.

Fire validation

The fire validation when added to a link connects a boundary event to the nextstep to indicate if the validation must be started for this boundary event.

In a human service diagram, go to the Properties > Behavior of a coach. SelectBefore or Never in the Fire Validation field. On selection of Before, the validationis done before moving to the next step.




Stay on page

The Stay On Page event in a human service flow causes the flow to return to theoriginating coach. For example, if there is a validation error in the input, the focusis returned to the originating coach to correct the input.

Server script to define validation

Specify validation logic in the Properties > Implementation for the server script.Add the error data to the system variable coachValidation by using an API. Forexample, tw.system.addCoachValidationError.

It takes three parameters. The first parameter is the system variablecoachValidation. The second parameter is a string that contains full path to thedata item that contains the error. The third parameter is the message that must bedisplayed in the event of the occurrence of an error. If the invalid data is notbound to any coach view, then the validation error is not displayed.

Implementing extensions with IBM Cloud OrchestratorYou can build custom extension operations that are based on business processesand human services, for UI extensions, by using the Business Process ManagerProcess Designer tool. The business logic of the extension is implemented by theBusiness Process Definition. The association between a UI extension that is basedon a human service and business process definition is done during the registrationof the extension operation in the orchestration actions or self-service offering.

IBM Cloud Orchestrator delivers a Business Process Manager toolkit that is calledSCOrchestrator_Toolkit. It provides many useful artifacts such as businessprocesses, services, human services, coaches, business object definitions, javaclasses that assist you to build custom extensions operations for IBM CloudOrchestrator. Additionally, the SCOrchestrator_Toolkit contains samples that showhow to build custom extensions. Other Business Process Manager toolkits aredownloadable from the IBM Cloud Orchestrator Catalog. They provide additionalcontent for different areas (networking, storage) that can be used to build IBMCloud Orchestrator extensions.

Restriction: If a process application or a toolkit in Business Process Manager hasmore than one defined snapshot, then only the artifacts at the top level can beused to define a new extension in the orchestration actions or self-service offering.The artifacts below the tip level are not considered.

Implementing a custom operation for IBM Cloud OrchestratorThe following steps are needed to develop a custom extension operation with orwithout a user interface for IBM Cloud Orchestrator:

Before you begin

Make sure that the SCOrchestrator_Toolkit is imported into the Business ProcessManager Process Center repository. See http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_toolkits_I.html.


http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_toolkits_I.html



Procedure1. Create a Business Process Manager Process Application as a container for your

extension operation. For information about managing process applications, seehttp://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_process_applications_A.html.

2. In the Business Process Manager Process Designer, open your Business ProcessApplication and declare a dependency on the SCOrchestrator_Toolkit.

Note: The toolkit contains useful building blocks for writing extensions.3. In the toolkits category, click + and add the dependency to the

SCOrchestrator_Toolkit.4. In the same manner, import and add dependencies to other toolkits as needed.5. Create business process definitions and human services (extensions) for IBM

Cloud Orchestrator.

Note: You can use the building blocks available in the SCOrchestrator_Toolkit.To use a building block that is provided by a toolkit, do the following tasks:v Drag the corresponding building block from the toolkit to the process or

service canvas in the Process Designer.v Connect it with the other steps or activities of the business process or service.v Map the input and output variables of the building block to the variables of

the embedding business process or service.6. Create a snapshot of your business process application. For information about

the steps, seehttp://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_snapshots_A.html

7. Register the extension operation in the IBM Cloud Orchestrator UI. For moreinformation about custom operation registration, see Designing self-service,Event-triggered actions, and User actions.

Results

You can now use the extension operation in IBM Cloud Orchestrator.Related tasks:Chapter 9, “Publishing IBM Cloud Orchestrator content to IBM Cloud OrchestratorCatalog,” on page 39IBM Cloud Orchestrator Catalog is a platform and one-stop-shop for IBM CloudOrchestrator customers, partners, and IBM employees. The content that you createcan be submitted internally or externally from IBM in Integrated ServiceManagement Library (ISML) for Cloud/Virtualization category. The primary goalis to have an environment where developers, partners, and IBM Service teamsshare content with one another. This web-based application is envisaged tofederate content from several repositories into a single cloud automation contentcatalog.


http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_process_applications_A.html



http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_snapshots_A.html

http://www.ibm.com/support/knowledgecenter/SSFPJS_8.0.0/com.ibm.wbpm.admin.doc/managinglib/topic/managing_snapshots_A.html

Start a custom extension operationStarting a custom extension operation is done with or without a user interface.Start the operation and the following activities are automatically run in thespecified sequence:1. During the following conditions, a task with an operation context is created in

the task engine with the status as ‘New':v A self-service offering or user action is triggered from within the IBM Cloud

Orchestrator UI.v A deployment operation or another operation that triggers the events are

started from the IBM Cloud Orchestrator UI.2. If a human service is not registered in the orchestration actions or self-service

offerings for this operation, then this step is skipped.v Human service starts with the coach UI panels.v It is passed to the operation context id (task id) as parameter.v The first activity of the human service is to run a REST call against IBM

Cloud Orchestrator to get the operation context business object. It is based onthe operation context id that is given as input parameter.

v The coach panels gather the parameters from the user and stores theparameters into the output business object of the human service.

v When all user input information is collected, the last activity in the BusinessProcess Manager human service (ReturnParameters) is run to persist theoutput business object into the operation context of the task engine. Thesebusiness objects can be used later by the extension Business Process ManagerBusiness Process. The status of the task in the task engine is set ‘Queued’ sothat the task can continue to run.

3. The task engine starts the Business Process Manager process, which gets theoperation context as input parameter. For self-service offering and user actions,the process starts directly after the human service ends, and for event-triggeredactions when the corresponding event fires. The Business ProcessManagerprocess defines an input business object, which contains theparameters that are collected by the user interface of the related human service.The parameter section of the operation context also contains the parametersthat are collected by the graphical user interface of the human service.

Implementation of a human service as a UI extensionA Business Process Manager human service that can be used as UI extension forIBM Cloud Orchestrator is developed with Business Process Manager ProcessDesigner. Observe the following guidelines:v Make the human service available in Business Process Manager as URL to the

participant group, which is used in IBM Cloud Orchestrator. This activity can bedone in the Process Designer as follows:1. Go to the Overview tab of the design view.2. In the Exposing section, select All Users in Expose to Start.3. Register the process in the orchestration actions or self-service offering

– In the IBM Cloud Orchestrator UI, go to PATTERNS > Pattern Design >Orchestration Actions or CONFIGURATION > Self-Service Catalog.

– Create a registry entry for the process you created.– You can request the new service from self-service offerings with the UI.


The participant group controls the visibility of the extension operation in theorchestration actions or self-service offerings for the user or user group. Itdecides which users or user groups are allowed to run the extension.

v The business object defines the interface of the human service and the relatedbusiness process. This business object contains the parameters to be returned bythe human service. The human service acts as an UI extension for IBM CloudOrchestrator, which are the input parameters of the related business process.Therefore, a human service defines an output variable with nameoutputParameterObject. It is of type business object that is defined by thecreator of the extension.

v Declare operation context id as an input variable of type string. The humanservice gets the operation context id as input variable. For example,operationContextId. As first activity of the human service (before it can accessthe operation context), it must use the activity GetOperationContext that isdelivered with the SCOrchestrator_Toolkit. This activity retrieves the operationcontext by using the operation context id.

v Define a UI coach or a sequence of coaches to collect the data that are neededfrom the user.

v As a last activity, the human service calls the ReturnParameters integrationservice of SCOrchestrator_Toolkit. Here, the data collected from the user isregistered on the operationContext. This data is then passed as an inputparameter to the associated business process.

Related concepts:“Coach validation framework” on page 12Coach validation framework

Implementation a Business Process Manager process as an extensionA business process that can be used as extension operation for IBM CloudOrchestrator is developed by using Process Designer. It must observe the followingguidelines:v The Process Designer must be made available in the Business Process Manager

as URL to the participant group. This group uses it in IBM Cloud Orchestrator.The participant group controls the user or user group visibility for the extensionoperation. It is made visible in the configurations to be registered as extensionoperation. It also decides which users or user groups are allowed to run theextension.

v Every Business Process has inputParameterObject, which is an input parameter.The type of this variable is same as the output parameter of the associatedhuman service. The first activity of the Business Process is GetInputParameter(part of SCOrchestrator_Toolkit), which populates the inputParameterObject.

v The business process gets the operation context object as an input parameterand must define a corresponding input variable of type OperationContext. It is apredefined business object definition that is delivered bySCOrchestrator_Toolkit.

v With activities, the business process can access the information that is containedin the operation context. Also, the information is handed over as parameter fromthe associated human service. It can also use REST calls to retrieve furtherinformation from IBM Cloud Orchestrator. REST calls are implementations thatare provided by SCOrchestrator_Toolkit.


Best practices and guidelinesWhen you create toolkits or Process Applications, there are some best practices tobe followed in naming conventions, structuring, modeling, and error handling.

Guidelines for naming and documenting your toolkit or processapplication

When you create toolkits, use the following naming conventions:v Name the toolkit after the utility or services it provides.v Add words like "Toolkit" or "Framework" so that you can differentiate it from

other process applications.v Avoid long names. You must use fewer than 64 characters.v White spaces between words can be added if it improves readability.v Avoid the version number in the name, unless you want to bring attention to the

major changes in the solution.v Add more information about the toolkit in Description field.v Choose an acronym for your toolkit. Do not use the prefix "IC“ as it is used for

content delivered by IBM.v Name your snapshots according to this scheme: AABB_YYYYMMDD. Exported

TWX archives of your toolkit get this snapshot name appended, so you caneasily identify the exported snapshots later.

AA The IBM Cloud Orchestrator release that is prerequisite for the toolkit orprocess application, for example, 24 for IBM Cloud Orchestrator V2.4.

BB Counting up the version of the toolkit, for example. 00 for the firstrelease, and 01 for the second release

YYYYMMDDThe date the snapshot was created

v When updating an existing process application or toolkit, do not change thechosen acronym because it is used to reference the processes in self-serviceofferings.

Guidelines for creating artifacts in a toolkit

The general best practices are as follows:v In the documentation field for a Business Process Manager artifact, enter a

description of the input and output parameters of that artifact.v Use the note object of Business Process Manager to improve the readability of

complex processes and human services.v As mentioned in the naming conventions, provide an understandable and

meaningful name for your artifacts.v Keep the interface definition between a Business Process Manager Human

Service and its associated Business Process Manager Business Process Definitionas short as possible. The interface is defined by a Business Process ManagerBusiness Object. This object is used to correlate a business process with itsassociated human services in the IBM Cloud Orchestrator UI. Use the BusinessProcess Manager human service only to collect the parameters that are neededby its associated business process. Implement the business logic in the businessprocess. It also helps if you enable the business process to be called by using theREST API from an external application, such as a portal application.


v Avoid Pre and Post execution assignments. Instead, add explicit activities, ifneeded. The execution assignments are hidden in the Business Process ManagerProcess Designer, and the logic of the corresponding activity or service becomesdifficult to understand. If needed, use the Pre and Post executions to makesimple assignments like initializing the associated Business Process Managerartifact. For example, consider having two consecutive coaches in a humanservice. In such cases, do not initialize the objects that are used by the secondcoach as being Post execution assignment of the first coach. If needed, do theinitialization as a pre-execution assignment of the second coach.

v Do not use passwords in environment variables or other artifacts that are visibleto everyone.

v When you deliver a solution for IBM Cloud Orchestrator, make sure that thereare no validation errors. These errors can be seen in the Process Designer.

v Avoid changing the interface of a building block that is delivered as a part of atoolkit. If you change the interface of building blocks in a toolkit, it becomescumbersome for all its dependent toolkits or Process Applications. Evenchanging the name might lead to redoing the mapping for all activities orservices that use the building block.

Guidelines to structure your solutionv In general, an extension content solution for IBM Cloud Orchestrator consists of

a Business Process Manager Process Application and a Business Process ManagerToolkit.The basic rule is that a process application contains artifacts that are ready to beused by the user and not meant to be changed or adapted to be useful. All otherartifacts are better placed in a toolkit.

v When structuring your solution, always consider the visibility of your artifacts.Artifacts of one process application are not visible by default to another processapplication.For example, a Business Process Manager, process A, can be called by anotherBusiness Process Manager, process B. The ‘Linked Process’ activity is used ifboth are in the same process application or if process A is in a dependant toolkit.Avoid cyclic dependencies, that is, when toolkit A depends on toolkit B, avoidhaving a dependency on toolkit A. If such a cyclic dependency occurs,restructure your toolkits to resolve it.

v Use Business Process Manager tags and smart folders to structure your solutionto make it more understandable. If you have UI parts that can be used in UIpanels, define them as Coach views. These views can be reused in differentCoaches. If you must change something later, for example, wording, you changeonly the reusable Coach view.

Guidelines for handling errors

An IBM developerWorks article explains extensively about exception handling andlogging from a business process management perspective. See Related Links. Itidentifies the types of exceptions that are encountered in a Business ProcessManager scenario. Also, it shows you how to handle them using IBM BusinessProcess Manager.

The following are best practices in error handling:v Use the PostMessage integration service that is delivered as a part of the

SCOrchestrator_Toolkit to report messages that occur in Business ProcessManager processes or Human Services back to the IBM Cloud Orchestrator UI.


For event and instance operations, these messages are written to the historysection of the pattern instance. For self-service offerings, these messages arewritten to the operationContext and are displayed in the UI.

v Define error message as localization resources.v Raise errors in your integration services or processes using the Error End Event

node.v Catch raised errors raised from integration services using Intermediate Error

Events or Event Subprocesses.v For Java classes that are used in Business Process Manager processes or human

services, define logging framework. For example, java.util.logging to logmessages to the WebSphere log.

v Use the logging capabilities of Business Process Manager to log messages to theWebSphere log. A good practice is to log in the entry and exit of an activity tosupport debugging better.


http://www.scribd.com/doc/92505753/IBM-Impact-2011-Five-Guidelines-to-Better-Process-Modeling-for-Execution-Stuart-and-ZahnYou can find many documents with guidelines and best practices about businessprocess modeling. One of it is Five Guidelines to Better Business Process Modeling forExecution’ from Jonas A. Zahn and Stuart Jones, which describes the following designguidelines:– Rule of Seven - limit any view to no more than seven steps for a good fit.– Activity granularity - activities must be similar in scope at each level. Avoid the

String of Pearls pattern, that is, series of activities in the same lane.– Activity description - use [action verb] + [business object] and avoid vague

verbs like ‘process’ and ‘perform’.

http://www.ibm.com/developerworks/websphere/library/techarticles/1105_ragava/1105_ragava.html

Importing and exporting toolkits and process applicationsYou can create toolkits or reuse toolkits that are shared by other contentdevelopers. To use a toolkit that is created and shared by other content providers,use the import toolkit feature. You can use export and import utilities to move thetoolkit from development process server to production process server or betweenany two process servers.

Importing toolkitsBefore you begin

To import toolkits into the Business Process Manager, complete the following steps:

Procedure1. In the Business Process Manager Designer, click Process Center.2. In Toolkits, click Import Toolkit.3. In Import Toolkit, click Browse to select the file to import.

Tip: The Toolkit file extension is in twx extension format.4. Click Ok.Related information:


http://www.scribd.com/doc/92505753/IBM-Impact-2011-Five-Guidelines-to-Better-Process-Modeling-for-Execution-Stuart-and-Zahn




Chapter 6, “Importing using the command-line interface,” on page 21

Exporting toolkitsTo export to a Business Process Manager export file, complete the following steps:

Procedure1. Select the Toolkits tab.2. Click the toolkit that you want to export from the list of toolkits.3. Find the snapshot that you want to export.4. If a snapshot does not exist, click Create New Snapshot.5. Click the Export option for the snapshot.6. Select BPMN export (.zip) or IBM BPM export (.twx) and click Export.7. Locate the directory to which you want to save the exported file.8. Name and save the file. The exported file can be imported into any Process

Center repository.

Business Process Manager securityFor a class of use cases, it is important to understand the security context of aBusiness Process Manager process or user interface. The activity-based userauthentication and authorization are described here.

Business Process Manager user interfaces are run as the currently logged in userand project. They are used as the initial dialog for collecting data in self-serviceofferings and in orchestration actions. They are also used for assignments in theMy Inbox panel. Retrieve the currently logged in user with this JavaScript (R)expression in Business Process Manager: tw.system.user_loginName

Activities in the system lane of a business process are run in the background.Therefore, there is no currently logged in user. By default, activities are run as anadmin user and project. The admin user is tw_admin in Business Process Manager.

Additionally, there are use cases where it is important to know which user,domain, and project submitted a self-service offering or orchestration action. Thisinformation is found in the variables user, domain, and project of the operationcontext.

For instance, the GenericRESTCall integration service ofthe SCOrchestrator_Toolkit extracts the authentication information from thesecurity context by default. The service then uses the extracted information toconstruct the security authentication token (SimpleToken) for REST calls to externalsystems. Because the tw_admin is an internal user, GenericRESTCall translatestw_admin to the default admin user (generally admin) for external calls. It isdesirable to run these REST calls on behalf of the person who submitted therequest. To do that, map the user, domain, and project variables from the operationcontext to the GenericRESTCall.


Chapter 6. Importing using the command-line interface

You can import IBM Cloud Orchestrator content using the command-line interface.

The following tools support the import of content by using command-lineinterfaces:v “Import content pack into Business Process Manager ”v “Import Workload Deployer command-line interface ”v “Virtual system pattern command-line interface” on page 22

Important: You must have a command shell to run these commands.

Import content pack into Business Process Manager

A Business Process Manager-based extension to IBM Cloud Orchestrator consists ofUI panels to collect more data. To import a content pack in to a Business ProcessManager, start the command-line interface in interactive mode and then run theimport command.

To start the command-line interface in interactive mode, use this syntax -wsadmin.sh -h <hostname> -user <username> -password <password> -langjython. To Import content pack, use this syntax - >>>AdminTask.BPMImport(’[-inputFile <file path>]’).

The wsadmin.sh is in the Business Process Manager server installation directoryand its parameters are as follows:

-h <host> or --hostSpecifies the host name or IP address of the Business Process Manager. Thisparameter is required.

-userSpecifies the user ID to authenticate to the Business Process Manager. Use thesame user ID and password that you use to log on to the tool. This parameteris optional.

--passwordSpecifies the password that is used to authenticate to the user. This parameteris optional and is case-sensitive.

wsadmin.sh -user admin -password admin -lang jythonwsadmin>AdminTask.BPMImport(’[-inputFile /tmp/abc.twx]’)

For more information about IBM Business Process Manager command-lineinterface, see http://www.ibm.com/support/knowledgecenter/SSFPJS_8.5.0/com.ibm.wbpm.ref.doc/topics/rref_bpmimport.html.

Import Workload Deployer command-line interface

For administrative functions of Workload Deployer, download the command-lineinterface onto a local workstation.

The command-line interface communicates with Workload Deployer, which helpsyou to manage the deployer appliance in a scripted and non-graphicalenvironment.


http://www.ibm.com/support/knowledgecenter/SSFPJS_8.5.0/com.ibm.wbpm.ref.doc/topics/rref_bpmimport.html

http://www.ibm.com/support/knowledgecenter/SSFPJS_8.5.0/com.ibm.wbpm.ref.doc/topics/rref_bpmimport.html

Workload Deployer includes the virtual system pattern, virtual image, and virtualapplication pattern.

Virtual system pattern command-line interface

The syntax for importing virtual system pattern command-line interface isdeployer -h <hostname> -u <username> -p <password> -f <scriptfile> -s <filepath>

-h <host> or --hostSpecifies the host name or IP address of the Workload Deployer component.This parameter is a required.

-u <userid> or --useridSpecifies the user ID to authenticate to the Workload Deployer component.This parameter is optional.

-p <password> or --passwordSpecifies the password that is used to authenticate to the Workload Deployercomponent. It is case-sensitive.

-f <script_file> <arg>*Use this optional parameter to cause the command line to run the specifiedJython script file with the specified arguments. Any arguments after the scriptfile name are passed to the Jython script. Only one -f parameter can bespecified on the command line.

deployer -h hostname -u admin -p admin -f samples\importPatterns.py -s <file path>

To import a pattern, first start the command-line interface in interactive mode asfollows:v To start the command-line interface in interactive mode, use this syntax -

deployer -h hostname -u username -p password.v The command to import virtual images into IBM Cloud Orchestrator is -

>>>deployer.virtualimages.create(’http://server.xyz.com/path/to/foo.ova’).

v The import from a local disk is >>>deployer.virtualimages.create(“<localfile path>”).

Note: deployer.virtualimages.create imports the virtual image into IBMCloud Orchestrator.

v The import command for virtual application pattern -deployer.applications.create(“<local file path>”)

Note: deployer.applications.create command imports a new virtual image tothe Workload Deployer component.

-h <hostname> or --hostnameSpecifies the host name or IP address of the Workload Deployer component.This parameter is required.

-u <userid> or --useridSpecifies the user ID to authenticate to Workload Deployer. This parameter isoptional.

-p <password> or --passwordSpecifies the password that is used to authenticate to Workload Deployer. Thisparameter is optional and is case-sensitive.


Chapter 7. Example scenarios for workflow-basedorchestration

Workflows are driven by the following triggers: self-service offerings,event-triggered actions, and user actions.

A quick start guide is available in the IBM Cloud Orchestrator Catalog for contentdevelopment. Search for this guide in the IBM Cloud Orchestrator Catalog byusing the search filter SCOrchestrator Content QuickStart Guide. For moreinformation about searching and downloading from the IBM Cloud OrchestratorCatalog, see Chapter 9, “Publishing IBM Cloud Orchestrator content to IBM CloudOrchestrator Catalog,” on page 39.

Self-service offerings scenarioSelf-service offerings are custom operations that can be run in the context of thedata center. Such offerings can be used to automate configuration tasks or toenhance the catalog of the available services with extra features. This scenariodepicts a self-service offering for registering the firewall host device on IBM CloudOrchestrator by storing the firewall details in the storehouse.

Procedure1. In the Process Designer, click Create a New ProcessApp or Toolkit and name

it RegisterFirewall.2. Open the RegisterFirewall application or toolkit in the Process Designer.3. Create a dependency on the SCO_Orchestrator_Toolkit and the

SCOrchestrator_Scripting_Utilities_Toolkit.a. Click the plus sign (+) to the right of Toolkit.b. From the Add dependency dialog, select SCO_Orchestrator_Toolkit.c. Select the latest snapshot.d. Repeat the procedure for SCOrchestrator_Scripting_Utilities_Toolkit.

4. Create a human service.a. Click the plus sign (+) to the right of User Interface.b. Add new human service and name it Register_Firewall_Host_HS. This

human service includes a coach that collects the required input.c. Click the Variables tab.


Table 1. Input Variables

Variable Type Description

operationContextId String The ID contains theoperation context objectidentifier, and it is passedduring the start of theoperation by theIBM CloudOrchestrator framework. Theidentifier is used to fetch theoperationContext, which isan object that contains all thedata that is related to theexecution of an operation.Note: This variable ismandatory for all humanservices that are run throughIBM Cloud Orchestrator.

outputParameterObject FirewallHost The output parameter is oftype FirewallHost businessobject that has registerfirewall host-relatedparameters such as host IPaddress, user name, andpassword.

Table 2. Default values of outputParameterObject

Property Value

hostIpaddress ""

username "root"

password ""

commandLine "iptables -I INPUT -p tcp --dport 80 -jACCEPT; service iptables save "

d. Create a business object and name it FirewallHost. Add the followingparameters to this business object:

Table 3. Output Variables

Variable Description

hostIpaddress IP address of the firewall host.

username Log in user on the firewall host.

password Password for the user on the firewall host.

commandLine Command line to configure firewall.

e. Create the following coaches:

Table 4. Coach

Coach Input fields

firewall_host_coach hostIpaddress

username

password

commandLine


Map the parameters from the outputParameterObject to these coach fields.f. Use the ReturnParameters integration service from the

SCOrchestrator_Toolkit before the 'end' activity.1) Click SCOrchestrator_Toolkit to expand it.2) Click Implementation.3) Drag and drop the ReturnParameters integration service.

g. Map the operationContextId and outputParamaterObject variable as aninput to this service.1) Click ReturnParameters.2) Click local.input.3) Map local.input.operationContextId to operationContextId,

Local.Input.outputParamaterObject to outputParamaterObject.h. Connect the activities to complete the human service.

5. Create a Business Process Definition.a. Click the plus sign (+) to the right of Processes.b. Create a Business Process Definition and name it as

Register_Firewall_Host_BPD.c. Click Variables tabd. Click Add Input and create the following input variables:


Variable Type Description

operationContext OperationContext The operationContext objectcontains all the data that isrelated to the execution of anoperation.

inputParameterObject FirewallHost The input parameter is oftype FirewallHost.

Note: Both the input variables are mandatory for all business processesthat are run from IBM Cloud Orchestrator.

e. Add the integration service GetInputParameter fromSCOrchestrator_Toolkit as first activity in the business process. Completethe data-mapping for this service:Input Mapping:tw.local.operationContext -> operationContexttw.local.inputParameterObject -> inputParameterObject_inOutput Mapping:inputParameterObject -> tw.local.inputParameterObject

f. Add the integration service SSH_ExecuteCommand fromSCOrchestrator_Scripting_Utilities_Toolkit. Complete the data-mappingfor this service:Input Map:tw.local.inputParameterObject.hostIpaddress -> remoteMachinetw.local.inputParameterObject.username -> usernametw.local.inputParameterObject.password -> passwordtw.local.inputParameterObject.comandLine -> commandLine

g. Connect the activities to complete the business process.6. Expose the human service to the participant group.

a. Go to the Overview tab of the human service.b. Select all users for Exposed to for the option under Exposing.

Chapter 7. Example scenarios for workflow-based orchestration 25

c. Select Expose as URL (Available from a URL).7. Expose the business process to the participant group.

a. Go to Overview tab for the business process.b. Select all users for Expose to Start to start option under Exposing.

8. Register the operation in the IBM Cloud Orchestrator UI.a. Log in to the IBM Cloud Orchestrator UI.b. Click CONFIGURATION > Self-Service Catalog.c. Click Offerings and then click Create Offering in the Actions menu.d. Enter the following details:

v Offerings name - enter the name of the new offering.v Description - enter the description.v Offering icon - select the icon from the list.v Process - select the Register_Firewall_Host_BPD from the list. It is the

Business Process Definitionthat is created in the Process Designer.v User Interface - select Register_Firewall_Host_HS. The human service is

created in the Business Process Designer.e. Click Create.

9. Run the Self-Service Offering.a. Go to Self-Service.b. Click Category.c. Click Offering.d. Enter the details and click OK.

10. After the operation completes successfully, check that the firewall settingcommand is executed on the host.


http://www.ibm.com/support/knowledgecenter/SSFPJS_7.5.0/com.ibm.wbpm.main.doc/managinglib/topic/managing_toolkits.htmlInformation about how to include integration service, process, coach, and humanservice inside the toolkit library.

Event-triggered action scenarioThis scenario depicts a event-triggered action for post deployment of a pattern byusing a Linux virtual machine. A script file on the Linux virtual machine mounts afilesystem from a storage device.

Before you begin

The script file to mount filesystem takes the following arguments as input:storageDeviceIpaddress, username, password, and mount point. In this example,the script file is copied on the deployed virtual machine and then it is run.

Note: The script file described in this topic is an example and it is not releasedwith the product.

Procedure1. In the Process Designer, create a Process Application and name it as

MountFileSystem.2. Open the Process Application in the designer.


http://www.ibm.com/support/knowledgecenter/SSFPJS_7.5.0/com.ibm.wbpm.main.doc/managinglib/topic/managing_toolkits.html

http://www.ibm.com/support/knowledgecenter/SSFPJS_7.5.0/com.ibm.wbpm.main.doc/managinglib/topic/managing_toolkits.html

3. Upload the script file as a Server File in the designer.4. Create dependency on the SCO_Orchestrator_Toolkit and

SCOrchestrator_Scripting_Utilities_Toolkit.5. Create a human service.

a. Create a human service and name it Mount_FileSystem_HS. This humanservice includes a coach, which collects the required input to mount afilesystem on a virtual machine.

b. Click Variables tab.


Input variables Data type Description

operationContextId String The ID contains theoperation context objectidentifier, and it is passedduring the start of theoperation by the IBM CloudOrchestrator framework. Theidentifier is used to fetch theoperationContext, which isan object that contains all thedata that is related to theoperation.Note: It is mandatory for allhuman services that are runfrom IBM CloudOrchestrator.


Output variables Data type Description

outputParameterObject MountFileSytem The output parameter is oftype MountFileSystembusiness object that hasmount filesytem relatedparameters, such asstorageDeviceIpaddress, username, password, and mountpoint.Note: It is mandatory for allhuman services that are runfrom IBM CloudOrchestrator.

c. Create a business object and name it as MountFileSystem.d. Add following parameters to this business object.


Input variables Description

storageDeviceIpaddress IP address or host name of the storagedevice.

username Log in user to the storage device

password Password for login user to the storagedevice.

mountPoint Mount point of the filesystem on the storagedevice.


e. Create the following coaches:

Table 9. Coaches

Coach Input fields

mount_filesytem_coach storageDeviceIpaddress

username

password

mountPoint

Map the parameters from the outputParameterObject to these coach fields.f. Use the ReturnParameters integration service from the

SCOrchestrator_Toolkit before the 'end' activity. Map theoperationContextId and outputParamaterObject variable as an input to thisservice.

g. Connect the activities to complete the human service.6. Register the event-triggered action in the user interface of IBM Cloud

Orchestrator.a. Log in to the IBM Cloud Orchestrator UI.b. Click CONFIGURATION> Actions Registry.c. Click Create Action.d. Enter the following details:

v Orchestration name - enter the name of the new instance.v Description - enter the description.v Action type- select Event-triggered action from the listv Event selection- select After provisioning from the list. It specifies when

the event must be run.v Apply to - select Selected Virtual System Patterns.v Virtual System Patterns - select the configured virtual system pattern.v Process - select the Mount_FileSystem_BPD. It is the Business Process

Definition that is created in the IBM Cloud Orchestrator Business ProcessDesigner.

v User Interface - select Mount_FileSystem_HS. It is the Human Service thatis created in the IBM Cloud Orchestrator Business Process Designer.

v Sequence priority - select 5e. Click OK.

7. Run the event-triggered actiona. Go to PATTERNS > Instances > Virtual System Patterns (Classic).b. Select the virtual system pattern on which the action was registered.c. Click Deploy on top right.d. Click Configure actions.e. Click the Orchestration name that was set.f. Enter the required details and click OK.

8. After the operation completes successfully, check the virtual machine for themounted filesystem.


User action scenarioThe scenario depicts user action to create a user on a provisioned virtual machine.

Before you begin

Before you start this activity, copy the script file to the virtual machine that createsa user. In this example, createuser.sh exists on the virtual machine.

Procedure1. In the Process Designer, click Create a New Process App and name it Create

User.2. Create dependency on the SCO_Orchestrator_Toolkit and

SCOrchestrator_Scripting_Utilities_Toolkit.3. Create a human service.

a. Open the process application in the designer.b. Create a human service and name it Create_User_HS. This human service

includes a coach, which collects the required input to create a user on avirtual machine.

c. Click Variables, and add the following input variables:


Input variable Data type Description

operationContextId String The ID contains theoperation context objectIdentifier. It is passed duringthe start of the operation bytheIBM Cloud Orchestratorframework. The Identifier isused to fetch theoperationContext, which isan object that contains all thedata that is related to thisoperation.Note: Input variableoperatingContextId ismandatory for all humanservices that are run fromIBM Cloud Orchestrator.


Variable Data type Description

outputParameterObject CreateUserRequest The output parameter is oftype CreateUserRequestbusiness object that containscreate user relatedparameters, such as username and password.Note: Output variableoutputParameterObject ismandatory for all humanservices that are run fromIBM Cloud Orchestrator.


d. Create a Business Object and name it as CreateUserRequest. Add thefollowing parameters to this business object:

Table 12. parameters

Parameter Data type Description

username String The name of the user.

password String The password for the user.

e. Create the following Coaches:

Table 13. Coaches

Coach Input fields

create_user_coach v User name

v Password

Map the parameters from theoutputParameterObject to these coach fields.

f. Include theReturnParameters integration service of theSCOrchestrator_Toolkit before the end activity.

g. Map the operationContextId and outputParamaterObject variable as inputto this service.

h. Connect the activities to complete the human service.4. Create a Business Process Definition.

a. Open the process application in the Process designer.b. Create a Business Process Definition and name it Create_User_BPD.c. Click Variables tab.

Table 14. Input variables

Input variable Data type Description

operationContext OperationContext The operationContext objectcontains all the data that isrelated to the operation.

inputParameterObject CreateUserRequest The input parameter is oftype CreateUserRequestbusiness object that hascreate user relatedparameters, such asusername and password.Note: Input variablesinputParameterObject andoperationContext aremandatory for all businessprocesses that are run in IBMCloud Orchestrator.

d. Add the following private variables:

Table 15. private variables

Private variables Description

VirtualMachine (VirtualMachine) It is of type 'VirtualMachine' business objectthat contains the all the virtualMachinerelated data.


Table 15. private variables (continued)

Private variables Description

virtualMachineIp Ipaddress of the virtual machine.

virtualMachineUsername User name to login to the virtual machine.

virtualMachinePassword Password to login to the virtual machine.

workingDirectory Directory in which the createuser.sh script ispresent.

commandLine CommandLine to be executed.

privateKey PrivateKey to login to the virtual machine.

virtualMachineId Identifier for virtual machine.

virtualSystemId Identifier for virtual system.

e. Add the integration service 'GetInputParameter' of SCOrchestrator_Toolkitas the first activity in the business process. Complete the data-mapping forthis service.

f. Add a script task as next activity in the business process. This script activityis used to read the virtualMachine details from the operationContext object.tw.local.virtualMachine = tw.local.operationContext.serviceInstance.virtuaMachines[0];tw.local.virtualMachineIp = tw.local.virtualMachine.networkInterfaces[0].ip;tw.local.virtualMachineId = tw.local.virtualMachine.id;tw.local.virtualSystemId = tw.local.operationContext.serviceInstance.metadata.id;

g. Add the integration service GetCredentialsofVirtualMachine fromSCOrchestrator_Toolkit as next activity in the business process. Thisintegration service returns the user credentials for the virtual machine.Complete the data-mapping for the service.

h. Add the integration service LinuxExecuteRemoteScriptfromSCOrchestrator_Scripting_Utilities_Toolkit as the next activity in thebusiness process. This integration service runs the script on the remotemachine. Complete the data-mapping for this service. The input parametersrequired for this service are:v scriptName - createuser.shv remoteMachineIp – virtualMachineIpv username – virtualMachineUsernamev password – virtualMachinePasswordv workingDirectory – workingDirectoryv commandLine – commandLine to be executed on the workingDirectory (

For example, ./createuser.sh testuser password)i. Connect the activities to complete the business process.

5. Expose the human service to the participant group. Go to Overview tab for thehuman service and add the participant group to Expose to start option.

6. Register the operation in the IBM Cloud Orchestrator UI.a. Log in to the IBM Cloud Orchestrator UI.b. Click CONFIGURATION> Actions Registry.c. Click Create Action.d. Enter the following details:


v Orchestration name - enter the name of the new Orchestration Actionsentry.

v Description - enter the description.v Action type - select User action.v Apply to - select either Selected Virtual System Patterns.v Virutal System Patterns - Select the configured virtual system pattern.v Process - select the name of the Business Process Manager Business

Process that implements the custom operation. (Create_User_BPD).v User Interface - select the name of the Business Process Manager human

service that implements the user interface for the custom operation.(Create_User_HS).

e. Click OK.7. Execute the user action:

a. Go to PATTERNS > Instances > Virtual System Instances (Classic)

b. Select the virtual system on which the action was registered.c. Click More Actions on the top right.d. Select the User Action and click Run.

8. After the operation completes successfully, check the virtual machine for thenew user.


Chapter 8. Automating the creation of categories, offerings,and user actions

You can automate the creation of categories, offerings, and user actions using thecatalogTool.sh tool.

Before you begin

The catalogTool.sh tool is installed together with IBM Cloud Orchestrator. Theinstallation directory of the tool is /opt/ibm/ccs/catalog.

The tool selects the JVM in the following order:1. The JVM used by the Business Process Manager, if it exists2. The JVM defined in PATH variable, if there is any3. The JVM in the JAVA_HOME variable, if it has been defined

The catalogTool.sh tool is installed on the Business Process Manager node.

To automate the creation of categories, offerings, and user actions, you need thefollowing items:v A configuration file that describes the IBM Cloud Orchestrator environmentv An XML file that represents the resources to be createdv Valid credentials to connect to the IBM Cloud Orchestrator. Admin role is

required.

Note: Although, in this topic, the script is catalogTool.sh, if you are installing ona Windows operating system, the script is catalogTool.bat.

About this task

The following directories contain the following items:

conf

v log4j.properties, logs, and trace configurationv env.properties, the configuration file for IBM Cloud Orchestrator (IP

address)

samplesVarious XML files that can be used as examples

lib Resources required by the script

logs Log files

To compile your own XML file, start from one of the provided samples and createyour <category>, <offering>, <instance-type>, and <instance-action> elements.

For a category, specify the name, for example:<category>

<name>A test category</name><description>An optional description</description><icon>Web</icon>

</category>


The description and icon fields are optional. For icon, the following values areallowed:

Cloud Cloud Category Icon

ApplicationApplication Category Icon

BackupBackup Category Icon

Client Client Category Icon

ConfigurationConfiguration Category Icon

Job Job Category Icon

NetworkNetwork Category Icon

Server Server Category Icon

StorageStorage Category Icon

Virtual MachineVirtual Machine Category Icon

Web Web Category Icon

For offerings, specify the following parameters:<offering>

<name>A test offering</name><description>An optional description</description><icon>Web</icon><category-name>Reference a category by name here</category-name><process toolkit-name="toolkit_name"><name>Enter the name of the process you want to link to the offering</name></process><user-interface toolkit-name="toolkit_name"><name>Enter the name of the user interface you want to link to the process</name></user-interface></offering>

You can use the same labels displayed in the UI when creating a new self serviceoffering. The description and icon fields are optional. For icon, the same fieldsthat are described for category are allowed here too.

The attribute toolkit-name for the <process> and <user-interface> elements isoptional and can be specified to state which toolkit contains theprocess/user-interface.

For instance actions, specify the following parameters:<instance-action selection-type="multiple">

<name>An instance action</name><description>An optional description</description><icon>Icon</icon>

<instance-type>Resource type to which you can apply the action</instance-type><process toolkit-name="toolkit_name"><user-interface toolkit-name="toolkit_name"><name>Enter the name of the process you want to link to the useraction</name></user-interface></process><tags>You can mark the instance with an unlimited amount of tags to filter actions.


<tag>Any_tagA</tag><tag>Any_tagB</tag></tags></instance-action>

The selection-type field can have a value of either "multiple" or "single"depending on if the action is applicable to only one instance or to severalinstances. The default is "single."

For instance type, specify the following parameters:<instance-type>

<name>A_unique_instance_type_name</name><Display name>The name as it appears in the UI</description><icon>Icon</icon>

<Provider>The provider</instance-type><details-view>

<toolkit-name>Toolkit_Name</toolkit-name><user-interface>UI display view of type of resource</user-interface>

</details-view><keyfields>

<keyfield><attribute>Instance type attribute</attribute><header>Header of the column that displays the corresponding attribute in the resource list view</header>

</keyfields><tags>You can mark the instance with an unlimited amount of tags to filter actions.

<tag>Any_tagA</tag><tag>Any_tagB</tag></tags>

</instance-type>

Keyfields are column headers in the UI. Detail-view is the details view panel of theUI.

Note: If you want to import XML files related to version 2.4 toolkits, ensure thatyour XML has the version attribute set to 2.4 in the catalog tag, for example<catalog version="2.4"> .

The overall structure of the XML file is:<catalog><automation-categories>your categories here</automation-categories>

<offerings>your offerings here</offerings>

<instance-types>your instance types here</instance-types>

<instance-actions>your instance actions here</instance-actions></catalog>

To create the resources described in <yourfile>.xml in the IBM Cloud OrchestratorSelf Service catalog, run the following command:./catalogTool.sh <yourfile>.xml <ICO username> <ICO username password>

where

Chapter 8. Automating the creation of categories, offerings, and user actions 35

v <yourfile>.xml is your catalog file to create your catalog resourcesv <ICO username> ia a IBM Cloud Orchestrator administrative user namev <ICO username password> is the password for the user specified previously

Note: Being an administrative tool, the tool must not be run in concurrent mode.You cannot run an instance of the tool and catalog administration from the IBMCloud Orchestrator.

Note:

For XML files that correspond to SmartCloud Orchestrator version 2.3 toolkits, thenew catalog tool is still supported but only if you have Workload Deployerinstalled.

For user actions, specify the following parameters:<user-action>

<name>A test useraction</name><description>An optional description</description><process><name>Enter the name of the process you want to link to the useraction</name></process><user-interface><name>Enter the name of the user interface you want to link to the useraction</name></user-interface></user-action>

The description field is optional.

The overall structure of the XML file is:<catalog><automation-categories>your categories here</automation-categories>

<offerings>your offerings here</offerings>

<user-actions>your user actions here</user-actions></catalog>

What to do next

Note: The catalog version must NOT be set for version 2.3 XML files.

An additional step is required if the tool is installed as separate component fromIBM Cloud Orchestrator, for example, the tool is purchased and downloaded fromIBM Cloud Orchestrator Catalog and installed on a desktop. You must edit the toolconfiguration file, located at conf/env.properties, with the following content:IWD_HOST = <IP or HOSTNAME of Cloud Orchestrator>IWD_PROTOCOL = httpsIWD_PORT = 8443

IWD_PROTOCOL = https and IWD_PORT = 8443 are the default values that you mustuse.


https://www-304.ibm.com/software/brandcatalog/ismlibrary/cloudorchestratorcatalog

Exporting using the catalogTool.sh toolYou can export all offerings, categories, instance types, and instance actions toXML using the catalogTool.sh tool.

About this task

Use the following commands to export:

./catalogTool.sh --export <xmlfile> <ico-user> <ico-password>To export everything.

./catalogTool.sh --export <xmlfile> <ico-user> <ico-password>--includeCategories=<category_1>,<category_2>--includeInstanceTypes=<instanceType_1>,<instanceType_2>

Exports all the indicated categories and related offerings. Exports theinstance types and the related instance actions.

./catalogTool.sh --export <xmlfile> <ico-user> <ico-password>--excludeCategories=<category_1>,<category_2>--excludeInstanceTypes=<instanceType_1>,<instanceType_2>

Exports everything except the indicated categories and related offerings.Exports everything except the instance types and the related instanceactions.

--includeCategories and --includeInstanceTypes can be used either together oralone. The same applies to --excludeCategories and --excludeInstanceTypes.

Chapter 8. Automating the creation of categories, offerings, and user actions 37


Chapter 9. Publishing IBM Cloud Orchestrator content to IBMCloud Orchestrator Catalog

IBM Cloud Orchestrator Catalog is a platform and one-stop-shop for IBM CloudOrchestrator customers, partners, and IBM employees. The content that you createcan be submitted internally or externally from IBM in Integrated ServiceManagement Library (ISML) for Cloud/Virtualization category. The primary goalis to have an environment where developers, partners, and IBM Service teamsshare content with one another. This web-based application is envisaged tofederate content from several repositories into a single cloud automation contentcatalog.

About this task

To download content from the IBM Cloud Orchestrator Catalog, access the IBMIntegrated Service Management Library and search for a solution.

To upload content to the IBM Cloud Orchestrator Catalog, access the Ready forIBM Tivoli software site and follow the validation process.

For additional information about content development, see the Content DevelopersCorner wiki.


https://www-304.ibm.com/software/brandcatalog/ismlibrary/cloudmarketplace

https://www-304.ibm.com/software/brandcatalog/ismlibrary/cloudmarketplace

https://www-304.ibm.com/partnerworld/wps/servlet/ContentHandler/isv_com_dvm_techval_tivoli

https://www-304.ibm.com/partnerworld/wps/servlet/ContentHandler/isv_com_dvm_techval_tivoli

https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/W14a769bd540e_4b7c_aefa_cf851f2221a7/page/Content%20Developers%20Corner

https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/W14a769bd540e_4b7c_aefa_cf851f2221a7/page/Content%20Developers%20Corner


Appendix A. SCOrchestrator toolkit

The SCOrchestrator_Toolkit is delivered as a part of IBM Cloud Orchestrator. Itprovides the essential Business Process Manager building blocks, which are neededto build Business Process Manager business processes and human tasks, which areused as extensions for IBM Cloud Orchestrator.

If you want to write an extension for IBM Cloud Orchestrator, you must performthe following tasks:v Ensure that the toolkit was imported into Business Process Manager, which is

done by the IBM Cloud Orchestrator installer.v Declare a dependency from your process application or toolkit to this toolkit.

The following building blocks are included with the toolkit:

Table 16. Building blocks

Building block Section Function

Business object Data Interface between WorkloadDeployer and BusinessProcess Manager businessprocesses that are providedas business objects within thetoolkit. You can use them forparameter and private datadeclarations with BusinessProcess Manager.

General system services,integration services, and webservices

Implementation Define Business ProcessManager process extensions.They have a definedinterface (input and outputvariable definitions) that arebased on standard businessobjects that are provided byBusiness Process Managerand theSCOrchestrator_Toolkit.

Human services User Interface Sample UI extensions for aIBM Cloud Orchestratorextension. ABusiness ProcessManager coach, which isincluded in a human service,defines a UI panel.

Set of sample BusinessProcess Manager processes,human services, and otherBusiness Process Managerartifacts

Tagged asSCOrchestrator_Samples,contain the ‘Sample’ prefix intheir name.

Provide samples that showyou how to use the buildingblocks that are deliveredwith the toolkit. Required towrite operation extensionsfor IBM Cloud Orchestrator.Some samples are ready touse, other must be adapted.The documentation that isprovided with every sampleartifact includes informationabout how to use it.


ConfigurationThe SCOrchestrator_Toolkit has a few configuration options. If you use your ownprocess application or toolkit that has a dependency on theSCOrchestrator_Toolkit, adapt the configuration options to your environment asfollows:v iwdAuthAlias - authentication alias that is used for REST calls from a Business

Process Manager process to Workload Deployer. It must be configured in theJava™ Authentication and Authorization Service of the WebSphere® ApplicationServer in which the Business Process Manager runs.

v restEndpoint - URL for Workload Deployer REST calls.v cloudGroupRestUrl - a constant that defines the URL of a cloudGroup. Retain it

as is.v taskRestUrl - a constant defining the URL of the task engine. Retain it as is.

These configuration options are implemented by Business Process Managerenvironment variables, which can be configured by using the admin console ofBusiness Process Manager.

Business objectsThe business objects provide a natural representation of the business data forapplication processing. You can use the business objects included in theSCOrchestrator_Toolkit to create custom objects.

The following business objects are delivered as part of theSCOrchestrator_Toolkit:v OperationContextv ServiceInstancev MetaDatav VirtualMachinev NetworkInterfacev Rolev Servicev CloudGroupv Hypervisorv HypervisorFilterv Parameter

Further, you must define the business objects for other Workload Deployer RESTcalls, for example, to retrieve the user information from IBM Cloud Orchestrator.

Representation of long types in business objects

Long types are not supported by Business Process Manager. Therefore, the simpletype business object LongString is introduced as a part of theSCOrchestrator_Toolkit.

It represents a long type that is encoded as a string. For a new business object thatcontains a long type, define a new variable with the data type LongString. Ensurethat it has the same name as defined by the IBM Cloud Orchestrator object


variable. An example is the variable created (LongString) found in the CloudGroup.When serializing JSON Objects to BPM business objects, the long typed variablesare automatically mapped to the defined Business Object variables of typeLongString. When deserializing business objects to JSON objects, the typeLongString indicates the mapping to the origin data type Long.

OperationContextThe operation context is an umbrella object that contains all data that is related tothe execution of an operation. This operation context object must be defined as aninput parameter variable for all business processes that are started as an extensionfor a IBM Cloud Orchestrator operation. Human services must define the operationcontext ID as an input parameter and as a first activity, must retrieve the operationcontext object with its ID.

The structure is as shown in the table:

Table 17. OperationContext Structure

Attribute Data type Description

id String The unique operation contextidentifier.

Status String The status of the task that isassociated with the operationcontext.

eventTopic String The array that contains anobject for each role.

description String The description of the ID.

Params Map The map that contains(key/value) pairs for storingarbitrary parameters. It canbe used, for example, tohand over parameters thatare collected from UI coachesin an extension HumanService to the associatedBusiness Process.

serviceInstance ServiceInstance The service instance is theinstance umbrella object thatcontains managedvirtualMachines, roles,services, and instance levelmetadata.

user String The ID of the user in whosecontext the operation isexecuted

domain String The name of the domain inwhose context the operationis executed

project String The name of the project inwhose context the operationis executed

Appendix A. SCOrchestrator toolkit 43

Service InstanceThe service instance is an instance umbrella object that contains managed virtualmachines, roles, services, and instance level metadata.

It has the following structure:

Table 18. Service Instance Structure


metaData Object This object contains instancelevel information like theinstance name, uniqueidentifier, type, owner, andaccess information.

virtualMachines Array of Object This array contains an objectfor each managed virtualmachine.

roles Array of Object This array contains an objectfor each role.

services Array of Object This array contains an objectfor each service. A service isa managed entity that is nota virtual machine or a role.

MetaDataThis business object describes the meta data of a service instance like its name,type, status, and unique identifier.


Table 19. MetaData Structure

Attribute DataType Description

name String The human-readable name for thisinstance.

type String The internal (non-localized) type.

status String The internal (non-localized) status.

id String The URI to retrieve the most currentversion of this document.

virtualSystemId String The URI to retrieve the virtualsystem if one is associated.

virtualApplicationId String The URI to retrieve the virtualapplication instance if one isassociated.

virtualApplicationPatternId String The storehouse URI for the virtualapplication pattern if one isassociated.

virtualSystemPatternId String The URI for the system pattern usedto create if one is associated.


Table 19. MetaData Structure (continued)

Attribute DataType Description

creator String The ID of the user who initiated thedeployment of the instance. This idis a resource id like/resources/users/1 for virtualsystem pattern and single imagedeployments, and a storehouse idlike /storehouse/admin/users/u-0in other cases.

cloudGroup String (URI) The cloud group that the virtualapplication instance was deployedto. The field can be empty forvirtual system pattern deployments,or single image deployments.

parameters Map This map contains a (key/value)pair for each parameter. For moreinformation, see “Parameter” onpage 50.

VirtualMachineThe VirtualMachine business object describes a virtual machine as part of adeployment.


Table 20. VirtualMachine structure


name String An identifier for the virtualmachine. It does not matchthe primary host name of thevirtual machine. Theidentifier is unique within aservice instance.

cloudGroup String The URI of the availabilityzone where the virtualmachine is deployed.

networkInterfaces NetworkInterface (List) A list of network interfacesthat the virtual machine isequipped with.

hostname String The primary host name forthe virtual machine. If thereare multiple networkinterfaces, the primary hostname is implementation-dependent.

virtualCpu Integer The number of virtualprocessors, that is, thenumber of processors thatthe guest operating systemobserves on this virtualmachine.


Table 20. VirtualMachine structure (continued)


memory Integer The amount of memory thatis observed by the guestoperating system. The unit ofmeasurement is megabytes (1- 1048576).

disk Integer The size of the primary/rootdisk.

imageId String The image that is used tocreate this virtual machine.Note: The virtual machineand image lifecycle areseparated from one another,that is, the image can goaway before the virtualmachine. Do consider thispoint when you dereferencethis URI.

parameters Map This map contains a(key/value) pair for eachparameter. For moreinformation, see “Parameter”on page 50.

Id String A unique string identifier ofthe virtual machine that isrelative to the serviceinstance base URI.

NetworkInterfaceThe NetworkInterface business object describes a network interface of a virtualmachine.


Table 21. NetworkInterface Structure


ip String The IPv4 address in dotteddecimal notation or the IPv6address.

hostname String A host name that mustresolve to the specified IPthrough DNS.

ipgroup String The URI of the IP groupfrom which this address wasallocated.

type String The value must be 'IPv4' or'IPv6'.


RoleThe Role business object describes a role that a virtual machine can have in apattern.


Table 22. Role Structure


name String The name of the role.

type String The type of the role.

endpoints String (List) A list that contains an objectfor each endpoint. See theendpoint section moredetails.

Parameters Map A JSON object that containscustom parameters that wereprovided by extensionwriters.

id String The unique identifier of therole.

EndpointThe endpoints contain the URIs on how to access a specified role.


Table 23. Endpoint Structure


Name String A human-readable string thatidentifies this endpoint.

URI String The URI to which thisendpoint points.

ServiceThe Service business object describes a service.


Table 24. Service Structure


name String A human-readable string thatidentifies this service.

type String Either a Java-style packageidentifier or a TOSCA nodetype.

parameters Map This object contains customparameters that wereprovided by extensionwriters. For moreinformation, see “Parameter”on page 50.


Table 24. Service Structure (continued)


id String The ID of the service.

CloudGroupThe CloudGroup business object describes a IBM Cloud Orchestrator cloud group.


Table 25. CloudGroup Structure


address String The network address or hostname used to communicatewith the VMware VirtualCenter represented by acloud group.

certified String Indicates if the SSL certificatefrom this VMware VirtualCenter has been accepted.Use theCloud.acceptCertificate()method to accept acertificate.

created LongString Specifies the creation time ofthe cloud group, representedas the number ofmilliseconds since midnight,January 1, 1970 UTC. Thisvalue is numeric and isautomatically generated bythe product. This attribute isavailable for all cloudgroups.

currentstatus String The current status of theCloud object. This attributecontains an 8 character stringvalue that is generated bythe product.

currentstatus_text String This is a stringrepresentation ofcurrentstatus in the preferredlanguage of the requesterand is automaticallygenerated by the product.This attribute is read-only.

defaultcloud String Specifies if this cloud groupis the default cloud groupused by Cloud Orchestrator.User created cloud groupswill always have this valueset to 'F'. This field expects astring value of 'T' or 'F' witha maximum of 1 character.


Table 25. CloudGroup Structure (continued)


description String Specifies a description of thecloud group. This fieldexpects a string value with amaximum of 1024 characters.

hypervisors String Specifies a list of the uniformresource identifiers (URIs) ofthe hypervisors that areassigned to the cloud group.The URIs are relative andshould be resolved againstthe URI of the cloud groupthat contains them.

id Integer Specifies the Id of the cloudgroup. This numeric value isautomatically generated bythe product.

name String Specifies the name associatedwith this cloud group. Thisfield expects a string valuewith a maximum of 64characters. Each cloud groupmust have a unique name.

owner String Specifies the user that is theowner of this cloud.

password String Password used to access theVMware Virtual Center thatmanages the cloud group.

type String The type of this cloud group.For custom cloud groups thisvalue is none, for managedcloud groups this value ismanager. This value may bespecified when the cloudgroup is created, but cannotbe changed afterwards.

updated LongString Specifies the time the cloudgroup was last updated,represented as the number ofmilliseconds since midnight,January 1, 1970 UTC. Thisvalue is numeric and isautomatically generated bythe product.

userid String User id that is used to accessthe VMware Virtual Centerthat manages the cloudgroup.


Table 25. CloudGroup Structure (continued)


vendor String Specifies the type ofhypervisors this cloud groupwill contain. This fieldexpects a string value with amaximum of 128 characters.This string value mustalways be OpenStack.

ParameterThe Parameter object is a free-form JSON object that holds additional parametersrequired by the extension developers.

The JSON object has the following limitations:v There is no support for JSON arrays (JSON arrays will be converted to Strings).v All non-string simple types are converted to string while storing.

Extension developers can read and write to these objects to persist additional data,that the extension requires in the context of a service instance. They can retrievethe data later from a Business Process Manager process or other extension. Thisstorage is backed by the storehouse metadata APIs.


Table 26. Parameter Structure


jsonString String JSON representation ofparameters. This attributeaccepts any valid JSONstring.

HypervisorThe Hypervisor business object models a stand-alone hypervisor object in IBMCloud Orchestrator, but not a hypervisor that is managed by a virtual center, likethe VMware hypervisor.


Table 27. Hypervisor Structure


address String Specifies the host name or IPaddress (dotted decimalnotation) at which thehypervisor can be reached.This field expects a stringvalue with a maximum of1024 characters.


Table 27. Hypervisor Structure (continued)


certified String Specifies if the SSL certificatefrom this hypervisor hasbeen certified. IBM CloudOrchestrator does not deploypatterns to a hypervisor untilit has been certified. Notethat the SSL certificate fromthe hypervisor must beretrieved before thehypervisor can be certified.The following string valuesare valid:

v T Hypervisor has beencertified.

v F Hypervisor is notcertified.

v I Hypervisor is notcertified and resourceshave not been discovered.

cloud String Specifies the uniformresource identifier (URI) ofthe cloud group to whichthis hypervisor has beenassigned. The URI is relativeand should be resolvedagainst the URI of thehypervisor.

created LongString Specifies the creation time ofthe hypervisor, representedas the number ofmilliseconds since midnight,January 1, 1970 UTC. Thisvalue is numeric and isautomatically generated bythe product.

currentmessage String Specifies the messageassociated with the currentstatus of the hypervisor. Forexample, it could give moredetails about the problemthat caused the hypervisor tobe placed in an error state.This field contains an 8character string value that isgenerated by the product.

currentmessage_text String Specifies the textualrepresentation ofcurrentmessage. This is astring representation ofcurrentmessage in thepreferred language of therequester and isautomatically generated bythe product. This field has amaximum of 1024 characters.




currentstatus String Specifies a string constantrepresenting the currentstatus of the hypervisor. Thisfield is an 8 character stringvalue that is automaticallygenerated by the product.

currentstatus_text String Specifies a textualrepresentation ofcurrentstatus. This is a stringrepresentation ofcurrentstatus in the preferredlanguage of the requesterand is automaticallygenerated by the product.

desiredstatus String Specifies the desired status ofthe hypervisor. Setting thisvalue will cause IBM CloudOrchestrator to initiate thesteps that are needed to getthe hypervisor to this state.This value is an 8 characterstring and can only be set toone of the following values:

v RM01025 Maintenancemode

v RM01006 Started

desiredstatus_text String Specifies a textualrepresentation ofdesiredstatus. This is a stringrepresentation ofdesiredstatus in the preferredlanguage of the requesterand is automaticallygenerated by the product.

id String Specifies the id of thehypervisor. This attribute canbe a string or a number.When the attribute is astring, there are practicallimits on the string lengthdue to the way the string isgenerated: ("PM-" + numericid).

name String Specifies the display nameassociated with thishypervisor. This field expectsa string value with amaximum of 64 charactersand must be unique amongall hypervisors defined toIBM Cloud Orchestrator.




networks String (List) Specifies the list of URIs ofthe networks associated withthis hypervisor. The URIs arerelative and they must beresolved against the URI ofthe hypervisor that containsthem. This list of networks isautomatically generated aspart of the discovery processand cannot be changed.

password String Specifies the password usedto log on to the hypervisor.This field expects a stringvalue with a maximum of128 characters.

storage String (List) Specifies the list of URIs ofthe storage associated withthis hypervisor. The URIs arerelative and they must beresolved against the URI ofthe hypervisor that containsthem. This list of storage isautomatically generated aspart of the discovery processand cannot be changed.

type String Specifies the type of thishypervisor. This value mustbe set to OpenStack. Thisfield expects a string valuewith a maximum of 128characters.

updated LongString Specifies the time thehypervisor was last updated,represented as the number ofmilliseconds since midnight,January 1, 1970 UTC. Thisvalue is numeric and isautomatically generated bythe product.

userid String Specifies the user ID used tolog on to the hypervisor. Thisfield expects a string valuewith a maximum of 128characters.

UUID String The universally uniqueidentifier for the hypervisor.For hypervisors that do nothave a UUID, this value willbe "none".


HypervisorFilterThe HypervisorFilter business object describes a filter object for a hypervisor.

The filter is used for REST calls from Business Process Manager to WorkloadDeployer. All fields are filtered out of the JSON string before they are sent toWorkload Deployer because the database does not have these fields. The GETmethod retrieves a hypervisor object from Workload Deployer through a REST call.It returns some additional fields that are not a part of the database representationfor a hypervisor object. If a subsequent post or put is done for a hypervisor object,these fields must be filtered out. Otherwise, it leads to errors in the REST call.

Table 28. HypervisorFilter Structure


currentstatus_text String Specifies a textualrepresentation ofcurrentstatus. This is a stringrepresentation ofcurrentstatus in the preferredlanguage of the requesterand is automaticallygenerated by the product.

desiredstatus_text String Specifies a textualrepresentation ofdesiredstatus. This is a stringrepresentation ofdesiredstatus in the preferredlanguage of the requesterand is automaticallygenerated by the product.

currentmessage_text String Specifies the textualrepresentation ofcurrentmessage. This is astring representation ofcurrentmessage in thepreferred language of therequester and isautomatically generated bythe product. This field has amaximum of 1024 characters.

cloud String Specifies the uniformresource identifier (URI) ofthe cloud group to whichthis hypervisor has beenassigned. The URI is relativeand should be resolvedagainst the URI of thehypervisor.

networks String (List) Specifies the list of URIs ofthe networks associated withthis hypervisor. The URIs arerelative and they must beresolved against the URI ofthe hypervisor that containsthem. This list of networks isautomatically generated aspart of the discovery processand cannot be changed.


Table 28. HypervisorFilter Structure (continued)


storage String (List) Specifies the list of URIs ofthe storage associated withthis hypervisor. The URIs arerelative and they must beresolved against the URI ofthe hypervisor that containsthem. This list of storage isautomatically generated aspart of the discovery processand cannot be changed.

uuid String The universally uniqueidentifier for the hypervisor.For hypervisors that do nothave a UUID, this value willbe "none".

ServicesTo simplify parameter handling, most of the REST calls to Workload Deployerhave a JSON object that is coded as a string in the input and output parameters.The activities of Business Process Manager Business Processes and Services operateon complex business objects. Therefore, building blocks are needed to convert abusiness object to a JSON string and vice versa.

The different types of services are General System Services, Integration Services,and web services.v The General System Services used are as follows:

– CreateBusinessObject_OperationContext

– GetVirtualMachineForRole

v The integration services used are as follows:– CreateBusinessObject_CloudGroup

– CreateBusinessObject_ServiceInstance

– DecodeAlias

– GenericRestCall

– GetCloudGroup

– GetOperationContext

– Post_ServiceInstance_MetaData_Parameter

– ReadBusinessObject

– WriteValuesToBO

– SetOperationContextParameters

– GenericBPDInvocation

v The web service that is used is GenericBPDInvocationWS.


General system servicesThe general system services of the Business Process Manager are defined alongwith their input and output variables.

CreateBusinessObject_OperationContext

The CreateBusinessObject_OperationContext service creates a business object oftype OperationContext based on a JSON input string.

Table 29. CreateBusinessObject_OperationContext Input Variables

Input Variable Data type Description

operationContextString String JSON string that representsthe operationContext

Table 30. CreateBusinessObject_OperationContext Output Variables

Output Variable Data type Description

operationContext OperationContext It is a OperationContextbusiness object

GetVirtualMachineForRole

The service retrieves all virtual machines from the service instance.

Table 31. GetVirtualMachineForRole Input Variable


roleName String Name of the role

serviceInstance ServiceInstance Service instance

Table 32. GetVirtualMachineForRole Output Variable


virtualMachine VirtualMachine (List) List of virtual machines

GetInputParameter

The GetInputParameter general system service retrieves the inputParameterObjectof Business Process Manager business process. The inputParameterObject is usedas a workflow extension for IBM Cloud Orchestrator. It must be the first activity ineach business process to be used as workflow extension for IBM CloudOrchestrator.

Table 33. GetInputParameter Input Variable


operationContext OperationContext The operation context object.


Table 33. GetInputParameter Input Variable (continued)


inputParameterObject_In ANY The inputParameterObject ofthe process must be mappedto this variable. It is requiredto enable a process to becalled as linked process byanother process. In this case,the inputParameterObject_Inis not null. In all other cases,the inputParameterObject isnull, which indicates that theprocess is called directlyfrom the Cloud OrchestratorUI.

Table 34. GetInputParameter Output Variable


inputParameterObject ANY The inputParameterObjectcontains the inputparameters for the businessprocess as collected by theassociated human service.

GetErrorMessage

The GetErrorMessage general system service receives as input an error XMLelement, which is returned by the variable tw.system.step.error. It extracts andreturns the error message and stack trace from the XML element as outputvariables.

Table 35. GetErrorMessage Input Variable


error XMLElement The XMLElement variablecontaining the errorexception information asreturned bytw.system.step.error variable.

Table 36. GetErrorMessage Output Variable


errorMessage String The error message extractedfrom the XMLElement inputvariable.

stackTrace String The stack trace extractedfrom the XMLElement inputvariable.


Integration servicesYou define the integration services of the Business Process Manager together withtheir input and output variables.

CreateBusinessObject_CloudGroup

The CreateBusinessObject_CloudGroup service creates a business object of typeCloudGroup that is based on a JSON input string.

Table 37. CreateBusinessObject_CloudGroup input variable


jsonString String JSON string that representsthe cloudGroup

Table 38. CreateBusinessObject_CloudGroup Output Variable


cloudGroup CloudGroup Cloud group

CreateBusinessObject_ServiceInstance

The CreateBusinessObject_ServiceInstance service creates a business object oftype ServiceInstance that is based on a JSON input string.

Table 39. CreateBusinessObject_ServiceInstance input variable


jsonString String JSON string that representsthe service instance

Table 40. CreateBusinessObject_ServiceInstance Output Variable


serviceInstance ServiceInstance Service Instance BusinessObject

DecodeAlias

The DecodeAlias service decodes the Workload Deployer Authentication Alias toretrieve a user ID and a password for the communication with Workload Deployer.A REST call requires caller authentication at Workload Deployer, so a plainpassword and user name are attached to a REST call for basic authentication.

Business Process Manager Standard Edition does not offer password encryption. Itis possible to implement encryption facilities and integrate, for example, asJavaScript or Java Integration Service. By default, WebSphere XOR encoding isapplied. If you want to use the WebSphere XOR encoding style, you need a JAASalias that is configured in the WebSphere Application Server console. For moreinformation about WebSphere XOR encoding style, see WebSphere documentation.For password decryption in Business Process Manager, you must know the JAASalias, which is set as an environment variable in the SCOrchestrator_Toolki toolkit(iwdAuthAlias).


Table 41. DecodeAlias input variable


iwdAuthAlias String WebSphere authenticationalias

Table 42. DecodeAlias output variable


iwdUser String Workload Deployer user ID

iwdPassword String Workload Deployerpassword

GenericRestCall

The GenericRestCall service is based on a Java implementation for a generic RESTCall on Workload Deployer.

By default, it extracts the authentication information from the security context. Theauthentication information uses it to construct the security authentication token(SimpleToken) for the REST calls that are made to external systems. As tw_admin isan internal user, GenericRESTCall translates tw_admin to a default admin user forexternal calls. For more information about business process security, see “BusinessProcess Manager security” on page 20. The GenericRESTCall also accepts a username on behalf of which a REST call must be made. It is especially useful forREST calls in the System Lane of a Business Process. They run by default as anadmin user. It is desirable to run these REST calls on behalf of the person whosubmitted the request. To do that, map the user and project variables from theoperation context to the GenericRESTCall

Table 43. GenericRestCall input variables


restMethod String The methods, such as POST,PUT, GET, and DELETE

jsonString String The input for PUT or POSTencoded as a JSON string

restUrl String The REST URL that followsthe host name (afterhttp://<hostname>. Forexample, /resources/clouds.

iwdUser String The user name on behalf ofwhich the REST call must bemade. If not specified, thefollowing users areconsidered:

v If it is run in the context ofBusiness Process Manageruser interface, the loggedin user is used.

v In case it is for activitiesthat run in the SystemLane of a business process,admin user is used.


Table 43. GenericRestCall input variables (continued)


domain String The domain name for theREST call context. If notspecified, the default domainis used

project String The project name for theREST call context. If notspecified, the user defaultproject is used

iwdApiVersion String The version of the WorkloadDeployer API. If notspecified, version 3.1 is used.

Table 44. GenericRestCall output variable


returnFromRest String Result of a REST call that isencoded as a JSON string

GetCloudGroup

The service issues a REST Call on Workload Deployer to retrieve a cloudGroup. Ituses the GenericRestCall integration service to run the REST Call, and theCreateBusinessObject_CloudGroup service to convert the JSON encoded string thatis returned into a CloudGroup Business Object.

Table 45. GetCloudGroup input variable


cloudGroupId String ID of the cloudGroup to beretrieved







Table 45. GetCloudGroup input variable (continued)



Table 46. GetCloudGroup output variables


cloudGroup CloudGroup CloudGroup business object

GetCredentialsOfVirtualMachine

The GetCredentialsOfVirtualMachine integration service is used to retrieve thecredentials of a virtual machine from IBM Cloud Orchestrator. The credentialsinclude user and password. In addition, it includes the private and public RSAkeys. The credentials can be used to access the operating system of the virtualmachine through ssh (Linux) or RXA (Microsoft Windows). For Linux basedoperating systems, the private and public RSA keys support key-basedauthentication. The public key is stored on the virtual machine and is alreadyconfigured as the authorized key of the ssh service in the operating system. Theprivate key can be used to access the root account of the operating system in thevirtual machine without using the password. The input of the integration serviceare the identifiers of the virtual system and the virtual machine. The output of theintegration service is strings representing the user name, password, and the privateand public RSA keys.

Table 47. GetCredentialsOfVirtualMachine input variables


virtualSystemId String Id of the virtual system

virtualMachineId String Id of the virtual machine







Table 47. GetCredentialsOfVirtualMachine input variables (continued)



Table 48. GetCredentialsOfVirtualMachine output variable


username String Name of the user

password String Password of the user

privateKey String Private key

publicKey String Public key

GetOperationContext

The service issues a REST call on Workload Deployer to retrieve the operationcontext. It uses the GenericRestCall Integration Service to run the REST call, andthe CreateBusinessObject_OperationContext Service to convert the JSON encodedstring that is returned into a OperationContext Business Object.

Table 49. GetOperationContext input variables


operationContextId String Id of the operationContext tobe retrieved








Table 50. GetOperationContext output variable


operationContext OperationContext OperationContext BusinessObject

GetServiceInstance

The GetServiceInstance integration service issues a REST Call on WorkloadDeployer to retrieve the service instance. It uses the GenericRestCall integrationservice to run the REST Call and the CreateBusinessObject_ServiceInstanceservice to convert the JSON encoded string that is returned into a ServiceInstanceObject.

Table 51. GetServiceInstance input variables


serviceInstanceId String Id of the serviceInstance tobe retrieved

Table 52. GetServiceInstance output variable


serviceInstance ServiceInstance The ServiceInstance object.

Post_ServiceInstance_MetaData_Parameter

The service issues a REST call on Workload Deployer to store a parameter in theparameter map of the serviceInstance > metadata section. It uses theGenericRestCall Integration Service to run the REST call.

Table 53. Post_ServiceInstance_MetaData_Parameter input variables


serviceInstance ServiceInstance The serviceInstance forwhich a parameter is to bestored in the metadata

key String The parameter key

value String The parameter value





Table 53. Post_ServiceInstance_MetaData_Parameter input variables (continued)





PostMessage

The PostMessage integration service issues a REST call on the Workload Deployer.It posts a message to the history section of the virtual system instance in the userinterface of IBM Cloud Orchestrator.

Note: The virtual system ID is not available for service operations, so thisoperation must not be used for self-service offerings.If globalization is needed, a localized message is passed as an input parameter. Ituses the GenericRestCall integration service to run the REST call.

Table 54. PostMessage input variable


message String serviceInstance for which aparameter is to be stored inthe metaData

operationContext OperationContext Operation context businessobject

mapUserDomainProjectFromOperationContextBoolean Determines whether the user,domain, and projectparamenters ofoperationContext are usedfor the REST call (forinformation about theseparameters, see“GenericRestCall” on page59). If not specified, false isused and the default valuesfor user, domain, and projectapply.


ReadBusinessObject

The service converts a business object into a JSON string so that it can be used. Forexample, as parameter for a REST call. It is a generic method that gets ANYbusiness object as input parameter.


Restriction: The business object that is specified as input parameter must not havea parameter of type Map.

Table 55. ReadBusinessObject input variable


BusinessObject ANY The business object to beconverted into JSON string

Table 56. ReadBusinessObject Output Variable


jsonString String Hypervisor Business Objectthat is converted into a JSONstring.

ReturnParameters

The ReturnParameters integration service is used to return parameters that arecollected by a human service. The collected parameters are used as inputparameters for the associated process. It must be the last activity of a humanservice that collects parameters for a business process, which is used as a workflowextension for IBM Cloud Orchestrator.

Note: The outParameterObject business object must be of the same business objecttype as the inputParameterObject of the associated process. The type is used byIBM Cloud Orchestrator to correlate a human service with its associated businessprocess.

Table 57. ReturnParameters input variable


operationContextId String Id of the operation context

outParameterObject ANY A business object thatcontains the parameters thatare collected by the humanservice. They are used asinput parameters for theassociated business process.

Table 58. ReturnParameters output variable


returnString String Result of REST call that isencoded as JSON String.

SetOperationContextParameters

The SetOperationContextParameters integration service helps to enable theworkflow of IBM Cloud Orchestrator extension to access and use parameters thatare collected by a human service. It stores the input parameter map as key/valuepairs into the parameter section of the operation context for the specifiedoperationContextId. This parameter is later given as input parameter to theBusiness Process Manager Business Process extension. The parameter 'startTask'specifies whether the Business Process Manager workflow must be triggered by theexecution of this integration service (true) or not (false). If false is selected, several


consecutive calls can be made by a human service extension to store theparameters that are collected into the operationContext of the task. This activity isdone before the Business Process Manager workflow process starts.

Note: This integration service is used internally to implement theReturnParameters integration service. Normally, it must not be used directly by thehuman service that is associated with a workflow extension. Instead, the higherlevel integration service ReturnParameters must be used.

Table 59. SetOperationContextParameters input variable


operationContextId String Id of the operation context

params Map Map of parameters to begiven as input parameter forthe associated businessprocess.

startTask Boolean True if the associatedbusiness process must bestarted (default false)

Table 60. SetOperationContextParameters output variable


returnString String Result of REST call that isencoded as JSON String.

WriteValuesToBO

The service gets a JSON string representation of a business object as input variableand generates the corresponding TWObject Business Object.

Restriction: Using 'ANY' for the type of the output variable business object leadsto an error in Business Process Manager. The business object type of the outputvariable (for example, Hypervisor) must be specified explicitly. Therefore, if youare using a Business Object other than 'Hypervisor', the integration service must becopied from the toolkit to your Business Process Application. You must adapt thetype of business object to the special context.

Table 61. WriteValuesToBO input variable


BusinessObject ANY The business object to beconverted into JSON string

Table 62. WriteValuesToBO output variable


jsonString String The business object that isconverted into a JSON string.

GenericBPDInvocation

The GenericBPDInvocation service is used internally by IBM Cloud Orchestrator todo some housekeeping actions, such as mapping parameters that are encoded as


JSON strings to business objects. Finally, it calls the customer extension BusinessProcess.

Cloud management servicesIBM Cloud Orchestrator offers cloud management services, for example, backupservices or server restart.

Approval

The cloud management services require approvals. The approval is implementedby the human service and coach of the Business Process Manager technology. It isa building block of the SCOrchestrator_Toolkit.

Table 63. Approval Input Variable


requester String Approval requester

parameters NameValuePair (List) List of parameters forapprovals. The list ofparameters in the form ofname-value pairs that areshown as extra informationin the approval UI panel.

Table 64. Approval Output Variable


reason String Reason for approval or rejectas specified in UI approvalpanel.

isApproved Boolean Approved (true) or not(false)

Instead of Business Process Manager Coach UI technology, the Cloud OrchestratorUI implements the approval panels. These approval panels show only the datafrom the Business Process Manager ‘Approval’ human service. You can usepredefined approval building blocks to build your own approval Business Processto display information that the approver needs to make a decision. The sampleBusiness Processes that are delivered as part of the toolkit, such asSample_DeployInstanceApproval and SampleDeleteInstanceApproval can be copiedand then customized to your needs. This customized approval Business Processcan then be enabled by registering it in the Orchestrator Actions .Related information:

http://www.ibm.com/support/knowledgecenter/SSFTDH_8.5.0/com.ibm.wbpm.main.doc/ic-homepage-bpm.htmlv IBM Business Process Manager documentation

http://www.neilkolban.com/IBM/Kolban’s Book on IBM Business Process Management available as download

http://www.scribd.com/doc/92505753/IBM-Impact-2011-Five-Guidelines-to-Better-Process-Modeling-for-Execution-Stuart-and-ZahnIBM Impact 2011 - Five Guidelines to Better Process Modeling for Execution -Stuart and Zahn


http://www.ibm.com/support/knowledgecenter/SSFTDH_8.5.0/com.ibm.wbpm.main.doc/ic-homepage-bpm.html

http://www.ibm.com/support/knowledgecenter/SSFTDH_8.5.0/com.ibm.wbpm.main.doc/ic-homepage-bpm.html

http://www.neilkolban.com/IBM/



http://www.ibm.com/developerworks/websphere/library/techarticles/1105_ragava/1105_ragava.htmlDeveloper Works: WebSphere Lombardi exception handling and logging -Gopalakrishnan Ragava and Sateesh Balakrishnan

SamplesA number of samples are delivered as part of the SCOrchestrator_Toolkit. Youmust adapt the samples to your needs before they are run. You can find the actualsamples documentation by opening the Business Process Manager process center(http:<central-server-2 IP>:9080/ProcessCenter/login.jsp) and selecting theSCOrchestrator_Toolkit.

Note: Refer to the Business Process Manager documentation to know how toconfigure group membership and swim lane participation to achieve the requiredrights for the user you want to grant access to for requests like approval orproblem handling.

Sample_AssignProblem

This sample process assigns the problem reported with sample process’Sample_ReportProblem’ to a user of participant group ’Problem Administrator’.Make sure that there are users defined for participant group ’ProblemAdministrator’.

Sample_DeleteInstanceApproval

This sample process includes an approval. It can be embedded in a IBM CloudOrchestrator deletion workflow. The intention is to approve the deletion process.Make sure to also adapt the participant to the group which should have theapproval right.

Sample_DeployInstanceApproval

This sample process includes an approval. It can be embedded in the IBM CloudOrchestrator deploy instance workflow. The intention is to approve the deployinstance process. Make sure to also adapt the participant to the group whichshould have the approval right.

Sample_Post_ServiceInstance_Data

This sample process is to post ServiceInstance data, in this case parameters forService Instance MetaData. The sample process first retrieves the ServiceInstancedata as JSON String, creates a ServiceInstance Business Object and finally postsa parameter to the Service Instance MetaData.

Note: To run the process, the default value for the ServiceInstance ID has to beupdated with a valid ServiceInstance ID.

Sample_Process

This sample process shows the input string collected with the human service’Sample_UserInterface’ to a user of participant group ’Problem Administrator’.Make sure that there are users defined for participant group ’ProblemAdministrator’.




Sample_Process_ShowVars

This is a sample process that shows the input string collected with the humanservice ’Sample_UserInterface’ to a user of participant group ’ProblemAdministrator’. Make sure that there are users defined for participant group’Problem Administrator’.

Sample_Process_wo_HumanService

This sample extension is a process without human service. It displays theoperation context business object in XML representation.

Sample_TestMultiTenancy

This sample is a simple test for REST calls within a process:1. Using the default admin user context.2. Using the caller's identity and domain/project scope that are stored in the

operationContext.

Template_BusinessProcess

This sample template helps to create a Business Process Manager Business Processthat can be used either as orchestrator action (event triggered action or user action)or as self-service offering within IBM Cloud Orchestrator. You can start developingyour own business process extension by copying this template and enhancing itwith your implementation logic.

Note: The variable type of the input parameter inputParameterObject has to bechanged from ’ANY’ to the concrete Business Object data type to be used. Do notforget to expose the process (Expose to start) to make it visible in theConfiguration panel of IBM Cloud Orchestrator.



Appendix B. Scripting utilities toolkit

The SCOrchestrator_Scripting_Utilities_Toolkit is delivered as a part of theIBM Cloud Orchestrator product. It provides the essential building blocks of theBusiness Process Manager. These building blocks are required to build BusinessProcess Manager Business Processes and human tasks, which are used asextensions for IBM Cloud Orchestrator.

When you work with remote devices, such as remote virtual machines and storagehosts, copy and run scripts/batch files on remote servers are frequently neededtasks. The Cloud Orchestrator Scripting Utilities Toolkit provides implementationservices that you can drag and drop during IBM Cloud Orchestrator BusinessProcess Manager process creation. These services can be used to copy files to aremote system or execute command lines on remote systems, including uploadedscripts/batch files.

Note: This toolkit is not designed to work with systems configured with restrictedshell access, for example rbash.

File upload restrictionsYou can only upload files that reside within a local file repository such as a localfolder or locally mounted folder.

It is defined by the toolkit environment variable localRepositoryBasePath. Bydefault, this variable is defined as /var/ibm/sco/scriptRepo.

For security reasons, the processes of the toolkit check whether the files to beuploaded are always within the repository base folder.

Business objectsThese business objects are delivered as part of theSCOrchestrator_Scripting_Utilities_Toolkit.

Some of the business objects are partly reused within other business objects.v VirtualServerKeyv RemoteMachineCredentialsv UploadFileDatav ExecuteCommandDatav OutputMapValuesv VirtualServerExecuteData

– VirtualServerKey– ExecuteCommandData

v VirtualServerUploadAndExecuteData– VirtualServerKey– UploadFileData– ExecuteCommandData

v VirtualServerUploadData


– UploadFileData– ExecuteCommandData

v VirtualSystem – Used internally only to hold the JSON data of this objectv VirtualServer – Used internally only to hold the JSON data of this object

VirtualServerKey

This is a key object to uniquely identify a virtual server.

Table 65. VirtualServerKey

Parameters Data type Description Sample data

virtualSystemId String ID - Field of thevirtual system, thatcontains the virtualserver that must bereferenced.

"1“... n

virtualServerId String ID - Field of thevirtual server(machine) that mustbe referenced.

"1“ ... n

RemoteMachineCredentials

Remote machine access data.

Table 66. RemoteMachineCredentials


remoteMachine String Remote machineIP-address or hostname.

"9.152.138.179“

remoteUser String Username to accessthe remote machinevia the protocol ofthe used process

"admin"

remotePassword String Password for theuser and protocol

"myPassword“

privateKey String Currently not usedby the sample.(Fetched by loadingvia virtualServerKey)

publicKey String Currently not usedby the sample.(Fetched by loadingvia virtualServerKey)

UploadFileData

Data to define a file upload task from local file repository. See “File uploadrestrictions” on page 71.


Table 67. UploadFileData


repositorySubFolder String Subfolder within thelocal repository - orempty string.

"SubFolder“

fileName String Source anddestination file nameof the file to beuploaded.

"HelloWorld.sh“

destinationDirectory String Destination directoryfor the uploaded file.If the folder does notexist, it is created.

"/tmp/folder“

makeExecutable Boolean Make the uploadedfile on the destinationmachine executablefor current user. InWindows operatingsystems this flag isignored. It is onlyavailable forcompatibility reasons.

True/False

ExecuteCommandData

Data to define a command line execution task.

Table 68. ExecuteCommandData


commandLine String Command to beexecuted on theremote machine. Thismight also be a shellor batch script.

"ls -l“

workingDirectory String The processes changethe current directoryto the given workingdirectory, before thecommand isexecuted.

"/tmp/test“

OutputMapValues

Data object that holds well-defined return parameters of a called process.

Table 69. OutputMapValues


errCode String Empty string if noerror occurred byprocessing theimplementationservice. Otherwise anerror code isreturned.

"CTJCA1699E“

Appendix B. Scripting utilities toolkit 73

Table 69. OutputMapValues (continued)


errMsg String Empty string if noerror occurred byprocessing theimplementationservice. Otherwise anerror message isreturned.

"Details about theproblem“

retCode String Contains the returncode of the calledcommand.

"0“

stdOut String Contains thestandard output ofthe called command.

">script called“

stdErr String Contains thestandard error outputof the calledcommand.

"file is notexecutable“

VirtualServerExecuteData

Data object that contains all required information to execute a command against avirtual system instance.

Table 70. VirtualServerExecuteData


virtualServerKey VirtualServerKey Identifies thedestination machine.

See referenced dataobject for details.

executeCmdLineData ExecuteCommandData Defines data for thecommand to beexecuted.


VirtualServerUploadAndExecuteData

Data object that contains all required information to upload a file and execute acommand against a virtual system instance.

Table 71. VirtualServerUploadAndExecuteData




uploadFileData UploadFileData Defines the data forthe upload task.


executeCmdLineData ExecuteCommandData Defines data for thecommand to beexecuted.


VirtualServerUploadData

Data object that contains all required information to upload a file to a virtualsystem instance.


Table 72. VirtualServerUploadData




uploadFileData UploadFileData Defines the data forthe upload task.


Implementation servicesThe toolkit contains a number of implementation services.

Implementation services are described in separate topics. The followingimplementation services are used only internally and are not described in detail:v Decrypt_Textv Encrypt_Textv GetVirtualMachinesv GetVirtualSystemInstancesv GetIPsOfVirtualMachine

For more information about the services, see the documentation inside the toolkitor service itself.

The implementation services of the toolkit are as follows:

SSH_UploadFile

This integration or implementation service uploads a file to a remote machine viaSSH protocol.

Table 73. SSH_UploadFile

Input parameters Data type Expected value Sample data

remoteMachine String Remote machine IPaddress or host name

"9.120.xxx.xxx"

userName String Login user name forthe above protocol

"root"

password String Login password.Optional. SeeTable 74 on page 76.

"**********"

PrivateKey String RSA-Key. Optional.See Table 74 on page76.

"RSA-Key"

fileName String Name of the file tobe uploaded from thelocal file repository

"HelloWorld.sh"

destinationPath String Full destination pathin the format of theremote machine

"/tmp/destination"


Table 73. SSH_UploadFile (continued)


localRepositorySubDir String Subdirectory orNULL/Empty string.See “File uploadrestrictions” on page71.

"/SubFolder/"

makeFileExecutable Boolean Make file executablefor"Implementation-Service“ user(ignored on Windowsoperating systems)

"True"

Table 74. Optional parameters

Optional parameters

Password="value" / PrivateKey=ignored For the connection to the remote machine, thecredentials "user" and "password" are used.

Password=empty / PrivateKey=empty If the private key of the BPM machine is insertedinto the trusted list of keys within the remote machine, it is also possible to connect on thistrusted relationship. In this case the password field must be left empty to identify thisconnection mode.

Password=empty / PrivateKey="value" If another trusted private key should be used toenable the connection, than it can be passed as a parameter. For this mode the passwordmust be left empty.

Table 75. General output parameter map for most of the implementation services

Output parameters Data type Expected value Sample data

OutputMap Map(Key-,Value-String)

Results of the specificimplementationservice

See individualsamples

Table 76. Possible keys and their values

Key string or key value Expected value Value string or sample data

errCode Error code, if error occurred "CTJCA1699E"

errMsg Error details, if error code isset

"Source file not available"

RC * Return code of the calledcommand line

"0"

stdOut * Standard output of a calledcommand line

">Hello world"

stdErr * Standard error output of acalled command line

"file/command not found"

* These keys are only available for services with command line.

SSH_ExecuteCommand

This integration or implementation service executes a command line on a remotemachine via SSH protocol.


Table 77. SSH_ExecuteCommand



"9.120.xxx.xxx"


"root"


"**********"


"RSA-Key"

commandLine String Command line orscript file, that mustbe executed on theremote machine

"ls -l"

cmdLineWorkingDirectoryString Full path in theformat of the remotemachine

"/tmp/destination"

For the output parameters, see Table 75 on page 76.

SSH_UploadFileAndExecuteCommand

This integration or implementation service:v Uploads a file to a remote machinev Executes a command line on a remote machinev Via SSH protocol

Table 78. SSH_UploadFileAndExecuteCommand



"9.120.xxx.xxx"


"root"


"**********"


"RSA-Key"


"HelloWorld.sh"

destinationPath String Full destination pathin the format of theremote machine.

"/tmp/destination"


"/SubFolder/"


Table 78. SSH_UploadFileAndExecuteCommand (continued)


makeFileExecutable Boolean Make file executablefor"Implementation-Service“ user.Ignored on Windowsoperating systems

"True"

commandLine String Command line orscript file that mustbe executed on theremote machine.

"ls -l"

cmdLineWorkingDirectoryString Full path in theformat of the remotemachine.

"/tmp/destination"


Windows_UploadFile

This integration or implementation service:v Uploads a file to a remote machinev via RXA toolkit/protocol

Table 79. Windows_UploadFile



"9.120.xxx.xxx"


"Administrator"

password String Login password "**********"

fileName String Name of the file tobe uploaded from thelocal repository.

"HelloWorld.bat"


"c:\tmp\destination\"

localRepositorySubDir String Subdirectory ornull/empty string.See “File uploadrestrictions” on page71.

"\SubFolder\"


Windows_ExecuteCommand

This integration or implementation service executes a command line on a remotemachine via RXA toolkit/protocol.

Table 80. Windows_ExecuteCommand



"9.120.xxx.xxx"


Table 80. Windows_ExecuteCommand (continued)



"Administrator"


commandLine String Command line orscript file that mustbe executed on theremote machine.

"dir"




Windows_UploadFileAndExecuteCommand

This integration or implementation service:v Uploads a file to a remote machinev Executes a command line on a remote machinev Via RXA toolkit/protocol

Table 81. Windows_UploadFileAndExecuteCommand



"9.120.xxx.xxx"


"Administrator"



"HelloWorld.bat"




"\SubFolder\"

makeFileExecutable Boolean Make file executablefor"Implementation-Service“ user.Ignored on Windowsoperating systems

"True"

commandLine String Command line orscript file that mustbe executed on theremote machine

"dir"


"c:\tmp\destination"



ExtractOutputMap

This integration or implementation service extracts the OutputMap values(Key-Value-Pairs) to concrete fields of a OutputMapValues object.

Table 82. ExtractOutputMap


OutputMap Map of strings See Table 75 on page76.

retValues OutputMapValues ErrCode

errMsg

retCode

stdOut

stdErr

See the samples inTable 76 on page 76.


GetRemoteMachineDataFromVirtualMachineKey

This integration or implementation service:v Evaluates the remote machine data, for example IP, user, password, and so onv Via its virtualSystem Key - virtualSystemID and virtualServerID

Table 83. GetRemoteMachineDataFromVirtualMachineKey


virtualServerKey VirtualServerKey virtualSystemID

virtualServerID

virtualSystemID=“12"

virtualServerID=“13"

The rest of the inputparameters are forinternal purposeonly.

Table 84. GetRemoteMachineDataFromVirtualMachineKey output parameters

Output parameters Data type Expected value

RemoteMachineData RemoteMachineCredentials remoteMachine

remoteUser

remotePassword

privateKey

publicKey


Sample processesThe SCOrchestrator_Scripting_Utilities_Toolkit contains sample processes,which are based on tasks, targeted against a single virtual server machine.

For output data for all of the samples, see General Output Parameters (parametermap) in “Business objects” on page 71.

For input data for the sample, see the business object references in the list below.

PROC_Sample_VirtualServer_SSH_UploadFile

For input data, see VirtualServerUploadData

PROC_Sample_VirtualServer_SSH_ExecuteCmd

For input data, see VirtualServerExecuteData

PROC_Sample_VirtualServer_SSH_UploadFileAndExecuteCmd

For input data, see VirtualServerUploadAndExecuteData

PROC_Sample_VirtualServer_Windows_UploadFile

For input data, see VirtualServerUploadData

PROC_Sample_VirtualServer_Windows_ExecuteCmd

For input data, see VirtualServerExecuteData

PROC_Sample_VirtualServer_Windows_UploadFileAndExecuteCmd

For input data, see VirtualServerUploadAndExecuteData

Sample UIsThe SCOrchestrator_Scripting_Utilities_Toolkit contains sample UIs, whichreflect the needs of the corresponding sample processes.

The sample processes and their matching sample UIs are related by theircorresponding business object.

The type of output parameter of the sample UI must match the type of inputparameter of the sample process.

The sample UIs are:

UI_Sample_SingleVirtualMachine_UploadFileFor output data, see the business object VirtualServerUploadData.

UI_Sample_SingleVirtualMachine_ExecuteCmdFor output data, see the business object VirtualServerExecuteData.

UI_Sample_SingleVirtualMachine_UploadFileAndExecuteCmdFor output data, see the business object VirtualServerUploadAndExecuteData.

The UI parts, used within the above sample UIs are:v UI_Sample_GET_SingleVirtualMachinev UI_Sample_GET_ExecuteCommandDatav UI_Sample_GET_UploadFileData


Deprecated implementation servicesThese integration or implementation services are deprecated and are notdocumented.v LinuxCopyFiletoRemoteMachinev LinuxCopyFiletoRemoteMachineusingKeyv LinuxExecuteRemoteScriptv LinuxExecuteRemoteScriptusingKeyv LinuxExecuteRemoteScriptwithArgsv LinuxUploadandExecuteRemoteScriptv LinuxUploadandExecuteRemoteScriptusingKey

For information about these deprecated services, see the SmartCloud Orchestratorversion 2.2 knowledge center.


http://www.ibm.com/support/knowledgecenter/SS4KMC_2.2.0/com.ibm.sco.doc_2.2/kc_welcome-sco.html

http://www.ibm.com/support/knowledgecenter/SS4KMC_2.2.0/com.ibm.sco.doc_2.2/kc_welcome-sco.html

Appendix C. Support IaaS toolkit

The SCOrchestrator_Support_IaaS_Toolkit provides capabilities that enable theuser to perform operations on the IaaS layer in IBM Cloud Orchestrator. Thetoolkit provides two different ways to perform the API calls:v An integration service "Generic IaaS Rest Call" that can be used to authenticate

and perform REST calls against any IaaS services in specified regions. Therequests can be performed on behalf of a users in a domain and project. It is themost flexible and documented way to perform REST calls to OpenStack servicesvia IaaS gateway.

v An integration service "Get IaaS Regions" that retrieves the list of availableregions in a multi-region cloud environment. There exists a helper method in theiaas_util.js file that implements the authentication routine based on theconfigured shared secret keys in the WebSphere runtime.

The toolkit provides building blocks that can be used in custom toolkits andprocess applications. These building blocks are required to build Business ProcessManager Business Processes and human tasks, and are also used as extensions.Cloud Orchestrator uses these extensions for actions against the IaaS layer. Forinformation about IaaS layer, see APIs provided by OpenStack and IaaS gateway.The toolkit provides an essential Java REST client API and samples that show howto use the API in Business Processes. To write an extension for IBM CloudOrchestrator, perform these mandatory tasks:v Import this toolkit into Business Process Manager.v Declare a dependency from your Process Application / toolkit to this toolkit.

The following building blocks are provided by this toolkit:v Libraries (in the Files section of the toolkit) - the libraries contain the Java classes

that implement the client-side of the OpenStack and Cloud IaaS gateway API.The libraries contain Java implementation of resources and methods. Theseresource implementations and methods can be used in human services andbusiness processes for actions against the OpenStack and IaaS gateway.

v Samples - the toolkit provides samples that illustrate the usage of the client-sideAPI. For example, the toolkit provides a sample to create and delete a tenant tothe OpenStack identity service Keystone. Another example is about themodification of the metadata of a server. The samples are implemented based ondefault Business Process Manager artifacts. It includes the following elements:– Business objects (BOs) (in the Data section of the toolkit) - some sample

objects that are used in the sample Business Process Manager Processes thatillustrate the flow of data between Business Process Manager and theOpenStack or IaaS gateway. You can easily use them for parameter andprivate data declarations with the standard Business Process Manager. Forexample, business objects can represent tenants and servers.

– Human services (in the User Interface section of the toolkit) - some samplehuman services and coaches are implemented to illustrate the usage of theAPI. For example, human services can specify the parameters of a tenant thatare required to create the tenant. Another example is to select a server thatexists in OpenStack. It shows its details and modifies its metadata.


– Business Process Manager processes - some sample processes that illustratethe usage of long-running tasks. These processes include, for example, thecreation and deletion of a tenant and the modification of the metadata of aserver.

v Integration services - the toolkit provides the following integration services:– REST API calls against OpenStack and IaaS gateway– Retrieve the list of available OpenStack regions

v Authentication Routines - authenticate with the OpenStack identity servicethrough the IaaS gateway.

Generic IaaS REST callThe IaaS Generic REST call makes REST calls to OpenStack services through theIaaS gateway. You can use the interface to specify the target region and service tostart, for example, the compute service Nova in the US-West region. The interface isnot typed and therefore expects and returns a string in a JSON format.

This generic interface allows any RESTful calls against the OpenStack APIs byspecifying the URL and JSON response.

The authentication of the client is done by using the shared secret key, which isconfigured at run time of the Business Process Manager. The shared secret is usedto generate a token for the admin user, which is used for authentication.

The integration service provides the following input variables:

restMethodThe method of the REST call, supported types are GET, POST, PUT, PATCH, andDELETE. It is a required property.

iaasServiceTypeThe type of the service that is instantiated and used to start the REST call.Examples for the service types are identity for keystone, compute for Nova,image for glance. It is a required property.

iaasEndpointTypeThe endpoint of the service to use. It is a required property. The supportedvalues arev For v2: adminURL, publicURL (default), and internalURL.v For v3: admin, public (default), and internal.

iaasRegionThe region from which the service is instantiated, for example, RegionOne. It isan optional property. The first region that is found is taken by default.

restUrlDefines the REST resource that must be started. For example, /tenants or/user/{user-id}. It is a required property.

restJsonContentThe content that must be posted or put to the REST URL. The string must havea valid JSON format as defined in the IaaS API. It is a required property.

iaasUserThe user of this request. It is an optional property. The default is admin.


iaasProjectThe project that performs the request. The user is authenticated and the scopeof the user for this project is determined. This property is optional. The defaultis admin.

iaasDomainThe domain of the user is authenticated. The user can only be uniquelydetermined by specifying the domain. This property is optional. The default isDefault.

The output variable of the integration service is

restJsonResponseThe response of the REST call as a string in JSON format.

OpenStack and Cloud API library in Business Process ManagerThe OpenStack and Cloud library contain Java classes that can be used to interactwith the OpenStack and Cloud IaaS gateway. The Java classes and methods can beused in any Java or JavaScript implementation in any of the Business ProcessManager artifacts. The basic concepts of how to use the library within BusinessProcess Manager are covered here.

Note: To allow the usage of Java implementations in JavaScript implementation,the Business Process Manager uses LiveConnect. During Java class access, itrequires a fully qualified package name because the engine must look up theclasses.

For example, to create an instance of the OpenStackConnectionFactory for a givenhost (String), the full package name must follow the Packages keyword:var connectionFactory = Packages.com.ibm.openstack.api.OpenStackConnectionFactory.newInstance(host);

To simplify the usage and avoid having to add the full package name for eachvariable, the developer can use the JavaScript by omitting the type definition. Inthis example, the object of typecom.ibm.openstack.api.OpenStackConnectionFactory is stored in the local variableconnectionFactory. Next, the variable can be used as described in the APIreference of the OpenStack and Cloud library. For example, to set up a connectionfor a user and password (both variables of type String) -var connection = connectionFactory.newConnection(username, password);

Follow this pattern and the API reference to implement activities of type Javascript in human services or processes to do actions against the IaaS layer. The nextsections focus on authentication and actions against OpenStack and IaaS gateway.

Get IaaS RegionsThe Get IaaS Regions integration service uses the generic IaaS client to retrieve thelist of available regions. These regions can be used to find IaaS services, forexample, the compute service in the US-West region.

The integration service does not require any input parameters. The outputparameter is

-regionsa list of region names that are available.

Related concepts:

Appendix C. Support IaaS toolkit 85

“Generic IaaS REST call” on page 84The IaaS Generic REST call makes REST calls to OpenStack services through theIaaS gateway. You can use the interface to specify the target region and service tostart, for example, the compute service Nova in the US-West region. The interface isnot typed and therefore expects and returns a string in a JSON format.

Samples for the IaaS support toolkitThe sample IaaS support toolkit provides basic samples for the IaaS supporttoolkit. The samples are available via the Sample IaaS Support Process Appprocess application which is installed together with the IaaS support toolkit bydefault.

The following samples are available:

Sample Create DomainThis sample shows how to create a new domain entity in the v3 API of theidentity service in Keystone. It assumes that Keystone v3 is enabled in theservice catalog. The samples also demonstrates how to create a new'Default' project for the domain and adding the admin user as a member tothe project.

Sample Delete DomainThis sample shows how to delete a domain entity in the v3 API of theidentity service in Keystone. The human service shows how to select adomain out of the list of domains. The process disables the domain anddeletes it afterwards.

Sample Create ProjectThis sample shows how to create a project entity in the v3 API of theidentity service in Keystone. The human service shows how to specify theproject details and checks whether the project already exists. The processcreates a project in Keystone.

Sample Delete ProjectThis sample show how to delete a project entity in the v3 API of theidentity service in Keystone. The human service shows how to select aproject out of the list of project . The process deletes the projects inKeystone.

Sample Project On-BoardingThis samples shows how to configure a new or existing project in CloudOrchestrator. The purpose of the sample is to show the API calls toconfigure the project to be operational. Therefore, the human services is awizard that steps the users through a list of steps to:v Create or select the project entity in Keystonev Configure the quota of the projectv Add users and roles to projectv Grant access to environment profiles, patterns, and images to the projectv Grant access to self-service offerings and operation actions to the project

Sample Create UserThis sample shows how to create a user entity within a domain in the v3API of the identity service in Keystone. The human service shows how tospecify the user details, how to select the domain, and how to select thedefault domain and role. The human service checks if the user alreadyexists. The process creates the user in the selected domain and assigns theselected project to the user with the role specified.


Sample Delete UserThis sample show how to delete a user entity in the v3 API of the identityservice in Keystone. The human service shows how to select a user fromthe list of users. The process deletes the user in Keystone.

Sample to create a tenant in OpenStack identity serviceThe sample shows how to create a tenant. A business object is created and itcontains the required parameters, such as name and description. It is assumed thatthe inputParameterObject is instantiated with the business object of type Tenant.

The code to create a tenant is as follows:// authenticate using the helper method in iaas_utils.js

var connection = authenticateIaaS(tw.env.iaas_host, tw.env.iaas_user,tw.env.iaas_password, tw.env.iaas_tenant,tw.env.iaas_use_gateway);

// lookup the first identity admin servicevar serviceFactory = Packages.com.ibm.openstack.api.

service.OpenStackServiceFactory.newInstance(connection);

var identityAdminServices = serviceFactory.lookupServices(Packages.com.ibm.openstack.api.service.IIdentityAdminService);

var identityAdminService = identityAdminServices.get(0);

// create a new resource of type tenantvar factory = Packages.com.ibm.openstack.api.model.

identity.IdentityFactory.eINSTANCE;var tenant = factory.createTenant();

// intialize the tenant resource object with theattributes from the inputParameterObject

tenant.setName(tw.local.inputParameterObject.name);tenant.setDescription(tw.local.inputParameterObject.description);tenant.setEnabled(tw.local.inputParameterObject.enabled);

// call the identity admin service to create a new tenanttenant = identityAdminService.createTenant(tenant);

// store the Id of the new tenant as a referencein the inputParameterObject

tw.local.inputParameterObject.id = tenant.getId();

// adapt authentication method -authentication based on the webshpere configuration settingsusing the helper method in iaas_utils.jsvar connection = authenticateIaaS();

Sample to get a list of servers from OpenStack compute serviceSee how to get a list of servers from OpenStack compute service.

Note: This example is a single region example.

The example code gets the details of a server, and the logic of the steps are asfollows:1. Authenticate to the identity service.2. Look up the compute service.3. Get a list of all servers.

Appendix C. Support IaaS toolkit 87

When the connection is established, the system must look up a compute service,which is registered in the service catalog of the identity service.

// get the service factory based on the connection(knows the identity service and the catalog)

var serviceFactory = Packages.com.ibm.openstack.api.service.OpenStackServiceFactory.newInstance(connection);

// lookup the compute servicesvar computeServices = serviceFactory.lookupServices

(Packages.com.ibm.openstack.api.service.IComputeService);// pick the first compute servicevar computeService = computeServices.get(0);

In the next step, you get the list of servers and fill a local list. The list containsBusiness Process Manager Business Objects (BOs) that are created in the processapplication or toolkit to hold values. This list can then be used in UI elements, forexample, as "selection box" (see the Sample Play with VM human service). Thebusiness object of type server can be found in the IaaS Support Toolkit. It has theattributes id and name of type string. The following code fills the list of serverswith the list of servers that are retrieved from the compute service.// the list of servers from compute service

var servers = computeService.getServers();// a local variable of type Server in the process or human servicetw.local.servers = new tw.object.listOf.Server();// iterate through the list of servers retrieved from compute servicefor (var i=0; i<servers.size(); i++) {

var s = new tw.object.Server(); // instantiate a new BOs.id =servers.get(i).getId(); // copy the ids.name=servers.get(i).getName(); // copy the nametw.local.servers.insertIntoList(i, s);

// add the new instance to the local list

Examples of how to obtain more details of a server can be found in the Get ServerDetails activity in the Sample Play with VM human service.

TroubleshootingRead the following considerations about troubleshooting the toolkit.

The pattern designers use patterns to do actions against an OpenStack service,which has a benefit on simplification and time-to-value. The library provides atypesafe implementation of the OpenStack API, which is less error-prone and morecomfortable than using REST calls and parsing JSON responses. However, thispattern has the following implications:v The Business Process Manager documentation denotes performance implication

in the usage of LiveConnect.v Debugging is difficult.v The Java script editor has no code completion and syntax highlight.

As a workaround for these implications, encapsulate the code in integrationservices or general system services. They are Java implementations of routines thatare provided by Business Process Manager.


Appendix D. Email notification toolkit

The SCOrchestrator_Email_Notification_Toolkit is delivered as a part of CloudOrchestrator. It provides the essential building block for sending email notificationswith improved usability.

Note: An SMTP server via a 100Custom.xml must be configured. The emailnotification toolkit uses this configured SMTP server value to send emailnotifications. For information about how to configure SMTP, see Configuring theSMTP server.

Using the toolkit, you can:v Send .HTML message filesv Send messagetext in HTML formatv Send messagetextv Attach a list of filesv Send to a list of recipients' email addressesv Send to list of cc recipients' email addresses

Note: Defined custom variables are automatically substituted by values.

Business objectsThese business objects are delivered as part of theSCOrchestrator_Email_Notification_Toolkit.

EmailTemplate

Table 85. EmailTemplate


subject String Email subject Message subject text

message String Email message text v Filename of htmlfile:"/tmp/email.html"or

v message-text inhtml format or

v message text

mimeType String Email type ofmessagepart

"text/html"

to String List of recipients'email addresses

"mailtest@localhost"

cc String List of cc recipients'email addresses

"mailuser1@localhost,mailuser2@localhost"(recipients listed withseparating comma orspace)

from String Sender's emailaddress

"root@localhost"


http://www-01.ibm.com/support/knowledgecenter/SSFPJS_8.0.1/com.ibm.wbpm.imuc.ebpm.doc/topics/tcfg_smtp_server.html?cp=SSFPJS_8.0.1%2F0-1-3-2-0-1-4-1-2-1-1-0&lang=en

http://www-01.ibm.com/support/knowledgecenter/SSFPJS_8.0.1/com.ibm.wbpm.imuc.ebpm.doc/topics/tcfg_smtp_server.html?cp=SSFPJS_8.0.1%2F0-1-3-2-0-1-4-1-2-1-1-0&lang=en

Table 85. EmailTemplate (continued)


attachmentFiles String List of attached files "/tmp/ibm-logo,/tmp/cloud.jpg"

variablepair

(NameValuePair):

- name(String)

- value(String)

List List ofEmail-VariableValuepairs for substitution

[{"name":"$FIRSTNAME","value":"xxxxx"},{"name":"&LASTNAME","value":"yyyyy"}]

tw.local.status

Table 86. Status

Output variable Data type Description Return codes

tw.local.status.tw.local.status == 0

Integer Indicates thesuccessfullyexecuted buildingblock to send anemail. Status ofexecuted process.

-1 missing message template xxx.html-2 missing attachment file-3 missing ’to’ recipient email-adress-4 missing sender email-adress-5 other failures

Implementation servicesThe toolkit contains a number of implementation services.

The following implementation services are used only internally and are notdescribed in detail:v Read Filev Send File

For more information about the services, see the documentation inside the toolkitor service itself.

The implementation services of the toolkit are as follows:

Send Email Template

This implementation service prepares the message and message-text and sends it tothe recipients' email addresses.

Table 87. Send Email Template


subject String Email subject Message subject text

message String Email message text v Filename of htmlfile:"/tmp/email.html"or

v message-text inhtml format or

v message text


Table 87. Send Email Template (continued)


mimeType String Email type ofmessagepart

"text/html“

to String List of recipients'email addresses

"mailtest@localhost“

cc String List of cc recipients'email addresses

"mailuser1@localhost,mailuser2@localhost"(recipients listed withseparating comma orspace)

from String Sender's emailaddress

"root@localhost"

attachmentFiles String List of attached files "/tmp/ibm-logo,/tmp/cloud.jpg"

Sample processesThe SCOrchestrator_Email_Notification_Toolkit contains the sample processSample Send Email from Template.

For output data and input data for Sample Send Email from Template, see theEmailTemplate business object in “Business objects” on page 89.

Sample UIThe SCOrchestrator_Email_Notification_Toolkit contains sample UIs, whichreflect the needs of the corresponding sample processes.

The sample processes and matching sample UIs are determined by theircorresponding data object. The type of output parameter of the sample UI mustmatch the type of input parameter of the sample process. The sample UI is SampleSend Email Notification. For output data, see the EmailTemplate business objectin “Business objects” on page 89.

Appendix D. Email notification toolkit 91


Appendix E. Support vSys classic toolkit

The SCOrchestrator_Support_vSys_Toolkit provides capabilities to deploy virtualsystem patterns (classic) through IBM Cloud Orchestrator. The toolkit providesbuilding blocks you can use in other toolkits or process applications to buildcustom services and processes.

The toolkit builds function on top of the IBM Cloud Orchestrator API and uses theGenericREST integration service and the direct IaaS REST integration services of theCloud Orchestrator toolkit to perform restful API calls.

The Customize Pattern integration service provides capability to convert aBusiness Process Manager business object of type Pattern into a JSON documentwhich is in the IBM Cloud Orchestrator format.

The service sample, Deploy Virtual System Instance, is a wizard used to deployan existing pattern with an integrated configuration panel. Other human servicesare available to show virtual server based selection and initiate actions against thehosting virtual system. Other integration services are built around the API and canbe extended using the GenericREST integration service.

Finally, the sample processes of the Processes section cover the previous SampleSupport vSys Process App samples that show how to build custom services todeploy and orchestrate virtual system patterns.

Business objectsThe business objects in the SCOrchestrator_Support_vSys_Toolkit are defined here.The variables of these business objects are described in the toolkit.

ChangeInstanceEndTimeBO

The ChangeInstanceEndTimeBO business object represents the customization dataobject regarding change of the time where the instance lifetime is ending. Duringcreation of the virtual system instance, there are several tasks created which arescheduled for certain time. This time must be changed in cases when the instanceend time gets changed. The contained parameters must be filled regarding the dateand times. This instance contains the actual scheduled tasks and times. A differentinstance can be used to hold the target dates and times.

CheckDateTime

This business object is used to hold data to check the instance for a scheduled endtime. If the instance end time is indefinite, the Date field is set to false whichmeans the end time of the instance cannot be changed. There are no related taskswith a timed schedule.

CloudGroupSelectionBO

This business object is used to hold related information regarding the cloud group.This information is required while the virtual system instance is being deployingaccording to its related pattern.


EnvironmentLimits

This is a business object that describes the environment limits (quota) as part of anenvironment profile.

EnvironmentLimitsBO

This is a business object that describes the environment limits (quota) and actualallocated and reserved resources as part of an environment profile.

EnvironmentProfileBO

The environment profile business object describe all references to uniquely identifyan environment profile as well as the associated environment limits. TheEnvironmentLimitBO is included in this business object.

Flavor

The flavor data object describes values about CPU, memory, and storage. Thevalues correspond directly from the flavors used for deployment or are targets fora resource allocation change (modify resource scenario).

ModifyResourceBO

The ModifyResource business object describes all data required to process amodification request to change actual resource allocations of CPU, memory, andstorage. The resource allocations are described in contained Flavor objects.

Part

The Part object represents the customization of parts within a pattern. The partcustomization is required for the following cases:v The flavor in case of deploying against a cloud groupv The cloud group, IP group, and flavor in case of deploying against an

environment profile

However, if no part customization is provided, the flavorId, cloudId, andipGroupId of the pattern are used for all parts within the pattern.

The field vmNics contains information about the network interfaces (IP address,host name, IP group) of each member of the part. It is a two-dimensional arraywhich means an array of NICs for each member of the part, specified by thememberCount of the part, containing:v IP address of the NIC, if specified by the pattern deployerv Host name of the NIC, if specified by the pattern deployer, can be omittedv IP group to be used, can be defaulted by the ipGroupId field of the part

PartBO

The Part business object represents the customization of part, part properties, andscripting parameters, both in the form of a list within a pattern.


PartProperty

The PartProperty object represents the customization of parameters within a part.These parameters are typically defined in the Open Virtualization Format (OVF).The key and pclass properties are used to identify the parameter and the valueproperty stores the actual value. The Customize Pattern integration serviceoverrides the value of each part parameter that is specified in the customization.

Pattern

This business object represents the customization of a virtual system pattern inCloud Orchestrator. The business object is converted by the 'Customize and DeployVirtual System Pattern' integration service into a string that is used to deploy thevirtual system pattern.

Note: Some of the properties are optional, others are required. The details can befound in the documentation section of the properties.

On a high level, the pattern object contains the following groups of customizations:v The customizations of the pattern itself, for example, name, start/end date, and

target.v The customizations of the parts of the pattern, for example flavor. See 'Part'

object.v The customizations of the parameters of the parts within the pattern, for

example, the password of the root user. See 'PartProperty' object.

The business object supports the following targets for deployment of the pattern:v Deploy the pattern into a single cloud group.v Deploy the pattern into an environment profile which requires that you select

the target cloud groups and IP groups for each part.

To simply the deployment into environment profiles and to avoid thecustomizations of cloud groups and IP groups for each part, the cloud group andIP group on the pattern level is used as a default for each part.

PatternBO

The PatternBO is just a different representation of the same information containedin the Pattern business object. The information is organized as an array of parts ofthe business object type 'PartBO' where each arrary element represents a part ofthe pattern.

ScriptProperty

This business object represents the customization of parameters of scripts within apart. Those parameters are typically defined in the OVF. The part, script, and keyproperties are used to identify the parameter and the value stored. The CustomizePattern integration overrides the value of each part parameter that is specified inthe customization.

For example, to identify the parameter with key param1 of the first script withinthe first part the user needs to set part=1, script=1 and key=param1.

Appendix E. Support vSys classic toolkit 95

UserInfoBO

This business object describes relevant properties of the current user. It is used inintegration services 'Get User Info' and 'Get Owner Of vSys Instance'.

VirtualServer

This data type describes the fields to be used to fill the displayed table to enableselection of a single server for manipulation. For example, it is used in integrationservice 'Get Virtual Machine.'

VirtualSystem

This business object is a helper object that stores the basic information about thevirtual system. It is used in most of the sample integration services delivered bythis toolkit within the integration service 'Get Virtual Machines'.

VirtualSystemPatternBO

This business object holds the complete set of customization properties of a virtualsystem. It is used in the sample integration services 'Deploy Single Pattern' and tolist available patterns for selection in 'Get Available Patterns'.

Integration servicesThe integration services that are used in SCOrchestrator_Support_vSys_Toolkittoolkit.

Note:

During processing the human service where all configuration data is collected, avirtual instance name is generated using the selected pattern name and a generatedUUID. The UUID ensures that the virtual instance name is unique. If it is notunique, you receive the error: The name or identifier you entered is already inuse.

Because a UUID is a long string, the resulting virtual machine name created withthe IP address prefix might exceed the maximum virtual machine name lengthpossible for VMware, which is 80 characters.

You can resolve this issue in the following ways:v Edit the name while executing the deploy service. In this case, there is the risk

of duplicating the name of the virtual instance name.v You can configure naming rules for the virtual machine name, which is different

from the internal instance name, in the environment profile. This results in ashorter and more customizable virtual machine name.

Get ACL of Virtual System Instance

The Get ACL of Virtual System Instance integration service retrieves the accesscontrol list of a virtual system instance that includes its virtual machines. Theinput is the ID of the virtual system instance. The out put is a JSON document thatdescribes the list of ACL entries of the virtual system instance.

Related API: GET /resources/instances/{id}/acl


Add user to ACL of Virtual System Instance

This Add user to ACL of Virtual System Instance integration service adds a userto the access control list of a virtual system instance and sets the permission. Theinput is the ID of the virtual system instance, the ID of the user, and thepermission flag. The output is a JSON document that describes the result of theAPI call.

Related API: POST /resources/instances/{id}/acl/user-{id}

Remove User from ACL of Virtual System Instance

This Remove User from ACL of Virtual System Instance integration serviceremoves the user and its permission from the access control list of a virtual systeminstance. The input is the ID of the virtual system instance and the ID of the user.The output is a JSON document that describes the result of the API call.

Related API: DELETE /resources/instances/{id}/acl/user-{id}

Update User in ACL of Virtual System Instance

The Update User in ACL of Virtual System Instance integration service updatesthe permission of a user in the access control list of a virtual system instance. Theinput is the ID of the virtual system instance, the ID of the user, and thepermission flag. The output is a JSON document that describes the result of theAPI call.

Related API: PUT /resources/instances/{id}/acl/user-{id}

Get Cloud Groups In Environment Profile

The Get Cloud Groups In Environment Profile integration service retrieves thecloud groups in an environment profile. The list of cloud groups can be used tocustomize targeting cloud groups of parts within a pattern. The input is the ID ofthe environment profile. The output is a JSON document that describes the list ofcloud groups in the environment profile. This integration service can be used forthe second step within a logical sequence of steps when you deploy a pattern in anenvironment profile:1. Get the list of environment profiles for a pattern and select one environment

profile for it.2. Get the list of cloud groups within the selected environment profile and select

cloud group for each part of the pattern.3. Get the list of IP groups within the selected environment profile and cloud

group, and select one IP group for each part in the pattern.

Related API: GET /resources/environmentProfiles

Get Environment Profiles For Pattern

The Get Environment Profiles For Pattern integration service retrieves the list ofenvironment profiles that can be used as a target for provisioning of a specifiedpattern. The input is the ID of the virtual system pattern. The output is a JSONdocument that describes the list of environment profiles. This integration servicecan be used for the first step within a logical sequence of steps when you deploy apattern in an environment profile:


1. Get the list of environment profiles for the pattern and select one environmentprofile for the pattern.

2. Get the list of cloud groups within the selected environment profile and selectcloud group for each part of the pattern.

3. Get the list of IP groups within the selected environment profile and cloudgroup, and select one IP group for each part in the pattern.


Get Flavors Of Cloud Group In Environment Profile

The Get Flavors Of Cloud Group In Environment Profile integration serviceretrieves the possible flavors that are valid for cloud groups within environmentprofiles. The list of flavors can be used to customize the parts of a pattern. Theinput is the ID of the environment profile and the ID of a cloud group within theenvironment profile. The output is a list of flavors that are valid for the selectedcloud group within the selected environment profile. This integration service canbe used for the last step within a logical sequence of steps when you deploy apattern in an environment profile:v Get the list of environment profiles for the pattern and select one environment

profile for the pattern.v Get the list of cloud groups within the selected environment profile and select

cloud group for each part of the pattern.v Get the list of IP groups within the selected environment profile and cloud

group, and select one IP group for each part in the pattern.v Get the list of flavors within the selected environment profile and cloud group,

and select one flavor for each part in the pattern.

Related API: GET /resources/flavor/?cloudId={id}

Get Ip Groups Of Cloud Group In Environment Profile

The Get Ip Groups Of Cloud Group In Environment Profile integration serviceretrieves the IP groups that are enabled for cloud groups within the environmentprofiles. The list of IP groups can be used to customize the network interfaces ofparts of a pattern. The input is the ID of the environment profile and the ID of acloud group within the environment profile. The output is a list of IP groups thatare enabled and configured for the selected cloud group within the selectedenvironment profile. This integration service can be used for the third step withina logical sequence of steps when you deploy a pattern in an environment profile:v Get the list of environment profiles for the pattern and select one environment

profile for the pattern.v Get the list of cloud groups within the selected environment profile and select

cloud group for each part of the pattern.v Get the list of IP groups within the selected environment profile and cloud

group, and select one IP group for each part in the pattern.


Check Quota Breach

This is an integration service to retrieve the environment limits (quota) of thecorresponding virtual system instance. It uses a REST call against WorkloadDeployer to retrieve the desired information.


Related API: GET /resources/environmentProfiles/{id}

Get Script Parameters

This integration service retrieves script parameters.

As input the integration service expects the:v part IDv part indexv PatternBO

As output the integration service returns a response string.

Related API: GET /resources/patterns/{id}/pparts/{id}/pscripts/

Execute Script Packages

This is an integration service to execute scripts.

As input the integration service expects the:v ID of the virtual systemv ID of virtual machinev script IDv script payload

As output the integration service returns a response string.

Related API: POST /resources/instances/{id}/virtualMachines/{id}/virtualMachineScripts/{id}/

Fetch Email Task

Before a virtual system instance is de-provisioned , an email notification is sentsaying that the virtual system instance is to be de-provisioned.

This integration service can be used to retrieve the time that the email notificationis sent before a virtual system instance is terminated by issuing a correspondingREST call against IBM Workload Deployer. It gets the operationContextId and thevirtualSystem information as input parameter and returns the time that the emailnotification for the termination of the virtual system instance is to be sent in theform of a ChangeInstanceEndTimeBO business object.

Related API: GET /resources/tasks/?name={name}

Fetch End Time

This integration service can be used to retrieve the end time of a virtual systeminstance by issuing a corresponding REST call against Workload Deployer.

It gets the operationContextId and the virtualSystem information as inputparameter and returns the end time of the virtual system instance in the form of aChangeInstanceEndTimeBO business object.

Related API: GET /resources/tasks/


Check Status Of Virtual System

This integration service retrieves the status of the virtual system instance. As inputthe integration service expects the id of the virtual system. As output theintegration service returns the internal status number and the deploy message ofthe status.

All the status codes and their value can be found in the file /opt/ibm/rainmaker/rainmaker.validator/private/expanded/ibm/rainmaker.logging-4.0.0.0/app/messages/en.properties on the server where Workload Deployer is installed.

Here is part of the file content:#NLS_ENCODING=UNICODE#NLS_MESSAGEFORMAT_NONE

RM01000=Initializing

RM01001=Defined

RM01002=Processing

RM01003=Transferring

RM01004=Transferred

RM01005=Starting

RM01006=Started

RM01007=Paused

RM01008=Quiescing

RM01009=Quiesced

RM01010=Stopping

RM01011=Stopped

RM01012=Ready to use

RM01013=Failed

RM01014=Transfer failed

RM01015=Timeout failed

RM01016=Active

RM01017=Inactive

RM01018=Packaging

RM01019=Unpackaging

RM01020=Snapshot

RM01021=Disconnected

RM01022=Registered

RM01023=Unregistered

RM01024=Deleting


RM01025=Maintenance mode

RM01026=Exporting

RM01027=DraftRM01028=Read-only

RM01029=CapturingRM01030=Captured

RM01031=PausingRM01032=ResumingRM01033=ResettingRM01034=ResetRM01035=QueueingRM01036=QueuedRM01037=DeployingRM01038=DeployedRM01039=ServicingRM01040=ServicedRM01041=Service transferredRM01042=Transferring serviceRM01043=Service appliedRM01044=Applying serviceRM01045=Transferring to apply serviceRM01046=Service rolled backRM01047=Rolling back serviceRM01048=Committing serviceRM01049=Committing serviceRM01050=CommittedRM01051=DormantRM01052=Executing scriptsRM01053=Transfering and applying serviceRM01054=Snapshot restoredRM01055=Snapshot deletedRM01056=Service failedRM01057=License not acceptedRM01058=StoredRM01059=WarningRM01060=Capture startedRM01061=Logged in and activeRM01062=Inactive

RM01063=monthsRM01064=weeksRM01065=daysRM01066=hoursRM01067=percentRM01068=Week ${0}, ${1}

RM01069=DeletedRM01070=Partially started

RM01071=Detached

RM01079=Re QueuedRM01080=HiddenRM01081=Sunset

RM01082=LockedRM01083=Active (Locked)

RM01075=Migrating


RM01090=Ping

RM01091=Configure

Customize and Deploy Virtual System

This integration service combines the 'Customize Pattern' and 'Deploy Pattern'integration services and calls both services after each other.

Customize Pattern

The Customize Pattern integration service converts the Pattern customization intoa JSON document that represents the virtual system to be deployed. The input is abusiness object of type Pattern that contains all customization of the pattern. Thedocumentation of the Pattern data object describes it in detail.

Call the Validate Pattern integration service on the pattern object. The output canbe passed to the Deploy Pattern integration service to deploy a virtual systempattern.

Deploy vSys Pattern

This integration service deploys a virtual system instance. The input is a JSONdocument describing the virtual system instance. This JSON document can eitherbe generated by custom code or via the 'Customize Pattern' integration service. Theoutput contains the details of the deployed virtual system instance.

Related API: POST /resources/virtualSystems

Get Available Patterns

This is an integration service to retrieve all available patterns. As input theintegration service expects the user. As output the integration servicereturns patterns as list of VirtualSystemPatternBO.

Related API: GET /resources/patterns

Get Pattern Details

The Get Pattern Details integration service retrieves the details of a pattern,which includes its parts and metadata. The input is the ID of the pattern. Theoutput is a JSON document that describes the pattern and its parts.


Get Pattern Details by Name

The Get Pattern Details by Name integration service searches a pattern by nameand retrieves its details, which include part information and metadata. The input isthe name of the pattern. The output is a JSON document that describes the patternand its part information. If the pattern is not found, the output is an empty string.



Validate Pattern Customization

The Validate Pattern Customization integration service validates the patternspecification that is defined in a business object of type Pattern. The input is thebusiness object that defines the pattern customization. The output is a flag thatindicates whether the customization is valid or not, and a list of error messagesthat indicates wrong customization.

Get Cloud Groups For Pattern

The Get Cloud Groups For Pattern integration service returns the list of cloudgroups that can be used to deploy a specific pattern. The input is the ID of thevirtual system pattern. The output is a list of cloud groups in JSON format asdescribed in the API.

Related API: GET /resources/clouds

Customize and Deploy Virtual System Pattern

The Customize and Deploy Virtual System Pattern integration service combinesthe Customize Pattern and Deploy Pattern integration services. The services arecalled one after the other.

Get Cloud Groups in EnvironmentProfile

This integration service retrieves the cloud groups in an environment profile. Thelist of cloud groups can be used to customize targeting cloud groups ofparts within a pattern. The input is the id of the environment profile. The outputis a JSON document describing the list of cloud groups in the environment profile.This integration service can be used for the second step within a logical sequenceof steps when deploying a pattern in an environment profile:1. Get the list of environment profiles for the pattern and select one environment

profile for the pattern.2. Get the list of cloud groups within the selected environment profile and

select cloud group for each part of the pattern.3. Get the list of ip groups within the selected environment profile and cloud

group, and select one ip group for each part in the pattern.


Get Environment Limits

This is an integration service to retrieve the environment limits (quota) of thecorresponding virtual system instance. It uses the integration service GetEnvironment Profiles to retrieve the desired information. As input the integrationservice expects the:v typev pattern IDv user information

As output the integration service returns a list of EnvironmentProfilesBO.


Update Environment Limits

This is an integration service to update the environment limits (quota) of aWorkload Deployer environment profile using a REST call against WorkloadDeployer.

Get Environment Profiles

This is an integration service to retrieve a list of environment profiles.

Related API: GET /resources/environmentProfiles/?patternid={id}&includeCloud=1"

List Flavors

This integration service retrieves the list of flavors using IaaS REST interface andreturns a list of Flavor data objects.

Get Upgrade Flavors For Virtual Machine

This integration service retrieves flavors from OpenStack (IaaS REST calls) whichcan be used to upgrade the virtual machine The input is the:v operation contextv tenant IDv current flavor

The output is a list of Flavor business objects.

Get User Information

This integration service retrieves information regarding the actual user. As inputthe integration service expects the user. As output the integration servicereturns response UserInfoBO.

Related API: GET /resources/users?username={user}

Get Requester Details

This integration service retrieves requester email information. The input is theuser name. The output is the email as string.

Related API: GET /resources/users

Get Virtual Machines

This integration service retrieves the virtual machines within a virtual systeminstance. The input is the ID of the virtual system instance. The output is a JSONdocument that describes the list of the virtual machines within the virtual systeminstance.

Related API: GET /resources/virtualSystems/{id}/virtualMachines

Get Virtual System

This integration service retrieves details of a virtual system instance. The output isa JSON document that describes the details of the virtual system instance.


Related API: GET /resources/virtualSystems

Get Virtual System Instance

This integration service retrieves the details of a virtual system instance includingits virtual machines. The input is the id of the virtual system instance. The outputis a JSON document that describes the details of the virtual system instance.


Get Virtual System Instances

This integration service retrieves the list of virtual system instances. The output isa JSON document that describes the details of the virtual system instance.


Get vSystem Instances

This integration service retrieves the list of virtual system instances. The output isa JSON document that describes the details of the virtual system instance.


Get Flavor Of Virtual Machine

This integration service retrieve a flavor from OpenStack and return the flavorwith details and tenant ID.

Get Flavors Of Cloud Group In Environment Profile

This integration service retrieves the possible flavors that are valid for cloudgroups within environment profiles. The list of flavors can be used to customizethe parts of a pattern.

The input is the ID of the environment profile and the ID of a cloud group withinthe environment profile. The output is a list of flavors that are valid for theselected cloud group within the selected environment profile. This integrationservice can be used for the last step within a logical sequence of steps whendeploying a pattern in an environment profile:1. Get the list of environment profiles for the pattern and select one environment



group, and select one ip group for each part in the pattern.4. Get the list of flavors within the selected environment profile and cloud group,

and select one flavor for each part in the pattern.

Related API: GET /resources/flavor/?cloudId={id}


Get IP Groups Of CloudGroups In Environment Profile

This integration service retrieves the IP groups that are enabled for cloud groupswithin environment profiles. The list of IP groups can be used to customize thenetwork interfaces of parts of a pattern.

The input is the ID of the environment profile and the ID of a cloud group withinthe environment profile. The output is a list of IP groups that are enabled andconfigured for the selected cloud group within the selected environment profile.This integration service can be used for the third step within a logical sequence ofsteps when deploying a pattern in an environment profile:1. Get the list of environment profiles for the pattern and select one environment



group, and select one ip group for each part in the pattern.


Resize Virtual Machine

This integration service resizes virtual machine resources by changing the flavor.The input is the:v virtual system IDv virtual machine IDv virtual machine namev current flavor

The output is false/true.

Related API reference: PUT /resources/virtualSystems/{id}/virtualMachines/{id},payload

Start vSys Instance

Starts a virtual system instance. The input is the ID of the virtual system instance.The output is the result of the API call.

Related API: PUT /resources/virtualSystems

Stop vSys Instance

Stops a virtual system instance. The input is the ID of the virtual system instance.The output is the result of the API call.

Related API: PUT /resources/virtualSystems

Delete vSys Instance

The Delete vSys Instance integration service deletes a virtual system instance.The input is the ID of the virtual system instance. The output is the result of theAPI call.

Related API: DELETE /resources/virtualSystems


Validate End Time

This is a validation service to validate that the date selected is not in the past.

Validate End Time Of Virtual System

This is a validation service to validate that a virtual system instance has beenselected and that the end time can be changed, for example, is not indefinite.

User interfaceThe user interface section of the SCOrchestrator_Support_vSys_Toolkit containssample implementations for asynchronous services (AJAX), coach views, andhuman services.

AJAX servicesThe user interface section of the SCOrchestrator_Support_vSys_Toolkit containssample implementations for asynchronous services (AJAX), coach views, andhuman services.

The names of the AJAX services are similar to its functionality. These are the basicservices to collect data for further human service processing.

The following items are internal AJAX services:

ListEnvironmentProfilesUsed to list the existing environment profiles

ListFlavorsForEnvProfileUsed to list flavors for a given environment profile

ListIPGroupsForEnvProfileUsed to list IP groups for a given environment profile

ListVirtualSystemPatternsUsed to list virtual system pattern

ListVirtualSystemsUsed to list virtual systems

ListVirtualSystemsForPatternUsed to list virtual systems for a given pattern

Coach viewsCoach views is a collection of coaches which show how to handle types of widgetswith their event handlers.

The following coaches are available:

Button EventThis coach is copied from the Kolban toolkit

CheckBoxDateVisibilityThis is an internal coach to handle dates

Conditional PasswordThis is an internal coach to handle password

Dialog BoxThis coach is copied from the Kolban toolkit


Human servicesThe human services that are used in SCOrchestrator_Support_vSys_Toolkit toolkit.

All of the samples can be used in self-service offerings.

Change Environment Profile Limits

This is a human service to collect data for environment profile limit changes. Itworks together with the corresponding business process definition.

Change Instance End Time

This is a human service to collect data to enable virtual system instance end timechanges based on selection of a virtual server. After selecting a virtual systempattern, the list of virtual system instances for the selected pattern is displayed.Having selected a virtual system instance, the current end date of the virtualsystem instance is displayed. You can now change the end time of the virtualsystem instance by selecting the new date and time.

Note: This human service can be used in a self-service offering. The prerequisitefor being able to change the end time is that the current end time of the virtualsystem is NOT indefinite.

Change Instance End Time (Instance Op)

This is a human service to collect data for virtual service instance end timechanges based on virtual server instances. See "Change Instance End Time" humanservice.

Delete Single Server Virtual System

This is a human service to collect data to select a single server for a virtual systembased on contained virtual server for deletion. It works together with thecorresponding business process definition.

Delete Single vSys Instance

This is a human service to collect data to select a single virtual system for deletion.It works together with the corresponding business process definition.

Delete vSys Instances

This is a human service to collect data to select a multiple virtual systems fordeletion. It works together with the corresponding business process definition.

Deploy Single Pattern

This human service provides a sample that shows the deployment of anapplication pattern via Workload Deployer into an environment profile. Anapplication pattern is chosen and is configured as a virtual system pattern prior todeployment. The human services demonstrate how to retrieve the pattern detailsand how to configure the properties (for example, name, scheduled start/end date,target cloud group, flavor, and so on) of the virtual system instance that is to bedeployed. A validation step has been added that checks if the customization isvalid and, if not, a coach shows a list of validation messages to the user.


The human service itself shows how to:v Specify the defaults of the pattern deploymentv Retrieve the pattern and its partsv Get environment profiles, their cloud groups, and their IP groupsv Show the pattern and parts in a coach view

The result of the human service is an object of type 'Pattern' which describes thecustomizations of the pattern, including:v Name of the virtual system instancev Target environment profile, cloud group, and IP groupv Flavor that is usedv Scheduled start/end datev Customized part properties

Modify Single Virtual Machine

This is a human service to drive data collection to modify the flavor or resourceallocations of a single server for a virtual system. The allocated resources getchanged while starting the virtual server. If the virtual server is in running state. itis stopped and restarted to change the resource allocations. The selection of theflavors listed for resource modification gets retrieved by the integration service"Get Upgrade Flavors For Virtual Machine." The matching business processdefinition to build a self-service offering is called "Modify Resource".

Restart Single Server Virtual System

This is a human service to collect data to select a single server for a virtual systembased on contained virtual server for restart activity. It works together with thecorresponding business process definition.

Restart Single vSys Instance

This is a human service to collect data to select a single virtual system for restart.It works together with the corresponding business process definition.

Restart vSys Instances

This is a human service to collect data to select multiple virtual systems for restart.It works together with the corresponding business process definition.

Stop Single Server Virtual System

This is a human service to collect data to select a single server for a virtual systembased on contained virtual server for stop activity. It works together with thecorresponding business process definition.

Stop Single vSys Instance

This is a human service to collect data to select a single virtual system to stop thisinstance. It works together with the corresponding business process definition.


Stop vSys Instances

This is a human service to collect data to select multiple virtual systems forstopping all the selected instances. It works together with the correspondingbusiness process definition.

Start Single Server Virtual System

This is a human service to collect data to select a single server for a virtual systembased on contained virtual server for start activity. It works together with thecorresponding business process definition.

Start Single vSys Instance

This is a human service to collect data to select a single virtual system to start theselected instance. It works together with the corresponding business processdefinition.

Start vSys Instances

This is a human service to collect data to select multiple virtual systems forstarting all selected instances. It works together with the corresponding businessprocess definition.

Select Pattern Instances

This human service shows how to select a set of virtual system instances of aspecified pattern. The output of the human service is a list of virtual system IDsthat can be used as input of the 'Stop Virtual System Instance' process.

Select Single Pattern Instance

This sample human service shows how to select a virtual system instance of aspecified pattern. The output of the human service is a list of virtual system IDsthat can be used as input of the 'Stop Single Server Virtual System' process.

Select Single Virtual Machine For Modify

This human service shows how to select a virtual system instance while displayingvirtual servers which get called by using IaaS REST calls. The output of the humanservice is a list of virtual system IDs, current, and target flavor that can be used asinput of the 'Modify Resource' process.

Select Single Server Virtual System

This sample human service shows how to select a virtual system instance based ondisplaying the contained virtual servers. The human service shows a table ofvirtual servers with the virtual system instance name and resource allocations forselection. The output of the human service is a virtual system ID that can be usedas input of the sample process 'Stop Single vSys Pattern Instance'.


Sample process servicesMost of the processes have a direct human service with a similar name to collectdata via coaches in the UI and forward the collected parameters to the processservices.

Change Environment Profile Limits

This sample process shows how to change environment profile limits via WorkloadDeployer. The process gets the input parameter collected by the related humanservice "Change Environment Profile Limits" and updates the profile limitsafterwards accordingly.

Change Instance End Time

This sample process shows how to change the virtual system instance end time viaWorkload Deployer. The process gets the input parameter collected by the relatedhuman service "Change Instance End Time" and updates the related scheduledtasks afterwards accordingly.

Note: If an instance has an indefinite end time, no task is scheduled to stop andremove the system. The end time can only be changed if an instance has a definedend time and therefore tasks scheduled can be changed in respect to executiontime.

Delete Single vSys Instance

This sample process shows how to stop virtual system instances via WorkloadDeployer. The process gets a virtual system and calls the API of WorkloadDeployer to stop the virtual system instance.

Delete vSys Instances

This sample process shows how to stop virtual system instances via WorkloadDeployer. The process gets a list of virtual system IDs. The process checks the listof virtual systems IDs and calls the API of Workload Deployer to stop the virtualsystem instance.

Deploy Selected Pattern

This sample process shows the configuration and deployment of a virtual systempattern via Workload Deployer. The input of the process is a business object oftype Pattern which contains the customization of the pattern, for example:v Name of the virtual system instancev Target cloud group (environment profile, IP group)v Flavor that is usedv Scheduled start/end datev Customized part properties

The process validates the customization, converts the customization in a JSONdocument, and calls the Cloud Orchestrator API to deploy the pattern. Afterdeployment, the process waits until the virtual system instance is started. The exactspecification of the input parameters is described in the description of the 'Pattern'business object. The process is a generic implementation and can be used withdifferent human services that return a business object of type 'Pattern'.


Deploy Virtual System Approval

This is a sample process which includes an approval. It can be embedded into theCloud Orchestrator deploy instance workflow. The intention is to approve thedeploy instance process. Ensure that you adapt the participant to the group whichmust have approval rights.

Modify Resource

This sample process shows how to change the flavor or resource allocations of avirtual server in system instances via Workload Deployer. The process gets avirtual system ID, stops the virtual machine, and changes the flavor via WorkloadDeployer which initiates a system start to activate the resource changes.

Restart Single vSys Pattern Instance

This sample process shows how to stop and start a single virtual system instancevia Workload Deployer. The process gets a virtual system ID, stops the instance,and afterwards, starts it again.

Restart vSys Pattern Instances

This sample process shows how to stop and start virtual system instances viaWorkload Deployer. The process checks the list of virtual systems IDs and calls theAPI of Workload Deployer to stop and start the virtual system instances in parallel.

Start Single vSys Pattern Instance

This sample process shows how to start a single virtual system instance viaWorkload Deployer. The process gets the virtual system ID and calls the API ofWorkload Deployer to start the virtual system instance.

Start vSys Pattern Instances

This sample process shows how to start virtual system instances via WorkloadDeployer. The process gets a list of virtual system IDs. The process checks the listof virtual system IDs and calls the API of Workload Deployer to start the virtualsystem instance.

Stop Single vSys Pattern Instance

This sample process shows how to stop a single virtual system instance viaWorkload Deployer. The process gets the virtual system ID and calls the API ofWorkload Deployer to stop the virtual system instance.

Stop vSys Pattern Instances

This sample process shows how to stop virtual system instances via WorkloadDeployer. The process gets a list of virtual system IDs. The process checks the listof virtual system IDs and calls the API of Workload Deployer to stop the virtualsystem instance.

Wait For Deletion Of Virtual System Instance

This process shows how to wait for a virtual system instance that has reachedstopped status. The process checks for the status in each iteration. Between each


iteration, the process waits for a specified number of minutes. If the status is notreached after a given number of checks, the process stops with an error taskassignment. The following parameters are required:v ID of the virtual system instancev Waiting status (internal status in Workload Deployer)v Maximum number of checksv Time in minutes between checks

As output, the process provides the status and the status message text.

Wait For Status Of Virtual System Instance

This process shows how to wait for a virtual system instance that has reached aspecified status. The process checks for the status in each iteration. Between eachiteration, the process waits for a specified number of minutes. If the status is notreached after a given number of checks, the process stops with an error taskassignment. The following parameters are required:v ID of the virtual system instancev Waiting status (internal status in Workload Deployer)v Maximum number of checksv Time in minutes between checks

As output, the process provides the status and the status message text.



Appendix F. Support vSys toolkit

The SCOrchestrator_Support_vSys_Next_Toolkit provides capabilities to deployvirtual system patterns through IBM Cloud Orchestrator. The toolkit providesbuilding blocks you can use in other toolkits or process applications to buildcustom services and processes.

The toolkit builds function on top of the IBM Cloud Orchestrator API and uses theGenericREST integration service and the direct IaaS REST integration services of theCloud Orchestrator toolkit to perform restful API calls.

The offering Deploy cloud services using advanced patterns in the Deploy cloudservices category is a wizard that you can follow to perform the deployment.Other integration services are built around the API and can be extended using theGenericREST integration service.

Business objectsThe business objects that are defined forSCOrchestrator_Support_vSys_Next_Toolkit are defined here. The variables ofthese business objects are described in the toolkit.

VSysNextPatternBO

This is a business object that describes the Virtual System Pattern.

VsysNextModelBO

This is a business object that describes the model that is used to deploy a VirtualSystem Pattern.

VSysNextDeploymentBO

This is a business object that describes the complete Deployment objects needed fordeploying a Virtual System Pattern.

VirtualSystemInstanceBO

This is a business object that describes Virtual System Instance.

NodeBO

This is a business object that describes a Node object that is part of the VirtualSystem Pattern. A Virtual System Pattern can have multiple Nodes.

NodeAttributeBO

This is a business object that describes the attribute that is part of the Node. ANode can have multiple Attributes.

DateTimeBO

This is a business object that describes Date and Time.


Integration servicesThe integration services that are used inSCOrchestrator_Support_vSys_Next_Toolkit toolkit.

Note:

During processing the human service where all configuration data is collected, avirtual instance name is generated using the selected pattern name and a generatedUUID. The UUID ensures that the virtual instance name is unique. If it is notunique, you receive the error: The name or identifier you entered is already inuse.

Because a UUID is a long string, the resulting virtual machine name created withthe IP address prefix might exceed the maximum virtual machine name lengthpossible for VMware, which is 80 characters.

You can resolve this issue in the following ways:v Edit the name while executing the deploy service. In this case, there is the risk

of duplicating the name of the virtual instance name.v You can configure naming rules for the virtual machine name, which is different

from the internal instance name, in the environment profile. This results in ashorter and more customizable virtual machine name.

Get Available VSysNext Patterns

GET /resources/VirtualsystemPatterns

The API enables the process designer to list all the accessible patterns.

Get Pattern Details

GET /resources/VirtualsystemPatterns/{id}

The API enables the process designer to get the detailed information about apattern, including the parts it is made of.

Update ACL of Virtual System Instance

PUT /resources/virtualApplications/{id}/accessRights/{name}?{ user or group }

{ "access_rights": "F"}

If no access rights are passed the user does not get access.

The API enables the process designer to change the access to an instance of avSysNext pattern.

Get ACL of Virtual System Instance

GET /resources/virtualApplications/{id}/accessRights

The API enables the process designer to list the ACL for a given pattern instance.


Deploy vSys Pattern

POST /resources/virtualSystemPatterns/{id}/ virtualSystemInstances/

The API enables the process designer to create a new instance of a vSysNextpattern.

Other than the basic resources to allocate the virtual servers (as the FLAVOR) thefollowing policies can be submitted once defined in the pattern:1. Placement2. Scaling3. Ifix4. Routing5. Security

Add-ons and script packages parameters must be surfaced during the deployment.

Get Virtual System Instance

GET /resources/virtualApplications/?patterntype=vsys

The API enables the process designer to obtain a list of pattern instances that areaccessible.

Start vSys Instance

PUT /resources/virtualApplications/{id}/

operationid = start

The API enables the process designer to start a pattern instance and all the virtualservers of the instance.

Stop vSys Instance

PUT /resources/virtualApplications/{id}/

operationid = stop

The API enables the process designer to stop a pattern instance and all the virtualservers of the instance.

Delete vSys Instance

DELETE /resources/virtualSystemInstances/{id}?deleteHistory={true|false}

The API enables the process designer to delete a create pattern instance of avSysNext pattern.

Get Virtual Machines for Virtual System

GET /resources/virtualSystemInstances/{id}/virtualMachines/

The API enables the Process designer to list all the virtual servers composing avSysNext pattern instance.

Appendix F. Support vSys toolkit 117

Get Virtual Machine Details

GET /resources/virtualSystemInstances/{instance_id}/virtualMachines/{vm_id}

The API enables the process designer to get the detailed information of a virtualserver member of a pattern instance.

Get Scripts of Virtual System Instance

GET /resources/virtualSystemInstances/{instance_id}/virtualMachines/{vm_id}/virtualMachineScripts/

The API enables the process designer to get the list of the script packagesregistered on the virtual server. They can be executed on the virtual server.

Get Script Details

GET /resources/virtualSystemInstances/{instance_id}/virtualMachines/{vm_id}/virtualMachineScripts

The API enables the process designer to get the details of a script package beforeexecuting it.

Execute Script on a Virtual Machine

POST /resources/virtualSystemInstances/{id}/virtualMachines/{id}/virtualMachineScripts/{id}

{ "key": "value", "key1": "value2"}

The API enables the process designer to execute an available script package againsta virtual server of a pattern instance.

Get Script Status

GET /resources/virtualSystemInstances/{instance_id}/virtualMachines/{vm_id}/virtualMachineScriptStatus

The API enables the process designer to verify the status of a script packageexecuted against a virtual server of a pattern instance.

Change the size of a virtual server of a pattern instance

POST /resources/virtualSystems/{id}/virtualMachines

The API enables the process designer to change the size (flavor) of a virtual server.

Get Snapshots of Virtual System Instance

GET /resources/virtualSystemInstances/{id}/snapshots

The API enable the process designer to list all the available snapshots for a givenpattern instance. Currently, for PureApp, it is admitted only a snapshot for eachinstance.


Create Snapshot of Virtual System Instance

POST /resources/virtualSystemInstances/{id}/snapshots

The API enable the process designer to create a snapshot for a given patterninstance. Currently, for PureApp, it is admitted only a snapshot for each instance.

Restore Snapshot of Virtual System Instance

POST /resources/virtualSystemInstances/{id}/snapshots/{id}

The API enables the process designer to restore a previously created snapshot.

Get Environment Profiles For Pattern

GET /resources/environmentProfiles

patternid={id}

The IP groups are elements contained into the Environment profile object.

The API enables the process designer to get all the environment profiles or the listof the environment profiles that can be used to deploy a specific vSysNext pattern.

Get Cloud Groups In Environment Profile

GET /resources/clouds

patternid={id}

The API enables the process designer to get all the cloud groups available for anenvironment profile or the list of the ones that can be used to deploy a vSysNextpattern from the environment profile.

Get Ip Groups Of Cloud Group In Environment Profile

GET /resources/environmentProfiles

patternid={id}

The API returns the IP groups for each cloud group.

The API enables the process designer to get the IP group that can be used todeploy a pattern instance from an Environment profile and a cloud group.

Get Flavors

GET /flavors/detail

The API runs against OpenStack NOVA. Restrictions can be applied to have certainflavors be available only for certain NOVA compute nodes.

The API enables the process designer to get the list of flavors for a given region.

Appendix F. Support vSys toolkit 119

Deploy cloud service using advanced patternsThis offering provides a wizard to deploy a vSys pattern.

You enter the following information:v Name of the virtual system instancev Target cloud group (environment profile, IP group)v Flavor that is usedv Scheduled start and end datesv Customized part properties

The offering deploys a vSys pattern based on the information you enter. You cansee the results of the deployment in Request History.

Note: The node "Additional File" is partially supported. To use it, you mustupload the file in the Pattern Designer and lock it. This way, the file isautomatically processed from the offering.

Note: Advanced deployments using an Environment Profile that has beenconfigured with the option IP addresses provided by Pattern Deployer are notsupported by this offering.


Appendix G. OpenStack Cinder Storage Volumes toolkit

Using the IBM Cloud Orchestrator Content Pack for OpenStack Cinder StorageVolumes, you can manage the lifecycle of block storage volumes through theOpenStack Cinder service. You can manage the block storage volumes in IBMCloud Orchestrator deployed instances.

Installing and configuringA good knowledge of IBM Cloud Orchestrator and of the Business ProcessManager programming model is required for using the toolkit as a softwaredevelopment kit (SDK) for building new content.

This content pack comes installed in IBM Cloud Orchestrator. This means that thetoolkit and the related offerings and actions are already available in the IBM CloudOrchestrator environment.

Before starting to use this content pack, you must:v On the region server that manages the region that you are working on, ensure

that you have:– The OpenStack Cinder service up and running.– At least one storage backend configured on Cinder and a volume type that

maps this backend. For instructions about how to configure a backend onCinder and how to create volume types, see the OpenStack documentation.

Upgrading

If you already have the toolkit installed and are upgrading from SmartCloudOrchestrator V2.3 to IBM Cloud Orchestrator V2.4, the toolkit is automaticallyupgraded. However, because of changes in the structure of the self-service catalogand new version 2.4 architecture, you must make some adjustments manually toclean up the environment so that the toolkits can run.

Make the following adjustments:v Remove the "Manage Volumes" user actionv Remove all the offerings under the category "Volume (Block Storage)

Management"

For information about removing user actions, see Managing actions.

Toolkit scenariosThere are a number of scenarios that are immediately available from the toolkit.

First, you register the required Self-Service Offerings and Instance Actions, basedon the configuration parameters specified in each of the scenarios.

The following scenarios are available:v “Creating new volumes” on page 122v “Attaching volumes” on page 123v “Detaching volumes” on page 124


http://docs.openstack.org/

v “Deleting volumes” on page 124v “Managing volumes related to a virtual system instance” on page 125

For more information about operation registration, see the following topics:v Chapter 8, “Automating the creation of categories, offerings, and user actions,”

on page 33v Orchestration workflowsv Working with self-servicev Making a process available as an orchestration action

Alternatively, you can use the Self-Service Catalog Population Tool to automaticallyregister all of them at once.

Creating new volumesYou can create new volumes in your instance.

This use case is available as a self-service offering.

To run this scenario, perform the following steps:1. Go to the Self-Service Catalog and open the Create resources for cloud service

environment category.2. Start the Create volumes offering.3. Select the region and availability zone in which you want to create your

volume.4. Select a storage service level (volume type) from among the ones defined in the

region that you have selected and click Next.5. Insert the base name of your volume, choose the number of volumes that you

want to create, provide an optional description, and enter the volume size inGB.

Note: If you create more than one volume, from the first volume, an increasingindex is added as a suffix to the volume base name.

6. Click Submit.

Table 88. Configuration

Name Create volumes

Category Create resources for cloud service environment

Process Create Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)

User interface Create Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)


Attaching volumesYou can attach a volume in your project to a virtual machine and optionally formatit as a single partition and mount it to a given mount point.

This use case is available as instance action applicable to a volume resourceinstance. The volume instance must be in available status.

To run this scenario, perform the following steps:1. Go to the volume resource view by clicking the ASSIGNED RESOURCES tab

and then clicking the Volumes icon.2. Select an available volume.3. Click the Attach volumes action.4. Select a virtual machine from the list and click Next.5. Select Format volume if you want to format and mount the volume. If so:

a. Select the virtual machine operating system: Windows or Linux.b. Select the filesystem type.c. Enter the mount point.d. Decide if you want to connect to the machine by providing credentials, or

by an SSH key stored in the keystore or by your own SSH key. ForWindows operating systems, connection using the SSH key is disabled.Click Next.

Note:

v You cannot enable this option for machines that are powered off.v This option is not supported for NIOS.

6. Check the summary and click Submit.

Note: For Linux operating systems, if you chose to mount the file system on whichyou have formatted the volume, no record in the /etc/fstab file is added. Whenyou reboot the machine, the file system is no longer mounted and you must mountit manually.

After having attached the volume, its format and mount options (if there are any)are stored in the volume metadata. Volume metadata also contains the filesystemlabel and UUID.


Name Attach volume

Instance type volumes

Process Attach Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)

User interface Attach Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)

Appendix G. OpenStack Cinder Storage Volumes toolkit 123

Detaching volumesIf necessary, you can umount and detach a volume.

This use case is available as an instance action applicable to a volume resourceinstance. The volume instance must be in in-use status.

If the volume has been previously formatted, its filesystem persistent data, such astype, label, and UUID are not deleted from the metadata.


and then clicking the Volumes icon.2. Select an in-use volume.3. Click the Detach volume action.4. If your volume is mounted, specify how you want to connect to the machine.

See the options in “Attaching volumes” on page 123.5. Check the summary and click Submit.


Name Detach volume


Process Detach Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)

User interface Detach Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)

Deleting volumesYou can delete one or more volumes that are in available status.

This use case is available as an instance action applicable to a volume resourceinstance. The volume instance must be in available status.


and then clicking the Volumes icon.2. Select one or more available volumes.3. Click the Delete volume action.4. Confirm the action.


Name Delete volume


Process Delete Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)


Managing volumes related to a virtual system instanceYou can attach or delete all the available volumes defined in the project that youare currently logged on to. You can detach the volumes in the same project that arein use by the selected virtual system instance.

This use case is available as instance action applicable to an openstackvms resourceinstance.

To run this scenario, perform the following steps:1. Go to the ASSIGNED RESOURCES tab and click the VMs icon.2. Select a virtual machine.3. Click the Manage volume action.4. Select a volume from the ones created in the project that you are currently

logged onto and in the region where your instance is hosted. When you select avolume, the action buttons are enabled or disabled depending on the status ofthe selected volume. If the volume is available, you can attach it to a virtualmachine or delete it. If the volume is in use, you can detach it from its virtualmachine.

5. Click the management action that you want to perform on the selected volume:

Attach

Select the virtual machine where you want to attach the volume.Choose whether or not to format and mount the volume. You cannotenable this option on machines that are powered off. If you chose toformat and mount the volume, select operating system type, filesystemtype, mount point, and configure the access to the machine. See“Attaching volumes” on page 123. After reviewing the summary, clickSubmit. The volume is attached, formatted, and mounted to theselected machine.

Note: For Linux operating systems, if you chose to mount the filesystem on which you have formatted the volume, no record in the/etc/fstab file is added. When you reboot the machine, the file systemis no longer mounted and you must mount it manually.

Detach

If the volume is mounted, you must configure access to the virtualmachine to unmount it before detachment. Review the summary andclick Submit. The volume is detached from the attached virtualmachine.

Delete

Review the summary and click Submit. The volume is deleted and nolonger appears in the volume list.

Note: Only volumes that are in "available" state or attached to theselected Virtual System instance are listed in the volume table.


Name Manage volume

Instance type openstackvms

Process Manage Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)

User interface Manage Volumes (SCOrchestrator_OpenstackBlockStorage_Toolkit)


Toolkit developer's referenceThis section contains reference information about the Business Process Managerartifacts exposed in the toolkit contained in the content pack. It is intended to beused by IBM Cloud Orchestrator content developers to extend the alreadyavailable scenarios or to write new scenarios leveraging the building blocksavailable from the toolkit.

The SCOrchestartor_OpenstackBlockStorage_Toolkit has dependencies against thefollowing toolkits:v SCOrchestrator_Support_vSys_Toolkit

v SCOrchestrator_Support_IaaS_Toolkit

v SCOrchestrator_Scripting_Utilities_Toolkit

v SCOrchestrator_Toolkit

v SCOrchestrator Nova Support Toolkit

The following items are the main building blocks of the toolkit:v “Environmental variables”v “Business objects”v “Human services” on page 127v “Coach views” on page 127v “Business processes” on page 128v “Integration services” on page 129

Environmental variablesSome environment variables are available so you can customize some behaviorswhen you run the use cases.

Environmental variables are defined in the toolkit in Toolkit Settings >Environment.

ATTACH_TIMEOUT

This variable specifies the maximum time, in minutes, to wait for a volumebecoming available after creation changing its status, for example from creating toavailable or from available to in-use.

Business objectsThere are Business Process Manager business objects defined in the toolkit.

AttachVolumesToInstanceRequestData

This business object is used for storing information about the volume which isbeing attached to a given instance.

CinderBreadcrumbsObject

This object is used for storing the temporary properties to manage the breadcrumbwidget that appears on the bottom part of some user interfaces.


VMCredentials

This object stores the virtual machine credentials and in case also public andprivate ssh keys.

Volume

This is the volume object. It contains info about the volume name, status, volumetype, ID, size, attachment metadata, and the server which it is attached to.

Volume_Attachment

This object stores the correspondence between the volume and the server it isattached to.

VolumeManager

This object contains the volume data, the operation which must be carried out onthis volume, the attachment data for this volume, the virtual machine object thevolume must be attached to and the region which the volume is defined on.

Volume type

This object represents the volume type or Storage Service Level.

Human servicesThere are a number of Human Services artifacts available in the toolkit.

Attach Volumes

This an entry point user interface for the "Attach volume" instance action.

Detach Volumes

This an entry point user interface for the "Detach volume" instance action.

Create Volumes

This an entry point user interface for the "Create volumes" self-service offering.

Manage Volumes

This an entry point user interface for the "Manage volumes" instance action.

Coach viewsThere are a number of coach view artifacts available in the toolkit.

Breadcrumbs

It is the breadcrumb widget that appears on the bottom part of some userinterfaces.

Generic Listener

It is the panel fragment which show the summary for detaching operation.


Password

The Password coach view renders the password as a masked input.

Server Selected Listener

This is the listener on the servers list. It disables the Next button if no servers areselected.

Vertical Two RadioButtons

A coach view for implementing a choice between two possibilities.

Volume Selected Listener

This is the listener on the volumes list. It disables the buttons which correspond toaction not compatible with the selected volume status. For example, volumes“in-use” can only be detached.

Business processesThere are a number of the business processes available in the toolkit.

Attach Volume

This process attaches a volume to a given virtual server and can, if necessary,format and mount it after the attachment. It returns the volume object after theattachment.

Attach Volume Utility

A wrapper for the Attach Volume process which provides a more usable interfacefor input parameters.

Create Volume

This process create a new volume of a given size within a given volume type on aspecified region. The volume is returned as output value if it has been availableafter a given timeout.

Create Volume Utility

A wrapper for the Create Volume process which provides a more usable interfacefor input parameters.

Create Volumes

This process loops over the number of requested volumes calling Create Volumeprocess for creating them.

Detach Volumes

This process detaches a volume and, if it is mounted, unmounts it beforedetachment.


Delete Volume

This process triggers a volume deletion and wait for it is completed.

Manage Volumes

This process create a new volume or manage an existing volume as stated by anoperationid (1=ATTACH, 2=DETACH, 3=DELETE). It is called by “ManageVolumes Offering” and “Manage Volumes Action” processes.

Integration servicesThere are a number of integration services available in the toolkit.

Attach Volume Service

This integration service attaches one or more Cinder Volumes to a given server.

Create Volume Service

This integration service creates a volume.

Delete Volume

This integration service deletes a volume.

Detach Volume

This integration service detaches a volume from a server.

Format Volume on Linux

This integration service connects to Linux machine, formats an attached volume,and mounts it to a given mount point. The volume is formatted as a singlepartition and mounted by using the script configure_volume.sh which is containedin the toolkit. It also updates the attachment metadata for the volume. The script isexecuted remotely via SSH by using the management IP address. The SSHconnection is tried for each available machine IP until it is successful. The SSHconnection can be carried out either by providing credentials or by using apre-configured privateKey.

Format Volume on Windows

This integration service connects to a Windows machine, formats an attachedvolume, and mounts it to a given mount point. The volume is formatted as asingle partition and mounted by using the script configure_volume.ps1 which iscontained in the toolkit. It also updates the attachment metadata for the volume.The script is executed remotely via SMB by using the management IP address. TheSMB connection is tried for each available machine IP until it is successful.

Get Message

This integration service gets a message from the loaded message bundle.


Get Volume

This integration service retrieves a volume given its ID.

Get Volume Attachment MetaData

This integration service returns the volume attachment data (filesystem type,mount point, filesystem label, and file system UUID) by retrieving them fromvolume metadata.

List Volume Types

This integration service retrieves all volume types defined on a given region.

List Volumes

This integration service gets the list of all volumes defined on a given region.

Load Message Bundle

This integration service loads the message bundles.

Set Volume Attachment Metadata

This integration service sets the volume attachment metadata.

Set Volume Metadata

This integration service set a volume metadata.

Umount Attached Volume Partition

This integration service connects to a Windows or Linux machine and unmountsthe mounted volume. It also updates the attachment metadata for the volume. Thescript is executed remotely via SMB or SSH by using the management IP address.The SMB or SSH connection is tried for each available machine IP until it issuccessful. The SMB or SSH connection can be carried out either by providingcredentials or by using a pre-configured privateKey (only for Linux).

Unset Volume Metadata

This integration service deletes one volume metadata.

Samples about how to use the available services and viewsThe services that are delivered as part of this content pack can be used as startingpoints and as samples for developing new content.

Using samples can give you an idea about how to invoke and combine theIntegration Services delivered in the content pack. You can clone and adapt themto better fit your needs. Once you are familiar with them, you can start creatingyour new offerings and actions.

For information about how to develop new content, see Developing IBM CloudOrchestrator content.


Importing XML into IBM Cloud OrchestratorRefer to this sample XML file that you can use, with the Self-Service CatalogPopulation Tool, to create all the Offerings and Orchestration Actions required toleverage the capabilities provided by this content pack in IBM Cloud Orchestrator.<?xml version="1.0" encoding="UTF-8"?><catalog version="2.4"><automation-categories><category><name>Deploy cloud services</name><description>A set of offerings to manage the life cycle of

cloud services</description><icon>Storage</icon></category></automation-categories>

<offerings><offering><name>Create volumes</name><description>This offering allows you to create a volume

to be used in a domain--> project.</description><icon>Storage</icon><category-name>Deploy cloud services</category-name><process><name>Create Volumes</name></process><user-interface><name>Create Volumes</name></user-interface></offering></offerings>

<instance-actions>

<instance-action selection-type="multiple"><name>Delete volumes</name><description>This action applies to available volumes in the project.

Selected volumes are to be deleted.</description><icon>Storage</icon><instance-type>volumes</instance-type><process><name>Delete Volume</name></process><tags><tag>cinder</tag><tag>available</tag></tags></instance-action>

<instance-action selection-type="single"><name>Detach volume</name><description>This action applies to volumes attached to virtual

servers and enables you to detach the volumes from thevirtual servers they are attached to.</description>

<icon>Detach</icon><instance-type>volumes</instance-type><process><name>Detach Volumes</name></process><user-interface><name>Detach Volumes</name></user-interface><tags><tag>cinder</tag><tag>in-use</tag></tags>


</instance-action>

<instance-action selection-type="single"><name>Attach volume</name><description>This action applies to volumes not attached to virtual

servers and enables you to attach the volumes to a virtual serverdefined in the same project.</description>

<icon>Storage</icon><instance-type>volumes</instance-type><process><name>Attach Volume</name></process><user-interface><name>Attach Volume</name></user-interface><tags><tag>cinder</tag><tag>available</tag></tags></instance-action>

<instance-action selection-type="single"><name>Manage volume</name><description>This action enables you to manage the volumes of a virtual server.

It provides a single view of the status of the volumes attached to thevirtual server and enables you to manage existing volumes and createnew ones on behalf of the virtual server.</description>

<icon>Storage</icon><instance-type>openstackvms</instance-type><process><name>Manage Volumes</name></process><user-interface><name>Manage Volumes</name></user-interface><tags><tag>nova</tag></tags></instance-action>

</instance-actions>

</catalog>

TroubleshootingThere are some known problems and limitations.v For NIOS, because formatting volumes is not supported, the Attach volumes

action is supported only if the Format volume option is not selected.

Logs and traces

If you receive an error, you can check the Business Process Manager log filesSystemOut.log and SystemErr.log at /opt/ibm/BPM/v8.5/profiles/Node1Profile/logs/SingleClusterMember1/.

You can find additional logs on the region server at /var/log/cinder and/var/log/nova. For errors regarding format and mount operation, a log fileformatFileSystem.log is present in the /tmp directory of the virtual machine. Errormessages are logged for all probable errors during deployment.


Error codes

Table 93. Error codes

Error code Cause

CTJCA2000E The volume was not available within the defined timeout. SeeATTACH_TIMEOUT variable. Its status might be creating or error.

CTJCA2001E A problem occurred while attempting to format and mount the attachedvolume. This is usually due to a connection problem.

CTJCA2002E A problem occurred while attempting to unmount the attached volume.This is usually due to a connection problem.

CTJCA2006E A problem occurred in updating metadata of the volume.



Appendix H. Infrastructure as a Service toolkit

The IBM Cloud Orchestrator Content Pack for Infrastructure as a Service providesa set of reusable artifacts in IBM Cloud Orchestrator to implement commoncustomers scenarios in the context of cloud infrastructure lifecycle: deployment ofvirtual servers, enablement of specific services bound to the customerinfrastructure, maintenance, and decommissioning of a service.

The main requirements addressed by this content pack are:v Support the lifecycle of cloud services fully integrated in the customer

infrastructure:– Setup or decommissioning of elements of the customer infrastructure, for

example, agents, specific software, and so on.– Consume or provide data to or from external systems, for example, CMDB,

LDAP, IPAM, and so on.– Maintenance of the cloud service enabled by means of base operations as stop

or start of the service, for example, offline, and so on.– Expose services to external systems for enterprise level integration.

v Provide a library of reusable artifacts, building blocks, that can be used toassemble the cloud automation scenarios described in the previous point (BPMartifacts) in IBM Cloud Orchestrator.

v Provide a few IBM Cloud Orchestrator Business Process Manager workingsamples implementing the most common cloud automation scenarios andincluding a large set of connected building blocks. These samples are used toenable a development model based more on customization of existing artifactsthan on the creation of new ones.

v Enable IT administrators to publish a cloud automation (service) controlling theconfiguration elements exposed to the end users by hiding, defaulting, andcustomizing the parameters of the cloud automation without needing the skillstypical of service developers.

This content pack covers only a subset of supported lifecycle scenarios. It onlyaddresses the deployment or configuration of a service, while all the interactionswith external systems (for example. CMDB, LDAP, IPAM and son on) are notincluded and will be made available in a future refresh.

To understand the available scenarios, familiarize with the following concepts:

Cloud serviceThe cloud service is the final virtual system that must be deployed andthat is configured according to the information contained in the servicetemplate. Using this content pack, you can create the following kinds ofcloud services according to the base pattern used to configure the service:v OpenStack Heat templatesv Classic Virtual System Patternsv Advanced Virtual System Patterns

Service templateThe service template is a document that describes how a given servicemust be deployed and configured. It contains all the information needed toconfigure the virtual system in terms of default parameters, optional


components, and additional management capabilities that must beconfigured on top of it. It also maintains information about which options,when a given service is instantiated, must be exposed to the final usersand which ones must be hidden and filled with default values. Servicetemplates are stored in the Storehouse library as JSON data structures.When a service template gets created, a companion self-service offering iscreated as well. The link between a service template and the correspondingoffering is represented by the ID of the offering that is stored as part of thetemplate name.

Flavor

The flavor is a sort of logical template that defines the virtual hardwareand environmental characteristics of the instance to be deployed. At alower level, a flavor is an appropriate combination of an EnvironmentProfile, a Cloud Group, an IP Group, and an OpenStack flavor that, onceselected, are used to instantiate the virtual system. This element has beenintroduced to simplify the user interaction when creating the offering (andits associated template) and when triggering it.

After the installation of this content pack, a number of default flavors areavailable, represented by a basic combination of the first EnvironmentProfile, Cloud Group, IP Group and the first three OpenStack flavorsdefined in the environment. Based on the organization of the environmentwhere this content pack gets installed, such default list of flavors mightneed to be updated. Instructions about how to do this are provided later inthis document.

Note: Flavors are available only when you create cloud services thatleverage Virtual System Classic patterns.

Offering to deploy a cloud serviceThis is the self-service offering created along with a service template andthat, once triggered, drive the deployment of the service as described bythe template. This offering is always bound to the same pair of HumanService and Business Process Definitions. The Human Service is able toautomatically select the template corresponding to the triggered offeringand to pass it to the service deployment and configuration logic.

Supported versionsv IBM Endpoint Manager versions 9.0 and 9.1v IBM Tivoli Storage Manager version 6.2v IBM Tivoli Monitoring version 6.3 Fix Pack 2

Note: Only Linux x86 machines are supported as nodes of the deployed systems.

Installing and configuringA good knowledge of IBM Cloud Orchestrator and of the Business ProcessManager programming model is required for using the toolkit as a softwaredevelopment kit (SDK) for building new content.

This content pack comes already installed in IBM Cloud Orchestrator. This meansthat the toolkit and the related offerings and actions are already available in theIBM Cloud Orchestrator environment. However, a set of configuration actions mustbe performed before you use the content pack.


From the IBM Cloud Orchestrator Catalog, download the external version of thiscontent pack because it contains a few additional artifacts required to fullyconfigure it. You can download the content pack here: http://www.ibm.com/software/ismlibrary?NavCode=1TW10SO27.

After you download the compressed file from the IBM Cloud Orchestrator Catalog,extract the following archive that contain prebuilt template packages to install andconfigure the management agents supported by this content pack:v itm-client.zip

v iem-client.zip

v tsm-client.zip

You must customize these files by adding the necessary agent installation packagesand then publishing to a reachable web server. See “Customizing the installationpackages of the management agents” on page 138.

Before starting to use this content pack, you must:v If it was never done in your environment before, run the Initialize the Data

Persistence Service offering located in the Infrastructure management servicescategory. This is required to initialize the IBM Cloud Orchestrator Content Packfor Persistency Services, which this toolkit depends on.

v Register at least one management server in the environment, from among thesupported ones. Different offerings must be used for this registration activitydepending on the kind of the management server configuration to create.To register a management server configuration for IBM Tivoli Monitoring andIBM Tivoli Storage Manager, run the Register a management server offeringlocated in the Infrastructure management services category.To register a management server configuration for IBM Endpoint Manager, runthe Register IBM Endpoint Manager Server offering located in theInfrastructure management services category.

v Review and customize the list of available default IBM Endpoint Managercompliance groups, Tivoli Storage Manager policies, and backup frequencies.

v If you want to enable the Backup & Restore capability, ensure that a workingYUM repository is correctly configured in the virtual images that you are goingto deploy. It must reference the operating system package repository. This isrequired in case the deployed instances miss some of the operating systemdependencies required for the installation of the management agents.Alternatively, you can specify an explicit YUM repository to be configured onthe deployed systems instead of requiring an existing one. This requires somecustomization to be applied to the toolkit.

v Ensure that the unzip utility is installed in the virtual images that you are goingto deploy. This is required for the installation of the management agents.

v Ensure that the virtual images included in the pattern being deployed exist inthe OpenStack region where the pattern is deployed.

v If you are going to configure additional volumes in your cloud service, ensurethat the OpenStack Cinder component is correctly configured and that at leastone volume type is available.

Specifically for cloud services that leverage Virtual System Classic patterns:v You can customize the user interaction type behavior that can be modified

through the user_interaction_type toolkit variable. See user_interaction_typein “Environmental variables” on page 149.

Appendix H. Infrastructure as a Service toolkit 137

http://www.ibm.com/software/ismlibrary?NavCode=1TW10SO27

http://www.ibm.com/software/ismlibrary?NavCode=1TW10SO27

v If the user interaction type has been set to simplified, the definition of theflavors must be customized to fit the resources available in the environment .See “Customizing the list of available flavors” on page 140.

v If the user interaction type has been set to simplified, ensure that all thepatterns that you are going to deploy through this solution have the parametersof each part be assigned a default value and are locked. Both at offering creationtime and at offering deploy time it is not possible to customize them and if arequired parameter does not have a value the deploy fails. Be aware that if thepattern contains parts with multiple NICs, all of them are assigned to the sameIP group.

Upgrading


Make the following adjustments:v Remove all the offerings under the Manage Cloud Services category. See

Self-service offerings.v In moving from SmartCloud Orchestrator V2.3 to IBM Cloud Orchestrator V2.4,

several changes have been implemented in the internal architecture of theproduct; the main one being the removal of the dependency against the Chefinfrastructure for installing software modules and its replacement with the IBMEndpoint Manager one. As a consequence, cloud services definitions (forexample, offerings) created with the version 2.3 toolkit, do not work in IBMCloud Orchestrator V2.4. You must manually remove the old definitions(offerings) and recreate new ones through the 2.4 version of the toolkit.

Customizing the installation packages of the managementagents

Three archives are provided to handle the installation and configuration of themanagement agents on the deployed systems.

Before using these archives, you must customize them to fit specific deploymentneeds:

iem-client.zip

The IBM Endpoint Manager Client installable file, for example,BESAgent-XXXX.rpm, must be added to the package. You can find the list ofIBM Endpoint Manager packages at http://support.bigfix.com/bes/install/downloadbes.html.

Here is the typical content of the iem-client.zip file after it has been fullycustomized:Archive: iem-agent.zip

BESAgent-9.0.649.0-rhe5.x86_64.rpminstall-iem-client.shreadme.txt

itm-client.zip

Export the IBM Tivoli Monitoring agent bundle for your platform into atemporary directory and add its content to a compressed file. This


http://support.bigfix.com/bes/install/downloadbes.html

http://support.bigfix.com/bes/install/downloadbes.html

compressed file must also contain the parent directory where the bundlefiles are located. Then, embed it in the itm-client.zip file. Finally, modifythe reference to the name of the created compressed file, that is specifiedby the lnx_itmAgentBundle shell variable, inside the install-itm-client.sh script.

The IBM Tivoli Monitoring agent bundles can be extracted, from the fromthe IBM Tivoli Monitoring server machine, using the tacmd exportBundlescommand. For documentation about the command, seehttp://www.ibm.com/support/knowledgecenter/SSTFXA_6.3.0/com.ibm.itm.doc_6.3/cmdref/exportbundles.htm.

For example, to extract the agent bundle for the Linux x86 platform, youcan use the following CLI:tacmd exportBundles -e c:\export -o LOCAL -t lz -p lx8266

If you need to handle the decommissioing flow of the IBM TivoliMonitoring agent, then the IBM Tivoli Monitoring Tivoli EnterpriseServices User Interface Extensions (namely, the tacmd CLI) componentmust be installed with the IBM Tivoli Monitoring agent. To do this, extractthe IBM Tivoli Monitoring CLI component for the platform for which youneed it into a temporary directory and add its content into a compressedfile. This compressed file must also contain the parent directory where thebundle files are located. Then, embed it in the itm-client.zip file. Finally,modify the reference to the name of the created compressed file, that isspecified by the lnx_itmCliBundle shell variable, inside theinstall-itm-client.sh script. For example, to extract the CLI bundle forthe Linux x86 platform, use the following command:tacmd exportBundles -e c:\export -o LOCAL -t ue -p lx8266

The KSH shell component must be available on the nodes where the IBMTivoli Monitoring agent must be installed. The agent installation script triesto find the KSH installable RPM package among the files contained in theitm-client.zip file. If that component is not available by default on thetarget systems, the corresponding RPM file can be retrieved from theoperating system package repository and added to the compressed file.Once there, it is automatically installed before the IBM Tivoli Monitoringagent.

Here is the typical content of the itm-client.zip file after it has been fullycustomized:Archive: itm-agent.zip

install-itm-client.shksh-20100621-19.el6.x86_64.rpmlz_063002000_lx8266.zipreadme.txtsilent_config.txtue_063002000_lx8266.zip

tsm-client.zip

Download the IBM Tivoli Storage Manager agent bundles for yourplatform from the IBM site and add them into this archive. For a list of theIBM Tivoli Storage Manager agent packages, see http://www-01.ibm.com/support/docview.wss?&uid=swg24034630.

Select the package for your platform and accept the terms and conditions.Download the .tar file containing the agent bundle. For example, for the


http://www.ibm.com/support/knowledgecenter/SSTFXA_6.3.0/com.ibm.itm.doc_6.3/cmdref/exportbundles.htm

http://www.ibm.com/support/knowledgecenter/SSTFXA_6.3.0/com.ibm.itm.doc_6.3/cmdref/exportbundles.htm

http://www-01.ibm.com/support/docview.wss?&uid=swg24034630

http://www-01.ibm.com/support/docview.wss?&uid=swg24034630

Linux x86 platform, download the file: 6.2.5.0-TIV-TSMBAC-LinuxX86.tar.The actual name may change according to the version available at themoment you download it.

After the package has been locally downloaded, it must be extracted into atemporary directory and its content added to a compressed file. Then, thiscompressed file must be added to the tsm-client.zip file. Finally, thereference to the created compressed file, that is assigned to theTSM_PACKAGE shell variable, inside the install-tsm-client.sh scriptmust be updated to match the name of the created compressed file.

Here is the typical content of the tsm-client.zip file after it has been fullycustomized:Archive: tsm-agent.zip

dsm.opt.templatedsm.sys.templateinstall-tsm-client.shreadme.txtTSM-6.2.zip

where TSM-6.2.zip contains all the files that have been extracted from thetar file containing the agent bundle. In this example, 6.2.5.0-TIV-TSMBAC-LinuxX86.tar.

Afterwards, you must upload these archives to a web server where they can bedownloaded from the deployed systems. Network connectivity between thedeployed systems and the web server must be ensured to allow a successfulinstallation and configuration of the agents.

Making the toolkit writableBy default, after it is installed, the SCOrchestrator_IAAS_Assets toolkit can beaccessed in read-only mode through the Business Process Designer. To apply thecustomization described in the following sections, you must make the toolkitwriteable.

To make the toolkit writable:1. Open the Business Process Designer tool.2. In the Toolkits tab, select the SCOrchestrator_IAAS_Assets toolkit and click

Manage.3. Select the Allow users to update the toolkit check box.

Customizing the list of available flavorsTo modify the list of available flavors, use the Business Process Manager ProcessDesigner Tool.

Open the SCOrchestrator_IAAS_Assets toolkit and select the BuildServiceFlavorsGeneral System Service.

This service generates the definitions of the available flavors. To add a new flavor,you must add a new block calling the BuildServiceFlavor Integration Service bycloning an existing one and chaining it to the already existing ones. Then, in theData Mapping > Input Mapping section, you can to customize the definition ofthe new flavor by specifying the name of the Environment Profile, Cloud Group,IP Group, and OpenStack flavor that are associated with it.

You can also remove or modify an already existing flavor similarly.


When adding a new flavor, be sure to copy and past an already-defined flavorinstead of adding a new block from scratch so that it inherits all the requiredconfigurations.

Afterwards, save the changes to make them available in IBM Cloud Orchestrator.

Customizing the list of IBM Tivoli Storage Manager policiesand backup frequencies

To modify the list of backup policies and frequencies, use the Business ProcessManager Process Designer Tool.

The lists, which you can see in the UI when you configure the Backup and Restorecapability, are defined in the Extract Params block of the Config Backup andRestore Human Service. Each name of a displayed backup policy is mapped intoan IBM Tivoli Storage Manager Policy domain. You must update this list to reflectthe values of the backup policy domains defined in the IBM Tivoli StorageManager server available in the environment.

The same applies for the backup frequencies. Each name of a displayed backupfrequency is mapped into a Tivoli Storage Manager backup frequency. This listmust be updated to reflect the values of the backup frequencies defined in theTivoli Storage Manager server available in the environment.

If policies and backup frequencies are not correctly defined in the Tivoli StorageManager server, the installation and registration of the Tivoli Storage Manageragent fail.

Customizing the list of available IBM Endpoint Managercompliance groups

To modify the list of compliance groups, use the Business Process Manager ProcessDesigner Tool.

This list, which you can see in the UI when you configure the Security andCompliance capability, is defined in the Config Security & Compliance HumanService. To access and modify the definition of the list, open the Variables sectionof the Human Service and select the availableGroups private variable.

Each name of a displayed compliance group is mapped into an IBM EndpointManager client setting that is set on the agents once installed.

You must update this list to reflect the values of the properties defined in the IBMEndpoint Manager server available in the environment to define the relatedautomatic groups.

More specifically, when a compliance groups is selected, a client setting called_BESCLIENT_GROUP_NAME is created on each agent with a value equal to the one ofthe selected compliance groups. To have these agents automatically subscribed toan IBM Endpoint Manager automatic group when creating that group, set theproperty Relevance Expression to is true and specify the following expression:exists setting "_BESClient_GROUP_NAME" of client AND value of setting

"_BESClient_GROUP_NAME" of client = "MY_VALUE"

This way, the group includes any computer that has the _BESCLIENT_GROUP_NAMEsetting set to MY_VALUE where MY_VALUE is the value associated to one of the defined


compliance groups.

Customizing the YUM repository for the deployed systemsBy default, when the IBM Tivoli Storage Manager agent must be installed on thedeployed systems, a YUM repository referencing the operating system installpackages is required to install any missing dependency.

Alternatively, an explicit YUM repository can be configured at runtime to thedeployed system.

To enable this capability, you must use the Business Process Manager ProcessDesigner Tool to customize the Config Backup and Restore Human Service.

The Extract Params block must be edited by adding a Javascript snippet similar to:if(tw.local.yumRepoUrl == null) {

tw.local.yumRepoUrl = "http://162.168.2.3/repo/rhel";}

where the value assigned to the tw.local.yumRepoUrl variable, must refer to theYUM repository of the operating system packages available in the environment.

Afterwards, the installation and configuration of the IBM Tivoli Storage Manageragent leverages that repository to install any missing dependency.

Configuring an SMTP server in IBM Cloud OrchestratorTo use the email notification feature, you must configure Business Process Managerto use an appropriate SMTP relay server inside your organization. Contact yourmail server administration to obtain the host name of the SMTP server.

Business Process Manager does not support any type of SMTP authentication ornon-standard SMTP ports.

Create a file called 100Custom.xml with the following content:<properties>

<server merge="mergeChildren"><email merge="mergeChildren">

<smtp-server merge="replace">$SMTP_HOST_NAME</smtp-server></email>

</server></properties>

Replace $SMTP_HOST_NAME with your SMTP server host name.

Put the 100Custom.xml file in the directory: /opt/ibm/BPM/v8.5/profiles/DmgrProfile/config/cells/PCCell1/nodes/Node1/servers/SingleClusterMember1/process-center/config

If the file is already there, edit it adding or updating the server/email section withthe provided information. Afterward, restart the Business Process Manager serverusing the service bpm restart command.



The following items are the main building blocks of the toolkit:v “Creating an offering to deploy a cloud service”v “Decommissioning a cloud service” on page 146v “Deleting an offering to deploy a cloud service” on page 146v “Deploying a cloud service” on page 147v “Registering a management server configuration” on page 147v “Unregistering a management server configuration” on page 148v “Modifying a management server configuration” on page 148

Creating an offering to deploy a cloud serviceYou can configure and create a new entry in the self-service catalog that can laterbe used to trigger the deployment of a new service in the cloud.

Through this offering, the Catalog Editor can compose a new service bycustomizing a set of basic deployment options and specifying the additionalmanagement capabilities that must be enabled in the deployed instance. At the endof this process, a new self-service offering is created in the catalog that can be usedto immediately trigger the deployment of the configured system, by exposing auser interface with a limited set of customization options.

To run this scenario, perform the following steps:1. In the Self-service user interface, click SELF-SERVICE CATALOG and open the

Design and create cloud service offerings category.2. Start the Create an offering to deploy a cloud service offering.3. After the offering starts:

a. If at least one of the supported management servers (IBM TivoliMonitoring, IBM Endpoint Manager, IBM Tivoli Storage Manager, orOpscode Chef) is not registered in the environment, you receive a messagespecifying that it is not possible to configure the correspondingmanagement capability. Additionally, you cannot enable the correspondingcapability for the cloud service being configured in the user interface.

b. Specify the general options related to the offering that is created:v Provide a name and optional description.v Select an icon to assign to the offering.v Specify the category under which the offering is created.v Specify whether an approval is requested for deploying the offering.

c. If the approval has been enabled, select the role of the users that receive theapproval request when the offering is triggered. Only the users having thatrole in the same project of the logged-on user triggering the offering receivethe request and have the possibility of approving it.

d. Provide your own OpenStack Heat template or select the pattern to deployfrom the available patterns.

e. If you provide the Heat template:1) Select the Region.2) Enter the Heat template.3) Configure the Heat template.


f. If you select a Classic Virtual System Pattern and the active user interactiontype has been set to simplified:1) Select a Flavor to size the instance to deploy. The list of available Flavors

depend on the customization done in the environment where thiscontent pack is installed.

2) Optionally, specify whether the selected Flavor can be shown to the finalusers and modified by them by checking Hide this configuration optionfrom users.

g. If you select a Classic Virtual System Pattern and the active user interactiontype has been set to full:1) Configure the general parameters of the selected pattern, such as, the

Environment Profile.2) For each part of the selected pattern:

a) Specify the Cloud Group and the Flavor.b) For each virtual NIC, specify the IP Group and, if required, the IP

address and host name.c) Specify any custom parameter associated to the part.d) Specify any custom parameter for the script packages associated to

the part.

Note: For all the parameters, you can specify whether they can beshown to the final users and modified by them by checking Hide thisconfiguration option from users.

h. If you select an Advanced Virtual System Pattern:1) Select the Deployment Configuration.2) Configure each node.

i. After you set the options related to the chosen pattern, specify thecredentials to be used to remotely accessing the virtual servers beingdeployed:v If you select Connect through SSH keys:

– The administrative user– An OpenStack key pair name or your own private key

Note: To create suitable key pairs to allow access to virtual servers youcan use the offering Register a key to enable access to virtual serversavailable in the Deploy cloud services category.

v If you select Connect through Credentials:– The administrative user name– The password of the administrative user

j. Select the management and additional capabilities to be configured in thedeployed system:v Security and Compliance: Enabled only if at least one IBM Endpoint

Manager server has been registeredv Backup and Restore: Enabled only if at least one IBM Tivoli Storage

Manager server has been registeredv Monitoring: Enabled only if at least IBM Tivoli Monitoring server has

been registeredv Storage Volumes: Through the OpenStack Cinder service.v Additional Software Installation: Enabled only if at least one Opscode

Chef Server has been registered


k. For each of the management services enabled, a page is displayed whereyou can configure them:

Security and ComplianceSpecify the location of the installation package of the agent, thecustomized iem-agent.zip file. Select the IP address or host name ofthe IBM Endpoint Manager server. Additionally, you can select anoptional compliance group, representing the name of an IBMEndpoint Manager automatic group where the installed agents aresubscribed.

Backup and RestoreSpecify the location of the installation package of the agent, thecustomized tsm-agent.zip file. Select the IP address or host nameof the IBM Tivoli Storage Manager server. Optionally, you canassociate the node to a backup policy and define the backupfrequency.

MonitoringSpecify the location of the installation package of the agent, thecustomized itm-agent.zip file. Select the IP address or host name ofthe IBM Tivoli Monitoring server.

Storage VolumesThe size of the volume to be created and attached to the systemmust be provided along with the volume type, the file system type,and the mount point. You can specify if they must be exposed tousers after the created offering is triggered.

Note: You can only create and attach volumes to the deployedservice when you select a flavor that refers to KVM cloud groups.

Additional Software InstallationSelect the Chef server. This step is optional and is required only ifmore than one Chef servers are registered in the environment. Thenspecify the software modules to be installed on specific parts of theselected pattern. For each entry, configure the correspondingparameters for the specified software.

4. Review the summary information and submit the operation. Click Create tostart the creation of the offering. At the end of the operation, a new self-serviceoffering is available under the category specified.

Table 94. Typical configuration of the offering

Name Create an Offering to Deploy a Cloud Service

Category Design and create cloud service offerings

Process Create Service Deployment Template (SCOrchestrator_IAAS_Assets)

User interface Create Service Template (SCOrchestrator_IAAS_Assets)


Decommissioning a cloud serviceYou can decommission a cloud service from the system.

In the context of this operation, any agent installed on top of the virtual machinesof the service are stopped and unregistered from the corresponding managementserver. Each attached storage volume is detached and deleted from the system.Then, the virtual system instance of the service gets removed.

Note: Because of a defect in the IBM Endpoint Manager V9.0 application, thedecommissioning of the IBM Endpoint manager agents does not remove thedefinition of the computer from the IBM Endpoint Manager server.


Manage the lifecycle of cloud services category.2. Start the Decommission a Cloud Service offering.3. After the offering starts:

a. Select the service instance to decommission.b. Review the summary information and submit the operation. When you click

Delete, the operation starts and its outcome is available in My Requests.

At the end of the operation, a notification report with the detailed outcome of theoperation is delivered to the user that requested the operation, provided that avalid email address and that a working Simple Mail Transfer Protocol (SMTP)server have been configured with IBM Cloud Orchestrator.


Name Decommission a Cloud Service

Category Deploy cloud services

Process Decommission Cloud Service (SCOrchestrator_IAAS_Assets)

User interface Decommission Cloud Service (SCOrchestrator_IAAS_Assets)

Deleting an offering to deploy a cloud serviceYou can remove an entry from the Self-Service Catalog created through the Createan Offering to Deploy a Cloud Service offering along with its template stored inthe Storehouse.


Design and create cloud service offerings category.2. Start the Delete an Offering to Deploy a Cloud Service offering.3. After the offering starts:

a. Select the offering to be removed.b. Submit the operation.

At the end of the operation, the offering and its associated template is removedfrom the system.


Name Delete an Offering to Deploy a Cloud Service

Category Design and create cloud service offerings


Table 96. Typical configuration of the offering (continued)

Process Delete Service Deployment Template (SCOrchestrator_IAAS_Assets)

User interface Delete Service Deployment Template (SCOrchestrator_IAAS_Assets)

Deploying a cloud serviceYou can deploy a cloud service by using the offering created through the Create anOffering to Deploy a Cloud Service offering.


Deploy cloud services category2. Start the offering.3. After the offering starts:

a. Specify a name for the instance that is being created.b. Based on the configuration of the offering, the user is asked to review and

provide a value for all those parameters that have been marked to beshown to the final users. Review and if necessary, assign a different value tothose parameters.

4. Review the summary info and submit the operation. Click Deploy to start theoffering.

At the end of the operation, a new virtual system instance is available andconfigured according to the options you specified.

If an approval has been enabled for the selected offering, the deployment andconfiguration of the service occur only if the request gets approved. Morespecifically, all the users matching the approver selection criteria receive adedicated request in their inbox that they can approve or reject. Based on thisdecision, the actual deployment of the service occurs or is rejected by the system.The deployment flow is suspended until one of those users takes ownership of therequest and accepts or rejects it.

At the end of the operation, a notification report with the detailed outcome of theoperation is delivered to the user that requested the operation, provided that avalid email address and that a working Simple Mail Transfer Protocol (SMTP)server have been configured with IBM Cloud Orchestrator.

Registering a management server configurationYou can register the basic configuration parameters in IBM Cloud Orchestrator toaccess an IBM Tivoli Monitoring or IBM Tivoli Storage Manager server.


Infrastructure management services category.2. Start the Register a management server offering.3. After the offering starts:

a. Specify the type of server configuration to be created: IBM TivoliMonitoring or IBM Tivoli Storage Manager.

b. Specify the server host name or IP address.c. Specify the user name of an administrative user to connect to the server.d. Specify the password for the user specified.


e. Submit the offering.


Name Register a management server

Category Infrastructure management services

Process Register Management Server (SCOrchestrator_IAAS_Assets)

User interface Register Management Server (SCOrchestrator_IAAS_Assets)

Unregistering a management server configurationYou can unregister the basic configuration parameters from IBM CloudOrchestrator to access a configured IBM Tivoli Monitoring or IBM Tivoli StorageManager server.


Infrastructure management services category.2. Start the Unregister a management server offering.3. After the offering starts:

a. Select the server configuration to be removed.b. Submit the offering.


Name Unregister a management server


Process Unregister Management Server (SCOrchestrator_IAAS_Assets)

User interface Unregister Management Server (SCOrchestrator_IAAS_Assets)

Modifying a management server configurationYou can update the basic configuration parameters in IBM Cloud Orchestrator toaccess a configured IBM Tivoli Monitoring or IBM Tivoli Storage Manager server.


Infrastructure management services category.2. Start the Modify a management server offering.3. After the offering starts:

a. Select the server configuration to modify.b. Review and modify the server connection port.c. Review and modify the username to connect to the server.d. Review and modify the password for the user specified.e. Submit the offering.


Name Modify a management server


Process Modify Management Server (SCOrchestrator_IAAS_Assets)

User interface Modify Management Server (SCOrchestrator_IAAS_Assets)


Toolkit developer's referenceThis section contains reference information about the Business Process Managerartifacts exposed in the toolkit contained in the content pack. It is intended to beused by IBM Cloud Orchestrator content developers to extend the alreadyavailable scenarios or to write new scenarios leveraging the building blocksavailable from the toolkit.

The following items are the main building blocks of the toolkit:v “Environmental variables”v “Business processes definitions”v “Human services” on page 150v “Coach views” on page 151v “Integration services” on page 151v “General system services” on page 151



storehouse_iaas_templates

This variable contains the default path in the Storehouse library where all theconfiguration templates are stored. Never modify the value of this variable. Itsdefault value is set to /storehouse/sco_iaas_templates/.

user_interaction_type

This variable allows to switch the UI to configure an offering and to deploy it fromthe simplified form into the full one. Allowed values are simplified or full. Thedefault value is simplified. The value of this variable has effect only when youselect Virtual System Patterns (Classic).

Business processes definitionsThere are a number of public Business Process Manager business objects defined inthe toolkit.

Create Service Deployment Template

This is the business process that handles the creation of a deployment templateand the creation of a new self-service offering associated with the template.

Decommission a Cloud Service

This is the business process that handles the decommission of a service.


Delete Service Deployment Template

This is the business process that handles the deletion of a service deploymenttemplate and its associated self-service offering, if any.

Run Service Deployment Template

This is the business process that handles the entire end-to-end deployment flowaccording to the configuration specified in the template.

Register Management Server

This is the business process that handles the registration of the management serverconfiguration of the supported type (IBM Tivoli Monitoring or IBM Tivoli StorageManager).

Modify Management Server

This is the business process that handles the modification of the registeredmanagement server configuration.

Unregister Management Server

This is the business process that handles the unregistration of the registeredmanagement server configuration.


Create Service Template

This is the Human Service that is used to collect all the parameters required tocreate a new service deployment template and its associated self-service offering.

Decommission a Cloud Service

This is the Human Service used to collect the information for decommissioning acloud service.

Delete Service Deployment Template

This is the Human Service used to collect the information for deleting an alreadyexisting deployment template and its associated self-service offering.

Deploy Service Template

This is the Human Service used to collect all the parameters needed to run thedeployment of a service template. This service is able to automatically select thedeployment template for which the offering associated to it has been created andto make a request to the user for only the subset of parameters that have not beenmarked as hidden by the operator who created it.


Register Management Server

This is the Human Service used to collect the information of the managementserver configuration (IBM Tivoli Monitoring or IBM Tivoli Storage Manager).

Modify Management Server

This is the Human Service used to modify the registered management serverconfigurations.

Unregister Management Server

This is the Human Service used to unregister the management serverconfigurations.

Coach viewsNo public coach views are available.

Integration servicesNo public integration services are available.

General system servicesNo public general system services are available.


Using samples can give you an idea about how to invoke and combine theIntegration Services delivered in the content pack. You can clone and adapt themto better fit your needs. After you are familiar with them, you can start creatingyour new offerings and actions.

For information about how to develop new content, see Chapter 5, “Developingtoolkit and application content,” on page 9.

TroubleshootingThere might be some problems or limitations.

If there is a failure running a scenario, the information available on the userinterface or through the mail report might not be enough to completely understandthe root cause of the failure. If this is the case, review the Business ProcessManager and IBM Cloud Orchestrator traces to see more specific error messages.For more information, see “Troubleshooting.”



Appendix I. IBM Endpoint Manager toolkit

With IBM Cloud Orchestrator Content Pack For IBM Endpoint Manager you canuse your existing IBM Endpoint Manager environment from IBM CloudOrchestrator and vice versa.

This content pack includes the following aspects of IBM Endpoint Manager andIBM Cloud Orchestrator:v As an IBM Cloud Orchestrator user, you can extend IBM Cloud Orchestrator

features on the IT management space by means of IBM Endpoint Manager. IBMCloud Orchestrator leverages IBM Endpoint Manager as a service to completecloud computing scenarios.

v As an IBM Endpoint Manager user, you can include a self service front end onyour environment: IBM Cloud Orchestrator self service catalog exposes featuresbuilt on IBM Endpoint Manager infrastructure as self service offerings.

v As an IBM Endpoint Manager user, you can directly manage, from IBMEndpoint Manager console, virtual machines deployed through IBM CloudOrchestrator by selecting and filtering IBM Endpoint Manager computerscorresponding to virtual machines deployed through IBM Cloud Orchestrator.

Supported versionsv IBM Endpoint Manager versions 9.0 and 9.1

Installing and configuringTo use this content pack, you must have knowledge of the IBM Endpoint Managerinfrastructure and its administration.

This content pack comes installed in IBM Cloud Orchestrator. This means that thetoolkit and the related offerings and actions are already available in the IBM CloudOrchestrator environment.

If it was never done in your environment before, run the Initialize the DataPersistence Service offering located in the Infrastructure management servicescategory. This is required to initialize the Persistence engine used by this toolkit.

Register at least one IBM Endpoint Manager Server configuration into IBM CloudOrchestrator. For more information, see “Registering IBM Endpoint Managerserver” on page 156.

Upgrading


Make the following adjustments:v Remove the Register Unlinked IEM Agents user action. See User actions.


v Remove all the offerings under the IBM Endpoint Manager ConfigurationServices and IBM Endpoint Manager Management Services categories. SeeSelf-service offerings.

v In moving from SmartCloud Orchestrator V2.3 to IBM Cloud Orchestrator V2.4,the persistence mechanism for storing information about registered IBM servershas been changed from Storehouse to the Persistency Services toolkit. Because ofthis, the information about registered IBM Endpoint Manager servers is lostwhen you upgrade to IBM Cloud Orchestrator V2.4. You must manuallyreregister your IBM Endpoint Manager servers in the upgraded environment.Virtual machines deployed in the V2.3 environment and hosting an IBMEndpoint Manager agent are managed by the new version of the toolkits afterthe upgrade to the 2.4 version.


This toolkit is a base dependency of both the IBM Cloud Orchestrator ContentPack for IBM Endpoint Manager Software Distribution and IBM CloudOrchestrator Content Pack for IBM Endpoint Manager Patch Management contentpacks. It provides a set of infrastructure management base offerings and all thebuilding blocks, in terms of Integration Services, General System Services, HumanServices, and Business Process Definitions, that enable the operation flows of thesecontent packs. The only operational flow here is represented by the “Deploy fixlet”action.

The following scenarios are available:v “Installing IBM Endpoint Manager agent on a provisioned virtual machine”v “Registering unlinked virtual servers” on page 155v “Registering IBM Endpoint Manager server” on page 156v “Unregistering IBM Endpoint Manager server” on page 156v “Modifying an IBM Endpoint Manager server” on page 157v “Deploy an IBM Endpoint Manager Fixlet Action to a list of computers” on page

157

Installing IBM Endpoint Manager agent on a provisionedvirtual machine

In the context of this toolkit, the integration service “InstallIEMAgentOnVM” isavailable to manage the installation of an IBM Endpoint Manager agent. It can bedirectly linked in the context of a custom process or service to orchestrate theinstallation and configuration of an IBM Endpoint Manager agent.

From the final user's point of view, there are two different ways of handling theinstallation of IBM Endpoint Manager agents on virtual machines deployedthrough IBM Cloud Orchestrator:v Through the “Deploy a Cloud Service with Additional Software” offering,

available in the IBM Cloud Orchestrator Content Pack for IBM EndpointManager Software Distribution. For more details, see the documentation of thatcontent pack.

v Through manually installing the agent, for example through a custom script, andand then linking it to the IBM Cloud Orchestrator virtual machines through the“Register unlinked virtual servers” offering.


Registering unlinked virtual serversYou can discover and re-configure unlinked IBM Endpoint Manager agents locatedon IBM Cloud Orchestrator virtual machines.


When this offering is submitted, the system inspects the selected virtual systeminstances for IBM Endpoint Manager agents not yet linked to IBM CloudOrchestrator. For each unlinked agent, it triggers a reconfiguration action.

At the end of the operation, a report with the detailed outcome of the operation isdelivered to the user who requested the operation, provided that there is a validemail address and that a working Simple Mail Transfer Protocol (SMTP) serverhave been configured with IBM Cloud Orchestrator.

To run this scenario, perform the following steps:1. Click SELF-SERVICE CATALOG and open the Infrastructure management

services category.2. Start the Register unlinked virtual servers offering.3. When the offering starts:

a. Select an IBM Endpoint Manager Server Configuration. This step is optionaland appears in the UI only if more than one IBM Endpoint Manager serverconfiguration are registered on the system. If just one configuration isavailable, it is used automatically.

b. Submit the operation.

After a while, you receive a message in your Inbox where all the unlinked agentsare shown and where you can select which of them must be re-configured. Oncecomplete, the operation continues re-configuring the selected agents.

The configuration of an IBM Endpoint Manager Agent to link it to a IBM CloudOrchestrator instance consists in setting the following client setting to the agent:sco_resource_id. This property specifies the ID of the OpenStack virtual machinewhere the agent is located.

AFter that property has been set, IBM Cloud Orchestrator can link that specificIBM Endpoint Manager agent to the hosting OpenStack virtual machine.


Name Register unlinked virtual servers


Process Takeover IEM Agents(SCOrchestrator_IEM_Integration_Toolkit)

User interface Takeover IEM Agents(SCOrchestrator_IEM_Integration_Toolkit)

Appendix I. IBM Endpoint Manager toolkit 155

Registering IBM Endpoint Manager serverYou can register the basic configuration parameters in IBM Cloud Orchestrator toaccess an IBM Endpoint Manager server.



services category.2. Start the Register IBM Endpoint Manager Server offering.3. When the offering starts:

a. Specify the IBM Endpoint Manager server host name or IP address.b. Specify the user name to connect to the IBM Endpoint Manager server.c. Specify the password for the user.d. Specify if the system must perform a connection check against the given

IBM Endpoint manager server and, in case of a failure, to abort theoperation.

e. Submit the offering.

Note: The credentials specified through this operation are the ones used by IBMCloud Orchestrator to contact the IBM Endpoint Manager infrastructure and totrigger all the requested operation. It is important that this user, corresponding toan operator console on the IBM Endpoint Manager side, has enough permissionsto access the resources that must be managed through IBM Cloud Orchestrator. Anoperator specifically dedicated to the IBM Cloud Orchestrator-triggered operationscan be defined in the IBM Endpoint Manager infrastructure and it must be givenaccess only to the content sites and computers that must be managed through IBMCloud Orchestrator so as to limit its scope.


Name Register IBM Endpoint Manager Server


Process Register IEM Server(SCOrchestrator_IEM_Integration_Toolkit)

User interface Register IEM Server(SCOrchestrator_IEM_Integration_Toolkit)

Unregistering IBM Endpoint Manager serverYou can to unregister the basic configuration parameters from IBM CloudOrchestrator to access a configured IBM Endpoint Manager server.



services category.2. Start the Unregister IBM Endpoint Manager Server offering.3. When the offering starts:

a. Select the IBM Endpoint Manager server configuration to be removed.b. Submit the offering.



Name Unregister IBM Endpoint Manager Server


Process Unregister IEM Server(SCOrchestrator_IEM_Integration_Toolkit)

User interface Unregister IEM Server(SCOrchestrator_IEM_Integration_Toolkit)

Modifying an IBM Endpoint Manager serverYou can update the basic configuration parameters in IBM Cloud Orchestrator toaccess an IBM Endpoint Manager server.



services category.2. Start the Modify IBM Endpoint Manager Server offering.3. After the offering starts:

a. Select the IBM Endpoint Manager server to modify.b. Review and modify the IBM Endpoint Manager server host name or IP

address.c. Review and modify the IBM Endpoint Manager server port.d. Review and modify the user name to connect to the IBM Endpoint Manager

server.e. Review and in case modify the password for the user.f. Specify if the system must perform a connection check against the given

IBM Endpoint manager server and, in case of failure, to abort the operation.g. Submit the offering.


Name Modify IBM Endpoint Manager Server


Process Modify IEM Server(SCOrchestrator_IEM_Integration_Toolkit)

User interface Modify IEM Server(SCOrchestrator_IEM_Integration_Toolkit)

Deploy an IBM Endpoint Manager Fixlet Action to a list ofcomputers

You can deploy a generic Fixlet Action, in an IBM Endpoint Manager environment,to a set of IBM Endpoint Manager computers hosted on the virtual machinesdeployed through IBM Cloud Orchestrator. You can deploy IBM Endpoint ManagerActions associated to Fixlets, Tasks, and Baselines.

This use case is available as an instance action.


This action is available both from the OpenStack Virtual Machines view and theOpenStack Heat Stacks views.

Note: You must already have configured at least one IBM Endpoint Managerserver in the IBM Cloud Orchestrator environment.

To run this scenario, perform the following steps:1. In the Self-service user interface, click ASSIGNED RESOURCES and then click

Stacks or VMs.2. Select one or more resources and start the Deploy fixlet action from the left

menu. The action is available only for active instances.3. When the offering starts:

a. Select an IBM Endpoint Manager server

Optional. This step appears on the UI only if more than one IBM EndpointManager server configuration has been registered on the system. If only oneconfiguration is available, it is used automatically.

b. Select a Fixlet

The list of the available Fixlets is displayed. Select one of them. You cansearch the table where Fixlets are shown by selecting a content site, byspecifying a search string in the corresponding box, and finally by clickingSearch. All the rows having at least one column that contains the searchstring are returned. The search is not case-sensitive.

c. Select the targets of the operation

If the operation starts from an OpenStack Heat stack, the list of availablecomputers is shown, corresponding to the IBM Endpoint Manager agentsinstalled on the virtual machines deployed through the selected Heat stack.If the operation starts from OpenStack Virtual Machines, the target selectionpage does not appear and the targeted agents are the ones hosted on theselected virtual machines.You can search the table where computers are shown by specifying a searchstring in the corresponding box and clicking Search. All the rows having atleast one column that contains the search string are returned. The search isnot case-sensitive.

d. Specify additional deployment options

You can specify the Execution Mode , specify Reboot Options, and set orupdate the values of custom parameters that can be defined inside theaction belonging to the Fixlet selected for execution. When Re-executeWhenever Applicable is checked, the selected Fixlet Action is activated onthe agents enabling the policy reevaluation mode, meaning that the IBMEndpoint Manager agent, after executing the action, continuously checks itscompliance. If it becomes non compliant, the action is re-executed. WhenExecute Once is checked, the action defined in the selected Fixlet isexecuted just once and is marked as completed.If a Baseline gets selected for the operation, the list of custom parameterscontains the union of all the parameters coming from all the actions that arecontained in the selected Baseline.Through the Reboot Options, you can specify if the target machines mustbe restarted or shut down at the end of the operation.

e. Submit and monitor the operation


When you click Submit, the execution of the action associated to the Fixletis triggered. The system implicitly executes the default action associated tothe selected Fixlet, if any, or the first available action, if a default one is notspecified.You can monitor the execution of the operation in the Action Log view.Based on the value specified for the Execution Mode parameter, thecomplete state of the operation assumes different meanings. Morespecifically, when Re-execute Whenever Applicable is checked, a completeoperation means that the selected action has been activated on the targetsystems. In this case, the outcome of the execution of the action is notreported back to IBM Cloud Orchestrator. When Execute Once is checked, acomplete operation means that the action specified in selected Fixlet hasbeen successfully executed on the target. systems.

Table 104. Configuration of the action for OpenStack virtual machines

Name Deploy fixlet

Applies to Multiple Instances


Process Run Fixlet Activation(SCOrchestrator_IEM_Integration_Toolkit)

User interface Deploy a Fixlet Action(SCOrchestrator_IEM_Integration_Toolkit)

Table 105. Configuration of the action for OpenStack Heat stacks

Name Deploy fixlet

Applies to Single Instance

Instance type heat

Process Run Fixlet Activation(SCOrchestrator_IEM_Integration_Toolkit)

User interface Deploy a Fixlet Action(SCOrchestrator_IEM_Integration_Toolkit)

Toolkit developer's referenceThis section contains reference information about the Business Process Managerartifacts exposed in the IBM Endpoint Manager toolkit contained in the contentpack. It is intended to be used by IBM Cloud Orchestrator content developers toextend the already available scenarios or to write new scenarios leveraging thebuilding blocks available from the toolkit.

The SCOrchestrator_IEM_Integration_Toolkit has dependencies against thefollowing basic toolkits that are delivered as a part of IBM Cloud Orchestrator:v SCOrchestrator_Scripting_Utilities_Toolkit


v SCOrchestrator_Persistence_Base_Toolkit


v SCOrchestrator Heat Support Toolkit


The following items are the main building blocks of the toolkit:


v “Environmental variables”v “Business objects” on page 161v “Coach views” on page 164v “Human services” on page 165v “Business processes” on page 166v “General system services” on page 167v “Integration services” on page 168

Environmental variablesThere are a number of environment variables available for customizing some of thebehaviors when you run use cases.

Environmental variable are defined in the Toolkit Setting > Environment sectionof the toolkit.

action_execution_wait_timeout

This variable specifies the maximum amount of time, in minutes, that IBM CloudOrchestrator waits for an IBM Endpoint Manager action to complete beforestopping with an error.

iem_post_action_deadline

This variable specifies the default amount of time the IBM Endpoint Manageragents waits before performing an automatic restart or shutdown of the system, ifit has been requested by the user. The default value is set to one minute. The valueof this variable, as a string representation, must follow the Duration format"PnYnMnDTnHnMnS", as defined in XML Schema 1.0 section 3.2.6.1.

iem_queries_max_rows

This variable specifies the maximum number of elements that can be loaded into atable (for example, Fixlets, Software Packages, Computers, and so on) whenrunning the “Deploy a Fixlet” and “Manage Software Packages” offerings, beforedisplaying a warning message asking the user to refine the filter conditions used toidentify the elements to load.

storehouse_iem_int_path

This variable specifies the default path on the Storehouse where the IBM EndpointManager server configurations get stored. The value of this variable must never bechanged.

persistence_namespace

This variable specifies the default namespace used by the Persistence toolkit wherethe IBM Endpoint Manager server configurations get stored. The value of thisvariable must never be changed.



ExecuteFixletBreadcrumbData

This object is used for storing the temporary properties to manage the breadcrumbwidget that appears on the bottom part of some user interfaces.

IemActionParameters

This object is used for storing information about the parameters associated to anIBM Endpoint Manager action.

IemActionSettings

This object is used for storing information about the activation parameters of anaction.

IemActionStatus

This object is used for storing information about the status of an IBM EndpointManager action.

IemAttribute

This object is used for storing information about a custom attribute to be retrievedwhen querying for Fixlets.

IemComputer

This object is used for storing information about a computer where the IBMEndpoint Manager agent is installed.

IemComputerActionResult

This object is used for storing the results of executing a given action on a givenIBM Endpoint Manager computer.

IemComputerFilter

This object is used for defining filtering options when querying lists of computersfrom the IBM Endpoint Manager server.

IemComputerSearchCondition

This object is used for defining searching conditions against attributes of acomputer object when querying lists of computers from the IBM EndpointManager server. It is a child object of the IemComputerFilter object.

IemContentSite

This object is used for storing information about an IBM Endpoint ManagerContent Site.


IemFixlet

This object is used for storing information about a IBM Endpoint Manager Fixlet.

IemFixletActivationRequest

This object is used for specifying information about the activation of a Fixlet.

IemFixletCategory

This object contains the attributes of a IBM Endpoint Manager Fixlet Category.

IemFixletSeverity

This object contains the attributes of a IBM Endpoint Manager Fixlet Severity.

IemFixletSource

This object contains the attributes of a IBM Endpoint Manager Fixlet Source.

IemPostActionBehavior

This object is used for specifying the Reboot Options, for example restart orshutdown actions, when activating a Fixlet.

IemProperty

This object is used for specifying the attributes of a IBM Endpoint Managerproperty.

IemQueryResult

This object is used for storing the results of executing a generic Session Relevancequery against the IBM Endpoint Manager server.

IemRelevanceAnswer

This object is used as a child object of IemQueryResult for storing the results ofexecuting a generic Session Relevance query against the IBM Endpoint Managerserver.

IemRelevanceResult

This object is used as a child object of IemQueryResult for storing the results ofexecuting a generic Session Relevance query against the IBM Endpoint Managerserver.

IemRelevanceSearchCondition

This object is used for defining searching conditions against attributes of a IBMEndpoint Manager resource, for example a Fixlet, when querying them from theIBM Endpoint Manager server.


IemServer

This object is used to handle the configuration information required to allow BPMto connect to a IBM Endpoint Manager environment (i.e. hostname, credentials, ...).

IemServerRegistrationData

This object is used to hold the input parameters of the "Register IEM Server"offering.

IemServerUnregistrationData

This object is used to hold the input parameters of the "Unregister IEM Server"offering.

IemServerUpdateData

This object is used to hold the input parameters of the "Modify IEM Server"offering.

ScoVirtualMachine

This object is used for storing the attributes of a IBM Cloud Orchestrator virtualmachine object.

ScoVirtualSystem

This object is used for storing the attributes of a IBM Cloud Orchestrator virtualsystem object.

TakeoverAgentsRequest

This object is used to hold the input parameters for the "Register Unlinked IEMAgents" offering and action.

UpdateComputerSettingsRequest

This object is used to hold the parameters used in the context of the "Takeover IEMAgents" business process for issuing an update request of the client settings of aIBM Endpoint Manager agent.

VMConnectivityInfo

This object is used to hold the data for the connection to a specified virtualmachine.



Button Click Listener

This is a generic utility view used to capture click events of a bound button and totrigger a corresponding Boundary Event. Upon triggering the Boundary Event, theview can also be configured to activate a loading overlay screen, for example byleveraging the “Overlay View” view.

Change Event Listener

This is a generic utility view used to capture onChange events related to thevariable bound to the view and to trigger a corresponding boundary event. Aftertriggering the boundary event, you can also configure the view to activate aloading overlay screen, for example, by leveraging the "Overlay View" view.

Generic Change Event Listener

This is a generic utility view used to capture “onChange” events related to thevariable bound to the view and to trigger a corresponding Boundary Event. It doesnot load overlay screens.

CustomHeadingView

This view is used by some Human Services to display a header information whenthey are embedded inside other UI wizards.

Fixlet Activation Settings

You can insert the currently supported settings for configuring a Fixlet activationoperation n the Fixlet Activation Settings view.

Manage Fixlets Breadcrumb

This view shows summary information about what the user has selected and whatis yet to be specified before submitting the operation.

Overlay View

This utility view is used to show a loading overlay screen that inhibits any userinteraction with the UI. It is used during long running Ajax operations to preventthe user from triggering other operations until the current one completes. In thetoolkit, it is used in conjunction with the Change Event Listener view. For a sampleutilization, see the implementation of the “Deploy a Fixlet” Human Service.

Password

The Password coach view renders the password as a masked input.

Show Msg Page

This view is used to display a generic messages to the user when specificconditions occur.


Version info

This coach view renders the version information of the toolkit. It is used in all thepages of the human services of the toolkit.


Deploy a Fixlet Action

This is the public Human Service that is used to collect the parameters required todeploy a Fixlet to a list of computers.

Modify IEM Server

This is the Human Service used to collect the parameters required to edit an IBMEndpoint Manager server configuration already stored in IBM Cloud Orchestrator.

Register IEM Server

This is the Human Service used to collect the parameters corresponding to an IBMEndpoint Manager server configuration to be created in IBM Cloud Orchestrator.

Select Fixlet

This is an internal Human Service used by the “Deploy a Fixlet Action” service tohandle the UI for the selection of a Fixlet.

Select IEM Server

This is an internal Human Service used to handle the selection of IBM EndpointManager server configuration in the context of all the Offerings and Actions thatmust interact with an IBM Endpoint Manager infrastructure.

Select Targets and Deploy Options

This is a Human Service that allows a user to search and select the targets and theadvanced deployment options for an IBM Endpoint Manager operation, such asthe deployment of a Software Package or the activation of a Fixlet.

Takeover IEM Agents

This is the public Human Service that is used by the ”Register unlinked virtualservers” offering to collect the parameters required to discover and re-configureunlinked IBM Endpoint Manager agents.

Unregister IEM Server

This is the Human Service that is used to collect the parameters required to deletean IBM Endpoint Manager server configuration already stored in IBM CloudOrchestrator.


Business processesThere are a number of the business processes available in the toolkit.

Modify IEM Server

In IBM Cloud Orchestrator, this business process updates an already availableconfiguration containing the parameters needed to connect to a IBM EndpointManager environment.

Register IEM Server

This business process registers a new configuration, containing the parametersneeded to connect to a IBM Endpoint Manager environment, in IBM CloudOrchestrator.

Run Fixlet Activation

This business process handles the activation of a Fixlet to a set of computers. Boththe Fixlet and the computers are defined in the IBM Endpoint Managerenvironment.

Takeover IEM Agents

This business process discovers and reconfigures unlinked IBM Endpoint Manageragents located on the virtual machines of a set of virtual system instances.

Unregister IEM Server

This business process deletes an already available configuration, containing theparameters needed to connect to a IBM Endpoint Manager environment, from IBMCloud Orchestrator.

Wait for Action Completion

This process waits for the completion of the given IBM Endpoint Manager action.If the action has a static list of targets, this service waits until it completes on all ofthem. If the action has a dynamic list of targets, this service immediately returnswith the aggregated state of the action regardless of the actual reported state foreach of its targets. Based on the value specified for the “Execution Mode”parameter, when activating the action, the “complete” state of the operationassumes two different meanings. More specifically, when the “Execution Mode” isset to “Re-evaluate Whenever Applicable,” a successfully complete operationmeans that the action has been activated on the target systems. In this case, theoutcome of the execution of the action is not reported back to IBM CloudOrchestrator. When the flag “Execution Mode” is set to “Execute Once,” asuccessfully complete operation means that the action has been successfullyexecuted on all the target systems. This process waits for a default timeout of 30minutes for the action to complete. An error is reported if the action is still runningwhen that timeout elapses. You can customize the default wait timeout bymodifying the value of the “action_execution_wait_timeout” environment variabledefined in the “Toolkit Settings → Environment” section of the toolkit. This is aninternal process and not publicly exposed.


Wait for Multiple Update Requests Completion

This process waits for the completion of a set of update client settings operationstriggered in the context of the "Takeover IEM Agents" business process. Thisprocess waits for a default timeout of thirty minutes for the operations tocomplete. An error is reported if any update operation is still running when thattimeout elapses.

In the Wait for Action Completion, you can customize the default wait timeout byby modifying the value of the action_execution_wait_timeout environmentvariable defined in the Toolkit Settings > Environment. This is an internal processnot publicly exposed.

General system servicesThere are some general system services available in the toolkit.

AddPostActionBehavior

This service updates the IemFixletActivationRequest data structure withinformation about the reboot behavior of the operation.

ComputeVirtualMachinesFromContext

This services retrieves the IBM Cloud Orchestrator virtual machines from theoperation context, based on the resources selected by the user: Heat stacks orOpenStack virtual machines.

GetAllVirtualMachines

This service retrieves the list of all the OpenStack virtual machines.

GetExecutionContextAndType

This service returns the IBM Cloud Orchestrator OperationContext of the enclosingHuman Service plus an additional parameter specifying the type of user operationthat triggered it (offering, user action or event-triggered action).

GetRegisteredIEMServers

This service returns the list of IBM Endpoint Manager servers stored in IBM CloudOrchestrator.

GetTranslatedMessage

This service returns the translated version of a string given its message key.

GetTranslatedMessages

This service returns the translated version of a list of string given their messagekeys.

InitPostActionBehaviorCoachData

This service initializes the data structures needed to handle the selection of thereboot options in the view used to collect those parameters from the user.


ListRelevantFixletsForComputer

This service lists the relevant IBM Endpoint Manager Fixlets for the givencomputer.

ListRelevantFixletsForComputers

This service lists the relevant IBM Endpoint Manager Fixlets for a list ofcomputers. The returned list of Fixlets is the union of all the Fixlets that arerelevant on at least one computer of the list.

SimpleListFilteredFixlets

This service is a wrapper around the generic “ListFixlets” service used by the“Select Fixlet” Human service. It directly exposes a simpler set of filterable Fixletparameters instead of the generic interface of the “List Fixlets” service.

Integration servicesThere are a number of integration services artifacts available in the toolkit. Theseservices can be reused by a IBM Cloud Orchestrator content developer to buildnew use cases other than the ones already provided.

ActivateFixlet

This service activates an IBM Endpoint Manager Fixlet to a set of targets,optionally allowing specification of advanced activation settings.

AddVSysInfoAndPruneComputers

This service loops through a list of IemComputer objects and for each of them itcomputes the virtual system name the computers belong to, if any. The computedvalue is then set to the corresponding attribute in the computer object. Onlycomputers having a valid reference to a visible Virtual System Instance arereturned by this service. This means that if the user calling this service does nothave permissions to access a certain Virtual System Instance, all the IBM EndpointManager agents hosted on that instance are not returned by this service.

CheckIEMServerConnection

This service is used to check that the connection to the IBM Endpoint Managerenvironment, using the provided credentials and network parameters, is workingcorrectly.

DeleteAction

This service stops and deletes a given IBM Endpoint Manager action.

Delete Computer

This service is used to delete a computer from a specified IBM Endpoint Managerserver.


Delete Computers

This service is used to delete a set of computers from a specified IBM EndpointManager server.

Deprecated GenericRestCall

This service is a private patched version of the “GenericRESTCall” service availablein the SCOrchestrator_Toolkit. It has been modified to allow to call a generic IBMCloud Orchestrator or Workload Deployer REST API, in an internal mode. Thisservice has been added just to overcome some limitations in a few WorkloadDeployer REST APIs. It must not be used to build new content.

ExecuteQuery

This service executes a generic IBM Endpoint Manager Session Relevance queryand returns its result to the caller process.

GetActionStatus

This service returns the current status of the given IBM Endpoint Manager action.

GenericRestCallWithIteration

This service is used to get the aggregated results of those IBM Cloud OrchestratorREST APIs that returns results in trunk.

GetIEMServerComputer

This service returns the IBM Endpoint Manager computer hosting the IBMEndpoint Manager server.

GetSelectedIEMServer

This service retrieves the IBM Endpoint Manager server configuration from theStorehouse for the server specified as the input parameter.

InstallIEMAgentOnVM

This service installs the IBM Endpoint Manager Agent on a specified virtualmachine.

InstallIEMAgentOnVMs

This service installs the IBM Endpoint Manager Agent on a specified set of virtualmachines.

InstallIEMAgentOnLinux

This service installs the IBM Endpoint Manager Agent on a specified Linux virtualmachine.

InstallIEMAgentOnWin

This service install the IBM Endpoint Manager Agent on a specified Windowsvirtual machine.


ListActionParametersForFixlet

This service lists the customizable parameters of a Fixlet's action.

ListApplicableComputersForFixlet

This service lists the IBM Endpoint Manager computers that are relevant for thegiven Fixlet

PruneDuplicateZombieIemComputers

This service cleans a list of the IBM Endpoint Manager computers so as to avoidhaving IBM Endpoint Manager computers with duplicated address.

ListComputers

This service lists the available IBM Endpoint Manager computers matching thegiven selection filter. The filter criteria for querying the list of computer can bespecified through an IemComputerFilter object.

The content of the IemComputerFilter object is then used to build the Relevanceexpression for querying the IBM Endpoint Manager computers.

The following sample JavaScript snippet shows how to initialize the filter objectbefore calling this service:tw.local.filter = new tw.object.IemComputerFilter();

tw.local.filter.properties = new tw.object.listOf.IemProperty();var prop = new tw.object.IemProperty();prop.name = "_WebReports_HTTPServer_PortNumber";prop.value = "80";tw.local.filter.properties[0] = prop;

tw.local.filter.searchConditions = new tw.object.listOf.IemComputerSearchCondition();var searchCondition = new tw.object.IemComputerSearchCondition();searchCondition.booleanGroupingType = "AND";searchCondition.attributeSpec = ’(operating system of it | "")’;searchCondition.attributeValuePattern = "win";tw.local.filter.searchConditions[0] = searchCondition;

var searchCondition2 = new tw.object.IemComputerSearchCondition();searchCondition2.booleanGroupingType = "AND";searchCondition2.attributeSpec = ’(name of it | "")’;searchCondition2.attributeValuePattern = "win";tw.local.filter.searchConditions[1] = searchCondition2;

var searchCondition3 = new tw.object.IemComputerSearchCondition();searchCondition3.booleanGroupingType = "AND";searchCondition3.relevanceExpr = ’if(exists (ip addresses of it)) then

(set of (ip addresses of it as string) contains "9.168.105.5") else false’;

Using the filter defined above, you can search for all the computers having a clientsetting “_WebReports_HTTPServer_PortNumber=80”, an operating system namecontaining the “win” keyword, a host name containing the “win” keyword, and anIP address of 9.168.105.5.

With the IemComputerSearchCondition object, you can build sophisticated searchconditions, going from a simple name/value client setting search (as shown by thetw.local.filter.properties variable in the above example) to a generic relevance


expression (as shown by the serachCondition3 variable, in the above example). Inthose expressions, the “it” keyword refers to the current computer in the result setof the query.

IemComputerSearchCondition elements can be combined into logical AND and/orOR groups, based on the value of the booleanGroupingType attribute. All theelements having the booleanGroupingType attribute set to “AND” are combinedtogether in an AND expression, while all the elements having thebooleanGroupingType attribute set to “OR” are combined into a “OR” expression.

ListComputesBySCOVMs

This service, starting from a set of virtual machines, retrieves the ones that havethe IBM Endpoint Manager agent installed.

ListContentSites

This service lists the available IBM Endpoint Manager content sites.

ListFixletCategories

This service lists the available Categories for the Fixlets available in the IBMEndpoint Manager environment, optionally filtered by content site.

ListFixlets

This service lists the available IBM Endpoint Manager Fixlets matching the givenselection filters.

ListFixletSeverities

This service lists the available Severities for the Fixlets available in the IBMEndpoint Manager environment, optionally filtered by content site.

ListFixletSources

This service lists the available Sources for the Fixlets available in the IBM EndpointManager environment, optionally filtered by content site.

Retrieve VM Credentials

This service retrieves the connectivity information of a specified virtual machine.

SendEmail

This service sends an email to the specified IBM Cloud Orchestrator user,leveraging the SMTP server configured with IBM Cloud Orchestrator.

StopAction

This service stops the given IBM Endpoint Manager action.

UpdateComputerSettings

This service triggers a client update request for updating the client settings of a listof IBM Endpoint Manager computers.


Samples about how to use integration servicesThe Business Processes and Human Services that are delivered as part of thiscontent pack can be used as starting points and as samples for developing newcontent.



Configuring an SMTP server in IBM Cloud OrchestratorTo use the email notification feature, you must configure Business Process Managerto use an appropriate SMTP relay server inside your organization. Contact yourmail server administration team to obtain the host name of the SMTP server.


Create a file called 100Custom.xml with the following content:properties>






If the file is already there, edit it adding or updating the “server/email” sectionwith the provided information. Afterwards, restart the Business Process Managerserver using the command: service bpm restart.

TroubleshootingError messages are logged for all probable errors during deployment.

Table 106.

Error code Description

CTJCA1500E The action has been stopped. This erroroccurs when someone on the IBM EndpointManager side manually stops the actiontriggered by IBM Cloud Orchestrator.

CTJCA1501E The action expired. This error occurs whenthe submitted action on the IBM EndpointManager side has expired before itscompletion


Table 106. (continued)

Error code Description

CTJCA1502E The operation failed. This error occurs whenthe submitted action on the IBM EndpointManager side completes with errors. Foradditional details, see the IBM EndpointManager BES Console and log files.

CTJCA1503E The timeout elapsed before the operationcompletion. This error occurs when thesubmitted action on the IBM EndpointManager side did not complete within thetimeout that IBM Cloud Orchestrator waitsfor an action to complete.

CTJCA1504E Unable to contact the specified IBMEndpoint Manager server. Check that thesever is running and that the providedparameters, address and credentials, arecorrect.



Appendix J. IBM Endpoint Manager for Patch Managementtoolkit

The IBM Cloud Orchestrator Content Pack For IBM Endpoint Manager for PatchManagement allows you to use your existing IBM Endpoint Manager environmentfrom IBM Cloud Orchestrator and vice versa to enable patch managementoperations.



The Web Reports engine must be up and running in the IBM Endpoint Managerenvironment.

A good knowledge of IBM Cloud Orchestrator and of the Business ProcessManager programming model is required for using the toolkit as a softwaredevelopment kit (SDK) for building new content.

This content pack comes already installed in IBM Cloud Orchestrator. This meansthat the toolkit and the related offerings and actions are already available in theIBM Cloud Orchestrator environment.



Enable and configure at least one Patch Management content site, in the IBMEndpoint Manager environment, corresponding to the platforms that you want topatch.

Upgrading


Make the following adjustments:v Remove the Apply a Patch user action. See User actions.v Remove all the offerings under the IBM Endpoint Manager Configuration

Services and IBM Endpoint Manager Management Services categories. SeeSelf-service offerings.


Toolkit scenariosThere is a scenario that is immediately available from the toolkit.

The following scenario is available:v “Apply an IBM Endpoint Manager patch to the virtual machines of a virtual

system instance”

Apply an IBM Endpoint Manager patch to the virtual machinesof a virtual system instance

You can submit the installation of a security patch, available in an IBM EndpointManager environment, to a set of IBM Endpoint Manager computers installed tovirtual machines deployed in the context of a virtual system instance.

This use case is available as an instance action.

Note: For this action to be successful, the virtual machines of the targeted virtualsystem instance must contain the script package that installs the IBM EndpointManager agent. At least one IBM Endpoint Manager sever configuration must havebeen registered in IBM Cloud Orchestrator and at least one Patch ManagementContent Site must be available from the IBM Endpoint Manager infrastructure.


Stacks or VMs.2. Select one or more resources and then start the Apply patch action from the

left menu. The action is available only for active instances.3. After the action starts:

a. Select an IBM Endpoint Manager server

Optional. The step appears in the UI only if more than one IBM EndpointManager server configuration has been registered on the system. If there isjust one configuration available, it is used automatically.

b. Search for and select a Patch

The list available patches is shown. Select one or more of them.To also see the patches that are not applicable, deselect Show onlyApplicable Patches. By default, all the patches contained in the firstavailable Patch Management related site, and not older than 30 days, areshown. If no Patch Management related site is enabled in the IBM EndpointManager environment, the content of the Master Action Site is displayed,regardless of the age of the contained Fixlets.In general, to display the list of patches, first to select a site and then,optionally, specify a maximum age, in days, for the returned patches (basedon their release date) and select a Severity, Category, and Source. The list ofavailable Sites from which you can choose is restricted to all the enabledsites for the Patch Management application, plus the Master Action Site andany custom site in the Patch Management Domain.You can also specify an optional search string. All the rows having at leastone column that contains the search string are returned. The search is notcase-sensitive. When you click Search, the loading of patches is triggeredaccording to the selected search criteria. To see the details about one of thedisplayed patches, click the name of the patch to see a complete description.Additionally, you can click the table headers to sort the table.


Note: Even if in these sections we always refer to patches, actually, from aIBM Endpoint Manager point of view, a patch is always a Fixlet (or a Taskor a Baseline). A dedicated column in the table specifies the type of a givenentry (Fixlet, Task or Baseline).

c. Specify additional deployment options

You can specify the Execution Mode , specify Reboot Options, and set orupdate the values of custom parameters that can be defined inside theaction belonging to the patch selected for execution. When Re-executeWhenever Applicable is checked, the selected patch is activated on theagents enabling the policy reevaluation mode, meaning that the IBMEndpoint Manager agent, after executing the patch, continuously checks itscompliance. If it becomes non compliant, the patch action is re-executed.When Execute Once is checked, the action defined in the selected patch isexecuted just once and is marked as completed.Through the Reboot Options, you can specify if the target machines mustbe restarted or shut down at the end of the operation.

d. Submit and monitor the operation

When you click Submit, the activation of the patch is triggered. The systemimplicitly executes the default action associated to the selected patch, if any,or the first available action, if a default one is not specified. You canmonitor the execution of the operation from the Action Log section of theselected virtual system. Based on the value specified for the ExecutionMode parameter, the complete state of the operation assumes differentmeanings. More specifically, when Re-execute Whenever Applicable ischecked, a complete operation means that the selected patch has beenactivated on the target systems. In this case, the outcome of the execution ofthe action is not reported back to IBM Cloud Orchestrator. When ExecuteOnce is checked, a complete operation means that the action specified inselected patch has been successfully executed on the target systems.


Name Apply a Patch



Tags active

Process Run Patch Activation(SCOrchestrator_IEM_PATCH_MGMT_Integration_Toolkit)

User interface Apply a Patch(SCOrchestrator_IEM_PATCH_MGMT_Integration_Toolkit)


Name Apply a Patch


Instance type heat

Tags createcomplete

Process Run Patch Activation(SCOrchestrator_IEM_PATCH_MGMT_Integration_Toolkit)

User interface Apply a Patch(SCOrchestrator_IEM_PATCH_MGMT_Integration_Toolkit)

Appendix J. IBM Endpoint Manager for Patch Management toolkit 177

Toolkit developer's referenceThis section contains reference information about the Business Process Managerartifacts exposed in the IBM Endpoint Manager toolkit contained in the contentpack. It is intended to be used by IBM Cloud Orchestrator content developers toextend the already available scenarios or to write new scenarios leveraging thebuilding blocks available from the toolkit.

The SCOrchestrator_IEM_PATCH_MGMT_Integration_Toolkit has dependenciesagainst the following toolkits:v SCOrchestrator_IEM_Integration_Toolkit



The following items are the main building blocks of the toolkit:v “Environmental variables”v “Human services”v “Coach views” on page 179v “General system services” on page 179



default_max_patch_age

This variable specifies the default maximum age, in days, of a patch for beingloaded in the table that shows the list of available patches.


Apply a Patch

This is the Human Service that is used to collect the parameters required to installa patch on a list of computers.

Select a Patch

This is an internal Human Service, used by the “Apply a Patch” service, thathandles the search and selection of a patch.



PatchDetails

This View is used by the “Select a Patch” service to handle the dialog containingthe detailed information for a given patch.

General system servicesThere are some general system services available in the toolkit.

ListPatches

This service is a wrapper around the “ListFixlets” integration service to retrieve thelist of available patches filtered according a set of customizable criteria.




Appendix J. IBM Endpoint Manager for Patch Management toolkit 179


Appendix K. IBM Endpoint Manager for Software Distributiontoolkit

With IBM Cloud Orchestrator Content Pack for IBM Endpoint Manager forSoftware Distribution you can use an existing IBM Endpoint Manager environmentfrom IBM Cloud Orchestrator and vice versa to enable Software Distributionoperations.



The Web Reports engine must be up and running in the IBM Endpoint Managerenvironment.

The Software Distribution content site must be correctly configured in the IBMEndpoint Manager environment and at least one Software Package must be createdwith its installation task through the Manage Software Distribution dashboard.This is a prerequisite to run the Manage Software Packages offerings and actions.

A good knowledge of IBM Cloud Orchestrator and of the Business ProcessManager programming model is required for using the toolkit as a softwaredevelopment kit (SDK) for building new content.

This Content Pack comes already installed in IBM Cloud Orchestrator. This meansthat the toolkit and the related offerings and actions are already available in theIBM Cloud Orchestrator environment.



Upgrading


Make the following adjustments:v Remove the Manage Software Packages user action. See User actions.


v Remove all the offerings under the IBM Endpoint Manager ConfigurationServices and IBM Endpoint Manager Management Services categories. SeeSelf-service offerings.


The following scenarios are available:v “Submitting an IBM Endpoint Manager software task to a list of computers”v “Deploying a cloud service with additional software” on page 183

Submitting an IBM Endpoint Manager software task to a list ofcomputers

You can submit an IBM Endpoint Manager software task to a list of computers.

You can submit the execution of a software task, belonging to a specified softwarepackage and available in a IBM Endpoint Manager environment, to a set of IBMEndpoint Manager computers that typically, but not necessarily, correspond to avirtual machines deployed through IBM Cloud Orchestrator.

Note: You must already have configured at least one IBM Endpoint Manager severinto IBM Cloud Orchestrator. At least one shared Software Package with therelated activation tasks must be available from the IBM Endpoint Manager server.


Stacks or VMs.2. Select one or more resources (only for virtual machines) and start the Deploy

fixlet action from the left menu. The action is available only for activeinstances.

3. When the offering starts:a. Select an IBM Endpoint Manager server

Optional. This step appears on the UI only if more than one IBM EndpointManager server configuration has been registered on the system. If only oneconfiguration is available, it is used automatically.

b. Select a Software Package

The list of the available shared Software Packages, created through the IBMEndpoint Manager Software Distribution Dashboard, is displayed. Selectone of them. You can search the table where Software Packages aredisplayed by specifying a search string in the corresponding box andclicking Search. All the rows having at least one column that contains thesearch string are returned. The search is not case-sensitive.

c. Select a Software Task

After selecting a Software Package, the list of tasks linked to that package isloaded and you must select one of them.

d. Specify additional deployment options

You can specify the Execution Mode, specify the Reboot Options, and setor update the values of custom parameters that can be defined inside theaction belonging to the task selected for execution. When Re-executeWhenever Applicable is checked, the selected task is activated on theagents enabling the policy reevaluation mode, meaning that the IBM


Endpoint Manager agent, after executing the task, continuously checks itscompliance. If it becomes non compliant, the task action is re-executed.When Execute Once is checked, the action defined in the selected task isexecuted just once and is marked as completed.Through the Reboot Options parameter, you can specify if the targetmachines must be restarted or shut down at the end of the operation.

e. Submit and monitor the operation

When you click Submit, the activation of the task is triggered. You areredirected to the Action log page where you can monitor the execution ofthe operation. Based on the value specified for the Execution Modeparameter, the complete state of the operation assumes different meanings.More specifically, when Re-execute Whenever Applicable is checked, acomplete operation means that the selected task has been activated on thetarget systems. In this case, the outcome of the execution of the action is notreported back to IBM Cloud Orchestrator. When Execute Once is checked, acomplete operation means that the action specified in selected task has beensuccessfully executed on the target systems.


Name Deploy software package

Process Run Software Task(SCOrchestrator_IEM_SW_Integration_Toolkit)



Tags active

User interface Manage Software Packages(SCOrchestrator_IEM_SW_Integration_Toolkit)


Name Deploy software package

Process Run Software Task(SCOrchestrator_IEM_SW_Integration_Toolkit)


Instance type heat

Tags createcomplete

User interface Manage Software Packages(SCOrchestrator_IEM_SW_Integration_Toolkit)

Deploying a cloud service with additional softwareYou can submit the deployment of a Virtual System Pattern, of a Virtual SystemClassic Pattern, or of an OpenStack Heat template and, for each node of the thoseartifacts, specify an additional Software Package or Fixlet to be deployed to thevirtual machines corresponding to the given node.



Deploy cloud services category.2. Start the Deploy cloud service with additional software offering.

Appendix K. IBM Endpoint Manager for Software Distribution toolkit 183

3. After the offering starts:a. Select the cloud service to deploy.b. Configure the parameters required for the selected cloud service. The set of

parameters depends on the chosen type of cloud services.c. For each part the selected pattern:

1) Specify whether an additional Software Configuration must be executedon the virtual machines, through the IBM Endpoint Managerinfrastructure originated from this node. These are the options:

Configure Software PackagesYou can specify an additional Software Package task to beexecuted.

Configure Advanced ContentYou can specify a Fixlet to be activated.

None No additional configurations to be applied.2) Specify any custom parameters associated to the node.3) Specify any custom parameters for the script packages associated to the

part.4) If an additional Software Configuration has been requested, a Software

Task or a Fixlet with advanced deployment options must be specified.The selection of a Software Task or of a Fixlet and the deploymentoptions is the same in the “Deploy software package” and “Deployfixlet” actions.

5) If you want to install the IBM Endpoint Manager agent on the virtualmachine that you are going to deploy, select Install IEM Agent andspecify the necessary parameters: operating system of the virtualmachine, the IBM Endpoint Manager Agent package location, thecredentials to access the package and, if necessary, the credential toaccess the virtual machine.

d. Review the Summary. Click Submit to trigger the operation and monitor it.At the end of the operation, a report with the detailed outcome of theoperation is delivered to the user that requested the operation, providedthat a valid email address and that a working Simple Mail Transfer Protocol(SMTP) server have been configured with IBM Cloud Orchestrator.

For the installation of additional software to occur, an IBM Endpoint Manageragent must be installed on the virtual machines involved by the softwareinstallation. If this is not the case, a message is displayed reporting the virtualmachines that are not hosting a configured IBM Endpoint Manager agent.

Note: There is a known limitation when deploying patterns including parts fromIBM WebSphere Application Server Hypervisor Edition images. For some of thoseimages the pattern deploy operations might fail with an error:Runtime error in script ("Process: ’Configure Selected Pattern’ ProcessItem:’Structured Parse And Add Pattern Details’ Type: ’ITEM’" -1:-1).InternalScript error: com.lombardisoftware.core.TeamWorksRuntimeException:com.lombardisoftware.core.TeamWorksException: Type mismatch.Expected "tw.object.String" type, but found: "tw.object.String[]"

Table 111. Configuration of the offering

Name Deploy cloud service with additional software

Category Deploy cloud services


Table 111. Configuration of the offering (continued)

Process Deploy a Cloud Service with Additional Software(SCOrchestrator_IEM_SW_Integration_Toolkit)

User interface Deploy a Cloud Service with Additional Software(SCOrchestrator_IEM_SW_Integration_Toolkit)

Toolkit developer's referenceThere are Business Process Manager artifacts exposed in the toolkit contained inthe content pack. They are intended to be used by IBM Cloud Orchestrator contentdevelopers to extend the already available scenarios or to write new scenariosleveraging the building blocks available from the toolkit.

The SCOrchestrator_IEM_SW_Integration_Toolkit has dependencies against thefollowing basic toolkits that are delivered as a part of IBM Cloud Orchestrator:v SCOrchestrator_IEM_Integration_Toolkit

v SCOrchestrator_Persistence_Base_Toolkit

v SCOrchestrator_Support_vSys_Toolkit

v SCOrchestrator_Support_vSys_Next_Toolkit



v SCOrchestrator Heat Support Toolkit



The following items are the main building blocks of the toolkit:v “Business objects”v “Human services” on page 186v “Business processes” on page 187v “General system services” on page 188v “Integration services” on page 188


FixletInPatternActivationRequest

This object is used for storing the information about the request for deployingSoftware Packages and Fixlets on the virtual machines originating from a part of aVirtual System Pattern.

IemSoftwarePackage

This object is used for storing the attributes of a IBM Endpoint Manager softwarepackage, created through the Software Distribution Dashboard.

PatternWithFixlets

This object is used for exchanging information between the Human Service andBusiness Process Designer process related to the deployment of a Virtual System


Pattern with Additional Software. It contains all the information about theconfiguration of the pattern to be deployed, including the additional data fordeploying Software Packages and Fixlets specified by the user.

SwSelectionCoachData

This object is used for storing temporary properties to manage the softwareselection step in the user interfaces of the “Manage Software Packages” wizards.

DeployableNodeWithFixlets

This object is used for storing information about the Fixlets to be applied to thevirtual machines originating from a given node of a deployed pattern.

DeploymentTemplateWithFixlet

This object is used for associating a pattern deployment template with Fixletsactivation information.

IemFixletActivationProgress

This object is used for monitoring the progress of Fixlet actions.

PatternSelectionHolder

This object is used for storing basic information of the available patterns.

ServiceDeploySummary

This object is used for storing information of the Summary page of the 'Deploy aCloud Service with Additional Software' Human Service.


Deploy a Pattern with Additional Software

This is the Human Service used to collect the parameters required to trigger thedeployment of a Pattern including the additional data for deploying SoftwarePackages and Fixlets on the virtual machines of the pattern.

Manage Software Packages

This is the Human Service that is used to collect the parameters required toexecute a software task on a list of computers.

Collect vSys Pattern Deploy Params

This is the Human Service that is used to collect the parameters required to deploya Virtual System Classic Pattern.

Collect Fixlet Deploy Params for Nodes

This is an internal Human Service, used by the “Deploy a Cloud Service withAdditional Software” service, that handles the UI pages for selecting the cloud


service to deploy, the Software Packages and/or Fixlets, and to configure thedeployment parameters.

Select Fixlet and Set Deployment Options in Pattern

This is an internal Human Service, used by the “Deploy a Pattern with AdditionalSoftware” service, that handles the UI pages for selecting Software Packages andFixlets in the context of configuring the deployment of a Virtual System Pattern.

Select Pattern

This is an internal Human Service, used by the “Deploy a Cloud Service withAdditional Software” service, that handles the UI pages for selecting the pattern todeploy.

Select Software Task

This is an internal Human Service, used by the “Manage Software Packages”services to handle the selection of Software Packages and tasks.

Business processesThere are business processes available in the toolkit.

Deploy a Cloud Service with Additional Software

This business process handles the deployment of a Virtual System Pattern, aVirtual System Classic Pattern, or an OpenStack Heat template and deploys thespecified additional Software Packages and/or Fixlets on the virtual machinesthrough the IBM Endpoint Manager infrastructure.

Activate Fixlet Actions

This business process handles the Fixlet activation.

Compute Virtual Machines - VSYS

This business process retrieves the virtual machines of a deployed Virtual SystemClassic Pattern.

Deploy Heat Template

This business process takes care of handling the deployment of a specifiedOpenStack Heat template.

Deploy Single Pattern

This business process handles the deployment of a specified Virtual System ClassicPattern.

Deploy vSys.Next Pattern

This business process handles the deployment of a specified Virtual SystemPattern.


Run Software Task

This business process handles the Fixlet activation.

General system servicesThere are general system services available in the toolkit.

GetTranslatedMessages

This service returns the translated version of a list of string given their messagekeys.

Integration servicesThere are a number of integration services artifacts available in the toolkit. Theseservices can be reused by a IBM Cloud Orchestrator content developer to buildnew use cases other than the ones already provided.

ListApplicableTasksForSoftwarePackages

This service lists the IBM Endpoint Manager software tasks that belong to theprovided software package and that are relevant for the list of computers providedas input. If the provided list of computers is empty, all the tasks of the givensoftware package are returned.

ListSoftwarePackages

This service lists the shared software packages available from the IBM EndpointManager environment.

ListTasksForSoftwarePackages

This service lists the software tasks associated to the given software packageavailable from the IBM Endpoint Manager environment.

Link VMs to Nodes (vSys.Next)

This service retrieves the virtual machines of a deployed Virtual System Pattern.

Link VMs to Nodes (Heat)

This service retrieves the virtual machines of a deployed OpenStack Heat template.

InstallIEMAgents

This service installs the IBM Endpoint Manager agent on a specified list of thevirtual machines.

IsIWDAvailable

This service is used to check if the Workload Deployer component is installed inthe environment.


Compute IEM Agents

This service retrieves from a specified list of virtual machines the ones that havethe IBM Endpoint Manager agent installed.

Samples about how to use integration servicesThe Business Processes and Human Services that are delivered as part of thiscontent pack can be used as starting points and as samples for developing newcontent.



Configuring an SMTP server in IBM Cloud OrchestratorTo use the email notification feature, you must configure Business Process Managerto use an appropriate SMTP relay server inside your organization. Contact yourmail server administration team to obtain the host name of the SMTP server.


Create a file called 100Custom.xml with the following content:properties>






If the file is already there, edit it adding or updating the “server/email” sectionwith the provided information. Afterwards, restart the Business Process Managerserver using the command: service bpm restart.



Accessibility features for IBM Cloud Orchestrator

Accessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use software products successfully. The majoraccessibility features of IBM Cloud Orchestrator are described in this topic.

Accessibility features

The following list includes the major accessibility features in IBM CloudOrchestrator:v Keyboard-only operationv Interfaces that are commonly used by screen readersv Keys that are discernible by touch but do not activate just by touching themv Industry-standard devices for ports and connectorsv The attachment of alternative input and output devices

Note: The default configuration of JAWS screen reader does not read tooltips.JAWS users must enable their current mode to read tooltips by selecting Utilities >Settings Center > Speech Verbosity > Verbosity Level > Configure VerbosityLevels.

User documentation is provided in HTML and PDF format. Descriptive text isprovided for all documentation images.

The knowledge center, and its related publications, are accessibility-enabled.

Related accessibility information

You can view the publications for IBM Cloud Orchestrator in Adobe PortableDocument Format (PDF) using the Adobe Reader. PDF versions of thedocumentation are available in the knowledge center.

IBM and accessibility

See the IBM Human Ability and Accessibility Center for more information aboutthe commitment that IBM has to accessibility.


http://www.ibm.com/able


Notices

This information was developed for products and services that are offered in theUSA.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785United States of America

For license inquiries regarding double-byte character set (DBCS) information,contact the IBM Intellectual Property Department in your country or sendinquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of those


websites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operating


platform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. The sampleprograms are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

Portions of this code are derived from IBM Corp. Sample Programs.

© Copyright IBM Corp. 2013, 2015. All rights reserved.

Programming interface informationThis publication primarily documents information that is NOT intended to be usedas Programming Interfaces of IBM Cloud Orchestrator. This publication alsodocuments intended Programming Interfaces that allow the customer to writeprograms to obtain the services of IBM Cloud Orchestrator. This information isidentified where it occurs, either by an introductory statement to a chapter orsection or by the following marking: Programming Interface information.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the web at www.ibm.com/legal/copytrade.shtml.

Terms and conditions for product documentationPermissions for the use of these publications are granted subject to the followingterms and conditions.

Applicability

These terms and conditions are in addition to any terms of use for the IBMwebsite.

Personal use

You may reproduce these publications for your personal, noncommercial useprovided that all proprietary notices are preserved. You may not distribute, displayor make derivative work of these publications, or any portion thereof, without theexpress consent of IBM.

Commercial use

You may reproduce, distribute and display these publications solely within yourenterprise provided that all proprietary notices are preserved. You may not makederivative works of these publications, or reproduce, distribute or display thesepublications or any portion thereof outside your enterprise, without the expressconsent of IBM.

Notices 195

http://www.ibm.com/legal/us/en/copytrade.shtml

http://www.ibm.com/legal/us/en/copytrade.shtml

Rights

Except as expressly granted in this permission, no other permissions, licenses orrights are granted, either express or implied, to the publications or anyinformation, data, software or other intellectual property contained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in itsdiscretion, the use of the publications is detrimental to its interest or, asdetermined by IBM, the above instructions are not being properly followed.

You may not download, export or re-export this information except in fullcompliance with all applicable laws and regulations, including all United Statesexport laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESEPUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUTWARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDINGBUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

IBM Online Privacy StatementIBM Software products, including software as a service solutions, (“SoftwareOfferings”) may use cookies or other technologies to collect product usageinformation, to help improve the end user experience, to tailor interactions withthe end user or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offeringscan help enable you to collect personally identifiable information. If this SoftwareOffering uses cookies to collect personally identifiable information, specificinformation about this offering’s use of cookies is set forth below.

Depending upon the configurations deployed, this Software Offering may usesession and persistent cookies that collect each user’s user name, or otherpersonally identifiable information for purposes of session management, enhanceduser usability, single sign-on configuration. These cookies cannot be disabled.

If the configurations deployed for this Software Offering provide you as customerthe ability to collect personally identifiable information from end users via cookiesand other technologies, you should seek your own legal advice about any lawsapplicable to such data collection, including any requirements for notice andconsent.

For more information about the use of various technologies, including cookies, forthese purposes, See IBM’s Privacy Policy at http://www.ibm.com/privacy andIBM’s Online Privacy Statement at http://www.ibm.com/privacy/details thesection entitled “Cookies, Web Beacons and Other Technologies” and the “IBMSoftware Products and Software-as-a-Service Privacy Statement” athttp://www.ibm.com/software/info/product-privacy.


http://www.ibm.com/privacy

http://www.ibm.com/privacy/details

http://www.ibm.com/software/info/product-privacy

Glossary

This glossary includes terms and definitions forIBM Cloud Orchestrator.

The following cross-references are used in thisglossary:v See refers you from a term to a preferred

synonym, or from an acronym or abbreviationto the defined full form.

v See also refers you to a related or contrastingterm.

To view glossaries for other IBM products, go towww.ibm.com/software/globalization/terminology (opens in new window).

Aaccount code

A code that uniquely identifies anindividual, billing, or reporting entitywithin chargeback and resourceaccounting.

account code conversion tableAn ASCII text file that contains thedefinitions that are required to convertthe identifier values defined by theaccount code input field to theuser-defined output account codes.

account reportA report that is used to show accountlevel information for usage and charge.

audit dataA data record that contains informationabout specific types of user activity,security events, and configurationchanges in the product and in the cloud.

availability zoneA logical group of OpenStack Computehosts. It provides a form of physicalisolation and redundancy from otheravailability zones, such as by usingseparate power supply or networkequipment.


http://www-306.ibm.com/software/globalization/terminology/

http://www-306.ibm.com/software/globalization/terminology/

BBill program

A program that performs cost extensionswithin SmartCloud Cost Management andsummarizes cost and resource utilizationby account code. The Bill program usesthe rate code table that is assigned to theclient to determine the amount to becharged for each resource consumed.

building blockThe model of an image that is created bycombining models of a base operatingsystem and software bundles. Eachbuilding block contains a semantic andfunctional model that describes thecontents of the components, for example,the installed products, supportedoperating systems, prerequisites, andrequirements.

business objectA software entity that represents abusiness entity, such as an invoice. Abusiness object includes persistent andnonpersistent attributes, actions that canbe performed on the business object, andrules that the business object is governedby.

business processA defined set of business activities thatrepresent the required steps to achieve abusiness objective. A business processincludes the flow and use of informationand resources.

Cchargeback identifier

A label, which is often tied to analgorithm or set of rules, that is notguaranteed to be unique, but is used toidentify and distinguish a specificchargeback item or chargeback entityfrom others.

cloud groupA collection of hypervisors from a singlevendor. See availability zone.

compute nodeA node that runs a virtual machineinstance, which provides a wide range ofservices, such as providing a developmentenvironment or performing analytics.

consolidation processA process during which the datacollectors process the nightly accountingand storage files that were created by thedata collection scripts and produce anoutput CSR file.

conversion mappingAn entry in a mapping table which allowsyou to map identifiers to accounts orother identifiers.

custom nodeA virtual image part that provides anunconfigured node for a pattern that hasa deployment manager or a control nodeas its base.

Eexception file

A file that contains a list of records withidentifier names that do not have amatching Parameter IdentifierNameattribute value.

exception processingA process in which the system writes allrecords that to do match an entry in theaccount code conversion table to anexception file.

Hhuman service

An activity in the business processdefinition that creates an interactive taskthat the process participants can performin a web-based user interface.

hypervisorSoftware or a physical device that enablesmultiple instances of operating systems torun simultaneously on the samehardware.

Kkernel The part of an operating system that

contains programs for such tasks asinput/output, management and control ofhardware, and the scheduling of usertasks.


Pparameter (parm)

A value or reference passed to a function,command, or program that serves asinput or controls actions. The value issupplied by a user or by another programor process.

parm See parameter.

performance counterA utility that provides a way for softwareto monitor and measure processorperformance.

primary keyIn a relational database, a key thatuniquely identifies one row of a databasetable.

process applicationA container in the Process Centerrepository for process models andsupporting implementations. A processapplication typically includes businessprocess definitions (BPDs), the services tohandle implementation of activities andintegration with other systems, and anyother items that are required to run theprocesses. Each process application caninclude one or more tracks.

prorationA process that distributes the overall orindividual resources of an account andthe cost of those resources across multipleaccounts at a specified percentage.

proration tableAn ASCII text file that defines theidentifier values and rate codes that areused in the proration process.

Rrate code

The identifier of a rate that is used to linka resource unit or volume metric with itscharging characteristics.

rate groupA group of rate codes that is used tocreate rate subtotals in reports, graphs,and spreadsheets.

registryA repository that contains access andconfiguration information for users,systems, and software.

Sservice operation

A custom operation that can be run in thecontext of the data center. Theseoperations are typically administrativeoperations and are used to automate theconfiguration. Service operations can alsobe used to enhance the catalog ofavailable services with extra functionality.

shared serviceA predefined virtual application patternthat is deployed and shared by multipleapplication deployments in the cloud,including virtual applications, virtualsystems, and virtual appliances.

software bundleA collection of software installation files,configuration files, and metadata that canbe deployed on a virtual machineinstance.

Ttoolkit

A container where artifacts can be storedfor reuse by process applications or othertoolkits.

Vvirtual application

A complete set of platform resources thatfulfill a business need, including webapplications, databases, user registries,messaging services, and transactionprocesses. A virtual application is definedby a virtual application pattern. See alsovirtual application pattern.

virtual application patternA pattern that defines the resources thatare required to support virtualapplications, including web applications,databases, user registries, and more.These patterns are the deployment unitfor a virtual application. See also virtualapplication.

virtual machine (VM)An instance of a data-processing systemthat appears to be at the exclusivedisposal of a single user, but whose

Glossary 199

functions are accomplished by sharing theresources of a physical data-processingsystem.

virtual systemA collection of virtual machines.

virtual system instanceThe virtual environment that runs on ahypervisor in the cloud.

virtual system patternOne or more virtual images, which caninclude script packages, that implement adeployment topology. A virtual systempattern is a shared topology definitionused for repeatable deployment.

VM See virtual machine.


��

Product Number: 5725-H28

Printed in USA

Documents

IBM Cloud Orchestrator Version 2.4.0 Before using this information and the product it supports, read the information in Notices