SCO Content Development Guide

IBM SmartCloud Orchestrator
Version 2.3
Content Development Guide
Note
Before using this information and the product it supports, read the information in Notices on page 115.
Contents
Preface . . . . . . . . . . . . . . . v
Who should read this information . . . . . . . v
Chapter 1. Getting started with
SmartCloud Orchestrator content. . . . 1
Orchestrations . . . . . . . . . . . . . . 1
Content pack . . . . . . . . . . . . . . 1
Patterns . . . . . . . . . . . . . . . . 2
Virtual images . . . . . . . . . . . . . . 2
Chapter 2. SmartCloud Orchestrator
overview . . . . . . . . . . . . . . 3
Architecture . . . . . . . . . . . . . . 3
Chapter 3. Installing and configuring
IBM Process Designer . . . . . . . . 5
Chapter 4. Developing content for image
composition . . . . . . . . . . . . . 7
Chapter 5. Developing virtual system
patterns. . . . . . . . . . . . . . . 9
Chapter 6. Developing toolkit and
application content . . . . . . . . . 11
Implementing workflow orchestration . . . . . 11
Managing business processes . . . . . . . . 12
Process application . . . . . . . . . . . 12
Toolkit . . . . . . . . . . . . . . . 12
Snapshot . . . . . . . . . . . . . . 13
Business Process Definition . . . . . . . . 13
Service . . . . . . . . . . . . . . . 13
Participant group . . . . . . . . . . . 14
Coach validation framework. . . . . . . . 14
Implementing extensions with SmartCloud
Orchestrator . . . . . . . . . . . . . . 15
Implementing a custom operation for
SmartCloud Orchestrator . . . . . . . . . 15
Start a custom extension operation . . . . . 17
Implementation of a human service as a UI
extension . . . . . . . . . . . . . . 17
Implementation a Business Process Manager process
as an extension . . . . . . . . . . . . . 18
Best practices and guidelines . . . . . . . . 19
Guidelines for naming and documenting your
toolkit or process application . . . . . . . 19
Guidelines for creating artifacts in a toolkit . . . 19
Guidelines to structure your solution . . . . . 20
Guidelines for handling errors . . . . . . . 20
Importing and exporting toolkits and process
applications . . . . . . . . . . . . . . 21
Importing toolkits . . . . . . . . . . . 21
Exporting toolkits . . . . . . . . . . . 22
Business Process Manager security . . . . . . 22
Chapter 7. Importing using the
command-line interface . . . . . . . 23
Chapter 8. Example scenarios for
workflow-based orchestration. . . . . 27
Self-service offerings scenario . . . . . . . . 27
Event-triggered action scenario . . . . . . . . 30
User action scenario . . . . . . . . . . . 33
Chapter 9. Automating the creation of
categories, offerings, and user actions . 37
Chapter 10. Publishing SmartCloud
Orchestrator content to Cloud
Automation Marketplace . . . . . . . 41
Appendix A. SCOrchestrator toolkit . . 43
Configuration . . . . . . . . . . . . . 44
Business objects . . . . . . . . . . . . . 44
Representation of long types in business objects 45
OperationContext . . . . . . . . . . . 45
Service Instance . . . . . . . . . . . . 46
MetaData . . . . . . . . . . . . . . 46
VirtualMachine . . . . . . . . . . . . 47
NetworkInterface . . . . . . . . . . . 48
Role . . . . . . . . . . . . . . . . 49
Endpoint . . . . . . . . . . . . . . 49
Service . . . . . . . . . . . . . . . 49
CloudGroup . . . . . . . . . . . . . 50
params . . . . . . . . . . . . . . . 52
Hypervisor . . . . . . . . . . . . . 53
HypervisorFilter . . . . . . . . . . . . 56
Services . . . . . . . . . . . . . . . 58
General System Services . . . . . . . . . 58
Integration Services. . . . . . . . . . . 60
Cloud management services . . . . . . . . 69
Samples . . . . . . . . . . . . . . . 70
Appendix B. Scripting utilities toolkit 73
File upload restrictions . . . . . . . . . . 73
VirtualServerKey . . . . . . . . . . . 74
RemoteMachineCredentials . . . . . . . . 74
UploadFileData . . . . . . . . . . . . 74
ExecuteCommandData . . . . . . . . . 75
OutputMapValues . . . . . . . . . . . 75
VirtualServerExecuteData. . . . . . . . . 76
VirtualServerUploadAndExecuteData . . . . . 76
VirtualServerUploadData . . . . . . . . . 77
Implementation services . . . . . . . . . . 77
SSH_UploadFile . . . . . . . . . . . . 77
Copyright IBM Corp. 2013, 2014 iii
SSH_ExecuteCommand . . . . . . . . . 79
SSH_UploadFileAndExecuteCommand . . . . 79
Windows_UploadFile . . . . . . . . . . 80
Windows_ExecuteCommand. . . . . . . . 81
Windows_UploadFileAndExecuteCommand . . 81
ExtractOutputMap . . . . . . . . . . . 82
GetRemoteMachineDataFromVirtualMachineKey 82
Sample processes . . . . . . . . . . . . 83
Sample UIs . . . . . . . . . . . . . . 83
Deprecated implementation services . . . . . . 84
Appendix C. Support IaaS toolkit . . . 85
Generic IaaS REST call. . . . . . . . . . . 86
OpenStack and SmartCloud API library in Business
Process Manager . . . . . . . . . . . . 87
Get IaaS Regions . . . . . . . . . . . . 88
Samples for the IaaS support toolkit . . . . . . 88
Sample to create a tenant in OpenStack identity
service . . . . . . . . . . . . . . . . 89
Sample to get a list of servers from OpenStack
computer service . . . . . . . . . . . . 90
Troubleshooting . . . . . . . . . . . . . 90
Appendix D. Support vSys toolkit . . . 93
ChangeInstanceEndTimeBO . . . . . . . . 93
CheckDateTime . . . . . . . . . . . . 93
EnvironmentLimits . . . . . . . . . . . 94
EnvironmentLimitsBO. . . . . . . . . . 94
EnvironmentProfileBO. . . . . . . . . . 94
Flavor . . . . . . . . . . . . . . . 94
ModifyResourceBO . . . . . . . . . . . 94
Part . . . . . . . . . . . . . . . . 94
PartBO . . . . . . . . . . . . . . . 95
PartProperty . . . . . . . . . . . . . 95
Pattern . . . . . . . . . . . . . . . 95
PatternBO . . . . . . . . . . . . . . 95
ScriptProperty . . . . . . . . . . . . 96
UserInfoBO . . . . . . . . . . . . . 96
VirtualServer . . . . . . . . . . . . . 96
VirtualSystem . . . . . . . . . . . . 96
VirtualSystemPatternBO . . . . . . . . . 96
Integration services . . . . . . . . . . . . 96
Get ACL of Virtual System Instance . . . . . 97
Add user to ACL of Virtual System Instance . . 97
Remove User from ACL of Virtual System
Instance . . . . . . . . . . . . . . 97
Get Cloud Groups In Environment Profile . . . 97
Get Environment Profiles For Pattern. . . . . 98
Get Flavors Of Cloud Group In Environment
Profile . . . . . . . . . . . . . . . 98
Get Ip Groups Of Cloud Group In Environment
Profile . . . . . . . . . . . . . . . 98
Check Quota Breach . . . . . . . . . . 99
Get Script Parameters . . . . . . . . . . 99
Execute Script Packages . . . . . . . . . 99
Fetch Email Task . . . . . . . . . . . 99
Fetch End Time. . . . . . . . . . . . 100
Check Status Of Virtual System . . . . . . 100
Customize and Deploy Virtual System . . . . 102
Customize Pattern. . . . . . . . . . . 102
Deploy vSys Pattern . . . . . . . . . . 102
Get Available Pattern . . . . . . . . . . 102
Get Pattern Details . . . . . . . . . . 102
Get Pattern Details by Name . . . . . . . 103
Validate Pattern Customization . . . . . . 103
Get Cloud Groups For Pattern. . . . . . . 103
Customize and Deploy Virtual System Pattern 103
Get Cloud Groups in EnvironmentProfile . . . 103
Get Environment Limits . . . . . . . . . 104
Update Environment Limits . . . . . . . 104
Get Environment Profiles . . . . . . . . 104
List Flavors . . . . . . . . . . . . . 104
Get Upgrade Flavors For Virtual Machine . . . 104
Get User Information. . . . . . . . . . 104
Get Requester Details. . . . . . . . . . 104
Get Virtual Machines . . . . . . . . . . 105
Get Virtual System . . . . . . . . . . 105
Get Virtual System Instance . . . . . . . 105
Get Virtual System Instances . . . . . . . 105
Get vSystem Instances . . . . . . . . . 105
Get Flavor Of Virtual Machine . . . . . . 105
Get Flavors Of Cloud Group In Environment
Profile . . . . . . . . . . . . . . . 105
Get IP Groups Of CloudGroups In Environment
Profile . . . . . . . . . . . . . . . 106
Resize Virtual Machine . . . . . . . . . 106
Start ySys Instance . . . . . . . . . . 106
Stop ySys Instance. . . . . . . . . . . 107
Delete vSys Instance . . . . . . . . . . 107
Validate End Time. . . . . . . . . . . 107
Validate End Time Of Virtual System . . . . 107
User interface . . . . . . . . . . . . 107
Sample processes services . . . . . . . . . 110
Change Environment Profile Limits . . . . . 110
Change Instance End Time . . . . . . . . 110
Delete Single vSys Instance . . . . . . . . 111
Delete vSys Instances . . . . . . . . . . 111
Deploy Selected Pattern . . . . . . . . . 111
Deploy Virtual System Approval . . . . . . 111
Modify Resource . . . . . . . . . . . 111
Restart Single vSys Pattern Instance . . . . . 111
Restart ySys Pattern Instances . . . . . . . 112
Start Single vSys Pattern Instance. . . . . . 112
Start vSys Pattern Instances. . . . . . . . 112
Stop Single vSys Pattern Instance. . . . . . 112
Stop vSys Pattern Instances. . . . . . . . 112
Wait For Deletion Of Virtual System Instance 112
Wait For Status Of Virtual System Instance . . 112
Notices . . . . . . . . . . . . . . 115
Trademarks and Service Marks . . . . 117
Privacy policy considerations . . . . 119
Accessibility features for SmartCloud
Orchestrator . . . . . . . . . . . . 121
iv IBM SmartCloud Orchestrator 2.3: Content Development Guide
Preface
This publication documents how to author content for IBM
SmartCloud
Orchestrator.
Who should read this information
This information is intended for users and cloud administrators who build content
by using the SmartCloud Orchestration platform for their internal and wider
community use.
Copyright IBM Corp. 2013, 2014 v
vi IBM SmartCloud Orchestrator 2.3: Content Development Guide
Chapter 1. Getting started with SmartCloud Orchestrator
content
SmartCloud Orchestrator can be extended by providing different types of content
packages to enable SmartCloud Orchestrator to use the features that are delivered
by external software and infrastructure devices.
The different types of SmartCloud Orchestrator content that you can create and
deploy in the cloud are explained here.
Orchestrations
The following items are the orchestrations.
Content pack
Content Packs provide the building blocks for orchestrations that run on the
integrated Business Process Manager platform in SmartCloud Orchestrator.
Content Packs typically consist of a set of process applications and toolkits. Process
applications contain ready-to-use orchestrations and share library items from one
or more toolkits. Toolkits typically contain building blocks to be used by process
applications and other toolkits. They also provide sample processes and human
services to demonstrate the usage of those building blocks.
SmartCloud Orchestrator ships with a number of toolkits that provide building
blocks 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 6, Developing toolkit and application content, on page 11.
Processes and human services contained in process applications or toolkits can
then be configured to be run in SmartCloud Orchestrator in different ways:
Self-service offerings
A self-service offerings is a process that is not related to any pattern or
instance. For example, add a user. To understand how to create a
self-service operation, see the self-service offerings scenario. The offerings
are grouped into categories.
For more information about self-service offerings, see the following topics:
v Managing self-service offerings
v Using self-service
v Self-service offerings
Event-triggered action
Event-triggered actions are related to processes that are run as pre- and
post- operations during pattern deployment. For example, the operation
can be an automated approval process. To understand how to create an
event-triggered action in a real time scenario, see the event-triggered action
scenario.
Copyright IBM Corp. 2013, 2014 1
For more information about event-triggered action, see the following
topics:
v Event-triggered actions
v Making a process available as an orchestration action
User actions
A user action is a management extension for existing pattern instances, for
example, change a password.
For more information about user actions, see the following topics:
v User actions
v Making a process available as an orchestration action
Patterns
The following items are patterns.
Virtual system patterns
A virtual system pattern is one or more virtual images and applications
that implement a deployment topology. The topology parts are defined by
virtual images, add-ons, and script packages. A virtual system pattern is a
topology definition for repeatable deployment that can be shared.
See Chapter 5, Developing virtual system patterns, on page 9.
Virtual application patterns
Virtual application patterns are created to model virtual applications that
you can deploy to the cloud. A virtual application is defined by a virtual
application pattern. It is a complete set of operating system resources that
fulfill a business need, including web applications, databases, user
registries, messaging services, and transaction processes. Each virtual
application pattern is associated with a pattern type. This pattern type is a
collection of plug-ins that provide these resources and services for a
particular business purpose in the form of components, links, and policies.
The pattern types, product extensions of the cloud system, and the types of
virtual application that you build depend on the pattern types that you
enabled.
Virtual images
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance. Images can be extended to customize
the virtual images and the operating systems by adding script packages which
provide additional functionality during provisioning time and software bundles
that enhance the content of the image.
Software bundles
Software bundles contain and describe the software that is available for use
within a virtual image. They include information about how to install the
software, prerequisites of the software, and parameters that are available
for customizing the software. They combine the operating system
definition and custom software bundles to create virtual bundles that can
be provisioned in the cloud.
See Chapter 4, Developing content for image composition, on page 7.
2 IBM SmartCloud Orchestrator 2.3: Content Development Guide
Chapter 2. SmartCloud Orchestrator overview
IBM SmartCloud Orchestrator provides end-to-end service deployment across
infrastructure and operating system layers. It provides integrated IT capabilities for
orchestration workflow automation and IT governance, resource monitoring, and
cost management.
Your data center policies, process, and infrastructure can be integrated with the
cloud in a consistent, flexible, and automated way, across various IT domains. You
can define and implement business rules and IT policies with an intuitive
graphical tool. It helps you to connect the aspects of the different domains into a
consistent orchestration of automated tasks and human tasks.
Architecture
SmartCloud Orchestrator is built on OpenStack and common pattern modeling.
Business Process Manager provides workflow modeling and runtime capabilities. It
is integrated so that event triggered automation provides the basis for cloud-centric
workflow enablement. The contents, toolkits, and other building blocks can be
found, used, adapted, and shared in the marketplace. For more information about
the SmartCloud Orchestrator architecture, see Product architecture
Cloud Provisioning and Orchestration Development
Collaboration Community
To evaluate future versions of this product, join the Development Collaboration
Community. From the Cloud Provisioning and Orchestration Development
Collaboration Community, you can use the hosted beta system and download the
beta code. The hosted system has the latest evaluation code. If you want to
evaluate 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.
.
Chapter 3. Installing and configuring IBM Process Designer
You must install and configure Process Designer, one of the user interfaces for
Business Process Manager to start with SmartCloud Orchestrator content
authoring.
Before you begin
This procedure describes the IBM Process Designer installation and configuration
on a Windows operating system.
Procedure
1. Install and configure SmartCloud Orchestrator. See the Installing section of the
SmartCloud Orchestrator information center. Business Process Manager is
installed as a product component.
2. Install Process Designer on the Windows operating system on which you
perform content development. See Installing IBM Process Designer in the
Business 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 (kersrv-3) of the machine where
Business Process Manager is installed.
c. Save the file.
4. Start Process Designer to develop content.
Chapter 4. Developing content for image composition
The Image Construction and Composition Tool builds virtual images for
deployment in cloud environments.
The Image Construction and Composition Tool provides capabilities to define and
construct multipurpose virtual images that are flexible. First, you define an
operating system environment and then you define software, such as application
servers and development tools. Finally, you provide the components of the virtual
image, define input parameters, and a set of configuration actions for your virtual
image. The tool then constructs the image and automatically wires the defined
configuration actions into the activation framework of the image. You can deploy
this image and test it on the IBM Cloud. For each deployment, you can pass
unique input parameters that your configuration actions can access. The result is a
virtual image that automatically configures itself based on the requirements that
are defined by the deployer. This approach produces a flexible virtual image. You
can construct highly customized virtual images for both private and public cloud
deployments.
You can reuse and manage virtual images and software in the cloud environment.
It provides an interface to build a model of a virtual image by combining models
of a base operating system and software bundles as main building blocks. When
you create the virtual image model, the actual software installation and image
building process is fully automated.
Using the Image Construction and Composition Tool of SmartCloud Orchestrator,
you can perform the following activities:
v Import virtual images from your cloud provider
v Create new virtual images
v Extend, edit, or capture existing virtual images
v Delete virtual images
v Search for existing virtual images
v Share software bundles by either importing them from or exporting them to a
remote system
v Create new software bundles
v Clone existing software bundles
v Publish software bundles
v Delete existing software bundles
v Search for existing software bundles
For marketplace upload or distribution, create a bundle deployment guide or user
guide, which provides step by step information about the usage of the bundle.
This document must include the following information:
v Expected software installer versions
v Part number on Xtreme Leverage
v Sample inputs
v Information about the successful testing of the bundle and its operation system
v Prerequisites packages required on the base image
A bundle can contain two or more .ras files, so compress all the .ras files and the
guide so that you have one file to upload or distribute.
For more information about the Image Construction and Composition Tool, see
IBM SmartCloud Orchestrator 2.2 > Managing virtual images > Working with IBM
Image Construction and Composition Tool information center.
For more information about bundle import through the command line, see
Chapter 7, Importing using the command-line interface, on page 23.
Chapter 5. Developing virtual system patterns
Virtual system patterns are topology definitions for repeatable deployment that can
be shared.
IBM provides several virtual system patterns that you can purchase and use.
Topic Link
For more information about creating and
managing patterns
See Managing and deploying virtual
patterns.
For more information about pattern import
through command line
See Chapter 7, Importing using the
command-line interface, on page 23
Chapter 6. Developing toolkit and application content
You can develop toolkit and application content.
Implementing workflow orchestration
Workflow orchestration is a Business Process Manager based extension to
SmartCloud Orchestrator which consists of UI panels to collect additional data.
Workflow orchestration is optionally implemented by Business Process Manager
human service and a Business Process Manager business process, which define the
logical flow of activities of the extension. The extension itself consists of the human
service and the business process, which are developed with the standard Business
Process Manager designer. After development, it is registered as an extension
operation in the Orchestration Actions or Self-Service Offerings of SmartCloud
Orchestrator. After you register it, it is available in SmartCloud Orchestrator.
The Business Process Manager-based extension types are:
Event-triggered actions
A custom operation that plugs into the existing programming flow at a
predefined plug point or event. For example, the Before provisioning or
After provisioning event is used during the deployment of a virtual
application pattern or virtual system. This operation is used to extend the
basic capabilities ofSmartCloud Orchestrator management operations. For
more information about pattern deployment, see IBM SmartCloud
Orchestrator 2.2 > Managing orchestration workflows > Orchestration workflows
> Event-triggered actions in the SmartCloud Orchestrator information center.
User action
A custom action that you can run on a single image deployment, virtual
system instance, or virtual application instance. These kinds of operations
implement lifecycle management actions that extend the set of predefined
management actions for service instances. For example, because the list of
predefined operations does not include a system backup, it can be
implemented as an user action. IBM SmartCloud Orchestrator 2.2 > Managing
orchestration workflows > Orchestration workflows > User actions in the
SmartCloud Orchestrator information center.
Self-service offerings
A custom operation that is run in the context of the data center. These
operations are administrative operations that are used to automate the
configuration and user operations. Self-service offering are used to enhance
the catalog of available services with more features. They are classified into
different categories. For more information about self-service offering, see
the following topics in theSmartCloud Orchestrator information center:
v IBM SmartCloud Orchestrator 2.2 > Managing orchestration workflows >
Orchestration workflows > Self-service offerings
v IBM SmartCloud Orchestrator 2.2 > Working with self-service > Managing
self-service offerings
v IBM SmartCloud Orchestrator 2.2 > Working with self-service > Using
self-service
Managing business processes
IBM Business Process Manager Standard is a comprehensive Business Process
Management offering. It gives you visibility and insight to manage business
processes. 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 and
their components in Business Process Manager. It has a name and a unique tag
(acronym) that can have a maximum length of seven characters. Business Process
Manager process applications and their related artifacts are stored within a
repository, which is hosted and managed by the process center. Process
applications can be created either from the web interface of the process center
console 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 be
granted either by using the Business Process Manager process designer tooling or
the Business Process Manager process center console. If you are an administrator
user, 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 Process
Designer.
Process application
A process application can contain one or more Business Process Definitions, which
represent a model, or template, of a business process that is run. The process
application consists of the following definitions and activities:
v Input and output variable definitions
v Business object data definitions
v User interface panel definitions
v Activities of the process that include the flow
The flow defines how the various activities of the process are orchestrated. When a
process is started, an instance of the process is created from the process definition
template.
Toolkit
A toolkit is a container for Business Process Manager artifacts like Business Process
Definitions, Business Objects, Human Services, Coaches, and Business Process
Definitions. Toolkits are used to package reusable Business Process Manager
artifacts as package content that can be used to build other Business Process
Definitions. But in contrast to a Process Application, a toolkit cannot be deployed
to the Business Process Manager runtime environment as a stand-alone solution.
Instead, the artifacts that are contained can be used as building blocks by other
Process Applications, but must be declared as a dependency on the toolkit.
Multiple Process Applications can have a dependency on the same toolkit and
toolkits can have also dependencies on each other. Toolkits and Process
Applications 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
marketplace. You can download from marketplace and then import it into another
Process Center. In SmartCloud Orchestrator, do not use the option to export a
toolkit or Process Application to a Business Process Modeling Notation (BPMN)
file.
Snapshot
The status of a Process Application or a toolkit can be captured by the Process
Designer tool or the web console of the Process Center. This snapshot defines a
specific version of the toolkit. It consists of all the related artifacts and their content
or state at the time when the snapshot is taken. The tip level is the most recent
version of a Process Application or toolkit. As a prerequisite, define a snapshot of a
Process Application for most of the management actions like export Process
application or toolkit, archive, define a dependency on a toolkit.
Business Process Definition
A Business Process Definition is a reusable model of a process that defines what is
common to all runtime instances of that process model. Processes are graphically
modeled in the Process Designer tool, which captures the flow of steps (activities).
This graphical diagram represents activities in the process as boxes and lines
connect them to describe the flow of work. Each box represents an activity and is
labeled with its description in the diagram. A Business Process Definition must
contain 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 Definition
into one or more horizontal sections. For example, when an activity (Business
Process Manager artifact) is added to the process diagram, its vertical position
determines the lane to which it belongs. Because each lane can be associated with a
role, you can observe the association of an activity of a Business Process with the
role. For each Business Process Definition that you create, you must declare
variables to capture the business data that is passed from activity to activity in
your process. Variables can be input to the process (input variables), output from a
completed process (output variables), or local variable (private variables).
Related information:
http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/topic/
com.ibm.wbpm.main.doc/topics/cbpm_bpd.html
Service
The activities that are contained in the Business Process Definition describe the
overall flow of the process, but it does not capture the implementation of the
process. Services are reusable implementations of activities in a Business Process
Definition. When a Business Process Definition starts, the services carry out the
required functions.
The following types of services are available in Business Process Manager:
Integration service
Use an integration service when you want to integrate with an external
system. An integration service is the only type of service that can contain a
Java or web service or REST integration.
General system service
Use a general system service when you must coordinate other nested
services or when you must manipulate variable data. General System
services cannot include Java, web service, or REST integrations directly.
Chapter 6. Developing toolkit and application content 13
Human service
Use a human Service when you want an interactive service with UI panels
(Coaches). Human Services generate human tasks in the Business Process
Manager Process Portal.
Ajax service
Use an Ajax service when you want to include a control in a Coach to
implement dynamic data selection. For example, you can automatically
populate lists and complete edit boxes. An Ajax service can pull data
dynamically from a connected data source such as a database.
Decision service
Use a decision service when you want a condition to determine the
implementation.
Web service
Use a service to implement a web service in Business Process Manager.
http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/topic/
com.ibm.wbpm.wle.editor.doc/modeling/topic/creating_services_B.html
Participant group
A participant group is used to represent a set of users in your organization or
enterprise locally within an application. Participant groups can be found in the
Processes category within Business Process Manager Process Designer. The
members of a Participant Group are local to the Business Process Application in
which it is defined. In contrast, the Security Groups provide a global mechanism to
define groups.
Remember: A participant group is a logical group that does not exist outside of
the concept of the Business Process Application in which it is defined.
After a Business Process Application is installed on a Process Server in a different
environment, you must add or remove users in those groups. For this
management, use the Business Process Manager Process Admin Console.
Coach validation framework
Business Process Manager includes a server side validation framework for
validating coach data that is entered during run time. This feature simplifies the
validation logic that identifies invalid user input and sends notifications during
run time. Server script or a service defines the validation logic. Any service, other
than Ajax service or a human service can be used as a validation service. Multiple
coaches in a human service flow can use the same validation service or server
script. The coachValidation of type CoachValidation business object is a new
system variable that contains information about validation errors.
Fire validation
The fire validation when added to a link connects a boundary event to the next
step 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. Select
Before or Never in the Fire Validation field. On selection of Before, the validation
is 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 the
originating coach. For example, if there is a validation error in the input, the focus
is 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. For
example, tw.system.addCoachValidationError.
It takes three parameters. The first parameter is the system variable
coachValidation. The second parameter is a string that contains full path to the
data item that contains the error. The third parameter is the message that must be
displayed in the event of the occurrence of an error. If the invalid data is not
bound to any coach view, then the validation error is not displayed.
Implementing extensions with SmartCloud Orchestrator
You can build custom extension operations that are based on business processes
and human services, for UI extensions, by using the Business Process Manager
Process Designer tool. The business logic of the extension is implemented by the
Business Process Definition. The association between a UI extension that is based
on a human service and business process definition is done during the registration
of the extension operation in the orchestration actions or self-service offering.
SmartCloud Orchestrator delivers a Business Process Manager toolkit that is called
SCOrchestrator_toolkit. It provides many useful artifacts such as business
processes, services, human services, coaches, business object definitions, java
classes that assist you to build custom extensions operations for SmartCloud
Orchestrator. Additionally, the SCOrchestrator_toolkit contains samples that show
how to build custom extensions. Other Business Process Manager toolkits are
downloadable from the marketplace. They provide additional content for different
areas (networking, storage) that can be used to build SmartCloud Orchestrator
extensions.
Restriction: If a process application or a toolkit in Business Process Manager has
more than one defined snapshot, then only the artifacts at the top level can be
used 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 SmartCloud
Orchestrator
The following steps are needed to develop a custom extension operation with or
without a user interface for SmartCloud Orchestrator:
Before you begin
Make sure that the SCOrchestrator_toolkit is imported into the Business Process
ManagerProcess Center repository. See http://pic.dhe.ibm.com/infocenter/
dmndhelp/v8r0mx/topic/com.ibm.wbpm.admin.doc/managinglib/topic/
managing_toolkits_I.html.
Procedure
1. Create a Business Process Manager Process Application as a container for your
extension operation. For information about managing process applications, see
http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0mx/topic/
com.ibm.wbpm.admin.doc/managinglib/topic/
managing_process_applications_A.html.
2. In the Business Process Manager Process Designer, open your Business Process
Application 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
SmartCloud 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://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0mx/topic/
com.ibm.wbpm.admin.doc/managinglib/topic/managing_snapshots_A.html
7. Register the extension operation in the SmartCloud Orchestrator UI. For more
information about custom operation registration, see Administering >
Administering SmartCloud Orchestrator > Managing self-service offerings and
SmartCloud Orchestrator Administrator's guide > Managing the orchestration actions
> Event-triggered actions and SmartCloud Orchestrator Administrator's guide >
Managing the orchestration actions > User actions.
Results
You can now use the extension operation in SmartCloud Orchestrator.
Related tasks:
Chapter 10, Publishing SmartCloud Orchestrator content to Cloud Automation
Marketplace, on page 41
IBM Cloud Automation Marketplace is a platform and one-stop-shop for IBM
SmartCloud customers, partners, and IBMers. The content that you create can be
submitted internally or externally from IBM in Integrated Service Management
Library (ISML) for Cloud/Virtualization category. The primary goal is to have an
environment where developers, partners, and IBM Service teams share content
with one another. This web-based application is envisaged to federate content from
several repositories into a single cloud automation content catalog.
Start a custom extension operation
Starting a custom extension operation is done with or without a user interface.
Start the operation and the following activities are automatically run in the
specified 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 SmartCloud
Orchestrator UI.
v A deployment operation or another operation that triggers the events are
started from the SmartCloud 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 Workload
Deployer to get the operation context business object. It is based on the
operation context id that is given as input parameter.
v The coach panels gather the parameters from the user and stores the
parameters into the output business object of the human service.
v When all user input information is collected, the last activity in the Business
Process Manager human service (ReturnParameters) is run to persist the
output business object into the operation context of the task engine. These
business objects can be used later by the extension Business Process Manager
Business Process. The status of the task in the task engine is set Queued so
that the task can continue to run.
3. The task engine starts the Business Process Manager process, which gets the
operation context as input parameter. For self-service offering and user actions,
the process starts directly after the human service ends, and for event-triggered
actions when the corresponding event fires. The Business Process
Managerprocess defines an input business object, which contains the
parameters that are collected by the user interface of the related human service.
The parameter section of the operation context also contains the parameters
that are collected by the graphical user interface of the human service.
Implementation of a human service as a UI extension
A Business Process Manager human service that can be used as UI extension for
SmartCloud Orchestrator is developed with Business Process Manager Process
Designer. Observe the following guidelines:
v Make the human service available in Business Process Manager as URL to the
participant group, which is used in SmartCloud Orchestrator. This activity can
be done in the Process Designer as follows:
Go to the Overview tab of the design view.
In the Exposing section, select All Users in Expose to Start.
Register the process in the orchestration actions or self-service offering
- In the SmartCloud Orchestrator UI, go to Configuration > Orchestration
Actions or Configuration > Self-Service Offerings.
- 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 the
orchestration actions or self-service offerings for the user or user group. It
decides which users or user groups are allowed to run the extension.
v The business object defines the interface of the human service and the related
business process. This business object contains the parameters to be returned by
the human service. The human service acts as an UI extension for SmartCloud
Orchestrator, which are the input parameters of the related business process.
Therefore, a human service defines an output variable with name
outputParameterObject. It is of type business object that is defined by the
creator of the extension.
v Declare operation context id as an input variable of type string. The human
service gets the operation context id as input variable. For example,
operationContextId. As first activity of the human service (before it can access
the operation context), it must use the activity GetOperationContext that is
delivered with the SCOrchestrator_toolkit. This activity retrieves the operation
context by using the operation context id.
v Define a UI coach or a sequence of coaches to collect the data that are needed
from the user.
v As a last activity, the human service calls the ReturnParameters integration
service of SCOrchestrator_Toolkit. Here, the data collected from the user is
registered on the operationContext. This data is then passed as an input
parameter to the associated business process.
Related concepts:
Coach validation framework on page 14
Coach validation framework
Implementation a Business Process Manager process as an extension
A business process that can be used as extension operation for SmartCloud
Orchestrator is developed by using Process Designer. It must observe the following
guidelines:
v The Process Designer must be made available in the Business Process Manager
as URL to the participant group. This group uses it in SmartCloud Orchestrator.
The participant group controls the user or user group visibility for the extension
operation. It is made visible in the configurations to be registered as extension
operation. It also decides which users or user groups are allowed to run the
extension.
v Every Business Process has inputParameterObject, which is an input parameter.
The type of this variable is same as the output parameter of the associated
human 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 parameter
and must define a corresponding input variable of type OperationContext. It is a
predefined business object definition that is delivered by SCOrchestrator_toolkit.
v With activities, the business process can access the information that is contained
in the operation context. Also, the information is handed over as parameter from
the associated human service. It can also use REST calls to retrieve further
information from Workload Deployer. REST calls are implementations that are
provided by SCOrchestrator_toolkit.
Best practices and guidelines
When you create toolkits or Process Applications, there are some best practices to
be followed in naming conventions, structuring, modeling, and error handling.
Guidelines for naming and documenting your toolkit or
process application
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 can
easily identify the exported snapshots later.
AA The SmartCloud Orchestrator release that is prerequisite for the toolkit
or process application, for example. 23 for SmartCloud Orchestrator 2.3
BB Counting up the version of the toolkit, for example. 00 for the first
release, and 01 for the second release
YYYYMMDD
The date the snapshot was created
v When updating an existing process application or toolkit, do not change the
chosen acronym because it is used to reference the processes in self-service
offerings.
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 Definition
as short as possible. The interface is defined by a Business Process Manager
Business Object. This object is used to correlate a business process with its
associated human services in the SmartCloud Orchestrator UI. Use the Business
Process Manager human service only to collect the parameters that are needed
by its associated business process. Implement the business logic in the business
process. It also helps if you enable the business process to be called by using the
REST API from an external application, such as a portal application.
v Avoid Pre and Post execution assignments. Instead, add explicit activities, if
needed. The execution assignments are hidden in the Business Process Manager
Process Designer, and the logic of the corresponding activity or service becomes
difficult to understand. If needed, use the Pre and Post executions to make
simple assignments like initializing the associated Business Process Manager
artifact. For example, consider having two consecutive coaches in a human
service. In such cases, do not initialize the objects that are used by the second
coach as being Post execution assignment of the first coach. If needed, do the
initialization as a pre-execution assignment of the second coach.
v Do not use passwords in environment variables or other artifacts that are visible
to everyone.
v When you deliver a solution for SmartCloud Orchestrator, make sure that there
are 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 a
toolkit. If you change the interface of building blocks in a toolkit, it becomes
cumbersome for all its dependent toolkits or Process Applications. Even
changing the name might lead to redoing the mapping for all activities or
services that use the building block.
Guidelines to structure your solution
v In general, an extension content solution for SmartCloud Orchestrator consists of
a Business Process Manager Process Application and a Business Process Manager
Toolkit.
The basic rule is that a process application contains artifacts that are ready to be
used by the user and not meant to be changed or adapted to be useful. All other
artifacts 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 process
application.
For example, a Business Process Manager, process A, can be called by another
Business Process Manager, process B. The Linked Process activity is used if
both 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, avoid
having 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 solution
to make it more understandable. If you have UI parts that can be used in UI
panels, define them as Coach views. These views can be reused in different
Coaches. If you must change something later, for example, wording, you change
only the reusable Coach view.
Guidelines for handling errors
A IBM developerWorks article explains extensively about exception handling and
logging from a business process management perspective. See Related Links. It
identifies the types of exceptions that are encountered in a Business Process
Manager scenario. Also, it shows you how to handle them using IBM Business
Process 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 Process
Manager processes or Human Services back to the SmartCloud Orchestrator UI.
For event and instance operations, these messages are written to the history
section of the pattern instance. For self-service offerings, these messages are
written 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 log
messages to the WebSphere log.
v Use the logging capabilities of Business Process Manager to log messages to the
WebSphere log. A good practice is to log in the entry and exit of an activity to
support debugging better.
http://www.scribd.com/doc/92505753/IBM-Impact-2011-Five-Guidelines-to-
Better-Process-Modeling-for-Execution-Stuart-and-Zahn
You can find many documents with guidelines and best practices about business
process modeling. One of it is Five Guidelines to Better Business Process Modeling for
Execution from Jonas A. Zahn and Stuart Jones, which describes the following design
guidelines:
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 applications
You can create toolkits or reuse toolkits that are shared by other content
developers. 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 the
toolkit from development process server to production process server or between
any two process servers.
Importing toolkits
Before you begin
To import toolkits into the Business Process Manager, complete the following steps:
Procedure
1. 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.
Chapter 7, Importing using the command-line interface, on page 23
Exporting toolkits
To export to a Business Process Manager export file, complete the following steps:
Procedure
1. 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 security
For a class of use cases, it is important to understand the security context of a
Business Process Manager process or user interface. The activity-based user
authentication and authorization are described here.
Business Process Manager user interfaces are run as the currently logged in user
and project. They are used as the initial dialog for collecting data in self-service
offerings and in orchestration actions. They are also used for assignments in the
My 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 an
admin 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. This
information is found in the variables user, domain, and project of the operation
context.
For instance, the GenericRESTCall integration service of
the SCOrchestrator_Toolkit extracts the authentication information from the
security context by default. The service then uses the extracted information to
construct the security authentication token (SimpleToken) for REST calls to external
systems. Because the tw_admin is an internal user, GenericRESTCall translates
tw_admin to the default admin user (generally admin) for external calls. It is
desirable to run these REST calls on behalf of the person who submitted the
request. To do that, map the user, domain, and project variables from the operation
context to the GenericRESTCall.
Chapter 7. Importing using the command-line interface
You can import SmartCloud Orchestrator content using the command-line
interface.
The following tools support the import of content by using command-line
interfaces:
v Import bundle into the Image Construction and Composition Tool
v Import content pack into Business Process Manager on page 24
v Import Workload Deployer command-line interface on page 24
v Virtual system pattern command-line interface on page 24
Important: You must have a command shell to run these commands.
Import bundle into the Image Construction and Composition Tool
To download and configure the Image Construction and Composition Tool
command-line interface, see Managing virtual images > Working with IBM Image
Construction and Composition Tool > Using the command-line interface > Downloading
and configuring the command-line interface.
To import a bundle in to the Image Construction and Composition Tool, use the
Syntax - $ icct -h <hostname> -P 443 -u <username> -p <password> -f
<script_file> <arg> .
-h <host> or --host
Specifies the host name or IP address of the Image Construction and
Composition Tool. If you specify this option, do not use the URL to access the
web interface.
-P <port> or --port
Specifies the TCP/IP port that is used to communicate with the Image
Construction and Composition Tool. The default value of 443 is used. This
parameter is optional and is case-sensitive.
-u <userid> or --userid
Specifies the user ID to authenticate to the Image Construction and
Composition Tool. Use the same user ID and password that you use to log on
to the tool. This parameter is optional and is case-sensitive.
-p <password> or --password
Specifies the password that is used to authenticate to the Image Construction
and Composition Tool. This parameter is optional and is case-sensitive.
-f <script_file><arg>*
Causes the command line to run the specified Jython script file with the
specified arguments. Any argument that follows the script file name is passed
to the Jython script. Only one -f parameter can be specified on the command
line. This parameter is optional.
icct -h myicct.mycompany.com -u admin -p admin -f
samples/importBundle.py /tmp/xyz.ras
Tip: The python script is present in samples directory and it is used for import.
For more information about Image Construction and Composition Tool
command-line interface, see Managing virtual images > Working with IBM Image
Construction and Composition Tool > Using the command-line interface.
Import content pack into Business Process Manager
A Business Process Manager-based extension to SmartCloud Orchestrator consists
of UI panels to collect more data. To import a content pack in to a Business Process
Manager, start the command-line interface in interactive mode and then run the
import command.
To start the command-line interface in interactive mode, use this syntax -
wsadmin.sh -h <hostname> -user <username> -password <password> -lang
jython. To Import content pack, use this syntax - >>>AdminTask.BPMImport([-
inputFile <file path>]).
The Wsadmin.sh is in the Business Process Manager server installation directory
and its parameters are as follows:
-h <host> or --host
Specifies the host name or IP address of the Business Process Manager. This
parameter is required.
-user
Specifies the user ID to authenticate to the Business Process Manager. Use the
same user ID and password that you use to log on to the tool. This parameter
is optional.
--password
Specifies the password that is used to authenticate to the user. This parameter
is optional and is case-sensitive.
wsadmin.sh -user admin -password admin -lang jython
wsadmin>AdminTask.BPMImport([-inputFile /tmp/abc.twx])
For more information about IBM Business Process Manager command-line
interface, see http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0mx/
index.jsp?topic=%2Fcom.ibm.wbpm.ref.doc%2Ftopics%2Frref_bpmimport.html.
Import Workload Deployer command-line interface
For administrative functions of Workload Deployer, download the command-line
interface onto a local workstation.
The command-line interface communicates with Workload Deployer, which helps
you to manage the deployer appliance in a scripted and non-graphical
environment.
Workload Deployer includes the virtual system pattern, virtual image, and virtual
application pattern.
Virtual system pattern command-line interface
For more information about downloading and configuring the virtual system
pattern command-line interface, see Downloading and configuring the
command-line interface.
The syntax for importing virtual system pattern command-line interface is
deployer -h <hostname. -u <username> -p <password> -f <scriptfile> -s <file
path>
-h <host> or --host
Specifies the host name or IP address of the Workload Deployer component.
This parameter is a required.
-u <userid> or--userid
Specifies the user ID to authenticate to the Workload Deployer component.
This parameter is optional.
-p <password> or--password
Specifies the password that is used to authenticate to the Workload Deployer
component. It is case-sensitive.
-f <script_file> <arg>*
Use this optional parameter to cause the command line to run the specified
Jython script file with the specified arguments. Any arguments after the script
file name are passed to the Jython script. Only one -f parameter can be
specified 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 as
follows:
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 SmartCloud Orchestrator is -
>>>deployer.virtualimages.create(http://server.xyz.com/path/to/
foo.ova).
v The import from a local disk is >>>deployer.virtualimages.create(<local
file path>).
Note: deployer.virtualimages.create imports the virtual image into IBM
v The import command for virtual application pattern -
deployer.applications.create(<local file path>)
Note: deployer.applications.create command imports a new virtual image to
the Workload Deployer component.
-h <hostname> or --hostname
Specifies the host name or IP address of the Workload Deployer component.
This parameter is required.
-u <userid> or --userid
Specifies the user ID to authenticate to Workload Deployer. This parameter is
optional.
-p <password> or --password
Specifies the password that is used to authenticate to Workload Deployer. This
parameter is optional and is case-sensitive.
For more information about virtual image command-line interface, see Virtual
images command-line interface reference.
For more information about virtual application pattern command-line interface, see
Virtual application pattern command-line interface reference.
Chapter 7. Importing using the command-line interface 25
Chapter 8. Example scenarios for workflow-based
orchestration
Workflows are driven by the following triggers: self-service offerings,
event-triggered actions, and user actions.
A quick start guide is available in the marketplace for content development. Search
for this guide in the marketplace by using SCOrchestrator Content QuickStart
Guide in the search filter. For more information about searching and downloading
from marketplace, see Chapter 10, Publishing SmartCloud Orchestrator content to
Cloud Automation Marketplace, on page 41.
Self-service offerings scenario
Self-service offerings are custom operations that can be run in the context of the
data center. Such offerings can be used to automate configuration tasks or to
enhance the catalog of the available services with extra features. This scenario
depicts a self-service offering for registering the firewall host device on
SmartCloud Orchestrator by storing the firewall details in the storehouse.
Procedure
1. In the Process Designer, click Create a New ProcessApp or Toolkit and name it
RegisterFirewall.
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 Register_Firewall_Host_HS. This
human service includes a coach, which collects the required input.
c. Click Variables tab.
Table 1. Input Variables
Variable Type Description
operationContextId String The ID contains the
operation context object
identifier, and it is passed
during the start of the
operation by theSmartCloud
Orchestrator framework. The
identifier is used to fetch the
operationContext, which is
an object that contains all the
data that is related to the
execution of an operation.
Note: This variable is
mandatory for all human
services that are run through
Table 2. Output Variables
outputParameterObject FirewallHost The output parameter is of
type FirewallHost business
object that has register
firewall host-related
parameters such as host IP
address, user name,
password, and port.
Note: This variable is
services that are run through
d. Create a business object and name it FirewallHost. Add the following
parameters to this business object:
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.
port Port open on the firewall host.
e. Create the following coaches:
Table 4. Coach
Coach Input fields
firewall_host_coach HostIpaddress
username
password
port
Map the parameters from the outputParameterObject to these coach fields.
f. Use the ReturnParameters integration service from the
SCOrchestrator_Toolkit before the 'end' activity.
g. Map the operationContextId and outputParamaterObject variable as an
input to 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 as
Register_Firewall_Host_BPD.
c. Click Variables tab
d. Click Add Input and create the following input variables:
operationContext OperationContext The operationContext object
contains all the data that is
related to the execution of an
operation.
inputParameterObject FirewallHost The input parameter is of
type FirewallHost.
Note: Both the input variables are mandatory for all business processes that
are run from SmartCloud Orchestrator.
e. Add the following private variables:
Table 6. Private Variables
firewallHostjson String FirewallHost is in JSON
string format.
storehouseRestUrl String Storehouse URL at which the
firewall host JSON data is
stored.
f. Add the integration service GetInputParameter from
SCOrchestrator_Toolkit as first activity in the business process. Complete
the data-mapping for this service.
g. Add the integration service ReadBusinessObject
from SCOrchestrator_Toolkit as a next activity in the business process.
This integration service converts the FirewallHost business object that is
passed as an input into a JSON string. Complete the data-mapping for the
service.
h. Add the integration service GenericRestCall from SCOrchestrator_Toolkit
as a next activity in the business process. This integration service makes a
REST call to store the data onto the storehouse. Complete the data-mapping
for the service. The list of parameters are as follows:
v method PUT
v restUrl storehouseRestUrl
v jsonString firewallHostjson
v iwdUser storehouse user
i. Connect the activities to complete the business process.
5. Expose the human service to the participant group. Go to Overview tab of the
human service and add the participant group to Expose to start option.
6. Expose the business process to the participant group. Go to Overview tab for
the business process and add the participant group to Expose to start option.
7. Register the operation in the SmartCloud Orchestrator UI.
a. Log in to the SmartCloud Orchestrator UI.
b. Click Configuration > Self-Service Offerings.
c. Click Add.
d. Enter the following details:
v Offerings name - enter the name of the new offering.
v Description - enter the description.
Chapter 8. Example scenarios for workflow-based orchestration 29
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 OK.
8. Run the Self-Service Offering.
a. Go to Self-Service.
b. Click Category.
c. Click Offering.
d. Enter the details and click OK.
9. After the operation completes successfully, check the firewall host data that is
stored on the storehouse through the storehouse browser.
http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=
%2Fcom.ibm.wbpm.main.doc%2Fmanaginglib%2Ftopic%2Fmanaging_toolkits.html
Information about how to include integration service, process, coach, and human
service inside the toolkit library.
Event-triggered action scenario
This scenario depicts a event-triggered action for post deployment of a pattern by
using a Linux virtual machine. A script file on the Linux virtual machine mounts a
filesystem from a storage device.
Before you begin
The script file to mount filesystem takes the following arguments as input:
storageDeviceIpaddress, use rname, password, and mount point. In this example,
the script file is copied on the deployed virtual machine and then it is run.
Procedure
1. In the Process Designer, create a Process Application and name it as
MountFileSystem.
2. Open the Process Application in the designer.
3. Upload the script file as a Server File in the designer.
a. Create a human service and name it Mount_FileSystem_HS. This human
service includes a coach, which collects the required input to mount a
filesystem on a virtual machine.
b. Click Variables tab.
Input variables Data type Description
identifier, and it is passed
during the start of the
operation by the SmartCloud
Orchestrator framework. The
identifier is used to fetch the
data that is related to the
operation.
Note: It is mandatory for all
human services that are run
from SmartCloud
Orchestrator.
Output variables Data type Description
outputParameterObject MountFileSytem The output parameter is of
type MountFileSystem
business object that has
mount filesytem related
parameters, such as
storageDeviceIpaddress, user
name, password, and mount
point.
Note: It is mandatory for all
human services that are run
from SmartCloud
Orchestrator.
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 storage
device.
username Log in user to the storage device
password Password for login user to the storage
device.
mountPoint Mount point of the filesystem on the storage
device.
e. Create the following coaches:
Table 10. Coaches
Coach Input fields
mount_filesytem_coach storageDeviceIpaddress
username
password
Table 10. Coaches (continued)
Coach Input fields
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 the
operationContextId and outputParamaterObject variable as an input to this
service.
g. Connect the activities to complete the human service.
6. Register the event-triggered action in the user interface of SmartCloud
Orchestrator.
b. Click Configuration > Orchestration Actions.
c. Click Add.
v Orchestration name - enter the name of the new instance.
v Action type- select Event-triggered action from the list
v 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 SmartCloud Orchestrator Business Process
Designer.
v User Interface - select Mount_FileSystem_HS. It is the Human Service that
is created in the SmartCloud Orchestrator Business Process Designer.
v Sequence priority - select 5
e. Click OK.
7. Run the event-triggered action
a. Go to Images and Patterns > Virtual System Patterns.
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 the
mounted filesystem.
User action scenario
The 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 creates
a user. In this example, createuser.sh exists on the virtual machine.
Procedure
1. In the Process Designer, click Create a New Process App and name it Create
User.
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 a
virtual machine.
c. Click Variables, and add the following input variables:
Input variable Data type Description
Identifier. It is passed during
the start of the operation by
theSmartCloud Orchestrator
framework. The Identifier is
used to fetch the
data that is related to this
operation.
Note: Input variable
operatingContextId is
services that are run from
Variable Data type Description
outputParameterObject CreateUserRequest The output parameter is of
type CreateUserRequest
business object that contains
create user related
parameters, such as user
name and password.
Note: Output variable
outputParameterObject is
services that are run from
d. Create a Business Object and name it as CreateUserRequest. Add the
following parameters to this business object:
Table 13. 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 14. Coaches
Coach Input fields
create_user_coach
v User name
v Password
Map the parameters from the
outputParameterObject to these coach fields.
f. Include theReturnParameters integration service of the
SCOrchestrator_Toolkit before the end activity.
g. Map the operationContextId and outputParamaterObject variable as input
to 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 15. Input variables
Input variable Data type Description
operationContext OperationContext The operationContext object
contains all the data that is
related to the operation.
inputParameterObject CreateUserRequest The input parameter is of
type CreateUserRequest
business object that has
create user related
parameters, such as
username and password.
Note: Input variables
inputParameterObject and
operationContext are
mandatory for all business
processes that are run in the
d. Add the following private variables:
Table 16. private variables
Private variables Description
VirtualMachine (VirtualMachine) It is of type 'VirtualMachine' business object
that contains the all the virtualMachine
related data.
Table 16. 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 is
present.
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_Toolkit
as the first activity in the business process. Complete the data-mapping for
this service.
f. Add a script task as next activity in the business process. This script activity
is 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 from
SCOrchestrator_Toolkit as next activity in the business process. This
integration service returns the user credentials for the virtual machine.
Complete the data-mapping for the service.
h. Add the integration service LinuxExecuteRemoteScriptfrom
SCOrchestrator_Scripting_Utilities_Toolkit as the next activity in the
business process. This integration service runs the script on the remote
machine. Complete the data-mapping for this service. The input parameters
required for this service are:
v scriptName - createuser.sh
v remoteMachineIp virtualMachineIp
v username virtualMachineUsername
v password virtualMachinePassword
v workingDirectory workingDirectory
v 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 the
human service and add the participant group to Expose to start option.
6. Register the operation in the SmartCloud Orchestrator UI.
b. Click Configurations> Orchestrator Actions.
c. Click Add.
v Orchestration name - enter the name of the new Orchestration Actions
entry.
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 Instances > Virtual Systems
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 the
new user.
Chapter 9. Automating the creation of categories, offerings,
and user actions
You can automate the creation of categories, offerings, and user actions using the
SCO-CatalogImport.sh tool.
Before you begin
The SCO-CatalogImport.sh tool is installed together with SmartCloud Orchestrator.
The installation directory of the SCO-CatalogImport.sh tool is /opt/ibm/ccs/
catalog.
The tool selects the JVM in the following order:
1. The JVM used by Workload Deployer, if it exists
2. The JVM used by the Business Process Manager, if it exists
3. The JVM defined in PATH variable, if there is any
4. The JVM in the JAVA_HOME variable, if it has been defined
The SCO-CatalogImport.sh tool is installed both on the Workload Deployer node
and the Business Process Manager node.
To automate the creation of categories, offerings, and user actions, you need the
following items:
v A configuration file that describes the SmartCloud Orchestrator environment
v An XML file that represents the resources to be created
v Valid credentials to connect to the SmartCloud Orchestrator. Admin role is
required.
Note: Although, in this topic, the script is SCO-CatalogImport.sh, if you are
installing on a Windows operating system, the script is SCO-CatalogImport.bat.
About this task
The following directories contain the following items:
conf
v log4j.properties, logs, and trace configuration
v env.properties, the configuration file for SmartCloud Orchestrator (IP
address)
samples
Various 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 create
your <category>, <offering>, and <user-actions> 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 are
allowed:
Cloud Cloud Category Icon
Application
Application Category Icon
Backup
Backup Category Icon
Client Client Category Icon
Configuration
Configuration Category Icon
Job Job Category Icon
Network
Network Category Icon
Server Server Category Icon
Storage
Storage Category Icon
Virtual Machine
Virtual Machine Category Icon
Web Web Category Icon
For offerings, specify the following parameters:
<offering>
<name>A test offering</name>
<icon>Web</icon>
<category-name>Reference a category by name here</category-name>
<process>
<name>Enter the name of the process you want to link to the offering</name>
</process>
<user-interface>
<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 service
offering. The description and icon fields are optional. For icon, the same fields
that are described for category are allowed here too.
For user actions, specify the following parameters:
<user-action>
<name>A test useraction</name>
<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>
To create the resources described in <yourfile>.xml in the SmartCloud Orchestrator
Self Service catalog, run the following command:
./SCO-CatalogImport.sh <yourfile>.xml <SCO username> <SCO username password>
where
v <yourfile>.xml is your catalog file to create your catalog resources
v <SCO username> ia a SmartCloud Orchestrator administrative user name
v <SCO username password> is the password for the user specified previously
Note: Being an administrative tool, the SCOCatalogImporter too must not be run
in concurrent mode. You cannot run an instance of the tool and catalog
administration from the SmartCloud Orchestrator.
What to do next
An additional step is required if the tool is installed as separate component from
SmartCloud Orchestrator, for example, the tool is downloaded from the IBM
Marketplace and installed on a desktop. You must edit the tool configuration file,
located at conf/env.properties, with the following content:
IWD_HOST = <IP or HOSTNAME of SmartCloud Orchestrator>
IWD_PROTOCOL = https
IWD_PORT = 443
IWD_PROTOCOL = https and IWD_PORT = 443 are the default values that you must
use.
Chapter 9. Automating the creation of categories, offerings, and user actions 39
Chapter 10. Publishing SmartCloud Orchestrator content to
Cloud Automation Marketplace
IBM Cloud Automation Marketplace is a platform and one-stop-shop for IBM
SmartCloud customers, partners, and IBMers. The content that you create can be
submitted internally or externally from IBM in Integrated Service Management
Library (ISML) for Cloud/Virtualization category. The primary goal is to have an
environment where developers, partners, and IBM Service teams share content
with one another. This web-based application is envisaged to federate content from
several repositories into a single cloud automation content catalog.
About this task
To download content from the Cloud Automation Marketplace, access the IBM
Integrated Service Management Library and search for a solution.
To upload content to the Cloud Automation Marketplace, access the Ready for IBM
Tivoli software site and follow the validation process.
For additional information about content development, see the Content Developers
Corner wiki.
Appendix A. SCOrchestrator toolkit
The SCOrchestrator_Toolkit is delivered as a part of SmartCloud Orchestrator. It
provides the essential Business Process Manager building blocks, which are needed
to build Business Process Manager business processes and human tasks, which are
used as extensions for SmartCloud Orchestrator.
If you want to write an extension for SmartCloud Orchestrator, you must perform
the following tasks:
v Ensure that the toolkit was imported into Business Process Manager, which is
done by the SmartCloud 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 17. Building blocks
Building block Section Function
Business object Data Interface between IBM
Workload Deployer and
Business Process Manager
business processes that are
provided as business objects
within the toolkit. You can
use them for parameter and
private data declarations
with Business Process
Manager.
General system services,
integration services, and web
services
Implementation Define Business Process
Manager process extensions.
They have a defined
interface (input and output
variable definitions) that are
based on standard business
objects that are provided by
and the
SCOrchestrator_Toolkit.
Human services User Interface Sample UI extensions for a
SmartCloud Orchestrator
extension. ABusiness Process
Manager coach, which is
included in a human service,
defines a UI panel.
Table 17. Building blocks (continued)
Building block Section Function
Set of sample Business
Process Manager processes,
human services, and other
artifacts
Tagged as
SCOrchestrator_Samples,
contain the Sample prefix in
their name.
Provide samples that show
you how to use the building
blocks that are delivered
with the toolkit. Required to
write operation extensions
for SmartCloud Orchestrator.
Some samples are ready to
use, other must be adapted.
The documentation that is
provided with every sample
artifact includes information
about how to use it.
Configuration
The SCOrchestrator_Toolkit has a few configuration options. If you use your own
process application or toolkit that has a dependency on the
SCOrchestrator_Toolkit, adapt the configuration options to your environment as
follows:
v iwdAuthAlias - authentication alias that is used for REST calls from a Business
Process Manager process to Workload Deployer. It must be configured in the
Java
Authentication and Authorization Service of the WebSphere
Application
Server 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 byBusiness Process Manager
environment variables, which can be configured by using the admin console of
Business Process Manager.
Business objects
The business objects provide a natural representation of the business data for
application processing. You can use the business objects included in the
SCOrchestrator_Toolkit to create custom objects.
The following business objects are delivered as part of the
SCOrchestrator_Toolkit:
v OperationContext
v ServiceInstance
v MetaData
v VirtualMachine
v NetworkInterface
v Role
v Service
v CloudGroup
v Hypervisor
v HypervisorFiler
v Parameter
Further, you must define the business objects for other IBM Workflow Deployer
REST calls, that is, retrieve the user information from SmartCloud Provisioning.
Representation of long types in business objects
Long types are not supported by Business Process Manager. Therefore, the simple
type business object LongString is introduced as a part of the
It represents a long type that is encoded as a string. For a new business object that
contains a long type, define a new variable with the data type LongString. Ensure
that it has the same name as defined by the SmartCloud Provisioning object
variable. An example is the variable created (LongString) found in the CloudGroup.
When serializing JSON Objects to IBPM business objects, the long typed variables
are automatically mapped to the defined Business Object variables of type
LongString. When deserializing business objects to JSON objects, the type
LongString indicates the mapping to the origin data type Long.
OperationContext
The operation context is an umbrella object that contains all data that is related to
the execution of an operation. This operation context object must be defined as an
input parameter variable for all business processes that are started as an extension
for a SmartCloud Orchestrator operation. Human services must define the
operation context ID as an input parameter and as a first activity, must retrieve the
operation context object with its ID.
The structure is as shown in the table:
Table 18. OperationContext Structure
Attribute Data type Description
id String The unique operation context
identifier.
Status String The status of the task that is
associated with the operation
context.
eventTopic String The array that contains an
object for each role.
description String The description of the ID.
Params Map The map that contains
(key/value) pairs for storing
arbitrary parameters. It can
be used, for example, to
hand over parameters that
are collected from UI coaches
in an extension Human
Service to the associated
Business Process.
serviceInstance ServiceInstance The service instance is the
instance umbrella object that
contains managed
virtualMachines, roles,
services, and instance level
metadata.
Appendix A. SCOrchestrator toolkit 45
Table 18. OperationContext Structure (continued)
user String The ID of the user in whose
context the operation is
executed
domain String The name of the domain in
whose context the operation
is executed
project String The name of the project in
whose context the operation
is executed
Service Instance
The service instance is an instance umbrella object that contains managed virtual
machines, roles, services, and instance level metadata.
It has the following structure:
Table 19. Service Instance Structure
metaData Object This object contains instance
level information like the
instance name, unique
identifier, type, owner, and
access information.
virtualMachines Array of Object This array contains an object
for each managed virtual
machine.
roles Array of Object This array contains an object
for each role.
services Array of Object This array contains an object
for each service. A service is
a managed entity that is not
a virtual machine or a role.
MetaData
This business object describes the meta data of a service instance like its name,
type, status, and unique identifier. It has the following structure:
Table 20. MetaData Structure
Attribute DataType Description
name String The human-readable name for this
instance.
type String The internal (non-localized) type.
status String The internal (non-localized) status.
id String The URI to retrieve the most current
version of this document.
virtualSystemId String The URI to retrieve the virtual
system if one is associated.
Table 20. MetaData Structure (continued)
Attribute DataType Description
virtualApplicationId String The URI to retrieve the virtual
application instance if one is
associated.
virtualApplicationPatternId String The storehouse URI for the vApp
pattern if one is associated.
virtualSystemPatternId String The URI for the system pattern used
to create if one is associated.
creator String The ID of the user who initiated the
deployment of the instance. This id
is a resource id like
/resources/users/1 for vSys and
single image deployments, and a
storehouse id like
/storehouse/admin/users/u-0 in
other cases.
cloudGroup String (URI) The that the virtual application
instance was deployed to. The field
can be empty for virtual system
pattern deployments, or single
image deployments.
parameters Map This map contains a (key/value)
pair for each parms. See the parms
section below for more detail.
VirtualMachine
The VirtualMachine business object describes a virtual machine as part of a
deployment.
Table 21. VirtualMachine structure
name String An identifier for the virtual
machine. It does not match
the primary host name of the
virtual machine. The
identifier is unique within a
service instance.
cloudGroup String The URI of the availaiblity
zone where the virtual
machine is deployed.
networkInterfaces NetworkInterface (List) A list of network interfaces
that the virtual machine is
equipped with.
hostname String The primary host name for
the virtual machine. If there
are multiple network
interfaces, the primary host
name is implementation-
dependent.
Table 21. VirtualMachine structure (continued)
virtualCpu Integer The number of virtual
processors, that is, the
number of processors that
the guest operating system
observes on this virtual
machine.
memory Integer The amount of memory that
is observed by the guest
operating system. The unit of
measurement is mebibytes. (1
== 1048576).
disk Integer The size of the primary/root
disk.
imageId String The image that is used to
create this virtual machine.
Note: The virtual machine
and image lifecycle are
separated from one another,
that is, the image can go way
before the virtual machine.
Do consider this point when
you dereference this URI.
parameters Map The map contains a
(key/value) pair for each
params. See the params
section for more details.
Id String A unique string identifier of
the virtual machine that is
relative to the service
instance base url.
NetworkInterface
The NetworkInterface business object describes a network interface of a virtual
machine.
Table 22. NetworkInterface Structure
ip String The IPv4 address in dotted
decimal notation or the IPv6
address.
hostname String A host name that must
resolve to the specified IP
through DNS.
ipgroup String The URI of the IP group
from which this address was
allocated.
Role
The Role business object describes a role that a virtual machine can have in a
pattern.
Table 23. Role Structure
name String The name of the role.
type String The type of the role.
endpoints String (List) A list that contains an object
for each endpoint. See the
endpoint section more
details.
Parameters Map A JSON object that contains
custom parameters that were
provided by extension
writers.
id String The unique identifier of the
role.
Endpoint
The endpoints contain the URIs on how to access a specified role.
Table 24. Endpoint Structure
Name String A human-readable string that
identifies this endpoint.
URI String The URI to which this
endpoint points.
Service
The Service business object describes a service.
Table 25. Service Structure
name String A human-readable string that
identifies this service
type String Either a Java style package
identifier or a TOSCA node
type.
params JSONObject This object contains custom
parameters that were
provided by extension
writers. See the params
section for mor e detail.
CloudGroup
The CloudGroup business object describes a SmartCloud Orchestrator cloud group.
Table 26. CloudGroup Structure
address String The network address or host
name used to communicate
with the VMware Virtual
Center represented by a
cloud group.
certified String Indicates if the SSL certificate
from this VMware Virtual
Center has been accepted.
Use the
Cloud.acceptCertificate()
method to accept a
certificate.
created LongString Specifies the creation time of
the cloud group, represented
as the number of
milliseconds since midnight,
January 1, 1970 UTC. This
value is numeric and is
automatically generated by
the product. This attribute is
available for all cloud
groups.
currentstatus String The current status of the
Cloud object. This attribute
contains an 8 character string
value that is generated by
the product.
currentstatus_text String This is a string
representation of
currentstatus in the preferred
language of the requester
and is automatically
generated by the product.
This attribute is read-only.
defaultcloud String Specifies if this cloud group
is the default cloud group
used by SmartCloud
Orchestrator. User created
cloud groups will always
have this value set to 'F'.
This field expects a string
value of 'T' or 'F' with a
maximum of 1 character.
description String Specifies a description of the
cloud group. This field
expects a string value with a
maximum of 1024 characters.
Table 26. CloudGroup Structure (continued)
endpointtype String Specifies the type of
endpoints managed by the
cloud group. This read-only
value depends on the target
endpoints currently added to
the cloud group. The value
of the endpoint type can be
one of the following:
v Hypervisor - the cloud
group manages one or
more hypervisor
endpoints.
v Pool - the cloud group
manages a pool.
v Cluster - the cloud group
manages a cluster.
v None - the cloud group
does not manage any
endpoint.
v Mixed - the cloud group
manages endpoints of
multiple types.
hypervisors String Specifies a list of the uniform
resource identifiers (URIs) of
the hypervisors that are
assigned to the cloud group.
The URIs are relative and
should be resolved against
the URI of the cloud group
that contains them.
id Integer Specifies the Id of the cloud
group. This numeric value is
the product.
name String Specifies the name associated
with this cloud group. This
field expects a string value
with a maximum of 64
characters. Each cloud group
must have a unique name.
owner String Specifies the user that is the
owner of this cloud.
password String Password used to access the
VMware Virtual Center that
manages the cloud group.
type String The type of this cloud group.
For custom cloud groups this
value is none, for managed
cloud groups this value is
manager. This value may be
specified when the cloud
group is created, but cannot
be changed afterwards.
Table 26. CloudGroup Structure (continued)
updated String Specifies the time the cloud
group was last updated,
represented as the number of
the product.
userid String User id that is used to access
the VMware Virtual Center
that manages the cloud
group.
vendor String Specifies the type of
hypervisors this cloud group
will contain. This field
expects a string value with a
This string value must
always be OpenStack.
params
The Parameter object is a free-form JSON object that holds additional parameters
required 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 retrieve
the data later from a Business Process Manager process or other extension. This
storage is backed by the storehouse metadata APIs.
Table 27. Params Structure
jsonString String JSON representation of a
parameter. This attribute
accepts any valid JSON
string.
Hypervisor
The Hypervisor business object models a stand-alone hypervisor object in
SmartCloud Orchestrator, but not a hypervisor that is managed by a virtual center.
Table 28. Hypervisor Structure
address String Specifies the host name or IP
address (dotted decimal
notation) at which the
hypervisor can be reached.
value with a maximum of
1024 characters.
certified String Specifies if the SSL certificate
from this hypervisor has
been certified. SmartCloud
Orchestrator does not deploy
patterns to a hypervisor until
it has been certified. Note
that the SSL certificate from
the hypervisor must be
retrieved before the
hypervisor can be certified.
The following string values
are valid:
v T Hypervisor has been
certified.
v F Hypervisor is not
certified.
v I Hypervisor is not
certified and resources
have not been discovered.
cloud String Specifies the uniform
resource identifier (URI) of
the cloud group to which
this hypervisor has been
assigned. The URI is relative
and should be resolved
against the URI of the
hypervisor.
created LongString Specifies the creation time of
the hypervisor, represented
as the number of
the product.
Table 28. Hypervisor Structure (continued)
currentmessage String Specifies the message
associated with the current
status of the hypervisor. For
example, it could give more
details about the problem
that caused the hypervisor to
be placed in an error state.
This field contains an 8
character string value that is
currentmessage_text String Specifies the textual
representation of
currentmessage. This is a
string representation of
currentmessage in the
preferred language of the
requester and is
the product. This field has a
currentstatus String Specifies a string constant
representing the current
status of the hypervisor. This
field is an 8 character string
value that is automatically
currentstatus_text String Specifies a textual
representation of
currentstatus. This is a string
representation of
desiredstatus String Specifies the desired status of
the hypervisor. Setting this
value will cause SmartCloud
Orchestrator to initiate the
steps that are needed to get
the hypervisor to this state.
This value is an 8 character
string and can only be set to
one of the following values:
v RM01025 Maintenance
mode
v RM01006 Started
desiredstatus_text String Specifies a textual
representation of
desiredstatus. This is a string
representation of
desiredstatus in the preferred
endpointtype String Specifies the type of
endpoint type of this
hypervisor object. This
read-only value is
determined based on the
actual endpoint type of the
resource. The value of the
endpoint type can be one of
the following:
v Hypervisor: The resource
is a hypervisor.
v Pool: The resource is a
pool.
v Cluster: The resource is a
cluster.
id String Specifies the id of the
hypervisor. This attribute can
be a string or a number.
When the attribute is a
string, there are practical
limits on the string length
due to the way the string is
generated: ("PM-" + numeric
id).
name String Specifies the display name
associated with this
hypervisor. This field expects
a string value with a
maximum of 64 characters
and must be unique among
all hypervisors defined to
networks String (List) Specifies the list of URIs of
the networks associated with
this hypervisor. The URIs are
relative should be resolved
hypervisor that contains
them. This list of networks is
automatically generated as
part of the discovery process
and cannot be changed.
password String Specifies the password used
to log on to the hypervisor.
value with a maximum of
128 characters.
storage String (List) Specifies the list of URIs of
the storage associated with
them. This list of storage is
type String Specifies the type of this
hypervisor. This value must
be set to OpenStack. This
characters.
updated LongString Specifies the time the
hypervisor was last updated,
represented as the number of
the product.
userid String Specifies the user ID used to
log on to the hypervisor. This
characters.
UUID String The universally unique
identifier for the hypervisor.
For hypervisors that do not
have a UUID, this value will
be "none".
HypervisorFilter
The HypervisorFilter business object describes a filter object for a hypervisor. The
filter is used for REST calls from Business Process Manager to IBM Workflow
Deployer. All fields are filtered out of the JSON string before they are sent to IBM
Workflow Deployer because the database does not have these fields. The GET
method retrieves a hypervisor object from IBM Workflow Deployer through a
REST call. It returns some additional fields that are not a part of the database
representation for 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 29. HypervisorFilter Structure
currentstatus_text String Specifies a textual
representation of
currentstatus. This is a string
representation of
desiredstatus_text String Specifies a textual
representation of
desiredstatus. This is a string
representation of
desiredstatus in the preferred
currentmessage_text String Specifies the textual
representation of
currentmessage. This is a
string representation of
currentmessage in the
preferred language of the
requester and is
the product. This field has a
cloud String Specifies the uniform
resource identifier (URI) of
the cloud group to which
this hypervisor has been
assigned. The URI is relative
and should be resolved
hypervisor.
networks String (List) Specifies the list of URIs of
the networks associated with
them. This list of networks is
storage String (List) Specifies the list of URIs of
the storage associated with
them. This list of storage is
Table 29. HypervisorFilter Structure (continued)
uuid String The universally unique
identifier for the hypervisor.
For hypervisors that do not
have a UUID, this value will
be "none".
Services
To simplify parameter handling, most of the REST calls to IBM Workflow Deployer
have 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 operate
on complex business objects. Therefore, building blocks are needed to convert a
business 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 Services
The general system services of the Business Process Manager are defined along
with their input and output variables.
CreateBusinessObject_OperationContext
The CreateBusinessObject_OperationContext service creates a business object of
type OperationContext based on a JSON input string.
Table 30. CreateBusinessObject_OperationContext Input Variables
Input Variable Data type Description
operationContextString String JSON string that represents
the operationContext
Table 31. CreateBusinessObject_OperationContext Output Variables
Output Variable Data type Description
operationContext OperationContext It is a OperationContext
business object
GetVirtualMachineForRole
The service retrieves all virtual machines from the service instance.
Table 32. GetVirtualMachineForRole Input Variable
roleName String Name of the role
serviceInstance ServiceInstance Service instance
Table 33. GetVirtualMachineForRole Output Variable
virtualMachine VirtualMachine (List) List of virtual machines
GetInputParameter
The GetInputParameter general system service retrieves the inputParameterObject
of Business Process Manager business process. The inputParameterObject is used
as a workflow extension for SmartCloud Orchestrator. It must be the first activity
in each business process to be used as workflow extension for the SmartCloud
Orchestrator.
Table 34. GetInputParameter Input Variable
operationContext OperationContext The operation context object.
inputParameterObject_In ANY The inputParameterObject of
the process must be mapped
to this variable. It is required
to enable a process to be
called as linked process by
another process. In this case,
the inputParameterObject_In
is not null. In all other cases,
the inputParameterObject is
null, which indicates that the
process is called directly
from the SmartCloud
Orchestrator UI.
Table 35. GetInputParameter Output Variable
inputParameterObject ANY The inputParameterObject
contains the input
parameters for the business
process as collected by the
associated human service.
GetErrorMessage
The GetErrorMessage general system service receives as input an error XML
element, which is returned by the variable tw.system.step.error. It extracts and
returns the error message and stack trace from the XML element as output
variables.
Table 36. GetErrorMessage Input Variable
error XMLElement The XMLElement variable
containing the error
exception information as
returned by
tw.system.step.error variable.
Table 37. GetErrorMessage Output Variable
errorMessage String The error message extracted
from the XMLElement input
variable.
stackTrace String The stack trace extracted
from the XMLElement input
variable.
Integration Services
You define the integration services of the Business Process Manager together with
their input and output variables.
CreateBusinessObject_CloudGroup
The CreateBusinessObject_CloudGroup service creates a business object of type
CloudGroup that is based on a JSON input string.
Table 38. CreateBusinessObject_CloudGroup input variable
jsonString String JSON string that represents
the cloudGroup
Table 39. CreateBusinessObject_CloudGroup Output Variable
cloudGroup CloudGroup Cloud group
CreateBusinessObject_ServiceInstance
The CreateBusinessObject_ServiceInstance service creates a business object of
type ServiceInstance that is based on a JSON input string.
Table 40. CreateBusinessObject_ServiceInstance input variable
jsonString String JSON string that represents
the service instance
Table 41. CreateBusinessObject_ServiceInstance Output Variable
serviceInstance ServiceInstance Service Instance Business
Object
DecodeAlias
The DecodeAlias service decodes the Workflow Deployer Authentication Alias to
retrieve a user ID and a password for the communication with Workflow Deployer.
A REST call requires caller authentication at Workflow Deployer, so a plain
password and user name are attached to a REST call for basic authentication.
Business Process Manager Standard Edition does not offer password encryption. It
is possible to implement encryption facilities and integrate, for example, as
JavaScript or Java Integration Service. By default, WebSphere XOR encoding is
applied. If you want to use the WebSphere XOR encoding style, you need a JAAS
alias that is configured in the WebSphere Application Server console. For more
information about WebSphere XOR encoding style, see WebSphere documentation.
For password decryption in Business Process Manager, you must know the JAAS
alias, which is set as an environment variable in the SCOrchestrator_Toolki toolkit
(iwdAuthAlias).
Table 42. DecodeAlias input variable
iwdAuthAlias String WebSphere authentication
alias
Table 43. DecodeAlias output variable
iwdUser String Workload Deployer user ID
iwdPassword String Workload Deployer
password
GenericRestCall
The GenericRestCall service is based on a Java implementation for a generic REST
Call on Workflow Deployer.
By default, it extracts the authentication information from the security context. The
authentication information uses it to construct the security authentication token
(SimpleToken) for the REST calls that are made to external systems. As tw_admin is
an internal user, GenericRESTCall translates tw_admin to a default admin user for
external calls. For more information about business process security, see Business
Process Manager security on page 22. The GenericRESTCall also accepts a user
name on behalf of which a REST call must be made. It is especially useful for
REST calls in the System Lane of a Business Process. They run by default as an
admin user. It is desirable to run these REST calls on behalf of the person who
submitted the request. To do that, map the user and project variables from the
operation context to the GenericRESTCall
Table 44. GenericRestCall input variables
restMethod String The methods, such as POST,
PUT, GET, and DELETE
Table 44. GenericRestCall input variables (continued)
jsonString String The input for PUT or POST
encoded as a JSON string
restUrl String The REST URL that follows
the host name (after
http://<hostname>. For
example, /resources/clouds.
iwdUser String The user name on behalf of
which the REST call must be
made. If not specified, the
following users are
considered:
v In case if it is run in the
context of Business Process
Manager user interface,
the logged in user is used.
v In case it is for activities
that run in the System
Lane of a business process,
admin user is used.
domain String The domain name for the
REST call context. If not
specified, the default domain
is used
project String The project name for the
specified, the user default
project is used
iwdApiVersion String The version of the Workload
Deployer API. If not
specified, version 3.1 is used.
Table 45. GenericRestCall output variable
returnFromRest String Result of a REST call that is
encoded as a JSON string
GetCloudGroup
The service issues a REST Call on Workflow Deployer to retrieve a cloudGroup. It
uses the GenericRestCall integration service to run the REST Call, and the
CreateBusinessObject_CloudGroup service to convert the JSON encoded string that
is returned into a CloudGroup Business Object.
Table 46. GetCloudGroup input variable
cloudGroupId String ID of the cloudGroup to be
retrieved
Table 46. GetCloudGroup input variable (continued)
following users are
considered:
admin user is used.
is used
project is used
Table 47. GetCloudGroup output variables
cloudGroup CloudGroup CloudGroup business object
GetCredentialsOfVirtualMachine
The GetCredentialsOfVirtualMachine integration service is used to retrieve the
credentials of a virtual machine from the SmartCloud Orchestrator. The credentials
include user and password. In addition, it includes the private and public RSA
keys. The credentials can be used to access the operating system of the virtual
machine through ssh (Linux) or RXA (Microsoft Windows). For Linux based
operating systems, the private and public RSA keys supports key-based
authentication. The public key is stored on the virtual machine and is already
configured as the authorized key of the ssh service in the operating system. The
private key can be used to access the root account of the operating system in the
virtual machine without using the password. The input of the integration service
are the identifiers of the virtual system and the virtual machine. The output of the
integration service are strings representing the username, password, private, and
public RSA key.
Table 48. GetCredentialsOfVirtualMachine input variables
virtualSystemId String Id of the virtual system
virtualMachineId String Id of the virtual machine
Table 48. GetCredentialsOfVirtualMachine input variables (continued)
following users are
considered:
admin user is used.
is used
project is used
Table 49. 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 Workflow Deployer to retrieve the operation
context. It uses the GenericRestCall Integration Service to run the REST call, and
the CreateBusinessObject_OperationContext Service to convert the JSON encoded
string that is returned into a OperationContext Business Object.
Table 50. GetOperationContext input variables
operationContextId String Id of the operationContext to
be retrieved
Table 50. GetOperationContext input variables (continued)
following users are
considered:
admin user is used.
is used
project is used
Table 51. GetOperationContext output variable
operationContext OperationContext OperationContext Business
Object
GetServiceInstance
The GetServiceInstance integration service issues a REST Call on Workflow
Deployer to retrieve the service instance. It uses the GenericRestCall integration
service to run the Rest Call and the CreateBusinessObject_ServiceInstance
service to convert the JSON encoded string that is returned into a ServiceInstance
Object.
Table 52. GetServiceInstance input variables
serviceInstanceId String Id of the serviceInstance to
be retrieved
Table 53. GetServiceInstance output variable
returnFromRest String Result of REST call that is
encoded as JSON String
Post_ServiceInstance_MetaData_Parameter
The service issues a REST call on Workflow Deployer to store a parameter in the
parameter map of the serviceInstance > metadata section. It uses the
GenericRestCall Integration Service to run the REST call.
Table 54. Post_ServiceInstance_MetaData_Parameter input variables
serviceInstance ServiceInstance The serviceInstance for
which a parameter is to be
stored in the metadata
key String The parameter key
value String The parameter value
following users are
considered:
admin user is used.
is used
project is used
PostMessage
The PostMessage integration service issues a REST call on the Workflow Deployer.
It posts a message to the history section of the virtual system instance in the user
interface of the Workflow Deployer.
Note: The virtual system ID is not available for service operations, so this
operation must not be used for self-service offerings.
If globalization is needed, a localized message is passed as an input parameter. It
uses the GenericRestCall integration service to run the REST call.
Table 55. PostMessage input variable
message String serviceInstance for which a
parameter is to be stored in
the metaData
Table 55. PostMessage input variable (continued)
operationContext OperationContext Operation context business
object
mapUserDomaniFromOperationContent Boolean Determines whether the user,
domain, and project
paramenters of
operationContext are used
for the REST call (for
information about these
parameters, see
GenericRestCall on page
61l). If not specified, false is
used and the default values
for user, domain, and project
apply.
ReadBusinessObject
The service converts a business object into a JSON string so that it can be used. For
example, as parameter for a REST call. It is a generic method that gets ANY
business object as input parameter.
Restriction: The business object that is specified as input parameter might not
have a parameter of type Map.
Table 56. ReadBusinessObject input variable
BusinessObject ANY The business object to be
converted into JSON string
Table 57. ReadBusinessObject Output Variable
jsonString Hypervisor Hypervisor Business Object
that is converted into a JSON
string.
ReturnParameters
The ReturnParameters integration service is used to return parameters that are
collected by a human service. The collected parameters are used as input
parameters for the associated process. It must be the last activity of a human
service that collects parameters for a business process, which is used as a workflow
extension for SmartCloud Orchestrator.
Note: The outParameterObject business object must be of the same business object
type as the inputParameterObject of the associated process. The type is used by
SmartCloud Orchestrator to correlate a human service with its associated business
process.
Table 58. ReturnParameters input variable
operationContextId String Id of the operation context
outParameterObject ANY A business object that
contains the parameters that
are collected by the human
service. They are used as
input parameters for the
associated business process.
Table 59. ReturnParameters output variable
returnString String Result of REST call that is
encoded as JSON String.
SetOperationContextParameters
The SetOperationContextParameters integration service helps to enable the
workflow of SmartCloud Orchestrator extension to access and use parameters that
are collected by a human service. It stores the input parameter map as key/value
pairs into the parameter section of the operation context for the specified
operationContextId. This parameter is later given as input parameter to the
Business Process Manager Business Process extension. The parameter 'startTask'
specifies whether the Business Process Manager workflow must be triggered by the
execution 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 the
parameters that are collected into the operationContext of the task. This activity is
done before the Business Process Manager workflow process starts.
Note: This integration service is used internally to implement the
ReturnParameters integration service. Normally, it must not be used directly by the
human service that is associated with a workflow extension. Instead, the higher
level integration service ReturnParameters must be used.
Table 60. SetOperationContextParameters input variable
operationContextId String Id of the operation context
params Map Map of parameters to be
given as input parameter for
the associated business
process.
startTask Boolean True if the associated
business process must be
started (default false)
Table 61. SetOperationContextParameters output variable
returnString String Result of REST call that is
encoded as JSON String.
WriteValuesToBO
The service gets a JSON string representation of a business object as input variable
and generates the corresponding TWObject Business Object.
Restriction: Using 'ANY' for the type of the output variable business object leads
to an error in Business Process Manager. The business object type of the output
variable (for example, Hypervisor) must be specified explicitly. Therefore, if you
are using a Business Object other than 'Hypervisor', the integration service must be
copied from the toolkit to your Business Process Application. You must adapt the
type of business object to the special context.
Table 62. WriteValuesToBO input variable
BusinessObject ANY The business object to be
converted into JSON string
Table 63. WriteValuesToBO output variable
jsonString String The business object that is
converted into a JSON string.
GenericBPDInvocation
The GenericBPDInvocation service is used internally by SmartCloud Orchestrator
to do some housekeeping actions, such as mapping parameters that are encoded as
JSON strings to business objects. Finally, it calls the customer extension Business
Process.
Cloud management services
SmartCloud Orchestrator offers cloud management services, for example, backup
services or server restart.
Approval
The cloud management services require approvals. The approval is implemented
by the human service and coach of the Business Process Manager technology. It is
a building block of the SCOrchestrator_Toolkit.
Table 64. Approval Input Variable
requester String Approval requester
parameters NameValuePair (List) List of parameters for
approvals. The list of
parameters in the form of
name-value pairs that are
shown as extra information
in the approval UI panel.
Table 65. Approval Output Variable
reason String Reason for approval or reject
as specified in UI approval
panel.
Table 65. Approval Output Variable (continued)
isApproved Boolean Approved (true) or not
(false)
Instead of Business Process Manager Coach UI technology, the SmartCloud
Orchestrator UI implements the approval panels. These approval panels show only
the data from the Business Process Manager Approval human service. You can
use predefined approval building block to build your own approval Business
Process to display information that the approver needs to make a decision. The
sample Business Processes that are delivered as part of the toolkit, such as
Sample_DeployInstanceApproval and SampleDeleteInstanceApproval can be copied
and then customized to your needs. This customized approval Business Process
can then be enabled by registering it in the Orchestrator Actions .
http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp?topic=
%2Fcom.ibm.wbpm.main.doc%2Fic-homepage-bpm.html
v IBM Business Process Manager 8.0.1 documentation
http://www.neilkolban.com/IBM/
Kolbans 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-Zahn
IBM Impact 2011 - Five Guidelines to Better Process Modeling for Execution -
Stuart and Zahn
http://www.ibm.com/developerworks/websphere/library/techarticles/
1105_ragava/1105_ragava.html
Developer Works: WebSphere Lombardi exception handling and logging -
Gopalakrishnan Ragava and Sateesh Balakrishnan
Samples
A number of samples are delivered as part of the SCOrchestrator_Toolkit. You
must adapt the samples to your needs before they are run. You can find the actual
samples documentation by opening the Business Process Manager process center
(http:<central-server-4 IP>:9080/ProcessCenter/login.jsp) and selecting the
Note: Refer to the Business Process Manager documentation to know how to
configure group membership and swim lane participation to archive the required
rights for the user you want to grant for requests like approval or problem
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 Problem
Administrator.
Sample_DeleteInstanceApproval
This sample process includes an approval. It can be embedded in a SmartCloud
Orchestrator deletion workflow. The intention is to approve the deletion process.
Make sure to also adapt the participant to the group which should have the
approval right.
Sample_DeployInstanceApproval
This sample process includes an approval. It can be embedded in the SmartCloud
Orchestrator deploy instance workflow. The intention is to approve the deploy
instance process. Make sure to also adapt the participant to the group which
should have the approval right.
Sample_Post_ServiceInstance_Data
This sample process is to post ServiceInstance data, in this case parameters for
Service Instance MetaData. The sample process first retrieves the ServiceInstance
data as JSON String, creates a ServiceInstance Business Object and finally posts
a parameter to the Service Instance MetaData.
Note: To run the process, the default value for the ServiceInstance ID has to be
updated 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 Problem
Administrator.
Sample_Process_ShowVars
This is a sample process that 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
Problem Administrator.
Sample_Process_wo_HumanService
This sample extension is a process without human service. It displays the
operation 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 Process
that can be used either as orchestrator action (event triggered action or user action)
or as self service offering within SmartCloud Orchestrator. You can start
developing your own business process extension by copying this template and
enhancing it with your implementation logic.
Note: The variable type of the input parameter inputParameterObject has to be
changed from ANY to the concrete Business Object data type to be used. Do not
forget to expose the process (Expose to start) to make it visible in the
Configuration panel of SmartCloud Orchestrator.
Appendix B. Scripting utilities toolkit
The SCOrchestrator_Scripting_Utilities_Toolkit is delivered as a part of the
SmartCloud Orchestrator product. It provides the essential building blocks of the
Business Process Manager. These building blocks are required to build Business
Process Manager Business Processes and human tasks, which are used as
extensions for SmartCloud Orchestrator.
When you work with remote devices, such as remote virtual machines and storage
hosts, copy and run scripts/batch files on remote servers are frequently needed
tasks. The SmartCloud Orchestrator Scripting Utilities Toolkit provides
implementation services that you can drag and drop during SmartCloud Business
Process Manager process creation. These services can be used to copy files to a
remote system or execute command lines on remote systems, including uploaded
scripts/batch files.
File upload restrictions
You can only upload files that reside within a locale file repository such as a local
folder or locally mounted folder.
It is defined by the toolkits environment variable:"localRepositoryBasePath
By default this variable is defined as: "/var/ibm/sco/scriptRepo
For security reasons the processes of the toolkit checks whether the files to be
uploaded are always within the repository base folder.
Business objects
These business objects are delivered as part of the
Some of the business objects are partly reused within other business objects.
v VirtualServerKey
v RemoteMachineCredentials
v UploadFileData
v ExecuteCommandData
v OutputMapValues
v VirtualServerExecuteData
VirtualServerKey
ExecuteCommandData
v VirtualServerUploadAndExecuteData
VirtualServerKey
UploadFileData
ExecuteCommandData
v VirtualServerUploadData
UploadFileData
ExecuteCommandData
v VirtualSystem Used internally only to hold the JSON data of this object
v 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 66. VirtualServerKey
Parameters Data type Description Sample data
virtualSystemId String ID - Field of the
virtual system, that
contains the virtual
server that must be
referenced.
"1... n
virtualServerId String ID - Field of the
virtual server
(machine) that must
be referenced.
"1 ... n
RemoteMachineCredentials
Remote machine access data.
Table 67. RemoteMachineCredentials
remoteMachine String Remote machine
IP-address or host
name.
"9.152.138.179
remoteUser String Username to access
the remote machine
via the protocol of
the used process
"admin"
remotePassword String Password for the
user and protocol
"myPassword
privateKey String Currently not used
by the sample.
(Fetched by loading
via virtualServerKey)
publicKey String Currently not used
by the sample.
(Fetched by loading
via virtualServerKey)
UploadFileData
Data to define a file upload task from locale file repository. See File upload
restrictions on page 73.
Table 68. UploadFileData
repositorySubFolder String Subfolder within the
local repository - or
empty string.
"SubFolder
Table 68. UploadFileData (continued)
fileName String Source and
destination file name
of the file to be
uploaded.
"HelloWorld.sh
destinationDirectory String Destination directory
for the uploaded file.
If the folder does not
exist, it is created.
"/tmp/folder
makeExecutable Boolean Make the uploaded
file on the destination
machine executable
for current user. In
Windows operating
systems this flag is
ignored. It is only
available for
compatibility reasons.
True/False
ExecuteCommandData
Data to define a command line execution task.
Table 69. ExecuteCommandData
commandLine String Command to be
executed on the
remote machine. This
might also be a shel
or batch script.
"ls -l
workingDirectory String The processes change
the current directory
to the given working
directory, before the
command is
executed.
"/tmp/test
OutputMapValues
Data object that holds well-defined return parameters of a called process.
Table 70. OutputMapValues
errCode String Empty string if no
error occurred by
processing the
implementation
service. Otherwise an
error code is
returned.
"CTJCA1699E
Table 70. OutputMapValues (continued)
errMsg String If errCode is empty,
this field can be
ignored, because it is
always empty. If
errCode is not empty,
this field contains
details about the
error.
"Details about the
problem
retCode String Contains the return
code of the called
command.
"0
stdOut String Contains the
standard output of
the called command.
">script called
stdErr String Contains the
standard error output
of the called
command.
"file is not
executable
VirtualServerExecuteData
Data object that contains all required information to execute a command against a
virtual system instance.
Table 71. VirtualServerExecuteData
virtualServerKey VirtualServerKey Identifies the
destination machine.
See referenced data
object for details.
executeCmdLineData ExecuteCommandData Defines data for the
command to be
executed.
See referenced data
object for details.
VirtualServerUploadAndExecuteData
Data object that contains all required information to upload a file to a virtual
system instance.
Table 72. VirtualServerUploadAndExecuteData
See referenced data
object for details.
uploadFileData UploadFileData Defines the data for
the upload task.
See referenced data
object for details.
executeCmdLineData ExecuteCommandData Defines data for the
command to be
executed.
See referenced data
object for details.
VirtualServerUploadData
Data object that contains all required information to upload a file and execute a
command against a virtual system instance.
Table 73. VirtualServerUploadData
See referenced data
object for details.
uploadFileData UploadFileData Defines the data for
the upload task.
See referenced data
object for details.
Implementation services
The toolkit contains a number of implementation services.
Implementation services are described in separate topics. The following
implementation services are used only internally and are not described in detail:
v Decrypt_Text
v Encrypt_Text
v GetVirtualMachines
v GetVirtualSystemInstances
v GetIPsOfVirtualMachine
For more information about the services, see the documentation inside the toolkit
or 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 via
SSH protocol.
Table 74. SSH_UploadFile
Input parameters Data type Expected value Sample data
remoteMachine String Remote machine IP
address or host name
"9.120.xxx.xxx
userName String Login user name for
the above protocol
"root
password String Login password.
Optional. See
Table 75 on page 78.
"**********
PrivateKey String RSA-Key. Optional.
See Table 75 on page
78.
"RSA-Key"
fileName String Name of the file to
be uploaded from the
local file repository
"HelloWorld.sh
destinationPath String Full destination path
in the format of the
remote machine
"/tmp/destination
Table 74. SSH_UploadFile (continued)
localRepositorySubDir String Subdirectory or
NULL/Empty string.
See File upload
restrictions on page
73.
"/SubFolder/
makeFileExecutable Boolean Make file executable
for
"Implementation-
Service user
(ignored on Windows
operating systems)
"True
Table 75. Optional parameters
Optional parameters
Password="value" / PrivateKey=ignored For the connection to the remote machine, the
credentials "user" and "password" are used.
Password=empty / PrivateKey=empty If the private key of the BPM machine is inserted
into the trusted list of keys within the remote machine, it is also possible to connect on this
trusted relationship. In this case the password field must be left empty to identify this
connection mode.
Password=empty / PrivateKey="value" If an other trusted private key should be used to
enable the connection, than it can be passed as parameter. For this mode the password
must be left empty.
Table 76. 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 specific
implementation
service
See individual
samples
Table 77. Possible keys and their values
Key string or key value Expected value Value string or sample data
For Key "errCode Error code, if error occurred "CTJCA1699E
For Key "errMsg Error details, if error code is
set
"Source file not available
* For Key "RC Return code of the called
command line
"0
* For Key "stdOut Standard output of a called
command line
">Hello world
* For Key "stdErr Standard error output of a
called 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 remote
machine via SSH protocol.
Table 78. SSH_ExecuteCommand
"9.120.xxx.xxx
the above protocol
"root
Optional. See
"**********
78.
"RSA-Key"
commandLine String Command line or
script file, that must
be executed on the
remote machine
"ls -l
cmdLineWorkingDirectory String Full path in the
format of the remote
machine
"/tmp/destination
For the output parameters, see Table 76 on page 78
SSH_UploadFileAndExecuteCommand
This integration or implementation service:
v Uploads a file to a remote machine
v Executes a command line on a remote machine
v Via SSH protocol
Table 79. SSH_UploadFileAndExecuteCommand
"9.120.xxx.xxx
the above protocol
"root
Optional. See
"**********
78.
"RSA-Key"
"HelloWorld.sh
remote machine.
"/tmp/destination
Table 79. SSH_UploadFileAndExecuteCommand (continued)
NULL/Empty string.
See File upload
73.
"/SubFolder/
for
"Implementation-
Service user.
Ignored on Windows
operating systems
"True
script file that must
be executed on the
remote machine.
"ls -l
machine.
"/tmp/destination
Windows_UploadFile
v via RXA toolkit/protocol
Table 80. Windows_UploadFile
"9.120.xxx.xxx
the above protocol
"Administrator
password String Login password "**********
local repository.
"HelloWorld.bat"
remote machine
"c:\tmp\
destination\"
null/empty string.
See File upload
73.
"\SubFolder\"
Windows_ExecuteCommand
This integration or implementation service executes a command line on a remote
machine via RXA toolkit/protocol.
Table 81. Windows_ExecuteCommand
"9.120.xxx.xxx
the above protocol
"Administrator
be executed on the
remote machine.
"dir
machine
"c:\tmp\
destination\
Windows_UploadFileAndExecuteCommand
v Executes a command line on a remote machine
v Via RXA toolkit/protocol
Table 82. Windows_UploadFileAndExecuteCommand
"9.120.xxx.xxx
the above protocol
"Administrator
"HelloWorld.bat
remote machine
"c:\tmp\
destination\
NULL/Empty string.
See File upload
73.
"\SubFolder\
for
"Implementation-
Service user.
Ignored on Windows
operating systems
"True
Table 82. Windows_UploadFileAndExecuteCommand (continued)
be executed on the
remote machine
"dir
machine
"c:\tmp\destination
ExtractOutputMap
This integration or implementation service extracts the OutputMap values
(Key-Value-Pairs) to concrete fields of a OutputMapValues object.
Table 83. ExtractOutputMap
OutputMap Map of strings See Table 76 on page
78
retValues OutputMapValues ErrCode
errMsg
retCode
stdOut
stdErr
See the individual
samples in Table 76
on page 78
GetRemoteMachineDataFromVirtualMachineKey
v Evaluates the remote machine data, for example IP, user, password, and so on
v Via its virtualSystem Key - virtualSystemID and virtualServerID
Table 84. GetRemoteMachineDataFromVirtualMachineKey
virtualServerKey VirtualServerKey virtualSystemID
virtualServerID
virtualSystemID=12
virtualServerID=13
The rest of the input
parameters are for
internal purpose only
Table 85. GetRemoteMachineDataFromVirtualMachineKey output parameters
Output parameters Data type Expected value
RemoteMachineData RemoteMachineCredentials remoteMachine
remoteUser
remotePassword
privateKey
publicKey
Sample processes
The 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 (parameter
map) in Business objects on page 73.
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 UIs
The SCOrchestrator_Scripting_Utilities_Toolkit contains sample UIs, which
reflect the needs of the corresponding sample processes.
The sample processes and matching sample UIs are determined by their
corresponding dataobject.
The type of output parameter of the sample UI must match the type of input
parameter of the sample process.
The sample UIs are:
UI_Sample_SingleVirtualMachine_UploadFile
For output data, see the business object VirtualServerUploadData.
UI_Sample_SingleVirtualMachine_ExecuteCmd
For output data, see the business object VirtualServerExecuteData.
UI_Sample_SingleVirtualMachine_UploadFileAndExecuteCmd
For output data, see the business object VirtualServerUploadAndExecuteData.
The UI parts, used within the above sample UIs are:
v UI_Sample_GET_SingleVirtualMachine
v UI_Sample_GET_ExecuteCommandData
v UI_Sample_GET_UploadFileData
Deprecated implementation services
These integration or implementation services are deprecated and are not
documented.
v LinuxCopyFiletoRemoteMachine
v LinuxCopyFiletoRemoteMachineusingKey
v LinuxExecuteRemoteScript
v LinuxExecuteRemoteScriptusingKey
v LinuxExecuteRemoteScriptwithArgs
v LinuxUploadandExecuteRemoteScript
v LinuxUploadandExecuteRemoteScriptusingKey
For information about these deprecated services, see the SmartCloud Orchestrator
version 2.2 information center.
Appendix C. Support IaaS toolkit
The SCOrchestrator_Support_IaaS_Toolkit provides capabilities that enable the
user to perform operation on the IaaS layer in SmartCloud Orchestrator. The
toolkit 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. The
requests can be performed on behalf-of a users in a domain and project. It is the
most flexible and documented way to perform REST calls to OpenStack services
via IaaS gateway.
v An integration service "Get IaaS Regions" that retrieves the list of available
regions in a multi-region cloud environment. There exists a helper method in the
iaas_util.js file that implements the authentication routine based on the
configured shared secret keys in the WebSphere run time.
The toolkit provides building blocks that can be used in custom toolkits and
process applications. These building blocks are required to build Business Process
Manager Business Processes and human tasks, and are also used as extensions.
SmartCloud Orchestrator uses these extensions for actions against the IaaS layer.
For information about IaaS layer, see APIs provided by OpenStack and IaaS
gateway. The toolkit provides an essential Java REST client API and samples that
show how to use the API in Business Processes. To write an extension for
SmartCloud Orchestrator, do the following 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 SmartCloud IaaS gateway
API. The libraries contain Java implementation of resources and methods. These
resource implementations and methods can be used in human services and
business processes for actions against the OpenStack and IaaS gateway.
v Samples - the toolkit provide samples that illustrate the usage of the client-side
API. For example, the toolkit provides a sample to create and delete a tenant to
the OpenStack identity service Keystone. Another example is about the
modification of the metadata of a server. The samples are implemented based on
default 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 that
illustrate the flow of data between Business Process Manager and the
OpenStack or IaaS gateway. You can easily use them for parameter and
private data declarations with the standard Business Process Manager. For
example, business objects can represent tenants and servers.
Human services (in the User Interface section of the toolkit) - some sample
human services and coaches are implemented to illustrate the usage of the
API. For example, human services can specify the parameters of a tenant that
are required to create the tenant. Another example is to select a server that
exists in OpenStack. It shows its details and modifies its metadata.
Business Process Manager processes - some sample processes that illustrate
the usage of long-running tasks. These processes include, for example, the
creation and deletion of a tenant and the modification of the metadata of a
server.
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 service
through the IaaS gateway.
Generic IaaS REST call
The IaaS Generic REST call makes REST calls to OpenStack services through the
IaaS gateway. You can use the interface to specify the target region and service to
start, for example, the "compute" service Nova in the "US-West" region. The
interface is not typed and therefore expects and returns a string in a JSON format.
This generic interface allows any RESTful calls against the OpenStack APIs by
specifying the URL and JSON response.
The authentication of the client is done by using the shared secret key, which is
configured at run time of the Business Process Manager. The shared secret is used
to generate a token for the admin user, which is used for authentication.
The integration service provides the following input variables:
restMethod
The method of the REST call, supported types are GET, POST, PUT, PATCH, and
DELETE. It is a required property.
iaasServiceType
The 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.
iaasEndpointType
The endpoint of the service to use. It is a required property. The supported
values are
v For v2: adminURL, publicURL (default), and internalURL.
v For v3: admin, public (default), and internal.
iaasRegion
The region from which the service is instantiated, for example, RegionOne. It is
an optional property. The first region that is found is taken by default.
restUrl
Defines the REST resource that must be started. For example, /tenants or
/user/{user-id}. It is a required property.
restJsonContent
The content that must be posted or put to the REST URL. The string must have
a valid JSON format as defined in the IaaS API. It is a required property.
iaasUser
The user of this request. It is an optional property. The default is admin.
iaasProject
The project that performs the request. The user is authenticated and the scope
of the user for this project is determined. This property is optional. The default
is admin.
iaasDomain
The domain of the user is authenticated. The user can only be uniquely
determined by specifying the domain. This property is optional. The default is
Default.
The output variable of the integration service is
restJsonResponse
The response of the REST call as a string in JSON format.
OpenStack and SmartCloud API library in Business Process Manager
The OpenStack and SmartCloud library contain Java classes that can be used to
interact with the OpenStack and SmartCloud IaaS gateway. The Java classes and
methods can be used in any Java or JavaScript implementation in any of the
Business Process Manager artifacts. The basic concepts of how to use the library
within Business Process 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, it requires a
fully qualified package name because the engine must look up the classes.
For example, to create an instance of the OpenStackConnectionFactory for a given
host (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 each
variable, the developer can use the JavaScript by omitting the type definition. In
this example, the object of type
com.ibm.openstack.api.OpenStackConnectionFactory is stored in the local variable
connectionFactory. Next, the variable can be used as described in the API
reference of the OpenStack and SmartCloud library. For example, to set up a
connection for 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 Java
script in human services or processes to do actions against the IaaS layer. The next
sections focus on authentication and actions against OpenStack and IaaS gateway.
Appendix C. Support IaaS toolkit 87
Get IaaS Regions
The Get IaaS Regions integration service uses the generic IaaS client to retrieve the
list of available regions. These regions can be used to find IaaS services, for
example, the "compute" service in the "US-West" region.
The integration service does not require any input parameters. The output
parameter is
-regions
a list of region names that are available.
Related concepts:
Generic IaaS REST call on page 86
Samples for the IaaS support toolkit
The sample IaaS support toolkit provides basic samples for the IaaS support
toolkit. The samples are available via the Sample IaaS Support Process App
process application which is installed together with the IaaS Support Toolkit by
default. The following samples are available:
Sample Create Domain
This sample shows how to create a new domain entity in the v3 API of the
identity service in Keystone. It assumes that Keystone v3 is enabled in the
service catalog. The samples also demonstrates how to create a new
'Default' project for the domain and adding the admin user as a member to
the project.
Sample Delete Domain
This sample shows how to delete a domain entity in the v3 API of the
identity service in Keystone. The human service shows how to select a
domain out of the list of domains. The process disables the domain and
deletes it afterwards.
Sample Create Project
This sample shows how to create a project entity in the v3 API of the
identity service in Keystone. The human service shows how to specify the
project details and checks whether the project already exists. The process
creates a project in Keystone.
Sample Delete Project
This sample show how to delete a project entity in the v3 API of the
identity service in Keystone. The human service shows how to select a
project out of the list of project . The process deletes the projects in
Keystone.
Sample Project On-Boarding
This samples shows how to configure a new or existing project in
SmartCloud Orchestrator. The purpose of the sample is to show the API
calls to configure the project to be operational. Therefore, the human
services is a wizard that steps the users through a list of steps to:
v Create or select the project entity in Keystone
v Configure the quota of the project
v Add users and roles to project
v Grant access to environment profiles, patterns, and images to the project
v Grant access to self-service offerings and operation actions to the project
Sample Create User
This sample shows how to create a user entity within a domain in the v3
API of the identity service in Keystone. The human service shows how to
specify the user details, how to select the domain, and how to select the
default domain and role. The human service checks if the user already
exists. The process creates the user in the selected domain and assigns the
selected project to the user with the role specified.
Sample Delete User
This sample show how to delete a user entity in the v3 API of the identity
service in Keystone. The human service shows how to select a user from
the list of users. The process deletes the user in Keystone.
Sample to create a tenant in OpenStack identity service
The sample shows how to create a tenant. A business object is created and it
contains the required parameters, such as name and description. It is assumed that
the 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 service
var 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 tenant
var factory = Packages.com.ibm.openstack.api.model.
identity.IdentityFactory.eINSTANCE;
var tenant = factory.createTenant();
// intialize the tenant resource object with the
attributes 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 tenant
tenant = identityAdminService.createTenant(tenant);
// store the Id of the new tenant as a reference
in the inputParameterObject
tw.local.inputParameterObject.id = tenant.getId();
// adapt authentication method -
authentication based on the webshpere configuration settings
using the helper method in iaas_utils.js
var connection = authenticateIaaS();
Sample to get a list of servers from OpenStack computer service
See how to get a list of servers from OpenStack computer 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 as
follows:
1. Authenticate to the identity service.
2. Look up the computer service.
3. Get a list of all servers.
When the connection is established, the system must look up a computer 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 services
var computeServices = serviceFactory.lookupServices
(Packages.com.ibm.openstack.api.service.IComputeService);
// pick the first compute service
var computeService = computeServices.get(0);
In the next step, you get the list of servers and fill a local list. The list contains
Business Process Manager Business Objects (BOs) that are created in the process
application or toolkit to hold values. This list can then be used in UI elements, for
example, as "selection box" (see the 'Sample Play with VM' human service). The
business object of type server can be found in the IaaS Support Toolkit. It has the
attributes id and name of type string. The following code fills the list of servers
with the list of servers that are retrieved from the computer service.
// the list of servers from compute service
var servers = computeService.getServers();
// a local variable of type Server in the process or human service
tw.local.servers = new tw.object.listOf.Server();
// iterate through the list of servers retrieved from compute service
for (var i=0; i<servers.size(); i++) {
var s = new tw.object.Server(); // instantiate a new BO
s.id =servers.get(i).getId(); // copy the id
s.name=servers.get(i).getName(); // copy the name
tw.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 activity
'Get Server Details' in the 'Sample Play with VM' human service.
Troubleshooting
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 a
typesafe implementation of the openstack API, which is less error-prone and more
comfortable than using REST calls and parsing JSON responses. However, this
pattern 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 integration
services or General System Services. They are Java implementations of routines
that are provided by Business Process Manager.
Appendix D. Support vSys toolkit
The SCOrchestrator_Support_vSys_Toolkit provides capabilities to deploy virtual
system pattern through SmartCloud Orchestrator. The toolkit provides building
blocks you can use in other toolkits or process applications to build custom service
and processes.
The toolkit builds function on top of the SmartCloud Orchestrator API and uses
the GenericREST integration service and the direct IaaS REST integration services of
the SmartCloud Orchestrator toolkit to perform restful API calls.
The Customize Pattern integration services provides capability to convert a
Business Process Manager business object of type Pattern into a JSON document
which is in the SmartCloud Orchestrator format.
The service sample, Deploy Virtual System Instance, is a wizard used to deploy
an existing pattern with an integrated configuration panel. Other human services
are available to show virtual server based selection and initiate actions against the
hosting virtual system. Other integration services are built around the API and can
be extended using the GernicREST integration service.
Finally, the sample processes of the Processes section cover the previous Sample
Support vSys Process App samples that show how to build custom services to
deploy and orchestrate virtual system patterns.
Business objects
The business object that is defined for SCOrchestrator_Support_vSys_Toolkit are
defined here. The variables of this business object are described in the toolkit.
ChangeInstanceEndTimeBO
The ChangeInstanceEndTimeBO business object represents the customization data
object regarding change of the time where the instance lifetime is ending. During
creation of the virtual system instance, there are several tasks created which are
scheduled to a certain time. This time must be changed in cases when the instance
end time get changed. The contained parameters must be filled regarding the date
and times. This instance contains the actual scheduled tasks and times. A different
instance 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 end
time. If the instance end time is indefinite, the Date field is set to false which
means the end time of the instance cannot be changed. There are no related tasks
with 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 deploying
according to its related pattern.
EnvironmentLimits
This is a business object that describes the environment limits (quota) as part of an
environment profile.
EnvironmentLimitsBO
This is a business object that describes the environment limits (quota) and actual
allocated and reserved resources as part of an environment profile.
EnvironmentProfileBO
The environment profile business object describe all references to unique identify
an environment profile as well as the associated environment limits. The
EnvironmentLimitBO is included in this business object.
Flavor
The flavor data objects describes values from CPU, memory, and storage. The
values correspond directly from the flavors used for deployment or is target for a
resource allocation change (modify resource scenario).
ModifyResourceBO
The ModifyResource business object describe all data required to process a
modification request to change actual resource allocations in respect of CPU,
memory, and storage. The resource allocations current and desired are described in
contained Flavor objects.
Part
The Part object represents the customization of parts within a pattern. The part
customization is required for the following cases:
v The flavor in case of deploying against a cloud group
v The cloud group and IP group flavor in case of deploying against an
environment profile
However, if no part customization is provided, the flavorId, cloudId, and
ipGroupId 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 array
which means an array of NICs for each member of the part, specified by the
memberCount of the part, containing:
v IP address of the NIC, if specified by the pattern deployer
v Host name of the NIC, if specified by the pattern deployer, can be omitted
v 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, and
scripting parameters, both in 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 value
property stores the actual value. The Customize Pattern integration service
overrides the value of each part parameter that is specified in the customization.
Pattern
This business object represents the customization of a virtual system pattern in
SmartCloud Orchestrator. The business object is converted by the 'Customize and
Deploy Virtual System Pattern' integration service into a string that is used to
deploy the virtual system pattern.
Note: Some of the properties are optional, others are required. The details can be
found 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 objects 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 clouds groups and IP groups for each part.
To simply the deployment into environment profiles and to avoid the
customizations of cloud groups and IP groups for each part, the cloud group and
IP 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 contained
in the Pattern business object. The information is organized as an array of parts of
the business object type 'PartBO' where each arrary element represents a part of
the pattern.
Appendix D. Support vSys toolkit 95
ScriptProperty
This business object represents the customization of parameters of scripts within a
part. Those parameters are typically defined in the OVF. The part, script, and key
properties are used to identify the parameter and the value stored. The Customize
Pattern integration overrides the value of each part parameter that is specified in
the customization.
For example, to identify the parameter with key param1 of the first script within
the first part the user need to set part=1, script=1 and key=param1.
UserInfoBO
This business object describes relevant properties of the current user. It is used in
integration services 'Get User Info' and 'Get Owner Of vSys Instance'.
VirtualServer
This data type described the fields to be used to fill displayed table to enable
selection of a single server for manipulation. For example, it is used in integration
service 'Get Virtual Machine.'
VirtualSystem
This business object is a helper object that stores the basic information about the
virtual system. It is used in most of the sample integration service delivered by
this toolkit within the integration service 'Get Virtual Machines'.
VirtualSystemPatternBO
This business object hold the complete set of customization properties of a virtual
system. It is used in the sample integration services 'Deploy Single Pattern' and to
list available patterns for selection in 'Get Available Patterns'.
Integration services
The integration services that are used in SCOrchestrator_Support_vSys_Toolkit
toolkit.
Note:
During processing the human service where all configuration data is collected, a
virtual instance name is generated using the selected pattern name and a generated
UUID. The UUID ensures that the virtual instance name is unique. If it is not
unique, you receive the error: The name or identifier you entered is already in
use.
Because a UUID is a long string, the resulting virtual machine name created with
the IP address prefix might exceed the maximum virtual machine name length
possible 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
to the internal instance name, in the environment profile. This results in a
shorter and more customizable virtual machine name.
There are two possible solutions for this problem: 1) The name might be edited
while executing the deploy service, where you take the risk of virtual instance
name duplication 2) The environment profile allows to configure naming rules for
the virtual machine name which is different to the internal instance name. This
results in a much shorter and more customizable virtual machine name. Refer to
SCO 2.3 infocenter documentation, chapter "Creating an environment profile",
paragraph "Virtual machine name format".
Get ACL of Virtual System Instance
The Get ACL of Virtual System Instance integration service retrieves the access
control list of a virtual system instance that includes its virtual machines. The
input is the ID of the virtual system instance. The out put is a JSON document that
describes 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 user
to the access control list of a virtual system instance and sets the permission. The
input is the ID of the virtual system instance, that is, the ID of the user and the
permission flag. The output is a JSON document that describes the result of the
API 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 service
removes the user and its permission from the access control list of a virtual system
instance. The input is the ID of the virtual system instance, that is, 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 updates
the permission of a user in the access control list of a virtual system instance. The
input is the ID of the virtual system instance, that is, the ID of the user and the
permission flag. The output is a JSON document that describes the result of the
API 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 the
cloud groups in an environment profile. The list of cloud groups can be used to
customize targeting cloud groups of parts within a pattern. The input is the ID of
the environment profile. The output is a JSON document that describes the list of
cloud groups in the environment profile. This integration service can be used for
the second step within a logical sequence of steps when you deploy a pattern in an
environment 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 of
environment profiles that can be used as target for provisioning of a specified
pattern. The input is the ID of the virtual system pattern. The output is a JSON
document that describes the list of environment profiles. This integration service
can be used for the first step within a logical sequence of steps when you deploy 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
3. Get the list of IP groups within the selected environment profile and cloud
Get Flavors Of Cloud Group In Environment Profile
The Get Flavors Of Cloud Group In Environment Profile integration service
retrieves the possible flavors that are valid for cloud groups within environment
profiles. The list of flavors can be used to customize the parts of a pattern. The
input is the ID of the environment profile and the ID of a cloud group within the
environment profile. The output is a list of flavors that are valid for the selected
cloud group within the selected environment profile. This integration service can
be used for the last step within a 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
v Get the list of cloud groups within the selected environment profile and select
v Get the list of IP groups within the selected environment profile and cloud
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 service
retrieves the IP groups that are enabled for cloud groups within the environment
profiles. The list of IP groups can be used to customize the network interfaces of
parts of a pattern. The input is the ID of the environment profile and the ID of a
cloud group within the environment profile. The output is a list of IP groups that
are enabled and configured for the selected cloud group within the selected
environment profile. This integration service can be used for the third step within
a 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
v Get the list of cloud groups within the selected environment profile and select
v Get the list of IP groups within the selected environment profile and cloud
Check Quota Breach
This is an integration service to retrieve the environment limits (quota) of the
corresponding virtual system instance. It uses a REST call against IBM Workload
Deployer to retrieve the desired information.
Related API: GET /resources/environmentProfiles/{id}
Get Script Parameters
This integration service retrieves script parameter.
As input the integration service expects the:
v part ID
v part index
v PatternBO
As output the integration service returns 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 system
v ID of virtual machine
v script ID
v script payload
As output the integration service returns 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 sent
saying that the virtual system instance is to be de-provisioned.
This integration service can be used to retrieve the time that the email notification
is sent before a virtual system instance is terminated by issuing a corresponding
REST call against IBM Workload Deployer. It gets the operationContextId and the
virtualSystem information as input parameter and returns the time that the email
notification for the termination of the virtual system instance are to be sent in the
form 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 system
instance by issuing a corresponding REST call against IBM Workload Deployer.
It get the operationContextId and the virtualSystem information as input
parameter and returns the end time of the virtual system instance in the form of a
ChangeInstanceEndTimeBO business object.
Related API: GET /resources/tasks/
Check Status Of Virtual System
This integration service retrieves the status of the virtual system instance. As input
the integration service expects the id of the virtual system. As output the
integration service returns the internal status number and the deploy message of
the 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 in kersrv-2.
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=Draft
RM01028=Read-only
RM01029=Capturing
RM01030=Captured
RM01031=Pausing
RM01032=Resuming
RM01033=Resetting
RM01034=Reset
RM01035=Queueing
RM01036=Queued
RM01037=Deploying
RM01038=Deployed
RM01039=Servicing
RM01040=Serviced
RM01041=Service transferred
RM01042=Transferring service
RM01043=Service applied
RM01044=Applying service
RM01045=Transferring to apply service
RM01046=Service rolled back
RM01047=Rolling back service
RM01048=Committing service
RM01049=Committing service
RM01050=Committed
RM01051=Dormant
RM01052=Executing scripts
RM01053=Transfering and applying service
RM01054=Snapshot restored
RM01055=Snapshot deleted
RM01056=Service failed
RM01057=License not accepted
RM01058=Stored
RM01059=Warning
RM01060=Capture started
RM01061=Logged in and active
RM01062=Inactive
RM01063=months
RM01064=weeks
RM01065=days
RM01066=hours
RM01067=percent
RM01068=Week ${0}, ${1}
RM01069=Deleted
RM01070=Partially started
RM01071=Detached
RM01079=Re Queued
RM01080=Hidden
RM01081=Sunset
RM01082=Locked
RM01083=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 into
a JSON document that represents the virtual system to be deployed. The input is a
business object of type Pattern that contains all customization of the pattern. The
documentation of the Pattern data object describes it in detail.
Call the Validate Pattern integration service on the pattern object. The output can
be passed to the Deploy Pattern integration service to deploy a virtual system
pattern.
Deploy vSys Pattern
This integration service deploys a virtual system instance. The input is a JSON
document describing the virtual system instance. This JSON document can either
been generated by custom code or via the 'Customize Pattern' integration service.
The output contains the details of the deployed virtual system instance.
Related API: POST /resources/virtualSystems
Get Available Pattern
This is an integration service to retrieve all available pattern As input the
integration service expects the user. As output the integration service
returns pattern as list of VirtualSystemPatternBO.
Related API: GET /resources/patterns
Get Pattern Details
The Get Pattern Detailsintegration service retrieves the details of a pattern,
which includes its parts and metadata. The input is the ID of the pattern. The
output is a JSON document that describes the patterns and its parts.
Get Pattern Details by Name
The Get Pattern Details by Name integration service searches a pattern by name
and retrieves its details, which include part information and metadata. The input is
the name of the pattern. The output is a JSON document that describes the pattern
and 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 pattern
specification that is defined in a business object of type Pattern if correct. The
input is the business object that defines the pattern customization. The output is a
flag that indicates whether the customization is valid or not, and a list of error
messages that indicates wrong customization.
Get Cloud Groups For Pattern
The Get Cloud Groups For Pattern integration service returns the list of cloud
groups that can be used to deploy a specific pattern. The input is the ID of the
virtual system pattern. The output is a list of cloud groups in JSON format as
described in the API.
Related API: GET /resources/clouds
Customize and Deploy Virtual System Pattern
The Customize and Deploy Virtual System Pattern integration service combines
the Customize Pattern and Deploy Pattern integration services. Both the services
get called one after the other.
Get Cloud Groups in EnvironmentProfile
This integration service retrieves the cloud groups in an environment profile. The
list of cloud groups can be used to customize targeting cloud groups of
parts within a pattern. The input is the id of the environment profile. The output
is 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 sequence
of steps when deploying a pattern in an environment profile:
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 the
corresponding virtual system instance. It uses the integration service Get
Environment Profiles to retrieve the desired information. As input the integration
service expects the:
v type
v pattern ID
v user information
As output the integration service returns list of EnvironmentProfilesBO.
Update Environment Limits
This is an integration service to update the environment limits (quota) of an IBM
Workload Deployer environment profile using a REST call against IBM Workload
Deployer.
Get Environment Profiles
This is an itegration 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 and
returns a list of Flavor data objects.
Get Upgrade Flavors For Virtual Machine
This integration service retrieves flavors from openStack (IaaS REST calls) which
can be used to upgrade the virtual machine The input is the:
v operation contex
v tenant ID
v current flavor
The output is a list of Flavor business objects.
Get User Information
This integration service retrieves information regarding the actual user. As input
the integration service expects the user. As output the integration service
returns response UserInfoBO.
Related API: GET /resources/users?username={user}
Get Requester Details
This integration service retrieves requester email information. The input is the
user 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 system
instance. The input is the ID of the virtual system instance. The output is a JSON
document that describes the list the virtual machines of the virtual system
instances.
Related API: GET /resources/virtualSystems/{id}/virtualMachines
Get Virtual System
This integration service retrieves parameter of a virtual system instance. The
outout is a 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 including
its virtual machines. The input is the id of the virtual system instance. The outout
is 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 outout is
a 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 outout is
a 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 flavor
with details and tenant ID.
Get Flavors Of Cloud Group In Environment Profile
This integration service retrieves the possible flavors that are valid for cloud
groups within environment profiles. The list of flavors can be used to customize
the parts of a pattern.
The input is the ID of the environment profile and the ID of a cloud group within
the environment profile. The output is a list of flavors that are valid for the
selected cloud group within the selected environment profile. This integration
service can be used for the last step within a logical sequence of steps when
deploying a pattern in an environment profile:
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 groups
within environment profiles. The list of IP groups can be used to customize the
network interfaces of parts of a pattern.
The input is the ID of the environment profile and the ID of a cloud group within
the environment profile. The output is a list of IP groups that are enabled and
configured for the selected cloud group within the selected environment profile.
This integration service can be used for the third step within a logical sequence of
steps when deploying a pattern in an environment profile:
Resize Virtual Machine
This integration service resize virtual machine resource by changing the flavor. The
input is the:
v virtual system ID
v virtual machine ID
v virtual machine name
v current flavor
The output is false/true.
Related API reference: PUT /resources/virtualSystems/{id}/virtualMachines/{id},
payload
Start ySys 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 ySys 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 the
API 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 been
selected and that the end time can be changed, for example, is not indefinite.
User interface
The user interface section of the SCOrchestrator_Support_vSys_Toolkit contains
sample implementations for asynchronous services (AJAX), coach views, and
human services.
AJAX services
The user interface section of the SCOrchestrator_Support_vSys_Toolkit contains
sample implementations for asynchronous services (AJAX), coach views, and
human services.
The names of the AJAX services are similar to its functionality. These are the basic
services to collect data for further human service processing.
The following items are internal AJAX services:
ListEnvironmentProfiles
Used to list the existing environment profiles
ListFlavorsForEnvProfile
Used to list flavors for a given environment profile
ListIPGroupsForEnvProfile
Used to list IP groups for a given environment profile
ListVirtualSystemPatterns
Used to list virtual system pattern
ListVirtualSystems
Used to list virtual systems
ListVirtualSystemsForPattern
Used to list virtual systems for a given pattern
Coach views
Coach views is a collection of coaches which show how to handle types of widgets
with their event handlers.
The following coaches are available:
Button Event
This coach is copied from the Kolban toolkit
CheckBoxDateVisibility
This is an internal coach to handle dates
Conditional Password
This is an internal coach to handle password
Dialog Box
This coach is copied from the Kolban toolkit
Human services
The 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. It works 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 time changes based on selection of a virtual server.
After selecting a virtual system pattern, the list of virtual system instances for the
selected pattern is displayed. Having selected a virtual system instance, the current
end date of the virtual system instance is displayed. You can now change the end
time of the virtual system instance by selecting the new date and time.
Note: This human service can be used in a self-service offering. The prerequisite
for being able to change the end time is that the current end time of the virtual
system is NOT indefinite.
Change Instance End Time (Instance Op): This is a human service to collect data
for virtual service instance end time changes based on virtual server instances. See
"Change Instance End Time" human service.
Delete Single Server Virtual System: This is a human service to collect data to
select a single server for a virtual system based on contained virtual server for
deletion. It works together with the corresponding 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 for deletion. It works together with the corresponding business
process definition.
Deploy Single Pattern: This human service provides a sample that shows the
deployment of an application pattern via IBM Workload Deployer into an
environment profile. An application pattern is chosen and is configured as a virtual
system pattern prior to deployment. The human services demonstrate how to
retrieve the pattern details and 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 be deployed. A validation step has been added
that checks if the customization is valid and, if not, a coach shows a list of
validation message to the user.
The human service itself shows how to:
v Specify the defaults of the pattern deployment
v Retrieve the pattern and its parts
v Get environment profiles, their cloud groups, and their IP groups
v Show the pattern and parts in a coach view
The result of the human service is an object of type 'Pattern' which describes the
customizations of the pattern, including:
v Name of the virtual system instance
v Target environment profile, cloud group, and IP group
v Flavor that is used
v Scheduled start/end date
v Customized part properties
Modify Single Virtual Machine: This is a human service to drive data collection
to modify the flavor, resource allocations, of a single server for a virtual system.
The allocated resource get changed while starting the virtual server. If the virtual
server is in running state. it is stopped and restarted to change the resource
allocations. The selection of the flavors listed for resource modification gets
retrieved by the integration service "Get Upgrade Flavors For Virtual Machine."
The matching business process definition to build a self-service offering is called
"Modify Resource".
Restart Single Server Virtual System: This is a human service to collect data to
restart activity. It works together with the corresponding 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 a 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 system based on contained virtual server for stop
activity. It works together with the corresponding business process definition.
Stop Single vSys Instance: This is a human service to collect data to select a
single virtual system to stop this instance. It works together with the
corresponding business process definition.
Stop vSys Instances: This is a human service to collect data to select a multiple
virtual systems for stopping all the selected instances. It works together with the
Start Single Server Virtual System: This is a human service to collect data to
start activity. It works together with the corresponding business process definition.
Start Single vSys Instance: This is a human service to collect data to select a
single virtual system to start the selected instance. It works together with the
Start vSys Instances: This is a human service to collect data to select a multiple
virtual systems for starting all selected instances. It works together with the
Select Pattern Instances: This human services shows how to select a set of virtual
system instances of a specified pattern. The output of the human service is a list of
virtual system IDs that can be used as input of the 'Stop Virtual System Instance'
process.
Select Single Pattern Instance: This sample human services shows how to select
a virtual system instances of a specified pattern. The output of the human service
is a list of virtual system IDs that can be used as input of the 'Stop Single Server
Virtual System' process.
Select Single Virtual Machine For Modify: This human services shows how to
select a virtual system instance while displaying virtual servers which get called by
using IaaS REST calls. The output of the human service is a list of virtual system
IDs, current, and target flavor that can be used as input of the 'Modify Resource'
process.
Select Single Server Virtual System: This sample human services shows how to
select a virtual system instance based on displaying the contained virtual servers.
The human service shows a table of virtual servers with the virtual system
instance name and resource allocations for selection. The output of the human
service is a virtual system ID that can be used as input of the sample process 'Stop
Single vSys Pattern Instance'.
Sample processes services
Most of the processes have a direct human service with a similar name to collect
data via coaches in the UI and forward the collected parameters to the process
services.
Change Environment Profile Limits
This sample process shows how to change environment profile limits via IBM
Workload Deployer. The process gets the input parameter collected by the related
human service "Change Environment Profile Limits" and updates the profile limits
afterwards accordingly.
Change Instance End Time
This sample process shows how to change the virtual system instance end time via
IBM Workload Deployer. The process gets the input parameter collected by the
related human service "Change Instance End Time" and updates the related
scheduled tasks afterwards accordingly.
Note: If an instance has an indefinite end time, no task is scheduled to stop and
remove the system. The end time can only be changed if an instance has a defined
end time and therefore tasks scheduled can be changed in respect to execution
time.
Delete Single vSys Instance
This sample process shows how to stop virtual system instances via IBM Workload
Deployer. The process gets a virtual system and calls the API of IBM Workload
Deployer to stop the virtual system instance.
Delete vSys Instances
Deployer. The process gets a list of virtual system IDs. The process checks the list
of virtual systems IDs and calls the API of IBM Workload Deployer to stop the
Deploy Selected Pattern
This sample process shows the configuration and deployment of a virtual system
pattern via IBM Workload Deployer. The input of the process is a business object
of type Pattern which contains the customizations of the pattern, for example:
v Name of the virtual system instance
v Target cloud group (environment profile, IP group)
v Flavor that is used
v Scheduled start/end date
v Customized part properties
The process validates the customizations, converts the customization in a JSON
document, and calls the SmartCloud Orchestrator API to deploy the pattern. After
deployment, the process waits until the virtual system instance is started. The exact
specification of the input parameters are described in the description of the
'Pattern' business object. The process is a generic implementation and can be used
with different 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 the
SmartCloud Orchestrator deploy instance workflow. The intention is to approve
the deploy instance process. Ensure that you adapt the participant to the group
which must have approval rights.
Modify Resource
This sample process shows how to change the flavor, resource allocations, of a
virtual server in system instances via IBM Workload Deployer. The process gets a
virtual system ID, stops the virtual machine, and changes the flavor via IBM
Workload Deployer 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 instance
via IBM Workload Deployer. The process gets a virtual system ID, stops the
instance, and afterwards, starts it again.
Restart ySys Pattern Instances
This sample process shows how to stop and start a single virtual system instances
via IBM Workload Deployer. The process checks the list of virtual systems IDs and
calls the API of IBM 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 via IBM
Workload Deployer. The process gets the virtual system ID and calls the API of
IBM Workload Deployer to start the virtual system instance.
Start vSys Pattern Instances
This sample process shows how to start virtual system instances via IBM Workload
of virtual system IDs and calls the API of IBM Workload Deployer to start the
Stop Single vSys Pattern Instance
This sample process shows how to stop a single virtual system instance via IBM
Workload Deployer. The process gets the virtual system ID and calls the API of
IBM Workload Deployer to stop the virtual system instance.
Stop vSys Pattern Instances
of virtual system IDs and calls the API of IBM Workload Deployer to stop the
Wait For Deletion Of Virtual System Instance
This process shows how to wait for a virtual system instance that has reached
stopped status. The process checks for the status in each iteration. Between each
iteration, the process waits for a specified number ofminutes. If the status is not
reached after a given number of checks, the process stops with an error task
assignment. The following parameters are required:
v ID of the virtual system instance
v Waiting status (internal status in IBM Workload Deployer)
v Maximum number of checks
v 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 a
specified status. The process checks for the status in each iteration. Between each
iteration, the process waits for a specified number ofminutess. If the status is not
reached after a given number of checks, the process stops with an error task
assignment. The following parameters are required:
v ID of the virtual system instance
v Waiting status (internal status in IBM Workload Deployer)
v Maximum number of checks
v Time in minutes between checks
As output, the process provides the status and the status message text.
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.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 information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks and Service Marks
IBM, the IBM logo, and ibm.com
are trademarks or registered trademarks of

International Business Machines Corporation in the United States, other countries,
or both. If these and other IBM trademarked terms are marked on their first
occurrence in this information with a trademark symbol (
or

), these symbols
indicate U.S. registered or common law trademarks owned by IBM at the time this
information was published. Such trademarks may also be registered or common
law trademarks in other countries. A current list of IBM trademarks is available on
the Web at http://www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are trademarks or
registered trademarks of Adobe Systems, Incorporated, in the United States and/or
other countries.
Intel, the Intel logo, Intel Inside, the Intel Inside logo, Intel Centrino, the Intel
Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are
trademarks or registered trademarks of Intel Corporation or its subsidiaries in the
United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Privacy policy considerations
IBM Software products, including software as a service solutions, (Software
Offerings) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offerings use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use
session and persistent cookies that collect each users user name, or other
personally identifiable information for purposes of session management, enhanced
user usability, single sign-on configuration. These cookies cannot be disabled.
If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.
For more information about the use of various technologies, including cookies, for
these purposes, See IBMs Privacy Policy at http://www.ibm.com/privacy and
IBMs Online Privacy Statement at http://www.ibm.com/privacy/details the
section entitled Cookies, Web Beacons and Other Technologies and the IBM
Software Products and Software-as-a-Service Privacy Statement at
http://www.ibm.com/software/info/product-privacy.
Accessibility features for SmartCloud Orchestrator
Accessibility features help a user who has a physical disability, such as restricted
mobility or limited vision, to use software products successfully. The major
accessibility features of SmartCloud Orchestrator are described in this topic.
Accessibility features
The following list includes the major accessibility features in SmartCloud
Orchestrator:
v Keyboard-only operation
v Interfaces that are commonly used by screen readers
v Keys that are discernible by touch but do not activate just by touching them
v Industry-standard devices for ports and connectors
v The attachment of alternative input and output devices
User documentation is provided in HTML and PDF format. Descriptive text is
provided for all documentation images.
The information center, and its related publications, are accessibility-enabled.
Related accessibility information
You can view the publications for SmartCloud Orchestrator in Adobe Portable
Document Format (PDF) using the Adobe Reader. PDF versions of the
documentation are available in the information center.
IBM and accessibility
See the IBM Human Ability and Accessibility Center for more information about
the commitment that IBM has to accessibility.
Product Number: 5725-H28

Printed in USA

SCO Content Development Guide

Uploaded by

Copyright:

Available Formats

SCO Content Development Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SCO Content Development Guide

Uploaded by

Copyright:

Available Formats

IBM SmartCloud Orchestrator

Authentication and Authorization Service of the WebSphere

are trademarks or registered trademarks of

Product Number: 5725-H28

You might also like