BMC Atrium Orchestrator 7-6-02 Development Studio User Guide

BMC Atrium Orchestrator
Development Studio User

Guide
Supporting
BMC Atrium Orchestrator version 7.6.02
February 2011
www.bmc.com
Contacting BMC Software
You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain
information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada
Address BMC SOFTWARE INC
2101 CITYWEST BLVD
HOUSTON TX 77042-2827 USA
Telephone 1 713 918 8800
or
1 800 841 2031
Fax 1 713 918 8000
Outside United States and Canada
Telephone +01 713 918 8800 Fax +01 713 918 8000
Copyright 2004 - 2011 BladeLogic, Inc.
BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are
registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in
other countries. All other BMC trademarks, service marks, and logos may be registered or pending
registration in the U.S. or in other countries. All other trademarks or registered trademarks are the
property of their respective owners.
ITIL is a registered trademark, and a registered community trademark of the Office of Government
Commerce, and is registered in the U.S. Patent and Trademark Office, and is used here by BMC Software,
Inc., under license from and with the permission of OGC.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks
of their respective owners.
UNIX is the registered trademark of The Open Group in the US and other countries.
The information included in this documentation is the proprietary and confidential information of BMC
Software, Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions
of the applicable End User License agreement for the product and to the proprietary and restricted rights
notices included in the product documentation.
Restricted rights legend
U.S. Government Restricted Rights to Computer Software. UNPUBLISHEDRIGHTS RESERVED
UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data
and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR
Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS
252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101
CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer support
Support website
You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support. From this
website, you can
read overviews about the several levels of support services and other programs that BMC offers
find the most current information about BMC products
search the knowledge base for issues similar to yours and possible solutions, or for articles about the product
order or download product documentation
download products and maintenance
report a problem or ask a question
subscribe to receive proactive e-mail alerts
find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and
telephone numbers
Support by telephone or e-mail
In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or
send an e-mail message to customer_support@bmc.com. (In the subject line, enter SupID:yourSupportContractID, such
as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC
Have the following information available so that Customer Support can begin working on your issue immediately:
product information
product name
product version (release number)
license number and password (trial or permanent)
operating system and environment information
machine type
operating system type, version, and service pack or other maintenance level such as PUT or PTF
system hardware configuration
serial numbers
related software (database, application, and communication) including type, version, and service pack or
maintenance level
sequence of events leading to the problem
commands and options that you used
messages received (and the time and date that you received them)
product error messages
messages from the operating system, such as file system full
messages from related software
3
License key and password information
If you have questions about your license key or password, use one of the following methods to get assistance:
Send an e-mail to customer_support@bmc.com.
Use the Customer Support website at http://www.bmc.com/support.
4 BMC Atrium Orchestrator Development Studio User Guide
Contents
About this book 11
Platform publications .....................................................................................................11
Searching across PDF documents in a folder and its subfolders .............................12
Conventions .....................................................................................................................12
Chapter 1 Introduction to BMC Atrium Orchestrator Development Studio 15
BMC Atrium Orchestrator overview ...........................................................................15
Architecture overview .........................................................................................16
Required components .........................................................................................16
Optional components ..........................................................................................17
BMC Atrium Orchestrator Development Studio overview .....................................18
Launch Pad ...........................................................................................................18
Connections ..........................................................................................................19
Library Manager ..................................................................................................19
Designer ...............................................................................................................20
Debugger ...............................................................................................................21
Chapter 2 Configuring BMC Atrium Orchestrator Development Studio 23
Before you configure a connection ..............................................................................23
Connecting to an environment .....................................................................................24
Troubleshooting connection problems .............................................................26
Chapter 3 Creating the Hello World workflow 29
Overview of creating the Hello World workflow ......................................................29
Before you begin to create the Hello World workflow .............................................30
Creating a module and a process for the Hello World workflow ...........................30
Creating and configuring the Append utility for the Hello World workflow . . .
31
Running the Hello World workflow ............................................................................35
Chapter 4 Creating a directory workflow 37
Overview of creating the workflows ...........................................................................37
Before you begin to create a workflow ........................................................................38
Creating a module and a workflow .............................................................................39
Configuring the Start activity .......................................................................................41
Creating and configuring the first Assign activity ....................................................42
Contents 5
Creating and configuring the Call Adapter activity ..................................................48
Testing the workflow and gathering sample data .....................................................50
Creating and configuring the second Assign activity ...............................................53
Configuring the End activity .........................................................................................61
Testing the workflow .....................................................................................................62
Creating the configuration items ..................................................................................65
Importing utilities modules ...........................................................................................67
Creating the connection details concept ......................................................................68
Testing the Make connection details for Invoke Command workflow ..................74
Creating the Copy File workflow .................................................................................76
Creating the Copy Files in Directory workflow ........................................................87
Testing the Copy Files in Directory process .............................................................104
Chapter 5 Using modules 107
Modules overview ........................................................................................................107
Library Manager ...........................................................................................................107
Importing modules from the repository .........................................................109
Importing modules from disk ..........................................................................109
Creating modules ..........................................................................................................110
Using process directories .............................................................................................111
Creating rules ................................................................................................................112
Creating schedules .......................................................................................................115
Configuration items ......................................................................................................118
Working with configuration items .................................................................119
Chapter 6 Process design 121
Process overview ..........................................................................................................121
Process types .......................................................................................................121
Process properties .........................................................................................................122
Adding activities to a process .....................................................................................123
Activity properties ........................................................................................................124
Activity Property PanelProperties tab ........................................................125
Activity Property PanelLogging tab ...........................................................125
Activity Property PanelMetadata tab .........................................................127
Compensations ..............................................................................................................128
Called processes ...........................................................................................................129
Using a called process .......................................................................................129
Automapping context items with called process inputs and outputs .......130
Called Process viewer .......................................................................................131
Calling Process viewer .....................................................................................131
Renaming a process or process directory ..................................................................132
Operator processes .......................................................................................................133
Using hyperlinks in processes exposed in the BMC Atrium Orchestrator
Operator Control Panel .....................................................................................133
WSDL to workflow process generation wizard .......................................................135
Searching for processes ................................................................................................138
Using the Advanced Search Results window ................................................139
Generating process documentation ..........................................................................140
Export the process module ..........................................................................................141
Chapter 7 Using software configuration management systems when creating workflows 143
Software configuration management overview .......................................................143
Configuring BMC Atrium Orchestrator Development Studio to use CVS .........144
Configuring BMC Atrium Orchestrator Development Studio to use Subversion
146
Configuring BMC Atrium Orchestrator Development Studio to use Perforce
................................................................................................................................................147
Chapter 8 Using a transform editor 149
Transform editors overview ........................................................................................149
Basic transform editor ..................................................................................................150
Test frame ............................................................................................................150
Select resource pane ..........................................................................................150
Preview frame ....................................................................................................150
Function sequence .............................................................................................151
Basic transform editor functions ......................................................................152
Advanced transform editor overview .......................................................................155
Sample pane ........................................................................................................156
Token pane ..........................................................................................................157
Document pane ..................................................................................................158
XPath helpers ......................................................................................................158
XSLT transform editor .......................................................................................160
XPath transform editor ......................................................................................178
Chapter 9 Activities 179
Activities overview .......................................................................................................179
Start activity ...................................................................................................................180
Start activity properties .....................................................................................180
End activity ...................................................................................................................181
Assign activity ...............................................................................................................183
Creating an assign statement ...........................................................................184
Deleting a context with an assign statement ..................................................186
Contents 7
Operator Dialog activity ..............................................................................................187
String input .........................................................................................................188
Password input ..................................................................................................188
Numeric input ....................................................................................................189
Date input ...........................................................................................................190
Boolean input ......................................................................................................191
List inputstatic values ...................................................................................192
List inputdynamic values .............................................................................193
Switch activity ...............................................................................................................194
For activity .....................................................................................................................196
Spawn activity ...............................................................................................................197
Launch Job activity .......................................................................................................198
Utility activity ................................................................................................................199
Using date utilities .............................................................................................199
Numeric utilities ................................................................................................203
Using string type utilities .................................................................................204
Metrics activity ..............................................................................................................207
Collecting business metrics .............................................................................207
Pause activity .................................................................................................................208
Script activity .................................................................................................................209
Script parameters ...............................................................................................210
Call Adapter activity ....................................................................................................212
Integration Mapping activity ......................................................................................213
Creating a new mapping .................................................................................213
Editing a mapping .............................................................................................215
Updating a mapping .........................................................................................215
Comment activity .........................................................................................................215
Chapter 10 Context item overview 217
Context Browser ............................................................................................................217
Search for a context item ...................................................................................218
Dynamic contexts ..........................................................................................................219
Dynamic context scenario .................................................................................219
System parameters ........................................................................................................220
Concepts ........................................................................................................................221
Chapter 11 Testing and debugging processes 223
Testing a process ...........................................................................................................223
The debugger tool .........................................................................................................224
Debugger view ...................................................................................................225
Execution Viewer ...............................................................................................225
Test console .........................................................................................................226
Context Viewer ...................................................................................................226
Debugger toolbar ...............................................................................................226
Using the Breakpoint Manager ...................................................................................227
Chapter 12 Troubleshooting 229
Troubleshooting common issues ................................................................................229
Log files for troubleshooting .......................................................................................229
Impact of secure module configuration on existing processes ..............................232
Appendix A Language enablement support for BMC Atrium Orchestrator 235
Limitations on using multibyte characters in BMC Atrium Orchestrator
Development Studio .....................................................................................................235
Language enablement support for BMC Atrium Orchestrator adapters .............236
Appendix B Glossary 239
Contents 9
About this book
This book contains detailed product information and is intended for process and
workflow developers who design, test, and deploy IT automation solutions.
Like most BMC documentation, this book is available in printed and online formats.
To request printed books or to view online books and notices (such as release notes
and technical bulletins), see the Customer Support website at http://www.bmc.com/
support. Most product shipments also include the books on a documentation CD.
Note
Online books are formatted as PDF or HTML files. To view, print, or copy PDF
books, use the free Adobe Reader from Adobe Systems. If your product installation
does not install the reader, you can obtain the reader at http://www.adobe.com.
The software also offers online Help. To access Help, press F1 within any product or
click the Help button in graphical user interfaces (GUIs).
Platform publications
The following table lists the documents that support the BMC Atrium Orchestrator
platform.
Document Description
BMC Atrium Orchestrator System
Administration Guide
Provides conceptual and procedural information about
managing the BMC Atrium Orchestrator grid environment
BMC Atrium Orchestrator Development
Studio User Guide
Describes how to use BMC Atrium Orchestrator Development
Studio
BMC Atrium Orchestrator Web Services
Guide
Describes the ORCA web service and the legacy web service
and provides information about how to use the JSP taglib with
the ORCA web service
BMC Atrium Orchestrator Operator Control
Panel Getting Started Guide
Provides instructions for operators to execute workflows in semi-
automated mode through a web-based user interface
About this Book 11
Document Description
BMC Atrium Orchestrator Installation Guide Describes how to plan for the installation of the BMC Atrium
Orchestrator product, install it, and upgrade it
Searching across PDF documents in a folder
and its subfolders
With Adobe Reader version 7.0 and later, you can perform a full-text search across
all PDFs that reside in the same folder and its subfolders.
If you do not have Adobe Reader version 7.0 or later, you can download the latest
Adobe Reader version from www.adobe.com for free.
To search for a word or phrase in PDF documents in a single directory
1 Start Adobe Reader.
2 In the toolbar, click the search icon (binoculars).
If the search icon is missing, right-click the toolbar to find more toolbar options.
Different versions of Adobe Reader put the option in different places.
3 In the Search window, select All PDF Documents in under Where would you
like to search?
4 Click the folder selection box and select Browse for Location.
5 Browse to the top-level folder that contains the PDF documents that you want to
search.
6 In the What word or phrase would you like to search for? box, type a search
term and click Search.
The search tool searches for the specified term in all of the PDFs in the selected
directory and its subdirectories and displays the results.
Conventions
This document uses the following special conventions:
Searching across PDF documents in a folder and its subfolders
All syntax, operating system terms, and literal examples are
presented in this typeface.
Variable text in path names, system messages, or syntax is displayed in italic text:
testsys/instance/fileName
This document uses a symbol to show menu sequences. For example, Actions =>
Create Test instructs you to choose the Create Test command from the Actions
menu.
Conventions
About this Book 13
Conventions
Introduction to BMC Atrium
Orchestrator Development Studio
This chapter provides a general overview of BMC Atrium Orchestrator and a more
detailed description of BMC Atrium Orchestrator Development Studio.
BMC Atrium Orchestrator overview
BMC Atrium Orchestrator is an IT process automation platform that automates tasks
across multiple functional areas, systems, and geographic locations.
Built on a high-availability and high-performance grid architecture, BMC Atrium
Orchestrator offers out-of-the-box workflows, leveraging your existing systems
(monitoring, service desk, BMC Atrium Configuration Management Database, and
others) to accelerate IT service execution across your enterprise.
BMC Atrium Orchestrator can automate a variety of tasks, including:
Automating the verification, diagnosis, and remediation of IT infrastructure failures
Accelerating routine tasks, such as provisioning and decommisioning physical
and virtual assets and IT services
Synchronizing information between Service Desk and other IT management systems
Orchestrating disaster recovery routines
Automatically recording configuration operations with change management
systems
By automating manual and repetitive IT tasks, BMC Atrium Orchestrator not only
reduces operational costs, but also assures you of compliance and that your best-
practice standards are met 100% of the time.
1
Architecture overview
BMC Atrium Orchestrator is built on a grid architecture that offers out-of-the-box high-
availability, load-balancing, and industry-leading performance.
The grid is composed of different types of components. A component can be a peer,
such as a configuration distribution peer (CDP) or an activity peer (AP). A
component can also provide a service, such as a graphing server or a repository.
When configured together, these components enable you to execute workflows
across your entire organization with full redundancy.
Any grid requires a core set of components. You can install other, optional
components during the initial system installation, or add them later.
Required components
Any BMC Atrium Orchestrator system requires the following key components: BMC
Atrium Orchestrator Access Manager (Access Manager), a repository, a
configuration distribution peer, and BMC Atrium Orchestrator Development Studio.
Access Manager
Access Manager is the security component for the BMC Atrium Orchestrator
product. It enforces authentication and authorization policies, and offers single sign-
on (SSO) capabilities for web components in the grid. Access Manager can interface
with external directory services such as Microsoft Active Directory and lightweight
directory access protocol (LDAP).
Repository
The repository stores BMC Atrium Orchestrator content, such as adapters and
workflow modules, in a central location. As the source of record, the repository is
accessed by a multitude of users, including workflow developers, software testers,
and system administrators. The repository enforces versioning and keeps a history of
workflow modules through their revisions. It also offers role-based access control so
that you can ensure that users can access only the appropriate content.
Configuration distribution peer
The configuration distribution peer (CDP) is the primary peer in the grid. It provides
a central administration point and is a workflow execution engine. The CDP houses
the BMC Atrium Orchestrator Grid Manager application, which enables
administrators to conduct various configuration, activation, and maintenance tasks
on the grid. It can also host adapters and workflow modules, which are used by the
grid to communicate with external systems. Typical grid configurations include one
CDP, although a grid can house two CDPs in high-availability (HACDP) mode.
BMC Atrium Orchestrator Grid Manager
The BMC Atrium Orchestrator Grid Manager component resides on the CDP server
and provides a user interface to add and maintain grids, peers, adapters, and process
schedules. It enables you to manage module deployment and activation. You can
also use BMC Atrium Orchestrator Grid Manager to enable collection of metrics
about grid and process performance.
BMC Atrium Orchestrator Development Studio
BMC Atrium Orchestrator Development Studio is a graphical authoring tool used to
create, modify, and test workflows. It is a thick-client application that can be
installed on Windows and Mac operating systems. Using BMC Atrium Orchestrator
Development Studio, you can edit rules and schedules to trigger workflows
automatically by external events or at regular intervals. Your developers can
maintain control of workflows in their local BMC Atrium Orchestrator Development
Studio environment or through an external source code management (SCM) system.
However, before the workflows can be activated on a grid, they first must be
exported to the repository.
Optional components
In addition to the required components, you can install additional peers or other
services to expand the capabilities of BMC Atrium Orchestrator.
Activity peer
You can use an activity peer (AP) to execute workflows. Similar to a CDP, the AP can
host adapters, but it does not provide administrative services. When you add an AP
to the grid, the AP automatically downloads activated workflows from the CDP to
provide high-availability workflow load balancing. If a CDP became unavailable, the
AP would continue to process workflows with the other available peers in the same
grid.
Lightweight activity peer
Lightweight activity peers (LAPs) host adapters. Because they present a very small
footprint, LAPs can be hosted on the same servers that house the third-party
applications with which the grid communicates. LAPs are particularly helpful when
a third-party system requires the adapter to make calls locally, or an adapter
requires access to software libraries that cannot be installed outside of the third-
party application.
BMC Atrium Orchestrator Operator Control Panel
The BMC Atrium Orchestrator Operator Control Panel is a web-based interface that
enables operators, such as service desk, network operators, and IT technicians, to run
workflows in a semi-automated mode. It enables operators to manually launch a
workflow, follow its progress in a graphical view, and provide input as required.
Using BMC Atrium Orchestrator Operator Control Panel, operators can fulfill IT
services more accurately and efficiently while maintaining full control of workflow
execution.
Graphing server and graphing components
The graphing server and components render graphical representations of process
metrics. Process metrics are measurements related to the processes running on the
grid, including any user-defined business metrics collected by workflow activities.
BMC Atrium Orchestrator Development
Studio overview
Use BMC Atrium Orchestrator Development Studio to create and edit workflows
that you want to use on the grid.
The BMC Atrium Orchestrator platform repository stores modules that contain
workflows that you import into BMC Atrium Orchestrator Development Studio.
Using the BMC Atrium Orchestrator Development Studio design tools, you can
customize the workflow processes for your environment, build complex workflows,
test and validate processes, create and manage process schedules, and more.
Launch Pad
The Launch Pad is the main navigation pane, with icons that launch BMC Atrium
Orchestrator Development Studio components. It provides a central point for
navigating the BMC Atrium Orchestrator Development Studio environment and tools.
Table 1: BMC Atrium Orchestrator Development Studio components
Launch Pad button Description
Connections Opens the Connections dialog box, used to configure connections to the
CDP
Library Opens the Library Manager, used to import and export modules
BMC Atrium Orchestrator Development Studio overview
Launch Pad button Description
Designer Opens the Designer, the main work area of BMC Atrium Orchestrator
Development Studio where processes are created and edited
Debugger Opens the Debugger, used for testing and debugging processes
Help Opens the BMC Atrium Orchestrator Development Studio Online Help
Connections
Connections establish communications between BMC Atrium Orchestrator
environments and BMC Atrium Orchestrator Development Studio. You establish
communication with an environment through the Connections window.
You can configure multiple environments for BMC Atrium Orchestrator
Development Studio, but only one connection can be active at a time. On the
Welcome view, the active environment is indicated with a green check mark. BMC
Atrium Orchestrator Development Studio must be configured and connected to an
environment when you are importing and exporting to the repository, or when you
are testing and debugging processes. You are prompted to log in to the connected
environment when you launch BMC Atrium Orchestrator Development Studio and
before an action that requires a communication with the environment.
Note
You can import to and export from disk even if you are not connected to a BMC
Atrium Orchestrator environment.
Library Manager
The Library Manager provides the interface between BMC Atrium Orchestrator
Development Studio and the repository.
After you establish a connection to an environment, you use the Library Manager to
import modules from the repository and unbundle the modules in BMC Atrium
Orchestrator Development Studio. Unbundling loads modules into the BMC Atrium
Orchestrator Development Studio workspace and enables you to edit and customize
module processes, rules, configurations, and schedules.
You can navigate the Library Manager by using the Import Modules, Unbundle
Modules, Compare Modules, and Export Modules tabs.
Designer
The Designer contains the process design and modeling tools at the core of BMC
Atrium Orchestrator Development Studio: Project Navigator, Activity Palette, and
the process canvas.
Project Navigator
The Project Navigator organizes the modules and processes imported and
unbundled in your workspace. In this pane, you can perform basic and advanced
searches of processes. New modules are created in this pane. When you double-click
a process name, that process is displayed on the process canvas.
Activity Palette
The Activity Palette displays the activities that you use to develop processes. Drag
and drop the activities onto the process canvas to use them in a process. You can set
the Activity Palette to
Process canvas
The process canvas is the area where you develop, build, and modify workflows.
You drop activities onto the canvas from the Activity Palette. The process canvas
tabs, Process and PDL (Process Design Language), offer different views of a process.
The process canvas is also called the design canvas.
The Process tab graphically displays a process and its activities.
The PDL tab displays a read-only view of the XML representation of a process.
When you edit an activity, the Process tab displays the Properties, Logging, and
Metadata tabs for the activity. If the activity is a called process, a For activity, or a
Switch activity, the Process tab also displays the Results tab.
Figure 1: Designer window
Debugger
The Debugger tool enables you to step through process testing with the option to use
breakpoints. The Debugger tool can simulate a BMC Atrium Orchestrator Operator
Control Panel for processes, even those not exposed in BMC Atrium Orchestrator
Operator Control Panel.
Configuring BMC Atrium
Orchestrator Development Studio
Before you can edit processes in BMC Atrium Orchestrator Development Studio, you
must establish a connection to an environment. After you connect to an
environment, the Designer, Debugger, and Library Manager views are enabled, and
you can start working in BMC Atrium Orchestrator Development Studio.
Before you configure a connection
Ensure that the BMC Atrium Orchestrator platform is installed and configured. In
order to connect to an environment, the following BMC Atrium Orchestrator
platform components must be installed and running:
Access Manager and the repository
Grid Manager
One or more grids created using by Grid Manager
Note
Enabling an adapter on a peer is necessary only if:
You intend to test processes that use adapters.
You build a workflow that interacts with other systems.
In that case, enable an adapter for that system and configure it to connect with the
external system.
2
Connecting to an environment
BMC Atrium Orchestrator Development Studio uses connections to establish
communication with an environment. Connections are displayed in the
environments pane of the Welcome page.
To establish a connection to a CDP
1 From the Welcome page, click Connections.
2
Click .
BMC Atrium Orchestrator Development Studio creates a new connection with a
default connection name. BMC recommends changing the connection name to a
more descriptive name for your environment.
Tip
If you connect BMC Atrium Orchestrator Development Studio to multiple
environments, it is helpful to give the connection a concise name that you
associate with the environment.
3 Enter the authentication information:
Field Description
Connection Name Specifies the name for the connection
User name Specifies the Access Manager account to use to log on to the environment and
configure the connection
This account must have a role of administrator or designer. When BMC Atrium
Orchestrator Development Studio needs to connect to a grid, this name is the default
used in the grid login dialog box.
Password Specifies the password that corresponds to the user name
Host Name/IP Specifies the host name or IP address of the CDP server
Peer Context Contains baocdp by default
If the CDP peer was installed using a Peer Context other than the default, then this
must be edited to match.
Port Specifies the web server HTTP port specified during the CDP server installation
The default installation value is 8080.
Field Description
Protocol Specifies the protocol used to retrieve the configuration file from the CDP server
To use the https option, additional configuration is needed on the CDP and the BMC
Atrium Orchestrator Development Studio workstation. See the BMC Atrium
Orchestrator System Administration Guide for details.
4 Click Connect.
If the server has multiple IP addresses, an IP address window is displayed from
which you select the IP address to use.
5 Click Yes to proceed with the connection.
6 Click Close to exit the BMC Atrium Orchestrator Development Studio
Configuration window.
To cancel a connection during creation
1 While creating a connection, click Cancel to void the configuration.
2 Select Yes to confirm deleting the connection.
3 Click Close.
To cancel a connection during the connect process
1 While BMC Atrium Orchestrator Development Studio is attempting to connect to
an environment, click Cancel to exit from the connection process.
2 Click Close.
To delete a connection
If you attempt to delete the currently active connection, BMC Atrium Orchestrator
Development Studio warns you. Although you can delete the active connection, the
workspace containing the run books, modules, and processes remains. You cannot
export processes from the workspace until you connect to an environment.
1 In the Connections List panel, select the connection to delete.
2 Click Delete.
3 Click OK to delete the connection.
Tip
To stop the delete process, click Cancel.
Troubleshooting connection problems
The troubleshooting steps that follow can help you resolve connections issues. If the
successful connection text is not displayed due to errors during the configuration,
check the connection entries you provided. If errors persist, contact BMC Customer
Support.
Verify the host name or IP address.
Verify that Access Manager is running.
Verify that the server is running.
Verify that the computer that is running BMC Atrium Orchestrator Development
Studio can access the server. For example, ping the server.
Ensure that BMC Atrium Orchestrator Development Studio and the CDP are
running the same version of BMC Atrium Orchestrator.
Ensure that BMC Atrium Orchestrator Development Studio is running on a
supported platform.
Ensure that clocks on the computer that is running BMC Atrium Orchestrator
Development Studio and the computer that is running the CDP are in sync. If they
are out of sync by several minutes, the connection does not work.
Verify that you are using the correct settings for user name, password, peer
context, port, and protocol.
To review the connection settings, open the bao.options file located in the root
folder of the CDP.
Example
In this example bao.options file, the CDP is installed on vm-w23-xyz010, the
peer context is baocdp, the port is 38080, and the protocol is http.
-P installLocation=C:\Program Files\BMC Software\AO
-J AO_INSTALL_TYPE=install_new
-J AO_INSTALLING_FEATURES=CDP,WEBSERVER,OCP
-J AO_REPOSITORY_URL=http://vm-w23-xyz010:8080/baorepo
-J AO_CERT_PASSWORD=
-J AO_CERT_PRINCIPAL=My Company Name
-J AO_ENVIRONMENT_NAME=ENV1
-J AO_START_SERVER_ON_SUCCESS=true
-J AO_OCP_DEPLOYMENT_CONTEXT=baoocp
-J AO_AM_DEPLOYMENT_CONTEXT=baoam
-J AO_GRAPH_DEPLOYMENT_CONTEXT=baograph
-J AO_PEER_NAME=CDP1
-J AO_PEER_NET_CONFIG_VALIDATE=false
-J AO_PEER_NET_CONFIG_CDP_CONTEXT=baocdp
-J AO_PEER_NET_CONFIG_CDP_HOST=vm-w23-xyz010
-J AO_PEER_NET_CONFIG_CDP_PASSWORD=
-J AO_PEER_NET_CONFIG_CDP_PORT=38080
-J AO_REPOSITORY_HOST=vm-w23-xyz010
-J AO_REPOSITORY_PORT=8080
-J AO_REPOSITORY_USER_NAME=admin
-J AO_REPOSITORY_PASSWORD=
-J AO_PEER_NET_CONFIG_CDP_USER=admin
-J AO_PEER_NET_CONFIG_GRID_NAME=GRID1
-J AO_PEER_NET_CONFIG_PEER_NAME=CDP1
-J AO_PEER_NET_CONFIG_NEW_PEER_NAME=LAP1
-J AO_PEER_NET_CONFIG_PROTOCOL=http
-J AO_SECURITY_ACTIVE=true
-J AO_SECURITY_COMM_PORT=61616
-J AO_SECURITY_COMM_PROTOCOL=ssl
-J AO_SECURITY_WEB_PORT=8080
-J AO_SECURITY_WEB_PROTOCOL=http
-J AO_WEBSERVER_SSL_ENABLED=false
-J AO_WEBSERVER_PORT=38080
-J AO_WEBSERVER_SHUTDOWN_PORT=8005
-J AO_PEER_COMM_PORT=8081
-J AO_WEBSERVER_DETECTED_OLD_SETTINGS=false
-J AO_SERVER_STOP_SUCCCESSFUL=false
-J AO_REPOSITORY_PROTOCOL=http
Creating the Hello World workflow
This chapter provides a detailed example of the major steps in creating a workflow.
The example workflow inserts the words Hello World into a text file.
This example focuses on the steps that enable you to quickly experience workflow
development in BMC Atrium Orchestrator Development Studio. Detailed
information about creating workflows and about the tools that you use is contained
in other sections of the book.
Chapter 4 provides another example of creating a workflow.
Overview of creating the Hello World workflow
The following tasks capture the actions needed to create a workflow to insert Hello
World in a text file.
1 Before you begin to create the Hello World workflow on page 30 discusses the
environment that must exist and the information that you must have to use BMC
Atrium Orchestrator Development Studio to create the workflow.
2 Creating a module and a process for the Hello World workflow on page 30
shows how to create the basic structure for the workflow.
3 Creating and configuring the Append utility for the Hello World workflow on
page 31 shows how to use one of the BMC Atrium Orchestrator utilities to insert
the Hello World text in a file.
4 Running the Hello World workflow on page 35 shows how to run the
workflow that inserts the text.
Tip
You can stop and then resume working on this process at any time. Save the process
every time you stop working on it. To resume work, double-click the process name
in the Project Navigator.
3
Before you begin to create the Hello World
workflow
Before you can use BMC Atrium Orchestrator Development Studio to create the
workflow, you or your system administrator must have completed the following
activities:
Use Grid Manager to define and configure an adapter of type ro-adapter-file on
the grid. Record the name assigned to the adapter during configuration. You will
need this information in a later step.
Start BMC Atrium Orchestrator Development Studio and configure a connection
to an environment.
Use BMC Atrium Orchestrator Development Studio to import and unbundle the
Autopilot-AD-Utilities.
For more information about these activities, see the BMC Atrium Orchestrator System
Administration Guide and other chapters in the BMC Atrium Orchestrator Development
Studio User Guide.
Creating a module and a process for the Hello
World workflow
When you create a workflow, you are creating a module and then a process within
that module. All the other activities for the workflow are created and configured
within the process.
To create a module
1 On the BMC Atrium Orchestrator Development Studio Launch Pad, click
Designer.
2 In the Project Navigator tree, right-click the name of the grid and select Create
New Module.
3 In the New Module dialog box, select Projects from the Module Type list.
4 Type Hello_World in the Name field, and then click OK.
Before you begin to create the Hello World workflow
The product creates a new module and lists it under the grid in the Project Navigator.
Figure 2: Project Navigator showing the new module
To create a process
1 Right-click the Hello_World module and select New Process.
2 In the Create New Process dialog box, type Hello World in the Process Name
field and click OK.
The new process name is added to the module in the Project Navigator, and the
design canvas displays the new process. When first created, a process contains
only the Start and End activities connected by the gray process line.
Figure 3: Design canvas with Start and End activities
Creating and configuring the Append utility
for the Hello World workflow
In this task, you use the Append utility to create an activity in the workflow to insert
the Hello World text in a file.
Creating and configuring the Append utility for the Hello World workflow
In the preceding task, you created a module and a process. The design canvas had
only a Start and an End activity, connected by the gray process line.
To create the Append utility activity
1 In the Project Navigator, click to expand AutoPilot-AD-Utilities =>
Terminal => File.
2 From the File folder, drag the Append utility to the design canvas.
3 Connect the Append utility to the Hello World process with the gray process line:
a Click the line to select it and highlight the green handles.
b Drag the handle closest to the End activity to the front (left side) of the Append
utility.
c Click the back (right side) of the Append utility and draw a new line to the
front (left side) of the End activity.
Best practice
Always connect a new activity or process to the overall process as soon as you
place the activity or process on the design canvas.
Figure 5: Design canvas with an Append utility added to the process
To configure the Append utility
1 Double-click the Append utility to open the Property Panel for the Append utility
activity.
Figure 6: Append utility activity Property Panel with the Properties tab selected
The Properties tab of the Property Panel lists the inputs and outputs for the
activity. A red check mark indicates that the input is required.
2 On the Properties tab of the Property Panel for the Append utility activity, double-
click in the Input Name/Value field that corresponds to the adapter name Output
Name.
The Properties tab is redisplayed in a different format. It is now the Properties
tab for the selected item.
Figure 7: Properties tab for the adapter name item
3 On the Properties tab, enter information for the adapter name input mapping:
a Ensure that the Parameter type is String.
b In the text box, type the name assigned to the ro-adapter-file adapter when it
was configured on the grid.
Figure 8: Input parameter area of the Properties tab for the adapter name item
c Click OK.
The Property Panel for the Append utility is redisplayed with the input
information displayed.
4 Repeat step 3 to enter the value for the file name input mapping. Type the path
and name for the file where you want to write Hello World.
This example uses c:\greeting.txt.
5 Repeat step 3 to enter Hello World as the value for the line 1 input mapping.
This is the text that you want to write to the specified file.
Figure 9: Input mapping area of the Append utility activity Property Panel
To finish creating the Append utility activity
1 On the Property Panel for the Append utility, click OK to return to the design
canvas.
2
Click to save the process.
Running the Hello World workflow
In this task, you verify the tasks that you have completed.
To test the process
1
In the toolbar under the menus, click ExecuteProcessAction .
If you have not already logged on to the grid, BMC Atrium Orchestrator
Development Studio displays the Login dialog box. BMC Atrium Orchestrator
Development Studio uses the peers and adapters on the grid to test the process.
2 If you have not already logged on to the grid, log on. Otherwise, proceed to step
3.
3 In the Execution Mode dialog box, select Test as if triggered by a rule, schedule
or SOAP. Then click OK.
BMC Atrium Orchestrator Development Studio runs the Hello World process.
The console window is opened below the design canvas, and the Process Log tab
displays the results of the process execution. These are the same results that are
posted to the processes.log file when the workflow is run on the grid. On the
design canvas, the Append activity has a brown box around it to indicate that it
has been executed.
4 Verify that the last line in the console window is The process terminated in
the completed state.
This message indicates that the process you created ran to completion. You must
still verify that the process accomplished the task that you wanted.
5 Go to the computer where the CDP is installed, and look in the directory that you
specified in the previous task. Verify that the greeting.txt file was created and that
it contains the text Hello World.
Creating a directory workflow
This chapter provides detailed examples of the steps for creating a workflow that
generates a directory listing and then runs a command on each file in the directory.
The workflow produced from these examples is called Copy Files in Directory.
The example workflow is built modularly and contains other workflows, also called
processes, that perform the operations needed to accomplish the larger goal. These
examples focus on the actual steps of creating a workflow. Detailed information
about why you create workflows and about the tools that you use is contained in
other sections of the book.
Overview of creating the workflows
When BMC Atrium Orchestrator executes a workflow, or process, it receives
information, manipulates that information, performs actions through other software
or runs commands on other servers, gathers additional information, and presents the
results. Information is passed in context items, and adapters direct the actions of the
other software. When you create a workflow, you identify the sources of the input
information in the Start activity, define the ways the context items are used to pass
and manipulate the information with assign statements, and instruct the adapters on
how to direct the other software.
The examples in this chapter create a set of workflows that work together to
accomplish the objective of generating a directory listing and then running the copy
command on each file in the directory. The tasks are grouped by workflow, and each
task assumes that you have completed the preceding tasks in this chapter. The main
tasks include:
1 Creating the Directory list workflow
The Directory list workflow lists the contents of a directory that you specify. This
workflow will be used in the top-level workflow, Copy Files in Directory. Because
this is the first workflow, its tasks are discussed in greater depth than for the other
workflows.
4
2 Creating configuration items
Configuration items are similar to constants. This task creates configuration items
that are used in subsequent workflows.
3 Creating the connection details concept
A concept is a context item containing multiple values. In this task, you create and
test a concept that contains the information required to invoke the copy command.
4 Creating the Copy File workflow
The Copy File process copies a specified file to a target directory.
5 Creating the Copy Files in Directory workflow
The top-level workflow, Copy Files in Directory, combines all the previous
workflows to accomplish the objective.
The sample workflows were developed in a Windows environment. If you want to
use them on other operating systems, you must modify them to conform to
requirements of the other operating systems.
Tip
You can stop and then resume working on a workflow at any time. Save the
workflow every time you stop working on it. To resume work, double-click the
workflow name in the Project Navigator.
Before you begin to create a workflow
Before you can use BMC Atrium Orchestrator Development Studio to create the
directory list workflow, you or your system administrator must have completed the
following actions:
Using Grid Manager, defined and configured an adapter of type ro-adapter-
command-line on the grid; record the name assigned to the adapter during
configuration; enabled the adapter on at least one peer on the grid
Started BMC Atrium Orchestrator Development Studio and configured a
connection to an environment
For more information about these activities, see the BMC Atrium Orchestrator System
Administration Guide and other chapters in the BMC Atrium Orchestrator Development
Studio User Guide.
Before you begin to create a workflow
Creating a module and a workflow
When you create a workflow, you are creating a module and then a workflow within
that module. All the other activities for the workflow are created and configured
within the workflow.
To create a module
1 On the BMC Atrium Orchestrator Development Studio Launch Pad, click
Designer.
2 In the Project Navigator tree, right-click the name of the grid and select Create
New Module.
3 In the New Module dialog box, select Projects from the Module Type list.
4 Type Samples in the Name field, and then click OK.
The product creates a new module, Samples, and lists it under the grid in the
Project Navigator, as shown in Figure 10 on page 39.
Figure 10: Project Navigator showing the new module
To create a workflow
1 In the Project Navigator tree, right-click Samples, the name of the new module,
and select New Process.
2 In the Create New Process dialog box, type List directory in the Process Name
field, ensure that the Expose Process options In Schedules and In Rules are
selected, and then click OK.
The following figure shows the Create New Process dialog box:
Figure 11: Create New Process dialog box
The new workflow name is added to the module in the Project Navigator, and the
design canvas displays the new workflow, as shown in Figure 12 on page 40.
When first created, a workflow contains only the Start and End activities.
Figure 12: New workflow added to the Project Navigator and displayed on the
design canvas
Configuring the Start activity
The Start activity for any workflow must contain the information that the workflow
uses to accomplish the task. That means that for the List Directory workflow, you
must configure the Start activity so that when the workflow runs, you can enter the
name of the directory to be listed, the name of the adapter to be used, and the
command to be used.
To configure the Start activity
1 On the design canvas, double-click the Start activity.
2 On the Properties tab of the Property Panel for the Start activity, create the first
input parameter:
a In the first empty row under Input Parameter Name field, type adapter name.
b Press Tab, and verify that the corresponding value under Context Name is the
same as in Input Parameter Name and that the Required check box is selected.
3 Repeat step 2 to create the second and third input parameters, directory
command and directory name.
Figure 13 on page 41 shows the Properties tab with the input parameters.
Figure 13: Input parameters for Start activity
4 Click OK to close the Property Panel for the Start activity and return to the design
canvas.
5 To save the workflow, click File => Save.
Best practice
Save the workflow frequently.
Configuring the Start activity
Creating and configuring the first Assign
activity
This task tells how to use assign statements to convert the input information context
items into a form that the adapter can use.
In the preceding tasks, you created a module and a workflow, and configured the
Start activity to define context items as the input parameters. The design canvas had
only a Start and an End activity, connected by the gray process line, as shown in the
following figure:
In this task, you create an Assign activity with an assign statement. The statement
has an input and an output parameter. The output parameter is an adapter request,
which is an XML file that communicates with the adapter.
To create the first Assign activity
1 Click the Activity Palette to open it, and drag an Assign activity to the design
canvas.
2 Connect the Assign activity to the workflow with the gray process line:
a Click the line to select it and highlight the green handles.
b Drag the handle closest to the End activity to the front (left side) of the Assign
activity.
Creating and configuring the first Assign activity
c Click the back (right side) of the Assign activity and draw a new line to the
front (left side) of the End activity. The result appears as shown in the
following figure:
Figure 15: Design canvas with an Assign activity added to the workflow
Best practice
Always connect a new activity to the workflow as soon as you place the activity
on the design canvas.
3 Double-click the Assign activity to open its Property Panel.
To create the assign statement
1
On the Properties tab of the Property Panel for the Assign activity, click to
add a new assign statement.
The Properties tab is redisplayed in a different format. It is now the Properties
tab for the assign statement, as shown in the following figure:
Figure 16: Assign statement Properties tab
2 On the Properties tab, enter information for the input parameter for the assign
statement.
This assign statement transforms the input parameter information into the
adapter request for the Command Line adapter.
Tip
The BMC Atrium Orchestrator User Guide for Base Adapters contains sample XML
for you to use with the adapters. When you create the adapter request in BMC
Atrium Orchestrator Development Studio, you can copy the sample XML and
paste it in the text box, and then revise it to meet the needs of your workflow.
When you use the sample XML, you must enclose it in <request-data> tags.
The instructions for this task provide the required XML so you do not need to
consult the BMC Atrium Orchestrator User Guide for Base Adapters to complete the
task.
a In the Parameter type field, select XML.
b Type the following XML code in the text box. The result appears as shown in
Figure 17 on page 45.
<request-data>
<command-request>
<commands>
<command><![CDATA[ ]]></command>
</commands>
</command-request>
</request-data>
Figure 17: Input parameter XML text
c Place the cursor inside the CDATA element in the command element (after
[CDATA[ and before ]]), and click Insert Context/Config Element .
Best practice
Place the command text inside the CDATA element to prevent any special
characters from being interpreted as XML codes.
d
In the Insert Context/Configuration Element dialog box, click to open the
Context Browser.
The top part of the Context Browser dialog box contains global context items,
and the bottom part contains local context items (that is, context items that are
specific to the workflow on the design canvas). The Context Browser dialog
box contains the local context items that you defined in the Start activity
adapter name, directory command, and directory nameas shown in Figure
18 on page 45.
Figure 18: Local context items
e In the Local Context area of the Context Browser, click directory command,
and then click Select.
f In the Insert Context/Configuration Element dialog box, click OK.
The Properties tab is redisplayed, showing the syntax for the input parameter
for the assign statement, including the directory command context item, as
shown in Figure 19 on page 46.
Figure 19: Input parameter with one context item
g Type a space after the context item, and then repeat steps d through f to add
the directory name context item.
The Properties tab is redisplayed, showing the syntax for the input parameter for
the assign statement, including the context items.
3 On the Properties tab, enter information for the output context item for the assign
statement:
a In the Context Type box, select Context Item.
b
Click to open the Context Browser.
c In the Context Browser, click New.
d In the Context Name field of the Create Context Data dialog box, type adapter
request, and then click OK.
e In the Local Context area, click adapter request and click Select.
The Properties tab of the Property Panel for the assign statement is redisplayed as
shown in Figure 20 on page 47. The output context name is adapter request.
Figure 20: Input and output parameters
4 On the Properties tab of the Property Panel for the assign statement, click OK.
The Properties tab of the Property Panel for the Assign activity is redisplayed as
shown in Figure 21 on page 47. It shows that one assign statement has been created.
Figure 21: Information about the adapter request assign statement
To finish creating the first Assign activity
1 On the Property Panel for the Assign activity, click OK to return to the design
canvas.
2
Click to save the workflow.
Creating and configuring the Call Adapter
activity
This task tells how to define the Call Adapter activity to call the Command Line
adapter to issue a command. The Call Adapter activity uses the adapter request
context item from the previous task.
In the preceding tasks, you created a module and a workflow, configured the Start
activity, and created an Assign activity with an assign statement. At the end of those
tasks, the design canvas had Start, Assign, and End activities, connected in sequence
by the gray process line, as shown in the following figure:
Figure 22: Design canvas with Start, Assign, and End activities
In this task, you create a Call Adapter activity and set the activity to log the results.
To create and configure the Call Adapter activity
1 Click the Activity Palette to open it, and drag a Call Adapter activity to the design
canvas.
2 Connect the Call Adapter activity to the workflow between the Assign activity
and the End activity with the gray process line, as shown in the following figure:
Figure 23: Design canvas with Assign activity and Call Adapter activity added to
the workflow
3 Double-click the Call Adapter activity to open its Property Panel.
Creating and configuring the Call Adapter activity
4 On the Properties tab of the Property Panel for the Call Adapter activity, select
Context Key for Adapter Name.
5
6 In the Local Context area, click adapter name and click Select.
7 On the Properties tab of the Property Panel for the Call Adapter activity, select
Context item for Adapter Input.
8
9 In the Local Context area, click adapter request and click Select.
10
On the Properties tab of the Property Panel for the Call Adapter activity, click
next to Adapter Output to open the Context Browser.
11 In the Context Browser, click New.
12 In the Create Context Data dialog box, type adapter response in the Name field
and click OK.
13 In the Local Context area, click adapter response and click Select.
14 On the Properties tab of the Property Panel for the Call Adapter activity, click OK
to return to the design canvas.
15 Save the workflow.
To configure logging for the Call Adapter activity
1 On the design canvas, double-click the Call Adapter activity to reopen its
Property Panel.
2 On the Property Panel, click the Logging tab, and then click the Before Execution
tab.
3 On the Before Execution tab, select the Log check box and type Before execution
in the text field.
Creating and configuring the Call Adapter activity
4 Right-click the Context Item text field, and from the Insert menu, select Local
Context Item => adapter request as shown in Figure 24 on page 50.
Figure 24: Inserting a context item in the log
The Before Execution tab shows the adapter request context item in the Context
Item text box. When you run the workflow, the text that you entered and the
contents of the context item that you selected are added to the log before the
workflow runs the Call Adapter activity.
5 On the Logging tab, click the After Execution tab.
6 On the After Execution tab, select the Log check box and type After execution in
the text field.
7 Repeat step 4 to select the adapter response context item.
8 Click OK to return to the design canvas.
Testing the workflow and gathering sample
data
In this task, you verify the tasks that you have performed so far and save the results
of the test as sample data to use in the next task, creating a second Assign activity.
Testing the workflow and gathering sample data
Before you begin
To test the workflow, you must know the name that was assigned to the ro-adapter-
command-line adapter when it was configured on the grid. If you do not know the
name, you can use the Grid Manager Manage => Adapters tab to find the name.
Note
Adapter names are case-sensitive. Ensure that you know the exact name that was
used when the adapter was configured.
To test the workflow
1
In the toolbar below the menu bar, click ExecuteProcessAction .
Development Studio uses the peers and adapters on the grid to test the process.
3.
or SOAP; and then click OK.
4 In the Job Input Parameters dialog box, double-click in the Value field for the
adapter name parameter and type the name that was assigned to the ro-adapter-
command-line adapter when it was configured on the grid.
5 Double-click in the Value field for the directory command parameter, and type
the appropriate command for your operating system.
For this example, type dir in the Value field.
6 Double-click in the Value field for the directory name parameter, and type the
name of the directory that you want to list.
For this example, type c:\ , as shown in Figure 25 on page 52.
Figure 25: Example input parameters for testing the workflow
7 Click OK.
BMC Atrium Orchestrator Development Studio runs the List directory workflow.
The console window is opened below the design canvas, and the Process Log tab
displays the results of the execution. These are the same results that are posted to
the processes.log file when the workflow is run on the grid. On the design
canvas, the Assign activity and the Call Adapter activity have brown boxes
around them to indicate that they have been executed.
This message indicates that the process that you created ran to completion.
Note
Do not clear or close the console window.
9 (optional) Review the contents of the console window.
This is the information that would have been written to the log file if the
workflow had been run on the grid.
The adapter request that was sent to the adapter on the grid is shown
immediately after "Before Execution".
The response from the adapter is shown immediately after "After Execution".
To gather sample data for the second Assign activity
1 Open a text editor and create a blank document.
2 Copy the entire contents of the console window's Process Log tab and paste it in
the blank document.
3 Save the document as process_sample.txt.
4 (optional) Review the contents of the process_sample.txt file.
5 (optional) If you ran the workflow on a Windows computer, in the
process_sample.txt file, change every instance of <DIR> to <DIR>
The transform editor that you use when creating the second Assign activity
would treat <DIR> as badly formed XML. This step replaces it with equivalent
valid XML.
6 Save the process_sample.txt file.
7 In the console window, click Clear and then click Close.
Creating and configuring the second Assign
activity
In this task, you create the second Assign activity and configure it to transform the
context items gathered by the Call Adapter activity to pass them to the End activity.
In the preceding tasks, you created a module and a process, configured the Start
activity, and created and configured an Assign activity and a Call Adapter activity.
At the end of those tasks, the design canvas had Start, Assign, Call Adapter, and End
Creating and configuring the second Assign activity
activities, connected in sequence by the gray process line as shown in the following
figure. You tested the process and saved the results to a text file.
Figure 26: Design canvas with an Assign activity and a Call Adapter activity
In this task, you create another Assign activity with three assign statements. Each
statement uses the same context item, adapter response, as the input parameter, but
generates different output parameters. The output parameters are context items
containing the directory listing generated by the command, the status of the
command, and any error messages generated by the command.
To create the second Assign activity
1 Click the Activity Palette to open it, and drag an Assign activity to the design
canvas.
2 Connect the Assign activity to the process with the gray process line, placing the
Assign activity after the Call Adapter activity and before the End activity, as
Figure 27: Design canvas with two Assign activities and a Call Adapter activity
3 Double-click the new Assign activity to open its Property Panel.
To create the first assign statement
1
2 On the Properties tab for the assign statement, select Context item as the input
parameter type, and use the Context Browser to select the adapter response
context item:
a
b In the Local Context area of the Context Browser, click adapter response, and
then click Select.
c In the Insert Context/Configuration Element dialog box, click OK.
3 On the Properties tab on the Property Panel for the Assign statement, click Basic
to open the Basic transform editor.
4 Use the Basic transform editor to extract the directory list information from the
adapter response:
a
Click to open a sample from the resource area.
The Select Resource dialog box is displayed.
b
Highlight the My Samples folder and click to create a new sample.
c In the File Name field of the Input dialog box, type sample directory listing,
and then click OK.
In the bottom pane of the Select Resource dialog box, <value/> is displayed.
d Use a text editor to open the process_sample.txt file.
e From the process_sample.txt file, copy the adapter response.
The adapter response is enclosed in square brackets and identified by adapter
response=. The response begins following the equal sign. Copy from <command-
result> to </command-result>, including all of the angle brackets. Do not
include the square bracket at the end.
f In the bottom pane of the Select Resource dialog box, delete the <value/> text
and paste the adapter response text that you copied from the
process_sample.txt file.
g
Click , and then click OK.
The Select Resource dialog box closes and the Basic Transform Editor displays
the adapter response text in the left pane.
h In the Basic transform editor, in the Function field, select XML => Element
name matches.
i In the first Operand field, type line.
j In the upper-right corner of the Basic transform editor, click Generate Preview
.
The Preview pane displays the directory listing, as shown in Figure 28 on page
56.
Figure 28: Basic transform editor with preview
k Click OK to close the Basic transform editor.
The Transform field on the Properties tab for the assign statement displays
Get all elements named "line."
5 On the Properties tab, for Output Context Type, select Context item.
6 Use the Context Browser to create a new context item called directory list:
a
b In the Context Browser, click New.
c In the Context Name field of the Create Context Data dialog box, type
directory list, and then click OK.
d In the Local Context area, highlight directory list and click Select.
7 On the Properties tab on the Property Panel for the assign statement, click OK.
The Properties tab on the Property Panel for the assign statement closes, and the
Properties tab on the Property Panel for the Assign activity is redisplayed with
the information about the input and output parameters of the first assign
statement for this Assign activity.
8 Save the process.
To create the second assign statement
1
parameter type, and use the Context Browser to select the adapter response
context item:
a
b In the Local Context area, click adapter response, and then click Select.
3 Use the Advanced transform editor to extract the status from the adapter
response:
a On the Properties tab on the Property Panel for the assign statement, select
Advanced from the Transform list.
b In the Transform Editor Setup Wizard, select XPath, and click Next.
c In the Sample Source pane, expand the My Samples directory, and select
sample directory listing.
d Click Finish to close the wizard and display the XPath transform editor.
e (optional) If the Document section is not visible, resize the XPath transform
editor window from the bottom to make it larger.
f In the text field of the Document section, type //command-output/metadata/
status and click Generate Preview .
Note
XPath expressions are sensitive to extraneous spaces in the expression. Ensure
that there are no spaces when you type the XPath expressions.
g Verify that the Preview Drawer contains <result><status>success</
status></result> .
If the Format XML check box is selected, the XML is displayed in a multiline
format.
h In the Document section, change the content of the text field to //command-
output/metadata/status/text( ) and click Generate Preview .
i Verify that the Preview Drawer contains <result> success </result> .
j Click Save and Exit to save the transform and close the Advanced transform
editor.
On the Properties tab, the Transform text area displays the transform that you
created.
4 On the Properties tab, select Context item for Output Context Type.
5 Use the Context Browser to create a new context item called status:
a
c In the Context Name field of the Create Context Data dialog box, type status,
and then click OK.
d In the Local Context area, click status and click Select.
6 On the Properties tab on the Property Panel for the assign statement, click OK.
The Properties tab on the Property Panel for the assign statement closes, and the
Properties tab on the Property Panel for the Assign activity displays information
about the input and output parameters of the first and second assign statements
for this Assign activity.
To create the third assign statement
1
2 On the Properties tab on the Property Panel for the assign statement, select
Context item as the input parameter type, and use the Context Browser to select
the adapter response context item.
The details for this step are the same as for step 2 of the preceding procedure, "To
create the second assign statement."
3 Use the Advanced transform editor to extract any errors from the adapter
response:
a On the Properties tab on the Property Panel for the assign statement, select
Advanced from the Transform list.
b In the Transform Editor Setup Wizard, select XPath, and click Next.
c In the Sample Source pane, expand the My Samples directory, and select
sample directory listing.
d Click Finish to close the wizard and display the XPath transform editor.
e (optional) If the Document section is not visible, resize the XPath transform
editor window to make it larger.
f In the text field of the Document section, type //command-output/metadata/
error and click Generate Preview .
The Preview Drawer contains only <result/> because there are no errors in
the sample directory listing.
g In the Document section, edit the content of the text field to //command-output/
metadata/error/text( ) and click Generate Preview .
The Preview Drawer contains only <result/> because there are no errors in
the sample directory listing.
h Click Save and Exit to save the transform and close the Advanced transform
editor.
On the Properties tab, the Transform text area displays the transform that you
created.
4 On the Properties tab, select Context item for Output Context Type.
5 Use the Context Browser to create a new context item called error.
The details for this step are the same as for step 5 of the preceding procedure, "To
create the second assign statement," substituting error for status.
The Property Panel for the Assign activity displays a row for each assign
statement that you created, as shown in Figure 29 on page 60.
Figure 29: Assign statements for the second Assign activity
7 On the Properties tab of the Property Panel for the Assign activity, click OK to
return to the design canvas.
8
To configure logging for the Assign activity
1 On the design canvas, double-click the second Assign activity.
2 On the Property Panel for the Assign activity, click the Logging tab and then click
the After Execution tab.
3 Select the Log check box, and type After output parsing in the text field.
4 Right-click in the Context Item text field, and from the Insert window, select
Local Context Item => status.
The After Execution tab shows the status context item in the Context Item text field.
5 Repeat step 4 to insert the error and directory list context items.
The Context Item field on the Logging => After Execution tab of the Property
Panel for the Assign activity shows the context items that you selected, as shown
in Figure 30 on page 61.
Figure 30: After Execution tab showing three context items
7
Configuring the End activity
In this task, you configure the End activity to log the results of the workflow and to
use the context items to show the directory listing.
In the preceding tasks, you created a module and a process, configured the Start
activity, and created and configured two Assign activities and a Call Adapter
activity. The process now appears as shown in the following figure:
Figure 31: Design canvas with two Assign activities and a Call Adapter activity
Configuring the End activity
Just as you configured the Start activity to receive the inputs required to perform the
List directory process, you configure the End activity to produce the results of the
List directory process.
To configure the End activity
1 On the design canvas, double-click the End activity.
2
On the Properties tab of the Property Panel for the End activity, click .
3 In the Context Browser-Select Multiple dialog box, press the Ctrl key and select
adapter response, directory list, error, and status, and then click Select.
4 On the Properties tab of the Property Panel for the End activity, use the blue
arrows to change the order of the context items to the order shown in Figure 32 on
page 62. Ensure each context item's Required check box is clear.
Figure 32: Output parameters of the End activity of the List Directory process
If the context items are marked as required and they are not created during the
workflow, then the workflow compensates instead of running to completion.
Best practice
Never mark context items in the End activity as required.
6 Save the process.
Testing the workflow
In this task, you verify all tasks that you have completed and verify that the
workflow produces the expected results.
Before you begin
Note
1
or SOAP, and then click OK.
adapter name parameter and type the name that was assigned to the ro-adapter-
Note
If you have not closed the workflow since you ran the previous test, the Value
fields might already be populated with the input values.
4 Double-click in the Value field for the directory command parameter, and type
the appropriate command for your operating system.
For this example, type dir in the Value field.
5 Double-click in the Value field for the directory name parameter, and type the
name of the directory that you want to list.
For this example, type c:\ .
6 Click OK.
BMC Atrium Orchestrator Development Studio runs the List directory workflow.
The console window opens below the design canvas, and the Process Log tab
displays the results of the execution. These are the same results that are posted to
the processes.log file when the workflow is run on the grid. On the design
canvas, the Assign activities and the Call Adapter activity have brown boxes
around them to indicate that they have been executed.
7 Review the contents of the console window and verify that the last line in the
console window is The process terminated in the completed state.
8 (optional) Repeat steps 1 to 6 using an invalid directory name. Verify that the last
line in the console window is The process terminated in the completed
state.
However, error messages regarding the invalid directory are displayed as shown
in the following sample:
After output parsing
[status=error]
[error=Exit code indicates error]
[directory list=
<result>
<line index="1">The system cannot find the path specified.</line>
</result>]
INFO - [Current Time=Thu Jul 29 14:29:04 CDT 2010] [Process
Name=:Samples:List directory] [Root Job Id=a43aa4c65dd03689:4ec77ace:
12a1f409a1d:-80001-1280431744093] [Job Id=a43aa4c65dd03689:4ec77ace:
12a1f409a1d:-80001-1280431744093]
The process terminated in the completed state.
9 (optional) Repeat steps 1 to 6 using a misspelled adapter name. Verify that the last
line in the console window is The process terminated in the compensated
state.
This message indicates that the process that you created could not run to
completion as shown in the following sample:
ERROR - [Current Time=Thu Jul 29 14:31:28 CDT 2010] [Process
12a1f409a1d:-80001-1280431888363]
An error occurred that triggered compensation:
Summary: Execution failed.
Caused by:
Summary: no peer with a running instance of commandLineadapter found
12a1f409a1d:-80001-1280431888363]
Stack Trace:
procdef:Samples:List directory:start:call-adapter[1]
12a1f409a1d:-80001-1280431888363]
The process terminated in the compensated state.
11 Click File => Exit to close BMC Atrium Orchestrator Development Studio.
Creating the configuration items
When you use configuration items in workflows, they act as constants for processes
on a grid. Two workflows that you will create later in this chapter, the Copy File
workflow and the Copy Files in Directory workflow, will use configuration items for
the adapter name, the directory command, and the copy command. This task creates
the configuration items that will be used in the subsequent workflows.
To create the configuration items
1 In the Project Navigator, expand the module in which you want to create the
configuration item and double-click Configuration.
2 In the Module Configuration pane, click Add Module Configuration Group
.
A new configuration group named NewContainer1 is added in the Module
Configuration pane, and the Name field in the Group Name pane displays
NewContainer1.
3 In the Name field, type Samples and then click Save.
4 In the Module Configuration pane, select the Samples configuration group that
you just created.
5
Click Add Module Configuration Item at the top of the Module
Configuration pane.
A new configuration item named NewValueNode1 is added in the Module
Configuration pane, and the Name field in the Item Details pane displays
NewContainer1.
6 Enter the following information in the Item Details pane, and then click Save.
Field Description
Name Enter CMD_Adapter.
Type Select Static Value.
Value Enter the name of the Command Line adapter configured on your grid (for
example, commandLineAdapter).
The configuration item and value are displayed below the selected group as
Figure 33: Module Configuration and Item Details panes
7 Repeat steps 4 through 6 to create a configuration item for the directory command
with the following details:
Field Description
Name Enter DirectoryCommand.
Value Enter dir.
8 Repeat steps 4 through 6 to create a configuration item for the copy command
with the following details:
Field Description
Name Enter CopyCommand.
Value Enter copy.
You have created the three configuration items as shown in Figure 34 on page
67.
Figure 34: Module Configuration pane
Importing utilities modules
The utilities modules are prepackaged workflows that perform common activities.
They can help you to create workflows. In this task you import the AutoPilot-OA-
Common-Utilities and the AutoPilot-AD-Utilities modules. You will use these
modules in subsequent workflows.
Before you begin
The AutoPilot-OA-Common-Utilities and the AutoPilot-AD-Utilities modules must
have been installed into the repository.
To import the AutoPilot-OA-Common-Utilities and the AutoPilot-AD-Utilities
modules
1 Click Library Manager.
2 On the Import Modules tab, click From Repository.
Importing utilities modules
3 In the Import Modules table, select the Import and the Unbundle check boxes
next to the AutoPilot-OA-Common-Utilities and the AutoPilot-AD-Utilities
modules as shown in the following figure:
Figure 35: Import Modules tab in the Library Manager
4 (optional) To select a specific version or revision of the module, click the version
number or revision number and select the number of the version that you want.
5 Click Import to import and unbundle the modules.
Creating the connection details concept
When you create the Copy File workflow, you will use the Invoke Command utility
to execute the copy command. The Invoke Command utility requires that the
information to execute the command be contained in a concept called connection
details. A concept is a context item containing multiple values. In this task, you create
a workflow to generate the connection details concept required by the Invoke
Command utility.
The connection details concept specifies the adapter to execute the command and
contains the information to enable the adapter to communicate with the target
computer.
In this task, you will create a workflow, configure input parameters for the
workflow, assign the input parameters to the connection details concept, and assign
the connection details concept to an output parameter.
Before you begin
The AutoPilot-OA-Common-Utilities must have been imported into the BMC
Atrium Orchestrator Development Studio workspace and unbundled, and must be
active on the grid. For information on activating a module on the grid, see BMC
Atrium Orchestrator System Administration Guide.
To create the workflow
1 In the Project Navigator tree, right-click Samples and select New Process.
2 In the Create New Process dialog box, type Make connection details for Invoke
Command in the Process Name field, ensure that none of the Expose Process
options are selected, and then click OK.
This workflow will be used only from within other workflows, so there is no
reason to expose it to users.
design canvas displays the new workflow. If the List directory workflow is still
open, the Make connection details for Invoke Command workflow is on a tab
separate from it.
To configure the input parameters
2 In the Input Parameter Name field on the Properties tab of the Property Panel for
the Start activity, type adapter.
3 Press Tab and verify that the name in the corresponding Context Name field is
the same as in the Input Parameter Name field and that the Required check box
is selected.
4 In the Input Parameter Name field on the next row, type working dir.
5 Press Tab and verify that the name in the corresponding Context Name field is
the same as in the Input Parameter Name field.
6 Clear the Required check box.
7 Repeat steps 4 to 6 to create the following input parameters, as shown in the
following figure:
command dir
command encryption type
timeout
Figure 36: Input parameters for the Start activity
Note
Only the adapter input parameter is required.
8 Click OK.
To create the connection details concept
1 Click the Activity Palette to open it, and drag an Assign activity to the process
canvas and connect it to the workflow.
2 (optional) Click the activity's Assign label, delete it, and type Make connection
details.
Tip
You can provide descriptive labels for any activity on the process canvas.
3 Double-click the Assign activity.
4
5 Select Context item as the input parameter type.
6
7 In the Context Browser, select the adapter context item.
8 In the output parameter section, use the Context Browser to create a new context
item called connection details:
a
c In the Context Name field of the Create Context Data dialog box, type
connection details, and then click OK.
d In the Local Context area, ensure that connection details is highlighted and
click Select.
9 Select the Concept check box.
10 In the Concept types field (to the right of the output parameter information), click
to expand the AutoPilot-OA-Common-Utilities:ConnectionDetails concept.
Note
If AutoPilot-OA-Common-Utilities has not been imported into the BMC Atrium
Orchestrator Development Studio workspace and unbundled, it will not be
available in the Concept types field.
11 Select adapter-name as shown in Figure 37 on page 71.
Figure 37: Properties tab for the first assign statement
12 (optional) In the Description field, type adapter-name.
Best practice
If you repeat the element name in the description field, you can see which
parameter maps to which element without opening each assign statement.
13 Click OK.
The first assign statement is complete, and the adapter context item has been
assigned as an element in the connection details concept, as shown in Figure 38
on page 72.
Figure 38: First assign statement
14 Repeat step 3 through step 13, except for step 8, to create the following elements
in the connection details concept.
Instead of repeating step 8, select the connection details as the output context name.
Input context item Concept element
working dir working-dir
command dir command-dir
command encryption type command-encryption-type
timeout timeout
15
16 Select String as the input parameter type, and type command-line in the text
field.
17 In the output parameter section, select the connection details concept as the
output context name, and select Concept.
18 Select the invocation-mechanism element in the AutoPilot-OA-Common-
Utilities:ConnectionDetails concept.
19 (optional) In the Description field, type invocation-mechanism.
20 Click OK to return to the Properties tab for the Assign activity.
The Assign activity creates the elements for the connection details concept, as
Figure 39: Assign statements for the Assign activity
21 Configure logging for the Assign activity:
a On the Property Panel, select the Logging tab, and then the After Execution
tab.
b Select the Log check box and type After execution in the Log text entry field.
c Right-click in the Context Item field, and select Local Context Item =>
connection details.
22 Click OK to close the Property Panel for the Assign activity.
To configure the output parameters
1 On the process canvas, double-click the End activity.
2 On the Properties tab of the Property Panel for the End activity, double-click in
the Context Name field.
3 In the Context Browser, click connection details, and click Select.
4 On the Properties tab of the Property Panel for the End activity, ensure that the
context item is not marked as required.
5 Click OK to return to the process canvas.
Testing the Make connection details for
Invoke Command workflow
In this task, you verify that the workflow creates a connection details concept.
Before you begin
Note
1
Development Studio uses the peers and adapters on the grid to test the workflow.
2 If you have not already logged on to the grid, log on; otherwise, proceed to step 3.
adapter parameter and type the name that was assigned to the ro-adapter-
For this test, you do not need to provide values for any of the other input parameters.
5 Click OK.
BMC Atrium Orchestrator Development Studio runs the Make connection details
for Invoke Command workflow. The console window opens below the design
canvas, and the Process Log tab displays the results of the workflow execution.
These are the same results that are posted to the processes.log file when the
workflow is run on the grid. On the design canvas, the Make connection details
Assign activity has a brown box around it to indicate that it has been executed.
Testing the Make connection details for Invoke Command workflow
This message indicates that the workflow that you created ran to completion.
Note
The connection details concept is shown immediately after "After Execution".
To gather sample data
2 From the console window, copy the XML definition of the ConnectionDetails and
paste it in the blank document.
The ConnectionDetails definition begins after the following text:
After execution [connection details=
An example definition is as follows:
<ConnectionDetails xmlns="AutoPilot-OA-Common_Utilities">
<adapter-name xmlns="">commandLineAdapter</adapter-name>
<invocation-mechanism xmlns="">command-line</invocation-mechanism>
<hostname xmlns="" />
<port xmlns="" />
<username xmlns="" />
<password xmlns="" />
<password-encryption-type xmlns="" />
<target xmlns="" />
<prompt xmlns="" />
<login-prompt xmlns="" />
<password-prompt xmlns="" />
<working-dir xmlns=""></working-dir>
<command-dir xmlns=""></command-dir>
<command-encryption-type xmlns=""></command-encryption-type>
<timeout xmlns=""></timeout>
<connection-name xmlns="" />
<terminate-connection xmlns="" />
<known-hosts-config xmlns="" />
<allow-unknown-hosts xmlns="" />
<preferred-pk-algorithm xmlns="" />
</ConnectionDetails>
Testing the Make connection details for Invoke Command workflow
Tip
When copying the definition, do not copy the square bracket ( ] ) that follows it in
the console window.
3 Save the document as Conn_Details.txt.
Creating the Copy File workflow
In this task, you create the Copy File workflow, which copies a specified file to a
target directory. Instead of the Command Line adapter, you use one of the
Operations Actions Management modules' utilities to perform the action.
You will use the Copy File workflow with the Directory list workflow in the top-
level workflow, Copy Files in Directory.
In this task, you:
Create a workflow
Configure input parameters for the workflow
Create the copy command
Invoke the copy command
Assign the results of the command to context items
Log the context items
Configure the output parameters
Before you begin
The AutoPilot-OA-Common-Utilities and the AutoPilot-AD-Utilities must have been
imported into the BMC Atrium Orchestrator Development Studio workspace and
unbundled, and must be active on the grid.
To create the Copy File workflow
2 In the Create New Process dialog box, type Copy File in the Process Name field,
ensure that the Expose Process options In Schedules and In Rules are not
selected, and then click OK.
design canvas displays the new workflow.
To configure the input parameters
2 In the Input Parameter Name field on the Properties tab of the Property Panel for
the Start activity, type connection details.
3 Press Tab and verify that the name in the Context Name field is the same as in the
Input Parameter Name field and that the Required check box is selected.
4 Repeat steps 2 and 3 to create the following required input parameters:
source file
destination directory
5 Click OK.
To create the copy command
1 Click the Activity Palette to open it, and drag an Assign activity to the process
canvas and connect it to the workflow.
2 (optional) Click the activity's Assign label, delete it, and type Create copy
command.
4
5 Select String as the input parameter type.
6 Right-click in the text entry field and select Module Configuration =>
Samples:Samples:CopyCommand (one of the configuration items that you
created in a previous task).
BMC Atrium Orchestrator Development Studio inserts the configuration item in
the text entry field as shown in the following figure:
Figure 40: Text entry field showing the configuration item
7 Type a space in the text entry field immediately to the right of the configuration
item, and then right-click after the space and select Local Context Item =>
source file.
BMC Atrium Orchestrator Development Studio inserts the context item in the text
entry field.
8 Type a space in the text entry field immediately to the right of the context item,
and then right-click after the space and select Local Context Item => destination
directory.
BMC Atrium Orchestrator Development Studio inserts the context item in the text
entry field, as shown in Figure 35 on page 68.
Figure 41: Text entry field showing the configuration item and context items
9 On the Properties tab, enter information for the output context item for the assign
statement:
a In the Context Type box, select Context Item.
b
c In the Context Browser, click New.
d In the Context Name field of the Create Context Data dialog box, type
command, and then click OK.
e In the Local Context area, click command and click Select.
The Properties tab of the Property Panel for the assign statement is redisplayed.
The output context name is command.
The Properties tab of the Property Panel for the Assign activity shows that one
assign statement has been created, as shown in the following figure:
Figure 42: Information about the assign statement
11 Click OK to exit the Property Panel.
To invoke the command
1 In the Project Navigator, expand the AutoPilot-OA-Common-Utilities module.
2 Drag the Invoke Command workflow from the AutoPilot-OA-Common-Utilities
module to the process canvas and place it after the Create copy command Assign
activity.
3 Connect the Invoke Command workflow to the Copy File workflow.
BMC Atrium Orchestrator Development Studio briefly displays a message that
two of three inputs have been auto-mapped.
4 Double-click the Invoke Command Call Process activity and review the Property
Panel, shown in Figure 43 on page 80.
Figure 43: Property Panel for the Invoke Command Call Process activity
BMC Atrium Orchestrator Development Studio automatically maps the existing
context connection details and command to the required input parameters with
the same names for the Invoke Command workflow. The program also creates
output context items for the Call Process activity that match the output
parameters for the Invoke Command workflow.
5 Click OK to close the Property Panel.
6 Save the Copy File workflow.
To test the Copy File workflow and gather sample data
1
3.
4 In the Job Input Parameters dialog box, select XML as the type for the connection
details parameter.
5 From the Conn_Details.txt file that you created in a previous task, copy the
connection details definition.
connection details parameter.
7 In the Enter XML Data dialog box, paste the connection details definition, and
then click OK.
8 In the Job Input Parameters dialog box, select String as the type for the source file
parameter.
source file parameter and type the fully qualified path and name of a file that you
want to copy.
This file must exist on the peer where the Command Line adapter is enabled.
10 In the Job Input Parameters dialog box, select String as the type for the
destination directory parameter.
destination directory parameter and type the fully qualified path to the directory
into which you want to copy the file.
This directory must exist on the peer where the Command Line adapter is enabled.
After step 11, the Job Input Parameters dialog box appears as shown in Figure 44
on page 81.
Figure 44: Job Input Parameters dialog box
12 Click OK.
BMC Atrium Orchestrator Development Studio runs the Copy File workflow.
The console window opens below the process canvas, and the Process Log tab
displays the results of the workflow execution. These are the same results that are
posted to the processes.log file when the workflow is run on the grid. On the
process canvas, the Create copy command and Invoke Command activities have
brown boxes around them to indicate that they have been executed.
Note
15 In the console window, find the adapter response.
The adapter response starts with [adapter response= and ends with ]. For this
adapter, the entire adapter response is the command result.
16 From the adapter response, copy the command result and paste it in an empty
text document.
The command result begins with <command-result> and ends with </command-
result>. Do not copy the square bracket at the end.
17 Save the text file as Sample_Command_Result.txt.
To save the results of the Invoke Command activity
Use this task to create context items that contain status and error information
extracted from the adapter response from the Invoke Command activity.
1 Drag an Assign activity to the process canvas after the Invoke Command activity
and connect it to the workflow.
3
4 On the Properties tab of the Property Panel for the assign statement, select
the adapter response context item:
a
b In the Local Context area of the Context Browser, click adapter response, and
then click Select.
5 On the Properties tab on the Property Panel for the assign statement, click Basic
6 Use the Basic transform editor to extract the status information from the adapter
response:
a
b
c In the File Name field of the Input dialog box, type sample command result,
and then click OK.
d Use a text editor to open the Sample_Command_Result.txt file.
e From the Sample_Command_Result.txt file, copy the command result.
Copy from <command-result> to </command-result>, including all of the
angle brackets.
and paste the command result text that you copied from the
Sample_Command_Result.txt file.
g
The Select Resource dialog box closes and the Basic Transform Editor displays
the command result text in the left pane.
h In the Basic transform editor, in the Function field, select XML => Element
name matches.
i In the first Operand field, type command-output/metadata/status.
j In the upper-right corner of the Basic transform editor, click Generate Preview
.
The Preview pane displays <result><status>success</status></result>.
k
In the Basic transform editor, in the Function sequence area, click to add a
new function.
l In the Basic transform editor, in the Function field, select XML => XML to
Text.
m In the upper-right corner of the Basic transform editor, click Generate Preview
.
The Preview pane displays success.
n Click OK to close the Basic transform editor.
The Transform field on the Properties tab on the Property Panel for the assign
statement displays a description of the functions that you selected.
8 Use the Context Browser to create a new context item called status:
a
c In the Context Name field of the Create Context Data dialog box, type status,
and then click OK.
d In the Local Context area, highlight status and click Select.
9 Click OK to close the Properties tab for this assign statement.
10
On the Properties tab for the Assign activity, click to add a new assign
statement.
11 On the Properties tab of the Property Panel for the assign statement, select
the adapter response context item.
12 On the Properties tab on the Property Panel for the assign statement, click Basic
13 Use the Basic transform editor to extract the error information from the adapter
response:
a (optional) If the Basic transform editor does not display the sample command
result in the Test Value pane, click to open a sample from the resource
area; otherwise skip to step c.
b (optional) Select sample command result from My Samples. Then click OK.
c In the Basic transform editor, in the Function field, select XML => Element
name matches.
d In the first Operand field, type command-output/metadata/error.
e In the upper-right corner of the Basic transform editor, click Generate Preview
.
Because there are no errors to display, the Preview pane displays <result/>.
f
In the Basic transform editor, in the Function sequence area, click to add a
new function.
g In the Basic transform editor, in the Function field, select XML => XML to
Text.
h Click OK to close the Basic transform editor.
The Transform field on the Properties tab on the Property Panel for the assign
statement displays a description of the functions that you selected.
15 Use the Context Browser to create a new context item called error.
16 Click OK to close the Properties tab for this assign statement.
17 Click OK to close the Property Panel for the Assign activity.
To log the results of the Assign activity
1 On the design canvas, double-click the second Assign activity.
2 On the Property Panel for the Assign activity, click the Logging tab and then click
3 Select the Log check box, and type After File Copy in the text field.
4 Right-click in the Context Item text field, and from the Insert window, select
Local Context Item => status.
The After Execution tab shows the status context item in the Context Item text field.
5 Repeat step 4 to insert the error context item.
The Context Item field on the Logging => After Execution tab of the Property
Panel for the Assign activity shows the context items that you selected, as shown
in the following figure:
Figure 45: Logging After Execution tab showing status and error context items
6 Click OK to return to the process canvas.
7
To configure the output parameters
1 On the design canvas, double-click the End activity.
2
On the Properties tab of the Property Panel for the End activity, click .
3 In the Context Browser-Select Multiple dialog box, press the Ctrl key and select
adapter response, error, and status. Click Select.
4 On the Properties tab of the Property Panel for the End activity, use the blue
arrows to change the order of the context items to the order shown in the
following figure. Ensure that each context item's Required check box is cleared.
Figure 46: Output parameters of the End activity of the Copy File workflow
Figure 47 on page 87 shows the process canvas view of the finished Copy File
workflow.
Figure 47: Completed Copy File workflow
Creating the Copy Files in Directory workflow
This task creates the top-level workflow, called Copy Files in Directory, in the same
module as the List directory, Copy File, and Make connection details for Invoke
Command workflows. It contains the other workflows that you created in the tasks
in this chapter.
In this task, you:
Create a workflow
Configure input parameters for the workflow
Add the Make Connections Details for Invoke Command workflow
Add the List directory workflow
Test the Copy Files in Directory workflow
Gather sample data from the test results
Add a For activity
Add an Assign activity
Add the Copy File workflow
Before you begin
To create and use this workflow, you must have completed all the previous tasks in
this chapter. The following workflows must already exist:
List directory
Make connection details for Invoke Command
Copy File
The following module configuration items must exist:
CMD_Adapter
DirectoryCommand
CopyCommand
To create the Copy Files in Directory workflow
2 In the Create New Process dialog box, perform the following actions:
a Type Copy Files in Directory in the Process Name field.
b Ensure that the Expose Process option In Schedules is selected.
c Type a description in the Description field.
For example, type This workflow reads a specified directory and runs the
copy command on each file found in the directory.
3 Click OK.
design canvas displays the new workflow with only the Start and End activities.
The Copy Files in Directory workflow is displayed on a new tab, and any other
open workflows are on different tabs.
To configure the Start activity
1 Double-click the Start activity on the design canvas.
2 On the Properties tab of the Property Panel for the Start activity, create the first
input parameter:
a In the Input Parameter Name field, type source dir.
b Press Tab and verify that the name in the corresponding Context Name field is
the same as in the Input Parameter Name field and that the Required check
box is selected.
3 Repeat step 2 to create the second input parameter, typing destination directory
in the Input Parameter Name field, as shown in the following figure:
Figure 48: Input parameters for Start activity
4 Click OK to close the Property Panel for the Start activity and return to the design
canvas.
5
To add the Make connections details for Invoke Command workflow
1 Drag the Make connections details for Invoke Command workflow to the process
canvas and connect it to the Start and End activities.
2 Double-click the Call Process activity to open the Property Panel for the Call
Process activity for the Make connections details for Invoke Command workflow.
BMC Atrium Orchestrator Development Studio created the output mappings
automatically.
3 In the Call process input mapping section of the Property Panel, double-click in
the Input Name/Value field that corresponds to the adapter output context item.
The Properties tab for that input is displayed.
4 On the Properties tab, for Input Parameter type, select Module Configuration.
5 Expand the configuration group, expand the Samples module, and expand the
Samples group.
6 Select CMD_Adapter from the Samples group, as shown in Figure 49 on page
90; then click OK.
Figure 49: Properties tab showing selected module configuration item
7 Click OK to close the Properties tab and display the Property Panel for the Call
Process activity, as shown in Figure 50 on page 91.
Figure 50: Property Panel for the Call Process activity
8 Click OK to close the Property Panel and return to the process canvas.
To add the List directory workflow
1 Drag the List directory workflow to the process canvas and connect it to the
workflow between the Make connections details for Invoke Command workflow
and the End activity.
2 Save the Copy Files in Directory workflow.
3 Double-click the Call Process activity to open the Property Panel for the Call
Process activity for the List directory workflow.
BMC Atrium Orchestrator Development Studio created the output mappings
automatically.
the Input Name/Value field that corresponds to the adapter name context item.
The Properties tab for that input is displayed.
5 On the Properties tab, select Module Configuration for Input Parameter type.
6 Expand the configuration group, expand the Samples module, and expand the
Samples group.
7 Select CMD_Adapter from the Samples group, and then click OK.
8 Repeat steps 4 through 7 to select the DirectoryCommand configuration item for
the directory command context item.
the Input Name/Value field that corresponds to the directory name output
context item.
10 For Input Parameter type, select Context item.
11 Use the Context Browser to select the source dir context item, and then click OK.
The Property Panel shows all the input and output mappings, as shown in Figure
51 on page 92.
Figure 51: Property Panel with input and output mappings for the called process
12 Click OK to close the Property Panel.
13 Save the Copy Files in Directory workflow.
To test the Copy Files in Directory workflow
In this task, you test the Copy Files in Directory as it is so far. You must know the
fully qualified paths of the directory from which you want to copy files and the
directory to which you want to copy files. These directories must be on the peer
where the adapter of type ro-adapter-command-line is enabled.
1
Development Studio uses the peers and adapters on the grid to test the workflow.
2 If you have not already logged on to the grid, log on; otherwise, proceed to step 3.
source dir parameter and type the name of the directory from which you want to
copy the files.
5 Double-click in the Value field for the destination directory parameter, and type
the name of the directory to which you want to copy the files.
Even though the Copy Files in Directory workflow does not use the destination
directory yet, you are required to provide the name. The following figure shows
the Job Input Parameters dialog box with values for the source directory and
destination.
Figure 52: Example input parameters for testing the workflow
6 Click OK.
BMC Atrium Orchestrator Development Studio runs the Copy Files in Directory
workflow. The console window opens below the process canvas, and the Process
Log tab displays the results of the workflow execution. These are the same results
that are posted to the processes.log file when the workflow is run on the grid. On
the process canvas, the Call Process activities have brown boxes around them to
indicate that they have been executed.
Note
To gather sample data
In this procedure, you save results from the test of the workflow to use in
subsequent tasks.
2 Copy the entire contents of the console window's Process Log tab and paste it in
the blank document.
3 Save the document as temp.txt.
4 Search temp.txt for directory list.
5 Copy the contents of the directory list, beginning with <result> and ending with
</result>.
Do not copy the square bracket at the end of the results.
6 Paste the directory list results in a new blank document and save it as
dir_list_sample.txt.
7 In the dir_list_sample.txt file, change every instance of <DIR> to <DIR>
The transform editor that you use in the subsequent activity would treat <DIR> as
badly formed XML. This step replaces it with equivalent valid XML.
8 Save the dir_list_sample.txt file.
An example dir_list_sample.txt follows:
<result>
<line index="1"> Volume in drive C has no label.</line>
<line index="2"> Volume Serial Number is 6850-9DBA</line>
<line index="3"> Directory of c:\pictures</line>
<line index="4">12/23/2010 04:52 PM <DIR> .</line>
<line index="5">12/23/2010 04:52 PM <DIR> ..</line>
<line index="6">12/14/2007 02:21 PM 33,063 IMG_0307.JPG</
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
line>
<line index="28"> 22 File(s) 587,520 bytes</line>
<line index="29"> 2 Dir(s) 1,633,210,368 bytes free</
line>
</result>
To add a For activity
To copy the files in the source directory, the copy command must be applied to each
file within that directory. In this task, you create the For activity that evaluates each
line in the results of the directory list to determine whether the line contains a file
name. If so, the file is copied from the source directory to the destination directory.
1 Drag a For activity to the design canvas, and connect it to the Copy Files in
Directory workflow between the List directory Call Process activity and the End
activity.
Each For activity includes a For component and an End For component. Connect
the For component to the List directory activity and the End For component to the
End activity.
2 Double-click the For activity to open its Property Panel.
3 Select Context item as the type of input parameter.
4 Use the Context Browser to select the directory list context item.
5 In the Transform area, select the Advanced transform editor.
6 Use the Advanced transform editor to extract the file information from the
directory list:
a In the Sample Source pane of the Transform Editor Setup Wizard, select My
Samples and click to create a new sample.
b In the File Name field of the Input dialog box, type sample directory list, and
then click OK.
c Use a text editor to open the dir_list_sample.txt file and copy its entire
contents.
Copy from <result> to </result>, including all of the angle brackets.
d In the bottom pane of the Select Resource dialog box, delete the <value/> text
and paste the result text that you copied from the dir_list_sample.txt file.
e
Click , and then click Finish.
The Transform Editor Setup Wizard closes and the XPath transform editor
displays the directory list result text in the left pane, as shown in Figure 53 on
page 97.
f (optional) If the Document pane is not visible at the bottom of the XPath
transform editor, drag the divider up from the bottom to open the Document
pane.
Figure 53: XPath transform editor including the Document pane
You use the Document pane to extract the lines that contain file names so that
the For activity can process them. In this case, the lines containing file names
are those that do not begin with a space or that do not contain <DIR>.
g In the XPath transform editor Document entry field type //line[ ] .
h Place the cursor between the square brackets; from the Groups list, select
String, and from the Functions list, select Starts with; and click Insert.
The Document entry field contains the following text:
//line[ starts-with(., "text") ]
i Delete text and type a blank in its place.
//line[ starts-with(., " ") ]
j Place the cursor after the closing parenthesis and before the closing square
bracket; from the Groups list, select Operators, and from the Functions list,
select Or; and click Insert.
//line[ starts-with(., " ") or ]
k Place the cursor after or and before the closing square bracket; from the
Groups list, select String, and from the Functions list, select Contains; and
click Insert.
//line[ starts-with(., " ") or contains(., "text") ]
l Delete text and type <DIR> in its place.
//line[ starts-with(., " ") or contains(., "<DIR>") ]
m
In the Document pane, click Generate Preview .
This expression extracts the lines that do not contain file names, as shown in
Figure 54: Preview Drawer showing results of the XPath expression
Note
Ensure that the Format XML check box is selected.
n Highlight the entire contents of the square brackets, except for the spaces
adjacent to the brackets; from the Groups list, select Boolean, and from the
Functions list, select Not; and click Insert.
//line[ not(starts-with(., " ") or contains(., "<DIR>")) ]
o
In the Document pane, click Generate Preview .
Now the expression extracts the lines that do contain file names, as shown in
Figure 55: Preview Drawer showing results of the final XPath expression
p Click Save and Exit to close the XPath transform editor.
The Transform field on the Properties tab on the Property Panel for the For
activity displays the expression that you created.
7 On the Properties tab, select Context item as the output context type.
8 Use the Context Browser to create a new context item called directory item.
9 Click OK to close the Property Panel for the For activity.
To create the Assign activity in the For activity
1 Drag an Assign activity from the Activity Palette to the process canvas.
2 Connect the Assign activity to the workflow between the For component and the
End For component.
3 Double-click the new Assign activity to open its Property Panel.
4
parameter type, and use the Context Browser to select the directory list context
item.
6 Use the Basic transform editor to extract the file name from the information in the
directory list context item:
a On the Properties tab, click Basic to open the Basic transform editor.
b
c
d In the File Name field of the Input dialog box, type directory item, and then
click OK.
e Use a text editor to open the dir_list_sample.txt file and copy one line that
contains a file name.
Copy from <line> to </line>, including all of the angle brackets.
and paste the line that you copied.
g
The Select Resource dialog box closes and the Basic transform editor displays
the sample line in the left pane.
h In the Basic transform editor, in the Function field, select String => Substring.
i In the first Operand field, type 40.
j In the second Operand field, type 256.
k In the upper-right corner of the Basic transform editor, click Generate Preview
.
The Preview pane displays the file name.
l Click OK to close the Basic transform editor.
The Transform field on the Properties tab on the Property panel displays Gets
the Substring of length 256.0 starting at 40.0.
7 On the Properties tab, for Output Context Type select Context item.
8 Use the Context Browser to create a new context item called source file.
9 Click OK to close the Properties tab for the first assign statement.
10
add another assign statement.
11 On the Properties tab for the assign statement, select String as the input
parameter type.
12 Right-click in the text entry field and select Local Context Item => Source dir.
BMC Atrium Orchestrator Development Studio inserts the source dir context item
in the field.
13 Type a slash immediately after the context item.
14 Right-click in the text entry field immediately after the slash and select Local
Context Item => Source file.
BMC Atrium Orchestrator Development Studio inserts the source file context item
in the field, as shown in Figure 56 on page 103.
Figure 56: Input source context items
15 Use the Context Browser to select the source file context item as the output
context item.
This task changes the value of the source file context item.
16 Click OK to close the Properties tab for the assign statement.
17 Click OK to close the Properties tab for the Assign activity.
To add the Copy File workflow
1 Drag the Copy File workflow to the process canvas.
2 Connect the Copy File workflow to the Copy Files in Directory workflow in the
For activity, between the Assign activity and the End For component.
BMC Atrium Orchestrator Development Studio briefly displays a message that it
has automatically mapped three of three inputs.
Figure 57 on page 104 shows the process canvas view of the finished Copy Files in
Directory workflow.
Figure 57: Completed Copy Files in Directory workflow
Testing the Copy Files in Directory process
In this task, you verify that the top-level process copies all the files in one directory
to another.
Before you begin
To test the process, you must know the names of the source directory and the target
directory. These directories must be on the peer where the ro-adapter-command-line
adapter is enabled. `
To test the Copy Files in Directory process
1 If the Copy Files in Directory process is not open on the process canvas, double-
click it.
2
source dir parameter and type the name of the directory from which you want to
copy the files.
destination directory parameter and type the name of the directory to which you
want to copy the files.
6 Click OK.
BMC Atrium Orchestrator Development Studio runs the Copy Files in Directory
process. The console window opens below the process canvas, and the Process
Log tab displays the results of the process execution.
7 Review the contents of the console window and verify that the last line in the
console window is The process terminated in the completed state.
8 Connect to the peer that executed the process, and verify that the files were
copied into the destination directory.
Using modules
Modules contain processes and the related schedules, configurations, and rules.
Modules can be independent or they can depend on processes and configuration
items in other modules. You can use BMC Atrium Orchestrator Development Studio
to create new or customized processes.
Modules overview
Generally, modules reside in the repository, which stores all content for BMC
Atrium Orchestrator. Modules can also reside in module archive files (.roar files) in
the BMC Atrium Orchestrator Development Studio workspace, particularly if they
are new or have been imported from the repository for editing or testing. You can
create new modules in BMC Atrium Orchestrator Development Studio. To use new
or revised modules, you export them to the repository and activate them on a grid.
Some of the modules in the repository contain prebuilt processes that automate
tasks. For example, Operations Actions utilities provide many out-of-the-box
processes that perform server tasks. You can use imported modules as a basis for
customized processes. To use or edit those processes, you must import the modules
from the repository or a disk and unbundle them in the Library Manager. The
Import Modules tab displays the latest version of the module, but you can import
any version that is available in the repository. To see all versions for a module, click
the version number for that module.
You can use software configuration management (SCM) systems to help manage
versioning of modules and their components.
Library Manager
Use the Library Manager to import, export, unbundle, and compare modules. Each
of these operations has its own tab in the Library Manager interface.
5
Import Modules tab
Use the Import Modules tab in the Library Manager to import modules into BMC
Atrium Orchestrator Development Studio and unbundle them. The Library Manager
offers repository and disk as import sources. The disk source enables you to import
modules from an alternate location, such as a hard drive. The import table on the
Import Modules tab enables you to import, or copy, files into BMC Atrium
Orchestrator Development Studio and unbundle them, which loads them into the
workspace. You can select to only import modules and return to the Library
Manager when you want to unbundle the modules.
Import: copies the module from the repository or disk to BMC Atrium
Orchestrator Development Studio and stores the files. However, the module is not
available for use.
Unbundle: copies the module from the repository or disk and loads it into the
BMC Atrium Orchestrator Development Studio workspace for revision, testing, or
export.
Best practice
Unbundle only those modules that you need. Large numbers of modules can cause
performance delays in BMC Atrium Orchestrator Development Studio and on the grid.
Note
You must be logged on to import modules from the repository. BMC Atrium
Orchestrator Development Studio will prompt you to log on if you are working
offline. You do not need to be logged on to BMC Atrium Orchestrator Development
Studio to import modules from disk.
Unbundle Modules tab
Use the Unbundle Modules tab to load imported modules into the workspace if you
did not unbundle the modules when you imported them.
Compare Modules tab
Use the Compare Modules tab to compare modules from the local workspace with
modules in the local library or the repository. In the repository, a module can have
multiple revisions of a version. Multiple developers can work on the same module
version, and every change is saved as a revision to that module version.
Export Modules tab
When you have completed designing and testing modules, you can export them to
the repository or to a disk. Use the Export Modules tab to select the modules to
Library Manager
export from the local library to the repository or local disk. During export, enter or
select a version for each selected module.
Importing modules from the repository
The repository stores the content that is used in BMC Atrium Orchestrator, including
modules and adapters.
To import and unbundle modules from the repository
2 On the Import Modules tab, click From Repository.
3 In the Import Modules table, select the Import check box to select a module to
import.
4 (optional) To unbundle the module when you import it, select the Unbundle check
box.
5 (optional) To select a specific version or revision of the module, click the version
number or revision number and select the number of the version that you want.
6 Click Import to import the modules.
The time necessary to import and unbundle modules depends on the number and
size of the modules that you select.
After the modules are imported and unbundled, you can use them in the Designer.
If a problem occurs
If you import a module that already exists in BMC Atrium Orchestrator
Development Studio, the system prompts you for an action. You can continue,
overwriting the existing module, or you can cancel the import.
If after you import a module it does not appear in the Designer, check the Import
Modules tab to see whether you imported but did not unbundle the module.
Importing modules from disk
In the BMC Atrium Orchestrator Development Studio workspace, modules are
stored in module archive files, called .roar files. You can import module archive files
from an external source, such as a hard drive.
Library Manager
To import and unbundle a module from a disk
2 On the Import Modules tab, click From Disk.
3 Navigate to the location of the module archive files.
4 In the Import Modules table, select the Import check box to select a module to
import.
5 (optional) To unbundle the module when you import it, select the Unbundle check
box.
6 (optional) To select a specific version or revision of the module, click on the
version number or revision number and select the number of the version that you
want.
7 Click Import.
The time necessary to import and unbundle modules depends on the number and
size of the modules that you select.
After the modules are imported and unbundled, you can use them in the Designer.
If a problem occurs
If you import a module that already exists in BMC Atrium Orchestrator
Development Studio, the system prompts you for an action. You can continue,
overwriting the existing module, or you can cancel the import.
If after you import a module it does not appear in the Designer, check the Import
Modules tab to see whether you imported but did not unbundle the module.
Creating modules
To package the processes with their related schedules, configurations, and rules, use
the Designer to create modules.
Ensure that the names that you assign to modules adhere to the following
requirements:
A module name is limited to the maximum file name size for the operating system
on which BMC Atrium Orchestrator Development Studio is running.
Creating modules
A module name can contain only alphanumeric characters, spaces, and
underscores. In the repository, BMC Atrium Orchestrator converts blank spaces in
the module name to underscores.
A module name must begin with a letter.
To create a new module
1 In the Designer view, select File => New module from the menu bar.
2 Use the menu to select the module type for the new module.
3 In the Owner field, type the module owner's name.
This value will be used as a prefix for the module name. If the module is a Project,
the Owner field is disabled.
4 In the Name field, type the module name; then click OK.
The module is displayed in the Project Navigator.
Using process directories
You can use a process directory to organize processes within a module. For example,
you might want to put a set of related processes in the same process directory.
Ensure that the names that you assign to process directories adhere to the following
naming requirements:
A process directory name is limited to the maximum file name size for the
operating system on which BMC Atrium Orchestrator Development Studio is
running.
A process directory name must begin with a letter and can contain only
alphanumeric characters, periods, dashes, or underscores.
A process directory name must be unique within the module or directory in
which it resides.
After you create a process directory, you can create new processes and process
directories in that directory and you can move existing processes or process
directories to the new process directory. You can also rename a process directory.
Using process directories
To create a process directory
1 In the Project Navigator, right-click the module name and select New Process
Directory.
2 In the process Directory Name field, type the process directory name and click
OK.
The process directory is added to the module tree in the Project Navigator.
To move a process to a process directory
1 In the Project Navigator, select the process that you want to move.
2 Drag and drop the selected process into the target process directory.
BMC Atrium Orchestrator Development Studio moves the process to the new
location and renames the process everywhere it is used in the workspace to reflect
the new location.
To move a process directory to a different module or process directory
1 In the Project Navigator, select the process directory that you want to move.
2 Drag and drop the selected process directory into the target process directory or
module.
BMC Atrium Orchestrator Development Studio moves the process directory and
all its contents to the new location. It renames all processes in the moved process
directory to reflect their new location.
Creating rules
Rules evaluate incoming events generated by monitor adapters and trigger processes
according to the results.
Every rule on a grid evaluates all XML input from the events from the monitor
adapters on the grid. Each rule can trigger only one process, but a single event might
cause multiple rules to evaluate to true, causing multiple processes to run.
When a process is triggered by a rule, the entire contents of the adapter event is
passed to the process to an input parameter. The input parameter must be created in
the Start Activity of the process and named inputevent. You can use a transform
editor to parse the input event and store extracted content in context items. For more
Creating rules
information about monitor adapter events, see the BMC Atrium Orchestrator User
Guide for Base Adapters.
To create a rule
1 In the Project Navigator, expand the module that will use the rule.
2 Double-click rules.
3 In the Rules Designer tab, click Add in the toolbar.
4 In the empty rule, enter the name for the rule in the Rule field.
5 Click the Search button on the far right and browse to select the process that you
want to run if the rule evaluates to true.
A process is listed in the process browser only if the Expose Process in Rules
property was selected for that process in the Process Properties dialog box or in
the New Process dialog box.
6 In the Match selection list, choose how you want the rule to be applied:
All indicates that if every condition evaluates to true, the process is executed.
Any indicates that if any condition evaluates to true, the process is executed.
The source for the condition comparison is the adapter event generated by the
monitor adapter. The adapter event is an XML document that you can transform
to extract a portion from for comparison.
7 To launch the transform editor, click the Transform button.
The Transform Editor wizard is displayed. For information about using the
transform editor, see the chapter "Using the Transform Editor."
Note
The Token pane is not present in the transform editor launched from the rules
designer because tokens cannot be used in XPath expressions executed against
adapter events.
8 Create the XPath expression to extract the content that you want to use for the
rule condition.
9 Click Save and Exit to save the expression and return to the rules designer.
10 Select the comparator that you want to use from the drop-down menu.
Creating rules
The comparator is a relational operator that compares the value derived from the
Source field to the contents of the Value field and evaluates the expression to true
or false.
11 Select the value type from the selection list to the right of the Value field, as
described in the following table:
Value type Description
String A character string
If you select String, enclose the value in single quotation marks.
Numeric A number
Date A date
Use the Calendar button below the Value field to populate the field.
All dates are stored in epoch time format. When comparing a date from
an event generated by an IMAP or POP monitor adapter, use the value
contained in the <sent-epoch-milliseconds> element.
Input Event A value from the incoming monitor adapter event
Use this value type to compare one part of the adapter event to another.
If you select this type, the Transform button is displayed below the Value
field to allow access to the transform editor.
12 In the Value field, enter the value that you want to compare to the source value.
For values with a Value Type of Input Event, the Value field is not available. The
value is the entire adapter event, or the segment of the adapter event as defined
with an XPath expression in the transform editor. Repeat steps 6 through 8 to
extract the portion that you want to compare to the source value.
13 (optional) Click the Add button to add additional conditions.
14 Click Apply to save the rule; click OK to clear the confirmation message.
The new rule is displayed in the Rules List.
Note
To use the rule to trigger a process to run, export the module containing the rule
to the repository and activate it on the grid.
Creating rules
Creating schedules
When a process is associated with a schedule on a grid, the process runs
automatically in accordance with that schedule. You use BMC Atrium Orchestrator
Development Studio to create the schedule.
To create a new job
1 In the Project Navigator, expand the module that contains the process that will
use the schedule.
2 Double-click schedule.
3 In the Schedule tab, click Add.
4 In the Create a new job wizard, type a description of the job in the Description
field, and then click Next.
This description is displayed in the job scheduler in BMC Atrium Orchestrator
Development Studio and in the Grid Manager schedule.
The job schedule has a Start, a Frequency, and a Stop component.
5 In the Job Schedule window, enter the Start value:
A 24-hour time format is used for scheduling. There are two start time options.
The job starts as soon as the module is activated on the grid.
You enter the time for the module to start in 24-hour format.
Note
If you enter a time in the past, the module starts the schedule based on that
time and executes at the next appropriate time according to the other schedule
parameters.
6 Select a Frequency option:
Run every sets the frequency in minutes and seconds. You can use this option
with either Start option.
Run once every sets the frequency in hours, days, weeks, or months. You can
use this option only with a designated Start time.
7 Select the Stop option.
Run forever sets the job to run without a defined termination point.
Creating schedules
Stop on sets a specific date and time at which to stop the job. Use the MM/DD/
YYYY format to set the value.
After N runs sets a fixed number of occurrences for the job.
8 Click Next.
9 On the Job Configuration page, enter the information as indicated in the following
table:
Field Description
Job Name Specifies the name of the job. The name must be unique within the
module. Job names can consist of alphanumeric characters, spaces,
parentheses, and underscores.
Peer Location Specifies the peer on which the process should run. If the value is
different from the value specified in the process properties, the value in
the schedule takes precedence.
any: specifies that the process can run on any peer in the grid. The
master job processor will distribute the process to the next available
peer.
this: specifies that the process runs on the peer that has the master job
processor
best: specifies that the grid must determine on the best peer to run the
process
peer: you specify the peer on which the process will run
Peer Name Specifies the name of the peer. This field is required when you select peer
in the peer location option. The peer name must match a peer on the grid
on which the module is activated.
Process ID Required. Specifies the process executed by this job. Use the Select
button to browse the processes in this module and select the process to be
scheduled.
Note: A process is listed in the process browser only if the Expose
Process in Rules property was selected for that process in the Process
Properties dialog box or in the New Process dialog box.
Creating schedules
Field Description
Input Parameters If there are any input parameters assigned to the selected process, these
fields specify the input parameters. Select a type and a value for the
parameters. The type can be string, numeric, date, or XML. Input
parameters with a red check mark are required. To save the job, you must
provide a value for each required parameter.
Note: You must press Enter after each input parameter.
Note
If you change the input parameters in the Start activity of the process after you
create the schedule job, you must open the job and edit it to reflect the changes.
10 Click Finish.
Table 2: Job scheduling options and expected results
Start Frequency Stop Results
at module activation Run every
XX minutes XX seconds
Run forever Job starts immediately
when the module or
adapter activates and
runs at selected
frequency forever.
Stop on MM/DD/YYYY
HH:MM:SS
Job starts immediately
when the module or
runs at selected
frequency until
designated stop time.
After N runs Job starts immediately
when the module or
runs N times at the
frequency selected.
at module activation n/a After 1 run Job starts immediately
when the module
activates or adapter and
runs once. The frequency
options are not available.
Start on MM/DD/YYYY
HH:MM:SS
Run every
Run forever Job starts at designated
time and runs at selected
frequency forever.
Start on MM/DD/YYYY
HH:MM:SS
Run once every After N runs Job starts at designated
time and runs N times at
the frequency selected.
Creating schedules
Start Frequency Stop Results
Start on MM/DD/YYYY
HH:MM:SS
n/a After 1 run Job starts at designated
time and runs once. The
frequency options are not
available.
Note
You can use Grid Manager to edit existing jobs and to add new jobs. However, those
changes are not visible in BMC Atrium Orchestrator Development Studio.
After a job finishes because of the specified Stop option, it is no longer available in
Grid Manager. If you created the job in BMC Atrium Orchestrator Development
Studio, you can review and edit it in BMC Atrium Orchestrator Development Studio
even after it has finished.
Configuration items
Module configuration items, much like global context items, can be used by
processes across modules, provided the modules are within the same grid.
When you use configuration items in processes, they act as constants for processes
on a grid. Use BMC Atrium Orchestrator Development Studio or Grid Manager to
set the value of the configuration item, and then every process on the grid that uses
the configuration item uses the same value. If you use Grid Manager to set a
different value for the configuration item, that value applies only to the processes
that are run on that grid. If the same module is run on a different grid, the changes
do not apply to that grid. You can use Grid Manager on that grid to set the
configuration item values as needed.
Configuration items cannot be used in rules or in a transform editor. However, you
can assign the value of a configuration item to a context item, and then use that
context item in a transform editor to extract some or all of the values for use in
activities in the process.
Note
You cannot review or extract any part of a secure module configuration item.
Although you can use Grid Manager to set the value of a configuration item, you
cannot use Grid Manager to make structural changes such as add, remove, or
rename configuration groups or configuration items. You must use BMC Atrium
Orchestrator Development Studio if you want to make structural changes to the
configuration.
Configuration items
Working with configuration items
Use these procedures to create and edit configuration items in BMC Atrium
Orchestrator Development Studio.
To create a configuration item
1 In the Project Navigator, expand the module in which you want to create the
configuration item and double-click Configuration.
2
In the Module Configuration pane, click Add Module Configuration Group.
A new configuration group named NewContainer1 is added in the Module
Configuration pane and the Name field in the Group Name pane displays
NewContainer1.
3 (optional) Change the name of the configuration group.
4 Click Save.
5 In the Module Configuration pane, select the configuration group.
6
Click Add Module Configuration Item at the top of the Module
Configuration pane.
A new configuration item named NewValueNode1 is added in the Module
Configuration pane and the Name field in the Item Details pane displays
NewContainer1.
7 Enter the required fields in the Item Details pane, and then click Save.
Field Description
Name The name of the configuration item
Configuration items
Field Description
Type Select the type of configuration item:
Static BMC Atrium Orchestrator treats the item as text.
XML BMC Atrium Orchestrator interprets the item as XML.
Secure BMC Atrium Orchestrator replaces the text that you type with an encrypted
version. It stores the encrypted version as an XML fragment. The unencrypted
content is not visible anywhere in the BMC Atrium Orchestrator interface.
Adapters decrypt secure data type items to use them, but the unencrypted content
is not visible in any log files.
Note: When you use a secure data type in a transform, ensure that the transform treats
the secure data as XML and not as a text string. If you pass the secure data to a context
item that is then used in a transform, you must ensure that the transform also treats
the secure data as XML and not as a text string.
Value The value for the configuration item
If you select Static Value or XML as the Type, the Value field expands to
accommodate the length of text that you type.
If you select Secure as the Typeyou cannot see the text that you enter for the
configuration item. The text is displayed as asterisks.
The configuration item and value are displayed below the selected group.
8 (optional) Repeat steps 5 through 7 to create additional configuration items.
Best practice
When using secure configuration items with BMC supplied activities such as the
Operations Actions utilities, they should be used only for passwords or commands.
Configuration items
Process design
This chapter describes the procedures to create and customize processes in BMC
Atrium Orchestrator Development Studio.
Process overview
Process design is a primary function of BMC Atrium Orchestrator Development
Studio. The Designer pane contains the design-modeling tools needed to create, edit,
and test processes. A process is a set of linked activities that perform a specific
function. BMC Atrium Orchestrator Development Studio enables you to automate
manual processes and when used with the BMC Atrium Orchestrator solution helps
you manage disparate processes across the organization. You can use pre-built
processes to rapidly develop processes customized for your environment.
Many processes are ready for use as soon as they are imported. You can customize
the imported process or create a new process in BMC Atrium Orchestrator
Development Studio. Processes can be simple like executing a SNMP get or complex
like analyzing an incoming event then generating and validating a resolution and
finally documenting a trouble ticket. Processes can call other processes to use
additional functionality.
Process types
Processes in BMC Atrium Orchestrator Development Studio can be complex or
simple. A simple process can involve converting a date or sending an email message.
A complex process can contain called processes, processes exposed as SOAP, and
operator processes. A process within a module can call processes from other
modules. These called processes create dependencies between modules. To
successfully execute a process that uses one or more processes from another module,
all relevant modules must be available in the workspace. Creating processes from
the WSDL generation wizard is described in a separate section.
Exposed as SOAP - Simple Object Access Protocol (SOAP) is used to service
requests to execute processes.
6
Operator process - An operator process that runs in the BMC Atrium Orchestrator
Operator Control Panel and contains all activities including the Operator Dialog
activity
Called processes - Processes that re-use the functions of existing processes. When
you insert processes from one process into another you create a called process.
Process properties
The process properties uniquely define a process within a module. Properties
include how the process is exposed, selecting a custom icon, and setting keywords.
The information in the process properties is used when searching on processes,
when using processes in rules or schedules, and when exporting modules.
The process properties window displays automatically when you create a new
process. To view the properties for existing processes you can double-click on the
process canvas when the process is displayed, or with the process displayed, right-
click on the process canvas and select process properties from the list.
Field Description
Process Name (required) Specifies the name of the process. The name must be unique within the
process directory. Process names are not case sensitive; Process1 and process1 are
considered to be duplicates.
The process name should not contain any extensions. Process names can consist of
alphanumeric characters, spaces, parentheses and underscores.
Process ID Specifies the process ID generated by BMC Atrium Orchestrator Development Studio
Icon Specifies the icon to use for the process. If you do not select a customized icon, the
default icon is used.
Expose Process Check box that indicates whether a process is exposed
In Schedules - Specifies that the process is used to determine frequency of
execution.
In Rules - Specifies that the process is used to control process execution.
In Operator Control Panel - specifies if the process will run in the Operator
Control panel
As SOAP - Indicates if the process will be exposed as a web service via SOAP
when activated on the grid.
Author Specifies the name of the person who created the process.
Category Specifies the grouping for the process.
Process properties
Field Description
Last Modified Indicates the date and time when the process was changed. This is a system
generated date.
Last Modified By Specifies the name of the person who last modified the process.
Process Timeout (ms) Specifies the length of time (in milliseconds) this process is allowed to run before
the compensation is called due to a timeout event.
Note: 1000 milliseconds = 1 second.
Status Specifies the state of the process.
Peer Location Specifies the peer on which the process should run.
any - specifies that the process can run on any peer in the grid. The master job
processor will distribute the process to the next available peer.
this - specifies that the process runs on the peer that has the master job processor
best - specifies that the grid must determine on the best peer to run the process
peer - you specify the peer on which the process will run
Peer Name Specifies the name of the peer. This field is required when you select 'peer' in the
peer location option. The peer name must match a peer on the grid on which the
module is activated.
Process Version Indicates the version of the process. This is a value you enter and maintain.
Record Metrics Specifies whether to record process metrics when the process executes. When set to
true, this option causes standard process metrics to be recorded each time this
process executes on a grid, provided the grid and database are properly configured.
All process metrics written to the metric table have a category of foundation.
For more information about configuring the grid and database for metrics, see the
BMC Atrium Orchestrator System Administration Guide.
Supported Systems Specifies the systems that support the process. This is a value you enter and maintain.
Keywords Specifies specific words to use for a search
Description Specifies the description of the process. This can be a helpful reference to provide a
summary of the process function.
Adding activities to a process
Adding activities to a process defines the functions the process performs. Once the
process is created, the process canvas appears showing the process tab as the default.
The start and end activity are displayed on the process canvas. You add activities to
the process to specify the actions process execute. Activities are found on the activity
palette in the pane on the left side.
Adding activities to a process
To add an activity to the process
1 Click the Activity Palette tab to display the activities.
The Activity Palette tab is a vertical tab to the left of the canvas.
2 Drag the activity to the process canvas and release the mouse button.
3 Click the line connecting the Start and End activities.
This action selects the line and green boxes appear on the connection line.
4 Click and hold the green box nearest the end activity until the arrow pointer turns
into a hand pointer.
5 Drag the pointer to the left side of the activity to add to the process.
6 Click and hold the mouse button on the grey arrow pointer next to the activity
until the arrow pointer turns into a hand pointer.
7 Drag the pointer to the left side of the end activity to connect the process.
8 Press Ctrl+S to save the activity.
Activity properties
Each activity in a process, with the exception of the comments, join, and end for
activities, has associated properties that can be defined, viewed or edited within
BMC Atrium Orchestrator Development Studio. These properties provide the
parameters for the activity, set logging messages and provide the opportunity to add
an activity specific description. Activities are configured through a Property Panel.
The Property Panel for most activities contains a Properties tab. This tab often
contains one or more tables of data. On tabs that contain tables, a tool bar is
provided to facilitate working with the data in the tables.
When you double-click the activity in the process canvas the Properties Panel
displays. The process resizes so that the entire process is visible in the top half of the
process canvas. The activity whose Property Panel is displayed is highlighted by a
green box. There are three possible tabs available on the Property Panel: Properties,
Logging and Metadata. The end, end for, join and comments activities do not have
an associated Property Panel. The spawn activity does not use the Properties tab;
only the Logging and Metadata tabs will be available on the Property Panel of a
spawn activity.
Activity properties
Activity Property PanelProperties tab
The Properties tab is used to define inputs, outputs, and context items for an activity.
The fields within Properties vary depending on the type of activity being defined.
The fields associated with each type of activity are described in this document. In the
Properties tab, features such as the Context Browser and transform editor are used
to define the activity.
Activity Property PanelLogging tab
In addition to the default information that is collected in the processes.log when you
execute a process, you can specify information to be logged for each activity in the
process. When you test the process in BMC Atrium Orchestrator Development
Studio, the log entries for the activity are written to the console window and to the
processes.log file on the computer where BMC Atrium Orchestrator Development
Studio is installed. When the process is executed on the grid, the entries are written
to the processes.log file on the peer that executes the process.
By default, when BMC Atrium Orchestrator runs a process on the grid, it logs only
process starting and ending information. However, you can use the Logging tab to
configure logging for additional information about each activity in the process.
The Logging tab enables you to configure process log messages to write before, after,
or before and after the activity executes. The log message can include static text as
well as the value of one or more designated context items at the time of the activity's
execution.
When processes are run on the grid, the log levels indicate the priority, or urgency,
of the message. The for levels, in ascending order of priority are: debug, info, warn,
and error. The log messages for an activity are written to the log only when the
activity log level priority is greater than or equal to the logging level set for the grid
where the process is executed. For example, if you set the log level for the activity at
info, the message will be written to the executing peer's processes.log file if the
logging level for the grid is set to debug or info, but not if the logging level for the
grid is set to warn or error.
See the BMC Atrium Orchestrator System Administration Guide for more information
about setting logging levels for grids.
Logging Level Description
DEBUG (default for processes.log) The most detailed logging level; logs low-level
messages, normal execution, recoverable erroneous conditions, and
nonrecoverable erroneous conditions
Activity properties
Logging Level Description
INFO Logs normal execution, recoverable erroneous conditions, and nonrecoverable
erroneous conditions
WARN Logs recoverable erroneous conditions and nonrecoverable erroneous conditions
ERROR The least detailed logging level; logs only error conditions that are not usually
recoverable
When processes are tested in BMC Atrium Orchestrator Development Studio, all
configured log messages are written to the console window and to the processes.log
on the computer where BMC Atrium Orchestrator Development Studio is running.
Best practice
While developing a workflow, log the following items to assist with troubleshooting:
adapter requests
adapter responses
the value of context items before and after they are changed
the results of any complicated transform
Configuring logging for activities
Use the Logging tab on the Property Panel for the activity to configure logging for
the activity. You can log information before the activity is executed, after it is
executed, or before and after.
To configure logging for an activity
1 On the process canvas, double-click an activity to display the Property Panel for
the activity.
2 On the Property Panel, select the Logging tab.
3 To enter information in the log before the activity is processed, select the Before
Execution tab. To enter information in the log after the activity is processed select
The text boxes on the tabs are the same. You can set logging to occur before and
after the activity is executed by using both tabs.
4 Click the Log check box to activate logging and enter any text you want to write
to the log file in the Log text box.
Activity properties
5 Use the selection list to the right of the Log text box to specify the log level to
apply to the log entry when the process is executed on the grid.
6 To insert the value of each context item that you want to log:
a Click inside the Context Item text box.
b
Click Insert Context/Config Element .
c
In the Insert Context/Configuration Element dialog box, click to open the
Context Browser.
d In the Context Browser, select the context item whose value you want to log.
7 Click OK.
Activity Property PanelMetadata tab
Each activity has definable metadata associated with it. The Metadata tab allows you
to define or edit the activity's metadata. All activities contain two fields in the
Metadata tab, Description and Check Point. A Call Process activity contains an
additional field, Time-To-Live.
Field Description
Description A detailed description of the activity. This description is visible in this window
and in the View PDL tab.
Check Point Establishes a point at which data generated by a process is captured for use in
the event of a process failure. If a Peer were to fail and process execution was
moved to another Peer (or back to the same Peer if it recovers), process
execution would resume after the last successful check point activity. All
process data captured at the check point before the Peer failure will be used to
continue with the process. The options are True or False. Selecting True will set
this activity as a check point activity.
Time-To-Live Only available for Call process activities. Time-To-Live is the number of
milliseconds the called process is allowed to run before it is stopped. If a called
process is stopped before completion, the Compensation for that called process
will be executed.
Step-Into This setting applies to the For and Spawn activities for use in the Operator
Control Panel. It specifies if you can step into the process when executing the
process in the Operator Control Panel.
Activity properties
Compensations
A compensation is a process that is executed if the defined process fails to run to
completion. Every process or activity can have a compensation defined. A process
can fail due to unavailability of resources, such as an adapter, or when the process
takes longer to complete than the allotted timeout value.
If the process fails to complete due to unavailable resources when an activity
executes, the compensation assigned to the failing activity is executed.
If there is no compensation assigned to the failing activity, the process
compensation is executed instead.
If the process is a called process, then the compensation assigned to the call
process activity executes.
If there is no compensation assigned to the call process activity, the called process
compensation executes instead.
This method of searching for a defined compensation in a higher process level
continues until the primary process layer is reached. If a process is not completed
and a compensation has not been designated at the failing level or higher, a 'debug'
level message will be written to the processes.log on the peer that was trying to
execute the process. If the process times out, the process compensation is executed.
To add a compensation to an activity in a process
1 Right-click the Activity button on the process canvas.
2 Select compensation from the menu.
3 Create a compensation process in the same manner as the originating process;
then click Done.
To add a compensation to a displayed process
1 Right-click on the process canvas.
2 Select Compensation from the menu.
3 Create the compensation process in the same manner as the originating process.
4 Press OK.
Compensations
Called processes
A called process is a process that is used, or called, in a Call Process activity within
another process. Any process can be a called process. When you use a called process
you leverage the functionality of pre-existing processes which reduces process
design time. For example, if you need to format a date as an epoch date, you can
write a process to do that, or you can drag the format date process from the OA
Utilities module into your process.
Note
Although the called process is contained within a Call Process activity, you do not
add the Call Process activity from the Activity Palette. The activity is automatically
created when you drag the called process onto the process canvas.
The input and output parameters and context items for a called process are separate
from the parameters and context items for the calling process. To communicate
between the processes, you must map the parameters from one process to the other.
If the calling process has context items that have the same name as parameters in the
called process, those parameters are automatically mapped to the context items. If
there are no matching context items for the called process output parameters,
matching context items are created and mapped to the output parameters when the
process is dragged to the process canvas.
Using a called process
Any process can be a called process. When you use an existing process within
another process, the existing process is a called process. The process that contains the
called process is the calling process.
To use a called process
1 On the process canvas, open the process that will be the calling process.
2 Drag the process that you want to call from the Project Navigator to the process
canvas.
3 Use the gray process line to connect the called process to the calling process.
4 (optional) Map context items from the calling process to the input parameters of
the called process.
If the input parameters have names that match the names of context items in the
calling process, they are automatically mapped to those context items.
a Double-click the called process.
Called processes
The Property Panel for the Call Process activity is displayed. The Properties
tab contains the Call Process Input Mapping section and the Called Process
Output Mapping section.
The Call Process Input Mapping section maps information from the calling
process to the input parameters of the called process. The Output Name
column is already populated with the names of the input parameters.
b In the Call Process Input Mapping on the Properties tab of the Property panel,
double click in the first Input Name field.
c Select Context item as the Parameter type and use the context browser to
select the context item that contains the information you want to use in the
specified output mapping.
d Click OK.
e Repeat steps b, c, and d for each output item that you want to map to a context
item in the calling process.
f Click OK to close the Property Panel for the Call Process activity.
5 Save the process.
Automapping context items with called process inputs and
outputs
BMC Atrium Orchestrator Development Studio can automatically map local context
items in a process to the input parameters of a called process. BMC Atrium
Orchestrator Development Studio can also automatically map the output parameters
of a called process to local context items.
Input parameters for the called process
If local context items from the calling process have the same names as the input
parameters for the called process, BMC Atrium Orchestrator Development Studio
automatically maps them to each other. The program makes the mapping when you
connect the called process to the calling process with the gray process line. BMC
Atrium Orchestrator Development Studio displays a message stating the number of
items automatically mapped.
Called processes
Tip
An automapped status message is displayed for 20 seconds in the corner of the
window. This message can be viewed by clicking the History link on the bottom of
the window.
If any of the input items were not automatically mapped, you can map them by hand.
Output parameters for the called process
If local context items from the calling process have the same names as the output
parameters for the called process, BMC Atrium Orchestrator Development Studio
automatically maps them to each other. The program makes the mapping when you
drag the called process to the process canvas.
If there are no local context items with the same names as the output parameters
from the calling process, BMC Atrium Orchestrator Development Studio creates
matching context items and automatically maps them to the output parameters. You
do not need to map any output parameters by hand.
BMC Atrium Orchestrator Development Studio does not automatically create a
mapping to a global context item, even if the name of the global context item
matches the name of the output parameter.
Called Process viewer
The Called Process viewer displays the processes called from within a process. The
viewer contains a hierarchy of called processes. This feature gives greater control
and oversight of processes during design.
To access the Called Process viewer, right-click the process canvas and select View
Called Processes. You can search for specific called processes in the viewer and open
them on the process canvas by double-clicking the process that you want to open.
The viewer window remains open until you close it. If you change information while
a viewer window is open, the displayed information does not refresh.
Calling Process viewer
The Calling Process viewer displays all the processes that call the process on the
process canvas. The names of the calling processes are displayed in the viewer. You
can double-click the name to display the calling process on the process canvas. The
viewer contains a search feature.
Called processes
To access the Calling Process viewer, right-click the process canvas and select View
Calling Processes. You can search for a specific calling process in the viewer and
open it on the process canvas by double-clicking it. The viewer window remains
open until you close it. If you change information while a viewer window is open,
the displayed information does not refresh.
Renaming a process or process directory
When a process is used in another process and when it is called by a rule or a
schedule, the process is identified by its name. BMC Atrium Orchestrator
Development Studio enables you to change the name of a process or process
directory and maintain referential integrity. When you rename a process or process
directory, the product changes the name everywhere that it is used within the
workspace.
When you start BMC Atrium Orchestrator Development Studio, the product builds
an index of every process. The index identifies everywhere the process is used in the
workspace. When you rename a process, BMC Atrium Orchestrator Development
Studio uses the index to change the name every place in the workspace. You need
not manually revise other processes, rules, or schedules that call the process. The
renamed process can still be called from web services and from the BMC Atrium
Orchestrator Operator Control Panel.
If you have created a custom label for the renamed process within a caller process,
that custom label is maintained when the called process is renamed. However, if you
have not created a custom label, when the called process is renamed, its label is also
changed.
To rename a process
1 In the Project Navigator, right-click a process and select Rename.
If BMC Atrium Orchestrator Development Studio has not completed the initial
indexing, it displays a message indicating how close it is to completing the index.
As soon as the index is complete, the product displays the New Process Name
dialog box and you can continue to rename the process.
2 In the New Process Name dialog box, type the new name for the process, and
then click OK.
To rename a process directory
1 In the Project Navigator, right-click the process directory and select Rename.
If BMC Atrium Orchestrator Development Studio has not completed the initial
indexing, it displays a message indicating how close it is to completing the index.
Renaming a process or process directory
As soon as the index is complete, the product displays the New Process Directory
Name dialog box and you can continue to rename the process directory.
2 In the New Process Directory Name dialog box, type the new name for the
process directory, and then click OK.
Note
When you export the module containing the renamed process or process directory to
the repository so that you can use it on a grid, be sure to export all the modules that
contain any of the processes, rules, and schedules that were changed to incorporate
the new name.
Operator processes
An operator process is a process that is exposed in the BMC Atrium Orchestrator
Operator Control Panel. All activities can be added to a process exposed on BMC
Atrium Orchestrator Operator Control panel.
Using hyperlinks in processes exposed in the BMC Atrium
Orchestrator Operator Control Panel
you can insert hyperlinks into processes that are exposed in the BMC Atrium
Orchestrator Operator Control Panel. The hyperlinks are formatted as static strings,
using http://, https:// or HTML, or made up of one or more context items.
In the BMC Atrium Orchestrator Operator Control Panel, hyperlinks are rendered in
the Results tab or the description window of the process you execute. Workflow
operators can click the link to access a website. While testing and debugging
operator workflows, in BMC Atrium Orchestrator Development Studio, the
hyperlinks are functional.
When creating an process exposed in the BMC Atrium Orchestrator Operator
Control Panel, you enter hyperlinks in:
Description field of the process property. The hyperlink is displayed in the BMC
Atrium Orchestrator Operator Control Panel when you click the show description
link.
In an activity in the details field of the Results tab. The hyperlink is displayed in
the results table in the BMC Atrium Orchestrator Operator Control Panel.
Operator processes
Tip
The configuration of your browser determines if clicking the link opens a new
window or a new tab.
Before you begin
Have open on the process canvas a process you are creating or editing that contains
at least one activity.
To insert a hyperlink to display in the BMC Atrium Orchestrator Operator
Control Panel process description field
1 Edit the process properties.
2 In the description type the link for the website. When running the process in the
operator control panel, this link is displayed in the process description. The
HTML link that follows creates a link that is displayed in bold text, called BMC
for the BMC Software, Inc. web site.
Figure 58: Sample HTML string for process description
<a href=http://www.bmc.com target=bmc><b>BMC</a>
To include a hyperlink in the Results tab of an process exposed in the BMC
Atrium Orchestrator Operator Control Panel
1 Double-click an activity on the process canvas.
2 In the Results tab of the Properties Panel enter the link in the details field.
The following example hyperlink creates a link, that is displayed in bold text,
called BMC for the BMC Software, Inc. web site.
Figure 59: A hyperlink created with HTML
<a href=http://www.bmc.com target=bmc><b>BMC</a>
The following example hyperlink is created with string http:// the BMC Software,
Inc. website.
Figure 60: A hyperlink created with http://
http://www.bmc.com
Operator processes
The following example hyperlink is created with the string https:// and opens the
email server to the login page.
Figure 61: A hyperlink created with https://
https://www.emailserver.com/
3 Click OK to close the Properties Panel.
4 When running the process in the BMC Atrium Orchestrator Operator Control
Panel the link is displayed in the Results tab.
To create a hyperlink using context items
1 Double-click the called process on the process canvas.
2 In the Results tab of the Properties Panel, click the context item button next to the
details field to open the Context Browser window.
3 Select or create a context item to use for the hyperlink. The context item can be a
URL or it can be made of multiple context items that create a URL.
4 Click OK to insert the context item and close Properties Panel.
5 When running the process in the BMC Atrium Orchestrator Operator Control
Panel the link is displayed in the Results tab.
WSDL to workflow process generation wizard
The WSDL to Workflow Process Generation Wizard helps you create a process that
executes a web service call. The wizard has options to allow HTTP authentication
and SOAP session IDs. For inputs and outputs that are complex values, like an XML
document rather than a simple string, helper processes can be created to compile the
input or deconstruct the output so that it is in a more usable format.
The WSDL wizard is a five step process whose steps are described in the table below.
When you complete the wizard, the WSDL process is displayed in the project canvas.
An input is created for each input defined in the wizard.
An additional required input, adapter name, is created to capture the name of the
Web Services Adapter to be used to execute the request.
An Invoke SOAP Request activity is created. Values provided in the wizard are
used to populate the input values for the process that will execute the SOAP
request with a Web Services Adapter request.
An output is created for each output defined in the wizard.
Additional outputs, status and error, are created to capture the status of the
request and, in the event of an error, the error message returned.
Table 3: Steps in the WSDL to workflow process generation wizard
Steps and fields Description
1. Select WSDL You browse the local file system or enter the URL for the WSDL file.
Include WSDL contents in request Specifies that the contents of the WSDL are included in the process.
Select this option if the WSDL is not available for the adapter request
at the time of process execution.
If you do not select to include the WSDL contents then the process
contains only the file location.
Service endpoint Specifies the WSDL endpoint. The service endpoint is automatically
populated when the WSDL operation is selected. To change the value
select the override checkbox.
2. Additional input parameters You select options for the WSDL process. The created process
includes and marks as required, the parameters specified in the
HTTP authentication and SOAP Session ID.
Add HTTP authentication Allows HTTP authentication for the WSDL process.
Username Specifies the user name used for HTTP authentication.
Password Specifies the password for HTTP authentication.
Add SOAP session ID Specifies the ID used for the SOAP session. The session ID is used
when multiple requests are made to the same SOAP service to
maintain a single session, rather than opening a new session for each
request.
3. Input Mapping You input the required inputs for operation selected in Step 1. If you
selected an operation for which there are no required inputs this
window does not display.
Input Names Indicates the input names for the WSDL operation.
4. Output Mapping You accept or change the output values for operation selected in Step
1 Select WSDL. The name defined in the Output Name is used by the
generated process. If you selected an operation for which there are no
outputs this window does not display.
5. Enter Process Information You enter the properties for the process.
Before you begin
To create and run a process with the WSDL to Process Generation Wizard, ensure that:
The AutoPilot-Utilities module is imported and unbundled in the BMC Atrium
Orchestrator Development Studio workspace for the grid in which you create the
process.
The AutoPilot-Utilities module is active on the grid in which the process will run.
The Web Services adapter is enabled on at least one peer on the grid in which the
process will run.
To create a process from a WSDL
1 From the Process Designer view, highlight the module in which to create the
process and select File then New Process then Process from WSDL.
2 Perform one of these actions to select the WSDL file.
Browse the local file system for the WSDL file and click Open.
Enter an HTTP or HTTPS URL for the location of the WSDL file.
3 To include the entire contents of the WSDL file in the process click the check box.
4 Click the Query button to query the WSDL file.
5 Expand the services and select the operation then click Next.
6 If you select HTTP basic authentication, in the Additional Input parameters
window, review or change the values of the username parameter name and
password parameter fields.
7 If you select add SOAP session ID in the Additional Input parameters window
review or change the session ID that is displayed.
8 In the Input Mapping window enter values for the required inputs for the WSDL
operation.
9 (optional) If the web service operation has outputs, in the Output Mapping
window edit or accept the default name from the WSDL definition for each
output.
10 In the Enter Process Information window, enter the properties for the process.
11 Click Finish.
To review the WSDL process
1 Double-click the Start activity to display the process inputs.
2 Double-click the process activity Invoke SOAP Request to display the mapping
of the process inputs.
3 Double-click the End activity to display the process outputs.
Searching for processes
You can search for processes using a regular or advanced search. The regular search
queries the processes and retrieves them using the following criteria:
Name - the process name as it appears in BMC Atrium Orchestrator Development
Studio (e.g. Get Router Parameters)
Process ID - a unique identifier for the process
Version - process version number
Author - the company or individual who built the process
Last Modified By - the username of the person who last modified the process
Module - the parent module of current process
Folder - the module folder
Type - the process type, as defined by the workflow author
Description - the full description as written in the process properties
Input - the list of input parameters with description
Output: the list of input parameters with description
Keywords: keywords from the process properties
To search for processes in the Project Navigator
1 In the Project Navigator, enter the search criteria in the search field.
2 Click the Search button.
3 Scroll to the highlighted process in the Project Navigator and click OK to select
the process and close the process browser.
To search for processes in the Project Navigator with the advanced method
1 In the Project Navigator, enter the search criteria in the search field.
2 Click the drop down arrow next to the Search button.
3 Select Advanced.
Tip
A progress bar is displayed while the search is running. You can cancel the search
at anytime.
4 In the Search Results window, you can review and select the processes.
Using the Advanced Search Results window
When the advanced search completes, the Advanced Search Results window
displays on a tab in the project canvas. The information in the Advanced Search
Results window is organized by the Name, Version, Category, Last Modified, Last
Modified by, Description, and Status fields.
The Advanced Search Results window enables you to extend the capabilities of the
basic search. You can manipulate the search results by sorting on the individual
headers, changing the order of the headers by dragging and dropping them. or
applying highlighting. You can save the results by clicking the save button.
To close the Advanced Search Results window, click the close button on the tab. To
remove the search criteria, click the clear button.
Before you begin
In order to see the Advanced Search Results window you must use the Advanced
Search feature.
To sort headers
1 In the Advanced Search Results window, click on a column header.
An upward pointing arrow displays in the column indicating that the information
is displayed in ascending order and the Advanced Search Results window
redisplays in ascending order based on the selected column.
2 To display a column in descending order, click on the column header a second
time.
To change the order of the headers
1 In the Advanced Search Results window, click and hold a column header.
2 Drag the column to a new location.
The Advanced Search Results window redisplays the results.
To save the Advanced Search Results
1 Click the Save button.
2 In the Save window specify the file name and location.
3 Click the Save button to save the results.
To highlight Advanced Search Results
1 In the Advanced Search Results window, click the Highlight the cells that
generate hits checkbox.
The cells in the table that contain the search value are highlighted.
Generating process documentation
The process documentation generation feature allows you to create a PDF or HTML
file that contains the attributes and a graphical representation of the process. This file
saves to the name and location you specify.
The uses for this documentation are many, like internal audits or as documentation
for operators in Operator Control Panel. In addition to the graphical representation
of a process, the process documentation contains process attributes such as:
Process name
Full path to the process
Module name and directories that contain the process
Process description from the process properties
Process properties
Input parameter names
Output parameter names
Generating process documentation
The generated process documentation resides outside of BMC Atrium Orchestrator
Development Studio, in location you choose. You can review the documentation in a
web browser or an application that displays PDF files.
To generate process documentation
1 In the Project Navigator, right-click on a process.
2 Select Generate documentation.
3 In the Workflow Doc Gen window select the file format, either HTML or PDF.
4 Specify the file path or click the Browse button and navigate to a location.
5 Click OK to save the file location.
The file is saved in the location and format you specified. The graphical
representation of the process is saved in a .png format in a directory with a name
based on the file name.
Export the process module
To deploy the processes in BMC Atrium Orchestrator, you must export the modules
to the repository.
The exported module is contained in an archive file that consists of:
Processes - Sets of linked activities that perform a function.
Rules - Specify criteria that can trigger a process in reaction to a monitor adapter
event.
Schedule - Specifies information that runs processes on a regular schedule, with
the ability to control start, end, and frequency parameters.
Configuration - Contains the configuration information for the module.
Exported modules in the repository are activated in BMC Atrium Orchestrator Grid
Manager, making processes in the module eligible for execution on the grid. After
activating a module on a grid, the module schedule is enabled triggering process
execution at defined intervals, and rules evaluate events to control process execution.
To export modules to the repository
Note
To export to the repository, you must be connected to a grid. BMC Atrium
Orchestrator Development Studio prompts you to log on when necessary.
1 Click the Library Manager button.
2 In Library Manager, click the Export Modules tab.
3 In the Export Modules table select the modules to export by clicking in the Export
checkbox next to the module name.
Tip
A flag displays in the Modified column of the Export Modules table if a module
changed after it was imported.
4 Enter or select the version of the module to export.
Tip
This field is not automatically populated. BMC Atrium Orchestrator Development
Studio verifies the version number before exporting.
5 Click the Export to Repository button.
6 On the Export Confirmation window, verify the information and click Proceed.
When the export process is finished, the Export Confirmation window disappears,
and BMC Atrium Orchestrator Development Studio displays the message Export
Successful in the bottom left corner of the window.
Note
You can review the export messages by clicking the History link on the bottom of the
window.
Using software configuration
management systems when
creating workflows
With BMC Atrium Orchestrator Development Studio, you can use software
configuration management (SCM) systems to track changes made to workflows.
(These systems might also be called source configuration management systems.) This
chapter describes how to configure BMC Atrium Orchestrator Development Studio
to work with supported SCM systems.
Software configuration management overview
As you develop workflows, especially if multiple developers are working on
different parts of the same workflow, you might want to use an external SCM system
to track the changes. With an SCM, you can reconcile different versions, revert to
previous versions, and more.
When you use an SCM with BMC Atrium Orchestrator Development Studio, you
can tell the status of your work relative to the shared SCM repository, and whether a
workflow is newly created, locally modified, or has conflicting changes relative to
the state of the shared SCM repository.
You can integrate BMC Atrium Orchestrator Development Studio with the following
SCM systems:
CVS
Perforce
Subversion
You must have one of the supported SCM systems installed and configured before
you can configure BMC Atrium Orchestrator Development Studio to use the SCM
system.
7
Note
The integration with external SCM systems is provided through third-party plug-ins.
Not all the features are supported. Some features may not work as expected.
The BMC Atrium Orchestrator Development Studio to SCM system relationship is
defined at the grid level. If you are using an SCM system, all the modules in any one
grid must be managed with the same SCM system. You can configure other grids to
use different SCM systems.
Configuring BMC Atrium Orchestrator
Development Studio to use CVS
Use this task to configure BMC Atrium Orchestrator Development Studio to manage
the workflows in a grid using CVS.
Before you begin
Before you can configure BMC Atrium Orchestrator Development Studio to
integrate with the CVS product, you must install and configure CVS. You must
know the username and password for a user with access to the CVS repository.
To configure BMC Atrium Orchestrator Development Studio to use CVS
1 In the project tree in the Project Navigator of the Designer view, right-click the
name of the grid whose modules you want to manage in CVS.
2 In the menu, select Team => Share Project.
3 In the Share Project dialog box, select CVS; then click Next.
4 Provide the following information in the Enter Repository Location page; then
click Next.
Field Description
Host The name of the host where the CVS repository is installed
Repository path The path on the host that leads to the location of the CVS repository that you
want to use
User The user who will be associated with the changes to the workflows
This must be a valid CVS user.
Password The password for the specified user
Configuring BMC Atrium Orchestrator Development Studio to use CVS
Field Description
Connection type The type of connection that BMC Atrium Orchestrator Development Studio
will make with the CVS repository: ext, extssh, pserver, and pserverssh2.
Port You can choose the default port, or you can specify the port to use.
Save password Not supported in BMC Atrium Orchestrator Development Studio
Configure connection
preferences
Not supported in BMC Atrium Orchestrator Development Studio
5 On the Enter Module Name page, either specify a new name for the CVS module,
or select an existing CVS module; then click Next.
Option Description
Use project name as module name A new module is created in CVS and given the same
name as the grid.
Use specified module name A new module is created in CVS and given the
specified name.
Use an existing module An existing module is used.
Use project name as module name and place it under
the selected module
A new module is created in CVS under the selected
module. The new module is given the same name as
the grid.
6 On the Shared project resources page, review the resources to be placed in CVS,
select Launch the Commit wizard, and then click Finish.
7 In the Commit Wizard, select the components that you want to commit to the
repository, type any comment that you want to include, and then click Finish.
BMC Atrium Orchestrator Development Studio is configured to work with CVS
to manage the source configuration of the grid workflows, and the selected
components are added to the CVS repository.
Note
To access CVS functions, right-click the grid, workflow, or other component in the
Project Navigator, and then select Team.
Configuring BMC Atrium Orchestrator Development Studio to use CVS
Development Studio to use Subversion
the workflows in a grid using the Subversion product.
Before you begin
integrate with Subversion, you must install and configure Subversion and you must
have created a repository.
To configure BMC Atrium Orchestrator Development Studio to use Subversion
name of the grid whose modules you want to manage in Subversion.
3 In the Share Project dialog box, select SVN; then click Next.
4 On the Enter Repository Location Information page, enter the URL for the
Subversion repository; then click Next.
5 On the Enter Folder Name page, specify the name for the Subversion folder in the
SVN repository; then click Next.
Option Description
Use project name as folder name A new folder will be created in Subversion and given
the same name as the grid.
Use specified folder name Type the name of the folder you want to use.
Note
The Select option is not supported in BMC Atrium Orchestrator Development
Studio.
6 On the Ready to Share Project page, enter any comments that you want for the
project; then click Finish.
BMC Atrium Orchestrator Development Studio is configured to work with
Subversion and the project is imported into the Subversion repository. The
Synchronize tab is displayed to enable you to commit the work.
Configuring BMC Atrium Orchestrator Development Studio to use Subversion
Note
To access Subversion functions, right-click the grid, workflow, or other
component in the Project Navigator, and then select Team.
For more information about the using the connection with Subversion, click Help
and then select Subclipse - Subversion Eclipse Plugin from the Contents.
Development Studio to use Perforce
the workflows in a grid using the Perforce product.
Before you begin
integrate with Perforce, you must install and configure Perforce and the BMC
Atrium Orchestrator Development Studio workspace must be mounted in the
Perforce client. For more information about mounting workspaces, see the Perforce
documentation.
You must know the username for a user with access to the Perforce repository.
To configure BMC Atrium Orchestrator Development Studio to use Perforce
name of the grid whose modules you want to manage in Perforce.
3 In the Share Project dialog box, select Perforce; then click Next.
4 In the Share Project wizard, on the Enter Perforce Server Connection Information
page, click Create a new Perforce server connection.
5 Enter the following information for the connection; then click Finish.
Field Description
Server address The host name and port of the Perforce server
User The Perforce user name
Field Description
Client workspace The Perforce workspace where the BMC Atrium Orchestrator Development
Studio workspace is mounted
Charset If the Perforce server is set to work in unicode mode, specify the character
set to use.
Otherwise, select none.
BMC Atrium Orchestrator Development Studio is configured to work with Perforce.
Note
To access Perforce functions, right-click the grid, workflow, or other component
in the Project Navigator, and then select Team.
Using a transform editor
BMC Atrium Orchestrator Development Studio contains transform editors that
enable you to manipulate data. The transform editors enable you to format data or
extract specific segments of data and assign the resulting output to a context item for
use in current or subsequent activities.
BMC Atrium Orchestrator Development Studio contains a Basic, Advanced, and a
Regex transform editor.
Transform editors overview
BMC Atrium Orchestrator Development Studio contains that enable you to
manipulate data. BMC Atrium Orchestrator Development Studio contains a Basic,
Advanced, and Regex transform editor.
The Basic transform editor allows data manipulation without using XML editors.
Using Basic transform editor functions and menus you can easily manipulate the data.
The Advanced transform editor is used to create and test any XPath or XSLT
expression applied against a defined input.
The Regex transform editor enables you to build a regular expression ("regex") that
can be evaluated on a context item value for a match, or perform pattern substitution
ion a context item value. It enables you to preview results against sample data, and
both the regex and sample data can be loaded from or saved as a resource, enabling
reuse throughout your development environment. To use the Regex transform editor
to select or build a regex for use in a process, use a Utility activity inside the process
(such as Utility Type string and Operation regex). Alternatively, you can launch the
Regex transform editor independent of a specific process through the Tools menu,
where you can experiment with regexes, and inspect and create sample data and
reusable regexes.
8
Basic transform editor
The Basic transform editor conducts basic transformations. When you use the Basic
transform editor, the value of a defined input is transformed and the result is saved
as a context item. The Basic transform editor consists of the Test Value frame, the
Preview frame and the Function Sequence section. The transform editor is launched
from the property panel by clicking the Basic transform button.
You can enter test data and then apply multiple functions to see the results on the
test data.
You can save and use sample data.
Test frame
The test frame enables you to display and edit input and open samples from the
resource frame for use in a transform. The test frame displays the input used for the
transform. In this frame you can edit the sample value, revert to the original sample,
open a sample value from the resource frame, or save the current file to a sample in
the resource frame. You can select and maintain XML samples in the resource area.
Select resource pane
You define the expression in the function sequence and execute it against the sample
in the resource pane. The results display in the Preview frame.
To use a sample from the select resource frame
1 From the resource pane in the Basic transform editor, click the Open a sample
button.
2 Select a sample either by choosing an option on the toolbar or expanding the
displayed XML samples.
3 Click OK to select the sample.
Preview frame
You use the Preview frame to review and alter the transform results.
Function sequence
The function sequence contains the actions to be performed by the transform. You
select the functions and their sequence to transform the data.
The function sequence pane sets the actions and the order they execute to transform
the data. The function sequence contains String, XML, Logical, Math, and Date and
Time functions. You can expand and collapse the functions by double-clicking the
folder name. Additional fields appear based on the function selected.
This example shows how to use the transform editor as part of an assign activity. For
this scenario, a process was created with an assign activity.
To use the Basic transform editor to convert an epoch date to an EU date format
This example shows how to use the Basic transform editor as part of an Assign
activity in a process.
1 Double-click the assign activity to display its property panel.
2 Click the Add button to add an assign statement that is a date.
a Select date from the Parameter Type list.
b Select the date to use as the input parameter.
3 Choose the output parameter context type.
a Create a context item called date.
b Click Select to use the context item.
c Click OK to accept the parameters.
4 Create another assign statement that is a context item using the output from the
first statement to format the date (the context item date).
5 Click OK.
6 On the property panel, click Basic to use the Basic transform editor.
7 In the Function Sequence section window, select Date Function from the
Function list.
8 Expand Date Function and select EU date (format).
9 In the Function Sequence section, select Operand Date (Exact).
10 Click OK.
11 Assign the output to a new context item.
a Click Output Context type Context Item.
b Click New and then create a context item named formatted date.
c Select the formatted date context item.
12 Click OK to finish the assign statement.
13 Press Ctrl+S to save the process.
Basic transform editor functions
The Basic transform editor provides the functions described in the following table.
Table 4: Basic transform editor functions
Function Operands Description
String
Substring Start Index, length Retrieves the substring of text that you specify.\
Substring Before Text Retrieves the substring that is displayed before
the specified text
Substring After Text Retrieves the provided substring that is displayed
after the specified text
Length n/a Retrieves the length of the string
Trim spaces n/a Trims leading and trailing spaces in the string,
and replaces multiple spaces with a single space
Lowercase All n/a Converts the string to lowercase
Uppercase All n/a Converts the string to uppercase
Replace Replace, with Replaces the specified text with the provided text
Convert to Numeric n/a Converts the XML or text to a numeric value.
Any letters, commas, or other delimiters are
removed, except decimal markers
XML
First Child n/a Retrieves the first child from the root
Last Child n/a Retrieves the last child from the root
Child at number Child Index Retrieves the child element at the specified position
XML to Text (newlines) n/a Extracts the text from all XML elements in the
input. The text from each element is on a separate
line
XML to Text n/a Extracts the text from all XML elements in the
input. The text is concatenated into one string
Items contents contain contains Extracts items whose text contains the specified
value
Element name contains contains Retrieves elements whose name contains the
specified value
Element name matches Node Name Retrieves elements whose name exactly matches
the specified value
Element attribute contains attribute, value Retrieves elements with a specific attribute that
contains the specified value
Element attribute range attribute, range Retrieves elements, including sub-elements, that
have a specific attribute whose value is contained
within the specified numeric range
Remove elements whose
attribute matches
attribute, value Removes items from XML with a specific
attribute matching the specified value
Remove elements whose
attribute contains
attribute, value Removes elements, including sub-elements, that
within a specified numeric range. The first
operand defines the name, and the second
operand defines the range
Remove elements in attribute
range
attribute, range Removes elements, including sub-elements, that
within the specified numeric range
Logical
Less Than Value These functions are self-explanatory
Less than or equal To Value
Greater than Value
Greater than or equal To Value
Is True n/a
Is False n/a
Equal To String String
Equal to Number Number
Not Equal to String String
Not Equal to Number Number
Math
Add number These functions are self-explanatory
Subtract number
Multiply number
Divide number
Modulo integer
Date and Time
Get From Date Day, Month (Number),
Month (Abbr), Month
(Full), Year (Short), Year
(Long), Hours, Minutes,
Seconds, AM/PM
These functions are self-explanatory
ISO Date (format) Year, Year and Month,
Date/Time (to min),
Date/Time (to sec), Date/
Time (exact)
ISO Date (parse) Year, Year and Month,
Date/Time (to min),
Time (exact)
US Date (format) Date/Time (to min),
Time (exact)
US Date (parse) Date/Time (to min),
Time (exact)
EU Date (format) Date/Time (to min),
Time (exact)
EU Date (parse) Date/Time (to min),
Time (exact)
Date Formatter Date to String, String to
Date
Uses the Java class SimpleDateFormat to convert
dates to strings or strings to dates
The codes in Table 5 on page 155 are used to
define the date and time format. For more
information, see the API documentation for the
Java class at http://sun.java.com.
Table 5: Date formatter codes
Letter Date or time component Examples
G Era designator AD
y Year 1996; 96
M Month in year July; Jul; 07
w Week in year 27
W Week in month 2
D Day in year 189
d Day in month 10
F Day of week in month 2
E Day in week Tuesday; Tue
a AM/PM marker PM
H Hour in day (0-23) 0
k Hour in day (1-24) 24
K Hour in AM/PM (0-11) 0
h Hour in AM/PM (1-12) 12
m Minute in hour 30
s Second in minute 55
S Millisecond 978
z Time zone (general) Pacific Standard Time; PST; GMT-08:00
Z Time zone (RFC 822) -0800
Note
The number of times a letter is repeated indicates the format of the string. For
example, yy results in the abbreviated format such as 96, while yyyy results in the full
year such as 1996.
Advanced transform editor overview
The Advanced transform editor uses XPath and XSLT expressions to transform
inputs and save the output as context items.
When you access the Advanced transform editor, a wizard opens to step you
through setting up a transform. You select either XPath or XSLT as the transform
type and can then select from XML samples and templates to build the expression.
These, along with tokens, can be selected with the wizard or selected and edited
within the transform editor window. Each subsequent time a defined transform is
accessed, the transform editor launches directly, displaying the existing expression
along with any associated XML sample and/or tokens. You use the transform editor
when defining rules.
The expressions are built and tested within the Advanced transform editor. These
expressions are entered in the Document pane. The transform expression can be
tested against an XML document sample using the Preview function. The XML
sample is used to test the expression and the results are displayed in a Preview
Drawer. Samples can be modified to accurately reflect the type of data transformed
during the actual process execution. These samples can be saved and used to test
future expressions. Sample responses for each BMC Atrium Orchestrator base
adapter are available.
Templates are provided for both XPath and XSLT expressions. These represent
common transforms and can be modified and saved as additional templates for use
in future transforms. With tokens you can incorporate values from previously
defined context items in the XPath or XSLT expression.
Sample pane
You can select and maintain XML samples through the resource area either from
step 2 of the transform editor Setup Wizard, or by using the Sample pane of the
XPath transform editor.
The Sample pane of the XPath transform editor consists of a toolbar and a sample
pane. The XML sample displayed in the Sample pane is used when previewing the
transform. The expression defined in the Expression Builder is executed against the
sample and the results are displayed in the Preview Drawer. You can modify a
displayed sample and save it, overwriting the original sample with the
modifications. The modifications can be saved as a new sample.
If a sample was not selected through the wizard, or if the current sample is no longer
the sample, you can open the samples file and select a new XML sample.
Note
Modified and additional user-defined samples should be stored under the My
Samples directory. With future BMC Atrium Orchestrator updates, the XML Sample
directory contents can be overwritten to reflect updates in the software. The contents
of the My Samples directory are excluded from any BMC Atrium Orchestrator updates.
To save a modified sample
1 With a modified sample displayed, click Save As in the Sample pane toolbar.
2 Type the name for the new sample in the File Name field at the top of the
window.
3 On the tree, click to select a location to save the new file.
4 Click OK to save the sample.
Token pane
In the Token pane, you use tokens to reference defined context items in an XPath
expression.
Within the XPath transform editor, context items are associated with user-defined
Token Names. For testing purposes, values are assigned. These values remain linked
with the transform for testing only; the actual values of the specified context items
are used during process execution. Sample values are assigned to Tokens for use in
the Preview function.
To add a token
1 Click the Add button in the Tokens pane toolbar.
2 In the newly added row, double-click the field in the Context Name column.
3 In the Context Browser, select the context item; then click Add Context.
4 Double-click the field in the Token Name column.
5 Type the token name; then click Enter.
6 Double-click the field in the Value column.
7 Type the test value; then press Enter.
8 In the Token Selector drop down menu, choose either the token name or the
appended token name.
To delete a token
1 In the Tokens pane, click the row of the token to be deleted.
2 Click the Delete button in the Tokens pane toolbar.
Document pane
The Document pane is the area used to create XPath expressions.
XPath expressions are created in the Document pane of the XPath transform editor.
This pane contains the Expression field, the XPath Helpers, the Token Selector, and
the toolbar. The functions within the document pane allow you to do the following:
Import a new document from the resource area. This clears the current expression
and displays the Resource Selection window from which a new template can be
selected.
Save the current expression to the resource area.
Preview the transform. The current expression executes against the selected XML
sample and the results are displayed in the Preview Drawer. If an XML sample is
not selected, the transform executes against a default XML document of <empty-
document/>.
XPath helpers
In the Document pane, XPath helpers are used to create XPress expressions.
To facilitate the creation of XPath expressions, the common functions have been
provided in drop-down menus. With the selection of the functions from these
menus, the proper syntax for the function inserts in the Expression field.
Group Function Description Syntax
String String Returns the value as a string string(.)
String Concat Concatenates a comma separated list of values
into a single string
concat(., 'text')
String Starts with Returns a value of 'true' or 'false' indicating
whether the sting begins with the specified text
starts-with(., 'text')
String Contains Returns a value of 'true' or 'false' indicating
whether the sting contains the specified text
contains(., 'text')
String Substring before Returns the portion of the string that precedes
the specified text
substring-before(.,
'text')
String Substring after Returns the portion of the string that succeeds
the specified text
substring-after(., 'text')
String Substring Returns a portion of the string, beginning at the
numeric position specified
substring(., number)
String String length Returns the number of characters in the string string-length(.)
String Normalize space Removes leading and trailing spaces from the
string
normalize-space(.)
String Translate Converts a string by replacing the characters in
'from' with the characters in 'to'
translate(.,'from','to')
Boolean Boolean Returns a Boolean value boolean(.)
Boolean Not Returns the opposite Boolean value not(.)
Boolean True Returns the Boolean value 'true' true()
Boolean False Returns the Boolean value 'false' false()
Number Number Returns the value as a number number(.)
Number Sum Returns the sum of numeric values for the
specified element
sum(.)
Number Floor Returns the smallest integer that is greater than
the specified number
floor(.)
Number Ceiling Returns the largest integer that is not greater
than the specified number
ceiling(.)
Number Round Rounds the specified number to the nearest
integer
round(.)
Operators Less than or equal Inserts the appropriate syntax for the function <=
Operators Less than Inserts the appropriate syntax for the function <
Operators Greater than or
equal
Inserts the appropriate syntax for the function >=
Operators Greater than Inserts the appropriate syntax for the function >
Operators Equal Inserts the appropriate syntax for the function =
Operators Not equal Inserts the appropriate syntax for the function !=
Operators Multiply Inserts the appropriate syntax for the function *
Operators Divide Inserts the appropriate syntax for the function div
Operators Modulus Inserts the appropriate syntax for the function mod
Operators Add Inserts the appropriate syntax for the function +
Operators Subtract Inserts the appropriate syntax for the function -
Operators And Inserts the appropriate syntax for the function and
Operators Or Inserts the appropriate syntax for the function or
Position Last Returns the index of the last child node last()
Position Position Returns the position of the current node, relative
to the parent node
position()
Position Count Counts the number of nodes count(.)
Position Name Returns the element name name(.)
To insert the function syntax for an XPath Helper
1 In the Document pane, use the Group menu to select the group.
2 Use the Functions menu to select the function.
3 Click the Insert button.
Tip
Use these steps to insert additional function syntax. The syntax inserts at the cursor.
To insert tokens in an XPath expression
1 Tokens are inserted in an XPath expression to use context items for the transform.
To define a token
1 Position the cursor in the Expression field at the point of token insertion. To
replace text in the current expression with the token, highlight the text to be
replaced.
2 Use the Token Selector drop-down menu and select the token.
Note
There are two choices in the drop-down menu for each token in the Tokens pane,
one with the token name and one with -esc appended to the token name.
3 Click the Preview button in the Document pane toolbar to execute the expression
and display the Preview Drawer.
XSLT transform editor
The XSLT transform editor consists of the Sample pane, the Tokens pane, the
Document tab, and the Source tab. The transform editor wizard launches to assist
with the creation of the initial transformation expression. After the expression is
created, when the Transform button is clicked the XSLT transform editor window is
displayed, populated with the current expression. The XML sample and any tokens
that were defined with the expression will be saved with the expression.
Sample pane
XML Samples are selected and maintained through the resource area either from
step 2 of the transform editor setup wizard or via the Sample pane of the XSLT
transform editor. The Sample pane of the XSLT transform editor consists of a toolbar
and a sample pane. The XML sample displayed in the Sample pane will be used
when previewing the transform. The expression defined in the Document pane is
executed against the sample and the results are displayed in the Preview Drawer.
You can modify a displayed sample and save it, overwriting the original sample
with the modifications. The modifications can be saved as a new sample.
If a sample was not selected through the wizard, or if the current sample is no longer
the sample, you can open the samples file and select a new XML sample. If a sample
is not selected, an <empty-document/> XML document is used as a default.
Note
Modified and additional user defined samples should be stored under the 'My
Samples' directory. With future BMC Atrium Orchestrator updates, the XML Sample
directory contents can be overwritten to reflect updates in the software. The contents
of the 'My Samples' will be excluded from any BMC Atrium Orchestrator updates.
To save a modified sample as a new sample
1 With a modified sample displayed, click the Save As button in the Sample pane
toolbar.
2 Type the name for the new sample in the file name field.
3 On the tree, browse to the location for the new file to be saved.
4 Click OK to save the sample.
Tokens pane
Tokens provide you with the ability to incorporate values from previously-defined
context items in an XSLT expression.
Within the XSLT transform editor, context items are associated with user defined
Token Names. For testing purposes, values are assigned. These values remains
linked with the transform for testing only, the actual values of the specified context
items are used during process execution. Tokens cannot be used in XPath
expressions executed against Adapter events. The Token pane is not present in the
transform editor launched from the Rules Designer.
To add a token
1 Click the Add button in the Tokens pane toolbar.
2 Double-click the field in the context name column.
3 Select the context item and click Add Context.
Tip
If the context item selected is a global context item, the globe icon displays in the
column to the right of the Context Name.
4 Double-click the field in the Token Name column.
5 Type the token name; then press Enter.
6 Double-click the field in the Value column.
7 Type the test value; then press Enter.
To delete an existing token
1 In the Tokens pane, click the row of the token to be deleted.
2 Click the Delete button in the Tokens pane toolbar.
Source pane
The Source pane provides a read-only view of the current XML document created
for the transform expression that has been created in the Document pane.
Document pane
The Document pane is the area used to create XSLT transforms.
The Document pane of the XSLT transform editor consists of the following areas: the
Node Palette, the Stylesheet Canvas, the Node Property Panel, and the toolbar.
XSLT Transforms are created by dragging and dropping node buttons from the
Node Palette to the Stylesheet Canvas. Nodes can be added by right-clicking on an
existing node on the Stylesheet Canvas and selecting a node from the pop-up menu
displayed. One advantage of the pop-up menu is that the nodes are filtered; only
allowable nodes can be selected, based on the current node. Each Stylesheet Canvas
is populated with the Output and Template nodes by default.
Each node that can be used to create an XSLT Transform has an associated Property
Panel with function specific fields. Required fields are indicated with bold font.
When values have been entered for all required fields in the Property Panel, click
Apply to save the values for that node and to continue working in the Stylesheet
Canvas. The Stylesheet Canvas will not be active until all required fields have been
populated and the Apply button has been clicked. The Property Panel for any
existing node can be viewed by clicking on that node.
Tip
Double-clicking on a node will toggle between collapsing and expanding any
associated child nodes.
In addition to the functions available in the toolbar, there are functions in the pop-up
menu that facilitate working with the nodes on the Stylesheet Canvas. This pop-up
menu is accessed by right-clicking on a node on the Stylesheet Canvas.
The functions on the menu become active as appropriate for the selected node.
Nodes are grouped on the Node Palette by type: Template, Parameter, Text, and
process.
Menu Item Description
Add Contains a submenu of all nodes that can be placed on the Stylesheet Canvas. Based on
the currently selected node, all nodes that can be added as a child to the selected node
will be active on the menu.
Move up Moves the selected node up one position.
Move down Moves the selected node down one position.
Demote Moves the selected node down one level. The selected node will become a child of the
node immediately above it.
Promote Moves the selected node up one level. The selected node will become a peer of its
current parent node.
Delete Deletes the selected node.
Duplicate Duplicates the selected node and places it on the Stylesheet Canvas below the selected
node, as a peer.
Expand all Expands all child nodes below the currently selected node.
Collapse all Collapses all child nodes below the currently selected node.
Stylesheet template nodes
The stylesheet template contains tools, referred to as nodes, that assist you in
defining the transform.
Stylesheet
By default, the Stylesheet node is the top node on the Stylesheet Canvas.
This node is required and cannot be deleted.
Field Description Required
Version Menu used to select the XSL version. Valid value: 1.0 Yes
Namespace The default value of http://www.w3.org/1999/XSL/Transform is provided.
Except in highly customized XSLT environments, the default namespace
should be used.
Yes
Additional
Namespaces
Button used to access the Additional Namespaces window. This advanced
function is used to define optional extensions to be included in XPath Select
statements.
NA
Additional namespaces
You can define additional namespace records. These records are used to define an
extension that can be included in an XPath Select statement, the property panel of an
Element node, or the Property Panel of an Attribute node.
To add a namespace
1 From the Stylesheet property panel, click Additional Namespaces.
2 Click the Add button in the right toolbar to add a record to the table.
3 Double-click the field in the record's Prefix column; then enter the prefix.
Tip
This value must be a qualified name (Qname), beginning with a letter, colon or
underscore and consisting of alphanumeric characters, underscores or dashes.
4 Double-click the field in the URI column, and enter the URI that points to the
schema for the extension.
5 When all namespaces have been added or removed, click OK.
Note
Records can be deleted by clicking the record to be removed and then clicking the
Delete button.
Output node
The Output node controls the format and appearance of the output generated by the
transform.
By default, an Output node is the second node on the Stylesheet Canvas.
Format Defines the encoding format for the XML output. Common values
include: UTF-8, ISO-8859-1, Windows-1252 and UTF-16. If this field is left
blank, an UTF-8 encoding value is assumed.
No
Indent Output Indicates whether the output generated by the transform should be
indented. If this box is unchecked, the output will not be indented, and it
will be contained on one continuous line.
Note: Indenting the output can increase the document size. If the output
is to be used only by downstream processes, and not read by people, you
should leave this box unchecked.
NA
CDATA Displays the elements whose values will be wrapped in CDATA. This
enables values that can contain XML special characters to be parsed
properly. To add elements to this field, use the Edit button.
No
Selecting elements for CDATA
Element values that can contain XML special characters need to be wrapped in
CDATA to prevent parsing issues. All elements can be selected to be CDATA
wrapped. Processing speed is not impacted by CDATA wrapping.
To select elements for CDATA
1 From the Output Property Panel, click the Edit button to display the available
elements from the selected XML sample and from the existing elements in the
Stylesheet Canvas.
2 Select the check box to the right of each element whose value should be wrapped
in CDATA.
Tip
Click Select all to choose all elements on the list at once.
3 Click Add to add an element to the list.
4 Double-click the record to enter the element name.
5 Double-click the element to edit it.
Tip
To delete an element, select it and click Delete.
Template
A template is used to contain rules to apply when a specified node is matched. At
least one Template must be defined for a style sheet.
The match criteria used against the source document determines the transforms
(rules) that are executed. The value of the Match field is an XPath expression. A
Match of '/' defines the entire XML document. By default, this is the third node on
the Stylesheet Canvas.
Name Unique reference for this template.
This value must be a qualified name (Qname), beginning
with a letter, colon or underscore and consisting of
alphanumeric characters, underscores or dashes.
Conditional
A Template must contain a value for
either the Name or Match field. A
value can be defined for both.
Match XPath expression that defines a portion of the XML
document on which the transforms in the Template's
child nodes will be executed.
Conditional
A Template must contain a value for
either the Name or Match field. A
value can be defined for both.
Mode An alphanumeric value, token or XPath expression that
will be used in the Apply Templates node to indicate
that this template will be applied.
No
Priority Numeric value, either positive or negative, that indicates
the order in which the template is called in the event
there are multiple templates with the same Mode value.
No
When adding a Template node to the Stylesheet Canvas, the Add Nodes to Selection
window appears.
This feature allows you to mark any available nodes to be added as child nodes and
placed on the canvas. For the Template node, the Parameter and Element nodes will
be available. Check the child nodes and click OK. The selected nodes will be placed
as children.
The Property Panel configuration for each of the child nodes added with the Add
Nodes to Selection window will need to be completed individually.
Apply templates node
The Apply Templates node applies a template to the current element or to the
current element's child nodes.
The placement of this node on the Stylesheet Canvas indicates the starting point in
the stylesheet where a template match should be applied. When adding an Apply
Templates node to the Stylesheet Canvas, the Add Nodes to Selection window displays.
This feature allows you to mark any available nodes to be added as child nodes. A
With Parameter node will be available. Check the child nodes and click OK. The
selected nodes are placed as children.
Select The XPath expression. Yes
Mode An alphanumeric value, token or XPath expression that corresponds to the
value of the Mode field defined in a Template node. All templates for which
an identical Mode value exists will be applied.
No
XPath Helpers
(Groups /
Functions)
The XPath helpers, Groups and Functions are used to facilitate the
formation of basic XPath statements.
NA
Nodes to Selection window must be completed individually.
Call template
The Call Template node calls a specifically named Template execute. The placement
of this node on the Stylesheet Canvas indicates the starting point in the stylesheet
where a named Template should be called.
This feature marks any available nodes added as child nodes and placed on the
canvas. For the Call Template node, the With Parameter node is available. Check the
child nodes and click OK. The selected nodes are placed as children.
Name Specifies the Name defined in the Template to be called.
Note: This value must be a qualified name (Qname), beginning with a letter,
colon, or underscore and consisting of alphanumeric characters, underscores,
or dashes.
Yes
Strip space
The Strip Space node defines elements that require removal of white space. This is a
top level node and can only be a child node of Stylesheet.
Elements Displays the elements whose values will have white space removed. To add
elements to this field, use the Edit button.
No
To select Strip Space node elements
1 From the Strip Space Property Panel, click the Edit button.
The Element List window appears.
The available elements from the XML sample and from the existing elements in
the Stylesheet Canvas displays on the list.
2 Click the check box to the right of each element whose value should have white
space removed.
Alternately, click Select all to select all elements on the list at one time.
Clicking the Unselect all button clears all check boxes, indicating that no
elements will have white space removed.
3 Click Add to add an element to the list.
5 If necessary, double-click the element to edit and enter the element name.
7 Double-click the element to edit it.
Tip
To delete an element, select it and click Delete.
8 Click OK.
Preserve space node
The Preserve Space node defines elements for which white space should be
preserved. This is a top-level node and can only be a child node of Stylesheet.
Element values that contain desirable white space can be designated to have that
white space preserved.
Elements Displays the elements whose values will have white space preserved. To
add elements to this field, use the Edit button.
No
To select elements
1 From the Preserve Space Property Panel, click the Edit button.
The available elements from the sample and from the existing elements in the
Stylesheet Canvas displays on the list.
2 Click the check box to the right of each element whose value should have white
space preserved.
Tip
If there are elements that will be present in the actual source that are not in the
sample, they can be added manually to the list.
3 Click the Add button in the right toolbar to add an element to the list.
5 Double-click the element to edit and enter the element name.
6 Click OK.
Parameter nodes
Parameter nodes are used in transforms to declare global or local parameters and
variables.
There are two types of parameter nodes:
Param node - Declares a global or local parameter.
Variable node - Declares a global or local variable.
Param node
The Param node is used to declare a global or local parameter.
Global parameters are defined by placing the Param node as a top-level node. Local
parameters are defined by placing the Param node as a child of a Template node.
Table 6: Param node properties
Name Parameter name for which a value will be defined.
This value must be a qualified name (Qname), beginning with a
letter, colon or underscore and consisting of alphanumeric
characters, underscores, or dashes.
Yes
Select The XPath expression used to define the parameter's value. Yes
XPath Helpers
(Groups / Functions)
NA
Variable node
The Variable node is used to define a value for a global or a local variable.
When the Variable node is placed as a child node of a Template node, it defines a
local variable. A global variable is defined when the Variable node is placed in the
top level of the style sheet.
Variables are used in conjunction with the Copy of node. A variable is specified in
the Select field of the Copy of Property Panel as $<name> where <name> is the
value defined in the Name field of a Variable node.
Table 7: Variable node properties
Name Variable name for which a value will be defined.
This value must be a qualified name (Qname), beginning with a
letter, colon or underscore and consisting of alphanumeric
characters, underscores or dashes.
Yes
Select The XPath expression used to define the variable's value. Yes
XPath Helpers
The XPath helpers, Groups and Functions, are used to facilitate the
NA
With Param node
The With Param node is used to define a value for a parameter that will be passed
into a Template.
This node can only be placed on the Stylesheet Builder Canvas as a child node of an
Apply Templates or a Call Template node.
Name Parameter name for which a value will be defined. This Name must match
the Name specified in the Param node of the Template being applied or called.
This value must be a qualified name (Qname), beginning with a letter, colon
or underscore and consisting of alphanumeric characters, underscores or
dashes.
Yes
Select The XPath expression used to define the parameter's value. Yes
XPath Helpers
(Groups /
Functions)
NA
Text nodes
The text nodes include the Element, Attribute, Comment, XML comment, Text, Copy
of, Value of, Copy, Token, Number, and Decimal format nodes.
Element node
The Element node is used to create an element in the resulting XML document.
Table 8: Element node properties
Name The name of the element to be created. Element names can consist
of alphanumeric characters and dashes.
Yes
Prefix A previously defined Prefix. This value is defined using the
Additional Namespaces function, available in the Property Panel
of the Stylesheet node. This is not typically defined for each element.
No
Namespace Namespace URI for the namespace to be applied to this element.
This is not typically defined for each element.
No
When adding an Element node to the Stylesheet Builder Canvas, the Add Nodes to
Selection window displays.
This feature allows you to mark any available nodes to be added as child nodes.
Attribute, Text, Element, Apply Templates, Call Template, and Value Of nodes are
available. Check the child nodes and click OK. The selected nodes will be placed as
children.
Attribute node
The Attribute node is used to create an attribute for an element in the resulting XML
document.
This node can only be placed on the Stylesheet Canvas as a child node of an Element
node. If an attribute is for an element, the Attribute node must be the first child node
for that Element. This feature allows you to mark any available nodes to be added as
child nodes. Text and Value Of nodes will be available. Check the child nodes and
click OK. The selected nodes will be placed as children.
Table 9: Attribute node properties
Name The name of the attribute to be created. Attribute names can consist of
alphanumeric characters and dashes.
Yes
Prefix A previously defined Prefix. This value is defined using the Additional
Namespaces function, available in the Property Panel of the Stylesheet
node. This is not typically defined for each attribute.
No
Namespace Namespace URI for the namespace to be applied to this attribute. This is
not typically defined for each attribute.
No
Nodes to Selection window needs to be completed individually.
Comment node
The Comment node is used to write a comment to the resulting XML document.
Table 10: Comment node properties
Comment The comment to be written to the resulting XML document.
For example, a Comment of XXX will be output to the resulting
XML document as 
No
XML comment node
The XML Comment node is used to write internal comments within the style sheet.
These comments are not output to the resulting XML document.
Table 11: XML comment node properties
Comment The internal comment to be written within the style sheet. No
Text node
The Text node is used write literal text to the resulting XML document.
Table 12: Text node properties
Text The string to be written to the resulting XML document. No
Disable output
escaping
Indicates whether XML special characters should be escaped in the
resulting XML document or output exactly as specified in the Text field.
For example, if the Text field contained a < character, with this option
unchecked, the resulting value would be < . If this option is checked,
the resulting value would be unchanged.
NA
Copy of node
The Copy of node copies a segment of the source document to the resulting XML
document, using an XPath expression to define the segment to be written.
Table 13: Copy of node properties
Select The XPath expression used to define the segment of the source
document to be written to the resulting XML document.
Yes
XPath Helpers
NA
Value of node
The Value of node extracts a value from the source document to write to the
resulting XML document, using an XPath expression to define the value to write.
Table 14: Value of node properties
Select The XPath expression used to define the segment of the source document
to be written to the resulting XML document.
Yes
XPath Helpers
(Groups /
Functions)
NA
Disable output
escaping
Indicates whether XML special characters should be escaped in the
resulting XML document or output exactly as extracted from the source
document.
For example, if the source document contained a < character that would
be contained in the resulting value, with this option unchecked, the
resulting value would be < . If this option is checked, the resulting
value would be unchanged.
NA
Copy node
The Copy node is used within a Template node. Based on the Match value for the
Template node, the Copy node copies the current node, excluding child nodes and
attributes of the current node, to the resulting document. The placement of this node
on the Stylesheet Canvas indicates the point in the style sheet where to copy the node.
There are no properties associated with the Copy node.
Token node
The Token node can be used to insert complex XML into the XSL document before
processing.
Table 15: Token node properties
Tokens Complete XML document. This document will be inserted into
the XSL before executing the transform.
No
Number node
The Number node is used to determine the integer position of a node or to format a
number.
The Value, Grp Sep, Grp Size fields apply to numeric formatting, the remaining six
fields apply to counting.
Table 16: Number node properties
Value The numeric value to be formatted. No
Grp Sep Specifies the grouping separator used to separate groups of digits. The default
value is a comma (,).
No
Grp Size Specifies the number of digits in each group. Each group will be separated by the
character defined in the Grp Sep field, and will count from right to left to establish
groups. The default value is 3.
No
Count An XPath expression used to specify the nodes in the source document to be counted. No
From An XPath expression used to specify the starting point for counting in the source
document.
No
Level Drop-down menu used to select the method for assigning the sequence number.
Valid values: single, multiple, any
No
Format Defines the output format for the number.
Valid values for Format:
1 (output format of 1 2 3)
01 (output format of 01 02 03)
a (output format of a b c)
A (output format of A B C)
i (output format of i ii iii iv)
I (output format of I II III IV)
No
Lang Specifies the language alphabet to be used for the numbering. No
Letter Drop-down menu used to select the numbering style for the language defined in
the Lang field. The default value is alphabetic.
Valid values: alphabetic, traditional
No
Decimal format node
The Decimal format node can be used to define the characters and symbols to be
used when converting numbers into strings.
The Name defined for this node is used in XPath expressions with the format-
number function. This is a top-level node and can only be a child node of Stylesheet.
Multiple Decimal Format nodes can be placed in a single Stylesheet, each with a
unique name.
Table 17: Decimal format node properties
Name The unique name for this format. No
Infinity Defines the string used to represent infinity. The default value is 'Infinity'. No
Decimal Sep Defines the character for the decimal point. The default value is period (.). No
Grp Sep Defines the character for the thousands separator. The default value is a
comma (,).
No
Mile Defines the character for the per thousand sign. The default value is '0/00'. No
Digit Defines the character to use when indicating a digit is required. The default
value is '#'.
No
Zero Defines the character to use for the digit zero. The default value is '0'. No
Pattern Sep Defines the character used to separate positive and negative sub patterns in a
format pattern. The default value is a semi-colon (;).
No
Percent Defines the character to use as a percentage sign. The default value is '%'. No
NaN Defines the string to use when the value is not a number. The default value is
'NaN'.
No
Minus Defines the character to use to indicate negative numbers. The default value is
a minus sign (-).
No
Process nodes
Process nodes are used in transforms to sort output data and perform actions when
specified conditions are met.
There are six supported process nodes.
For Each node - Contains nodes to execute against a specified note set
Sort node - Sorts the output and always must work in conjunction with a For Each
or Apply Templates node.
If - Processes child notes based on specified conditions.
Choose - Specifies a set of nodes that conditionally execute. This node is used in
conjunction with only one Otherwise node or with one or more When nodes.
When - Processes child nodes based on a conditional test. This node is used as a
child of a Choose node. Although many When nodes can be defined only the first
'true' case executes.
Otherwise - specifies the nodes to process if all When nodes evaluate to 'false'.
For Each node
The For Each node can be used to contain a node or series of nodes to be executed
against a specified node set.
The nodes to be executed are placed as children to the For Each node. Each child
node of the For Each is performed on each matching segment.
Table 18: For each node properties
Select The XPath expression used to define the node set. Yes
XPath Helpers
NA
When adding a For Each node to the Stylesheet Canvas, the Add Nodes to Selection
window is displayed.
This feature allows you to mark any available nodes to be added as child nodes. Sort,
Apply Templates and Call Template nodes are available. Check the child nodes and
click OK. The selected nodes are placed as children.
Sort node
The Sort node is used to sort the output.
This node is always used within a For Each or an Apply Templates node. The sort
options are applied on a per position basis within the value. If there is a conflict,
priority is given to the case preference.
Table 19: Sort node properties
Select XPath statement that defines the node or node set on which to sort. If an
XPath statement is not defined, the default node is the element.
No
Language Defines the language to be used for the sort. No
Date Type Defines the data type of the data to be sorted. The default value is 'text'.
Valid values: text, number
No
Ascending Sort Indicates whether the data sort in ascending order. The default value is
checked or true.
No
Upper Case First Indicates whether upper case letters sorts before lower case letters. The
default value is checked or true.
No
XPath Helpers
(Groups /
Functions)
NA
The follow sections illustrate output based on different selections in the Property
Panel for a Sort node.
Data Type - text vs. number
For the following sample: 10,2,1
The output order would be 1,10,2 with a data type of 'text' and it would be 1,2,10
with a data type of 'number'.
Upper Case First - checked vs. unchecked
For the following sample: Abc, abc, aBc
The output would be Abc, aBc, abc with the Upper first selection checked and it
would be abc, aBc, Abc with the Upper first selection unchecked.
If node
The If node can contain one or more child nodes that process based on a conditional
test. The nodes are placed as children to the If node. Each child node of the If
executes against each segment that tests true for the conditional statement provided.
Table 20: If node properties
Test The XPath expression used to determine if the child nodes should be
processed.
Yes
XPath Helpers
(Groups /
Functions)
NA
Choose node
The Choose node can be used to execute a conditional set of nodes.
The Choose node is used in conjunction with one or more When nodes and no more
than one Otherwise node. These nodes are children of the Choose. The When nodes
are applied in sequence using a match first method. The first When node that
evaluates to a true case will be executed. If no When nodes evaluate to true, the
Otherwise node executes. If no Otherwise has been defined, nothing executes. This
feature marks any available nodes to be added as child nodes. When and Otherwise
nodes are available. Check the child nodes and click OK. The selected nodes are
placed as children. When adding a Choose node to the Stylesheet Canvas, the Add
Nodes to Selection window displays.
There are no properties associated with the Choose node.
When node
The When node is used to process child nodes based on a conditional test.
The nodes to process if the conditional case is true are placed as children of the
When node. The When node is used as a child of a Choose node. Multiple When
nodes can be defined under a Choose node, but only one, the first true case, executes.
Table 21: When node properties
Test The XPath expression used to determine if the child nodes should
be executed.
Yes
XPath Helpers
NA
Otherwise node
The Otherwise node can be used to contain a node or a series of nodes to be
processed in the event all When nodes under a Choose node evaluate to false. The
nodes to be executed are placed as children to the Otherwise node. The Otherwise
node is always a child of a Choose node, following the When nodes.
There are no properties associated with the Otherwise node.
XPath transform editor
The XPath transform editor is used to create and test any XPath expression applied
against a defined input. You use the transform function to format data or segments
of data.
The Advanced transform editor uses XPath to format or extract segments of data and
assign the output to context items. XPath is an expression language used by XSLT to
access or refer to parts of an XML document. XPath is used by the XML Linking
specification. The XPath transform editor consists of three panes: the Sample pane,
the Tokens pane, and the Document pane.
Activities
This chapter describes how to use activities to create processes. The following
sections provide information on the function and configuration of each type of
activity that you can use in a process.
Activities overview
A process is a set of linked activities that perform specific functions. When you
create a process in BMC Atrium Orchestrator Development Studio, you can use an
unlimited number of activities. All processes begin with the Start activity and
terminate with the End activity. The only activity that depends on an external system
in order to be used in BMC Atrium Orchestrator Development Studio is the
Integration Mapping activity. The following table describes the available activities.
Table 22: Available activities
Activity Description
Start Represents the beginning of a process
When you create a process, the Start activity is automatically placed on
the process canvas and it cannot be deleted. All activities in a process
originate from the Start activity.
End Represents the end of a process
When you create a process, the End activity is automatically placed on
the process canvas and it cannot be deleted. All activities in a process
terminate in the End activity.
Assign Assigns values to a context item
In the individual assignment statements, data can be transformed or
appended together.
9
Activity Description
Operator Dialog Defines user inputs that will be requested during the execution of the
process
This activity is used only for process exposed in the BMC Atrium
Orchestrator Operator Control Panel. If the process is being run
through the BMC Atrium Orchestrator Operator Control Panel, it will
ask you for input. If it is being run by some method other than BMC
Atrium Orchestrator Operator Control Panel, the user inputs will be
supplied with default values, if defined.
Switch Creates conditional paths in a process
A Join object is automatically added to a Switch activity.
For Allows iterative processing of data in a process
Spawn Allows two or more process paths to be executed in parallel
Launch Job Launches a new process asynchronously
Utility Performs functions on string, numeric, and date type values
Metrics Records metrics for a process
Pause Suspends a process for a specified amount of time
Script Executes scripts that are written in the activity or called by the activity
Call Adapter Executes an action on an actor adapter running on the grid
Integration Mapping Some adapters, such as the BMC Remedy adapter, support tight
integration with processes. This activity interacts with those adapters to
quickly map external system data to and from context items.
Start activity
All processes contain a Start activity.
When you create a process, the Start activity is automatically connected to the End
activity. All processes originate from the Start activity. You map input parameters to
context items through the Start activity.
Start activity properties
The Property Panel for a Start activity consists of a single tab, Properties. To display
the Property Panel, double-click the Start activity. You add parameters by clicking
the Add button on the Properties tab. The following table provides detailed
descriptions of each field on the Properties tab of the Start activity.
Start activity
Table 23: Property panel fields for the Start activity
Field Description
Input Parameter Name Defines an input parameter that can have a value assigned
and can be used by activities in this process. If the Context
Name value is set before the Input Parameter Name value is
set, then the Input Parameter Name defaults to match the
Context Name.
If a process is exposed as SOAP, the initial character must be
a letter and can be followed by any combination of letters,
numbers, spaces, hyphens, dashes, periods, and underscores.
Context Name The name of the context item associated with the input
parameter name. This context item will be used within the
process to access the Input Parameter's value. If Input
Parameter Name is set before Context Name is set, then
Context Name defaults to match Input Parameter Name. This
field is edited using the Context Browser, which can be
launched by double-clicking the field.
Note: If this parameter is assigned to a global context item,
then a globe icon will appear to the left of the name.
Required Check box used to indicate whether this input parameter is
required for this process.
If a value is not provided for an input parameter that has
been designated as required prior to the execution of the
process, the process will fail and will trigger compensation.
If a value is not provided for an input parameter that has
been designated as not required prior to the execution of the
process, that input parameter will automatically be assigned
a value of an empty string.
TTL(mSec) Indicates the Time to Live for the context item. This is
assigned with the creation of a context item and can be edited
by double-clicking in the field.
Description Description of the input parameter to indicate the type of
value and expected purpose within the process.
End activity
Every process terminates with an End activity, which is automatically placed on the
process canvas when the process is created. You define context items to output
parameters through this activity.
Context items that are used within a process are mapped to an output parameter by
using the End activity. These output parameters are returned to a process that calls
the current process. The Property Panel for an End activity consists of a Properties tab.
End activity
An output parameter can be added to an End activity for each context item
populated in the process. For more information, see To add an output parameter to
the End activity on page 182.
After a record has been added, mappings can be assigned to the record fields.
Table 24: Property panel fields for the End activity
Field Description
Output Parameter Name The output parameter associated with a context item. This output
parameter returns a value to a calling process. If you run this process in
the Operator Control Panel, it displays this value to the operator when the
process completes. Output parameters are mapped to a context item
through the Call Process activity in the calling process.
If a process will be exposed as SOAP, the initial character must be a letter
and can be followed by any combination of letters, numbers, spaces,
hyphens, dashes, periods, and underscores.
Context Name The name of the context item in which a value was stored during the process.
Required Indicates whether this output parameter is required for the process.
If a value is not available for an output parameter that has been marked as
required, compensation will be triggered.
TTL(mSec) Indicates the time to live for the context item. This is assigned with the
creation of a context item and can be edited by double-clicking within the
cell.
Description Description of the output parameter to indicate the type of value and
expected purpose within the process.
The buttons on the toolbar in the upper right of the table can be used to add
additional items and to reorganize, edit, and delete existing items.
To add an output parameter to the End activity
1 Double-click the End activity to display the property panel.
2 To add one parameter, double-click the Context Name field.
3 In the Context Browser, perform the appropriate action.
a If you want to use an existing context item, highlight it and click Select.
b If you want create a new context item, click New. Then complete the Create
New Context screen, and click OK.
To add multiple output parameters to the End activity
1 Double-click the End activity to display the property panel.
End activity
2 To add multiple parameters, click the Multi-add button.
3 Select the context items you want to add.
You can select a range of context items to add by selecting the first item, then
Shift and click to select the last context item. To add noncontiguous context items,
Ctrl and click to select the context items.
4 Click Select.
Assign activity
The Assign activity is used to assign values to one or more context items. You can
assign a string, numeric value, date, XML, context item, dynamic context, or module
configuration values. You can apply transforms to the string, XML, context item,
module configuration, or dynamic context types.
You can also use the Assign activity to remove a context item or a dynamic context.
The Property Panel for an Assign activity displays the Properties, Logging, and
Metadata tabs.
Table 25: Property panel fields for an assign statement
Field Description
Description The description of the assign statement
Parameter Type Specifies the type of input defined.
Valid values: String, Numeric, Date, XML, Context item, Module
configuration, System parameter, Dynamic context
Varies based on Parameter Type The name of this input varies, depending on which parameter type you
select. Possible inputs include:
Name
Value
Module Configuration
A globe icon is displayed for global context items.
Context type The context item or dynamic context defined as the output.
Context name The name of the context.
Concept Indicates if the context item is used in a concept.
Assign activity
Field Description
Concept Type The concept type used for the output. This field is available only if the
Concept check box is selected
Concepts are optional. For more details, see the BMC Atrium Orchestrator
Operations Actions Management User Guide.
Creating an assign statement
When you create an assign statement, you assign context items in the table in the
Properties tab for the Assign activity. You can create multiple assignments in a single
Assign activity.
To add a new assign statement
1 Drag an Assign activity from the Activity Palette to the process canvas.
2 Double-click the Assign activity on the process canvas.
3 Click the green plus (+) at the top of the property panel to create a new assign
statement.
4 (optional) Enter a description of the assign statement in the Description field.
5 Enter the value to assign in the Input pane:
a Select the input parameter type.
b Assign the appropriate input for the selected parameter type.
Table 26: Types of parameters for assign statements
Parameter type Description
String Assigns a string value. Any string value can be typed into the input box.
To add the contents of a context or configuration item to the string, use the
Insert Context/Config button to the right of the input area. Multiple context and
configuration items can be added to a single string.
To use predefined XML samples from resources, or to save the contents of the
input box as a resource, use the buttons to the left of the input box.
Note: If you insert a context item containing XML in the string input area, when
BMC Atrium Orchestrator evaluates the input, it considers only the values in the
root tag of the XML.
Numeric Assigns a numeric value. Type a numeric value.
Assign activity
Parameter type Description
Date Assigns a date. Use the Calendar button to the right of the Value box to select
the date and time.
All dates are stored in UNIX Epoch Time format.
XML Assigns an XML document. Type the XML into the input box. The contents of
the input box must be a valid XML document.
To add the contents of a context or configuration item to the XML, use the Insert
Context/Config button to the right of the input area. Multiple context or
configuration items can be added.
To use predefined XML samples, or to save the contents of the input box as a
resource, use the buttons to the left of the input box.
Context Item Assigns a value from a previously defined context item to this context item.
Use the Context Browser button to add the name of the context. The Edit button
(pencil) can be used to manually enter or edit a context name.
Note: Note that new contexts can be created using the Context Browser and Edit
buttons in the assignment input section; however, if the context name is not
created by a previous step in the process, an undefined context error might
occur when the process executes.
Module Configuration Assigns a module configuration item or group.
You can select any item in the Module Configuration hierarchy tree. Selecting
leaf nodes enables you to select an individual configuration item. Selecting a non-
leaf node enables you to select an XML document containing all children of that
node.
System Parameter Assigns a system value determined at process run time.
Dynamic Context Assigns a dynamic context to a context item. Use the Context Browser button to
add the context item containing the name of the dynamic context item.
6 (optional) To use a transform to assign a more specific value to an input parameter
type of XML, context item, dynamic context, or module configuration, click Basic
or Advanced to open a transform editor.
The down arrow on the right of the Transform button can be used to select the
Basic transform editor or the Advanced transform editor.
7 Enter a context item for the output in the Output pane.
a Select a context type.
Assign activity
Table 27: Context types for assign statements
Context type Description
Context Item Specifies the name of a context in which to store the result. Enter the context
name by selecting it with the Context Browser, or type it using the Edit button
(pencil).
If you select an existing context, the contents of that context will be replaced. If a
new context name is entered, new context item will be created.
Dynamic Context Specifies the name of a context that contains the name of the dynamic context.
Select the context name using the Context Browser.
Remove Visible only if the input parameter type is Context Item or Dynamic Context.
Specifies a dynamic context item named by using the Input pane.
The dynamic context item removed is named by the contents of the context item
or dynamic context item in the input section.
8 (optional) To store the assign statement result in a concept element in a context:
a In the Output pane, select the Concept check box, and then select a Concept
Type hierarchy.
b Click OK to save the assign statement and return to the Assign activity
properties.
c Click OK to save the Assign activity and return to the design canvas.
Deleting a context with an assign statement
Context items and dynamic contexts can be removed from the local or global context
store by using an Assign activity.
To delete a context item or dynamic context
1 Double-click an Assign activity on the process canvas.
2 Click Add.
3 Enter the deletion statement name in the Description field.
4 Define the context item or dynamic context that you are deleting in the Input
pane:
a Click Browse to launch the Context Browser.
Assign activity
b Select the Parameter Type option: Context item or Dynamic context.
c Select the context name from the global or local context list.
5 In the Output pane, use the Context Type menu to select Remove.
6 Click OK.
The Properties summary view is redisplayed, showing the added assign
statement. The Output Name column contains a button with a red slash,
indicating the context item to be deleted.
7 Click OK.
Operator Dialog activity
The Operator Dialog activity enables the workflow operator to interact with a
process at runtime through the BMC Atrium Orchestrator Operator Control Panel.
The BMC Atrium Orchestrator Operator Control Panel is a web application within
BMC Atrium Orchestrator.
You can test processes that use an Operator Dialog activity in BMC Atrium
Orchestrator Development Studio. When you use an Operator Dialog activity, the
values you enter during execution are mapped to context items and for use in activities.
The Operator Dialog window has a header and a description that you provide. You
can use the description field to provide information to the person responsible for
running the operator process. You determine the type of inputs, specify if the inputs
are required, and a default value. The Operator Dialog activity can contain an
unlimited number of inputs and types. By default, none of the inputs is required.
There are six input types that used to define an operator input:
String
Password
Numeric
Date
Boolean
List
String input
The string input type prompts the operator for a string value. From the Properties
tab of the Operator Dialog Property Panel, use the following steps to add a string input.
To add a string input
1 In the Properties tab of the Operator Dialog Property Panel define the optional
Header and Description fields, and then click the Add button to begin creating an
input in the Inputs table.
2 Select the row and then select the cell to enter the input label for this input; then
press Enter.
3 If the operator must provide a value at run time, select the check box in the
Required column.
4 If the value is a string value, click the field in the Specialized Definition column
and type the default string; then press Enter.
5 To map the value to a context item, click the field in the Context column.
6 Select or create the context item.
7 When you have added all inputs, click OK.
Password input
The password input type prompts the operator for a password input that is assigned
to a specified context item. In BMC Atrium Orchestrator Development Studio, the
default password will be displayed on screen in the Property Panel for the designer.
In the BMC Atrium Orchestrator Operator Control Panel, and in BMC Atrium
Orchestrator Development Studio during testing, the password displays as asterisks
(*) to the operator in the Operator Dialog window. From the Properties tab of the
Operator Dialog Property Panel, use the following steps to add a password input.
To add a password input
1 Type the value for the Header and Description fields; then click the Add button.
2 Select the row, then select the field in the Type column.
3 Click Password.
4 Click the field in the Label column.
5 Type the label that displays in the dialog window for this input; then press Enter.
6 If a value is required, check the box in the Required column.
7 If the password has a default value, click the field in the Specialized Definition
column and type the password; then press Enter.
8 To map the input value to a context item, click the field in the Context column.
9 In the Context Browser select or create the context item to map.
10 Use steps 1 - 9 to add additional password inputs.
Numeric input
The numeric input type prompts the operator for a numeric value that is assigned to
a specified context item. An integer value displays as a decimal value; this has no
impact on process execution. From the Properties tab of the Operator Dialog
Property Panel, use the following steps to add a numeric input.
To add a numeric input
1 Type a value for the Header and Description fields and click the Add button.
2 In the input table, select the row and then the field in the Type column.
3 Click Numeric.
4 Click the field in the label column, type the label description, and click Enter.
5 If a value is required check the box.
6 If the input has a default value, click the field in the Specialized Definition column
and type the default number; then press Enter.
7 To map the input value to a context item, click the field in the Context column.
8 In the Context Browser, select the context item to map.
9 Use steps 1 - 8 to add additional numeric inputs.
Date input
The date input type prompts the operator for a date and time value. This value is
converted to epoch time at the time of execution and assigned to a specified context
item. From the Properties tab of the Operator Dialog Property Panel, use the
following steps to add a date input.
To add a date input
1 Type the value for the Header and Description fields. Click the Add button.
A new row will be created in the Inputs table. The default Type is String.
2 Double-click the field in the Type column, and then click Date.
4 Type the label for this input; then press Enter.
This label will be displayed to the operator during execution.
5 If a value must be provided by the operator for this input, select the Required
check box. By default, all inputs are non-required.
6 If the input is a date, click the field in the Specialized Definition column.
7 The Default Value for Date Input window appears. The time defined is a relative
value; the actual value will be determined at runtime.
8 Define values for the Days, Hours, and Minutes fields; then press Enter.
Note
Clicking Reset Default Value restores the original values. This is equivalent to
having no default set and at runtime the operator dialog uses the time of
execution as the default value of the date and time.
9 Click the field in the Context column.
10 Select the context item to which this input value will be mapped.
11 Use these steps to create additional date inputs.
During testing of the Operator process in BMC Atrium Orchestrator Development
Studio, the Operator Dialog activity window is displayed.
The date in the box is based on the default or, if no default was set, the current date
and time is displayed To change this date, click Date and use the calendar to select
the date value.
Boolean input
The Boolean input type prompts the operator to indicate with a check box a value of
true or false. This value is assigned to a specified context item. From the Properties
tab of the Operator Dialog Property Panel, use the following steps to add a Boolean
input.
To add Boolean input to an operator dialog activity
1 Type the value for the optional Header and Description fields; then click the Add
button.
A new row will be created in the Inputs table. The default Type is String.
2 After you select the row and the field in the Type column, click Boolean.
4 Type the label for this input; then press Enter.
This label will be displayed to the operator during execution.
5 To set the default value to true, select the check box in the Specialized Definition
column.
The input value must be mapped to a context item.
See the Context Browser section for details on this feature.
8 Use steps 1 - 7 to create additional boolean inputs.
During testing of the Operator process in BMC Atrium Orchestrator Development
Studio, if you choose Simulate Operator Control Panel when launching the test, the
Operator Dialog activity window is displayed.
List inputstatic values
The list input type prompts the operator to select one or more values from a list.
Selected values are assigned to a specified context item. By default all inputs are not
required. The labels you provide are displayed in BMC Atrium Orchestrator
Operator Control Panel when executing the process. From the Properties tab of the
Operator Dialog Property Panel, use the following steps to add a list input.
For lists, the mapped value is an XML document. With multiple selections the value
would be mapped as shown in the following example:
<items>
<item>[first item selected by user]</item>
<item>[second item selected by user]</item>
<item>[third item selected by user]</item>
</items>
If only one item is selected, the value would be mapped as shown in the following
example:
<items>
<item>[item selected by user]</item>
</items>
To define a list input with static value
1 In the Properties tab of the Operator Dialog, type the value for the Header and
Description fields and click the Add button.
2 Change the type by selecting the row and the field in the Type column, and then
selecting List.
4 Type the label for the input in the Label column and click Enter.
5 If the operator must provide a valuer select the Required check box. By default, all
inputs are non-required.
6 Click the field in the Specialized Definition column for an input.
7 If you want to select multiple values, select the Allow multiple selections check
box in the List Input Parameter window.
8 Click the Add button to add an element.
9 In the newly-created row, double-click the field in the Element column and type
the element name.
10 To create a list with dynamic selections, select the Provide Dynamic Selections
box.
a Click the context browser button.
b Select a context item.
c Click Select.
11 To set a default value click the Selected by default check box.
Note
In order to select the defaults, the context item value must be a "flat" XML
structure with a root tag that contains child tags (child tags cannot contain any
children).
For example:
<name>
<first option>
<second option>
</name>
12 When all elements are added and appear in order you want, click OK. You can
adjust the order using the Up and Down arrows.
List inputdynamic values
The list input type prompts the operator to select one or more values from a list that
is populated dynamically from context items. Selected values are assigned to a
specified context item. From the Properties tab of the Operator Dialog Property
Panel, use the following steps to add a list input.
To define a dynamic value list input
1 Type the value for the optional Header and Description fields; then click the Add
button to add a new row.
A new row is created in the Inputs table. The default Type is String.
2 After selecting the row and the field in the Type column, select List.
4 Type the label that displays in the Operator Control Panel for this input; then
press Enter.
5 Select the Required check box if you want a required input. By default, inputs are
not required.
6 Click the field in the Specialized Definition column to display the List Input
Parameter window.
7 Select Provide Dynamic Values.
8 Click the Context Browser button to select a context item to provide a dynamic
list of values.
9 To add a default dynamic selection, click the Provide Dynamic Selections check
box.
10 Click the Context Browser button to select the default dynamic selection.
11 Click OK.
12 Click the Context Browser button.
13 Select the context item to which the input value will be mapped; then click Select.
Switch activity
The Switch activity allows for conditional process paths to be executed, based on one
or more conditions evaluating to true. If all case paths evaluate to false, the default
path is taken.
When a Switch activity is placed on the process canvas, a Join object is automatically
placed to the right of it. All paths originating from a Switch activity must be
terminated at the corresponding Join activity.
The Join activity cannot be deleted individually. When a Switch activity is deleted,
all activities connected to the Switch, together with the Join activity, will be deleted
together as a group. Activities contained between the Switch and Join can be deleted
individually.
Switch activity
The Switch activity is pre-populated with two ports, Default and Case1. The default
port's chain of activities is executed in the event no case port path conditions
evaluate to true.
An unlimited number of case ports can be added. To add additional ports, right-click
on the Switch activity in the process canvas and select Add Port from the menu.
If additional ports are added and subsequently found to be unnecessary, the extra
ports can be deleted. To delete a port, place the mouse pointer over the unwanted
port until the arrow changes to a hand pointer, then right-click and select Delete Port
from the pop-up menu.
When a port on the Switch activity is connected to another activity, the connecting
line will contain a label. This label has a default value of the port name, but can be
changed by clicking on the label and typing the line label text.
The Property Panel for a Switch activity consists of three tabs, Properties, Logging,
and Metadata. The Logging and Metadata tabs follow the layout and principles
outlined in previous sections of this document.
The Properties tab for the Switch activity contains only one field, Execute All Cases.
The options for this field are true or false. When set to true, ALL case paths whose
conditions resolve to true will be executed. When set to false, only the first case path
encountered whose conditions resolve to true will be executed.
The following table provides an example of the cases that would be executed given
each option for the Execute All Cases field. The case path condition, either true or
false, is provided for each sample case.
Table 28: Switch activity - execution sample
Option Case -1 evaluates to
false
Case 2 -evaluates to true Case 3 - evaluates to
true
Execute All Cases set to true skipped executed executed
Execute All Cases set to false skipped executed skipped
Define the conditions for the case path on the properties panel for the linking arrow
between the Switch activity and the first activity on the case path.
To access the Switch activity case path properties
1 Double-click the linking arrow.
2 Click the Add button to create a new condition.
Switch activity
Note
The default path does not have associated properties. The activities on this path
are executed in the event that none of the conditions on any case path evaluate to
true.
For activity
The For activity allows for iterative processing of a list of input data within a process.
When a For activity is placed on the process canvas, an End For object is
automatically placed to the right of it. A For activity is linked to a series of activities,
terminating at an End For object. The process will execute the linked activities
between the For and End For activities for each item in the list, moving to the next
item on the list each time the End For object is reached. When all items in the list
have been processed by the For loop activities, the process will continue with the
activities that follow the End For object.
The End For object cannot be deleted individually. When a For activity is deleted, all
activities connected to the For activity, including the End For object, will be deleted
together as a group. Activities contained between the For and the End For can be
deleted individually.
The Property Panel for a For activity consists of four tabs, Properties, Logging,
Metadata, and Results. The Logging and Metadata tabs follow the layout and
principles outlined in previous sections of this document.
The Input parameter can be a context item or a dynamic context that contains an
XML document. An XPath expression is created through the Transform Editor to
designate the Input document that will be processed by the For loop activities. The
XPath expression selects the value from each element in the XML document in
sequence. When the list is exhausted, the process proceeds with the activities
subsequent to the End For object.
For example, with the following XML document as an input and an XPath
expression of //line the value of each of the three <line> elements will be processed
by the activities in the For loop.
<lines>
<line>value one</line>
<line>value two</line>
<line>value three</line>
</lines>
To configure a For activity
1 Select a Parameter type in the Input pane.
For activity
2 Launch the Context Browser.
3 Select a Context item to be evaluated or referenced.
4 Click the down arrow next to the Basicbutton, and select Advanced.
Note
XSLT is not a valid transformation option for a For activity. When launched from
a For activity's Properties tab, the Transform Editor will default to the XPath
option and will display the Sample Selection window first.
5 Use the wizard to designate the element or node that will be saved to the Output
Context item.
6 When the expression is complete, click Save and Exit to close the Transform
Editor.
Note
The For loop activities execute on each value in the list. Upon completing the list
provided by the Input, the process proceeds with the activities that follow the End
For object.
7 In the Output pane, select a Context type.
8 Click the Browse button to launch the Context Browser.
9 Select a Context item in which to store the item currently being processed by the
loop.
10 Click OK to save the contents of the Properties tab.
Spawn activity
The Spawn activity allows two or more process paths to be executed in parallel.
When a Spawn activity is placed on the process canvas, a Join object is automatically
placed to the right of it. All paths originating from a Spawn activity must be
terminated at the corresponding join object.
The join object cannot be deleted individually. When a Spawn activity is deleted, all
activities connected to the Spawn, together with the Join object, will be deleted
together as a group. Activities contained between the Spawn and Join can be deleted
individually.
Spawn activity
When a process is executed, any check points that have been set on activities that fall
between a Spawn activity and its corresponding Join object are disabled.
The Spawn activity is prepopulated with two ports. A port represents the start of a
path of execution that can be executed in parallel with any other ports on the Spawn.
An unlimited number of ports can be added. To add additional ports, right-click on
the Spawn button in the process canvas and select Add Port from the menu. Each
new port will be added below the existing ports.
If additional ports are added and subsequently found to be unnecessary, the extra
ports can be deleted. To delete a port, place the mouse pointer over the unwanted
port until the arrow changes to a hand pointer, then right-click and select Delete
Port from the menu.
The Property Panel for a Spawn activity consists of two tabs, Logging and Metadata.
The Logging and Metadata tabs follow the layout and principles outlined in
previous sections of this document.
Launch Job activity
The Launch Job activity spawns a new process and executes the existing workflow
without waiting for the launched process to complete.
The new process is launched asynchronously.
Run time can be set through a context item. At runtime, if the Launch Job activity
schedules a workflow that runs in the past, the process compensates.
A useful example of this feature is, verifying the number of servers to run a nightly
job. In this example, the site has approximately 2000 servers and the workflow runs
for 2 minutes. Rather than run at 2000 multiplied by 2 min., the workflow launches
in parallel.
To add a Launch Job activity
1 In the Designer window, drag the Launch Job activity from the activity palette to
the process canvas.
2 Link the Launch Job activity to the other activities in the process.
3 Double-click the Launch Job activity to setting the properties.
4 Click the Process browser button that appears next to the Process field.
Launch Job activity
The process browser window appears.
5 In the process browser window, select the process to launch.
a Enter the name or part of the name of the process in the search field.
b Click the Search button
6 Click OK to select the process that displays and close the process browser.
7 Select the runtime settings.
8 If you select the delay runtime setting, then enter the time to delay in
milliseconds, seconds, minutes, hours, or days the Launch Job activity. This can
be set as a hard-coded number, a context item, or a module configuration item.
9 If you select the run at runtime setting, then you can launch the context browser
to set a specific time.
Utility activity
The Utility activity allows common actions to be performed on strings, numbers and
dates. The resulting value is saved in an output context item.
The Property Panel for a Utility activity consists of three tabs, Properties, Logging
and Metadata. The Logging and Metadata tabs follow the standard layout and
principles. Detailed information on the Properties tab for each type of utility and
operation is provided in the following sections.
Using date utilities
You can use the date utilities to perform the following activities: after, before,
between, decrement, increment, and now.
Table 29: Date utility operations
Operation Description
after Given two dates, Date 1 and Date 2, this function checks to see whether Date 1
comes after Date 2.
before Given two dates, Date 1 and Date 2, this function checks to see whether Date 1
comes before Date 2.
Utility activity
between Given two dates, Date 1 and Date 2, this function checks to see whether a
specified Date falls between Date 1 and Date 2. In this case, the operation checks
the following: Date 1 < Date < Date 2.
decrement Decreases the specified date in the Date field by the unit value entered. For
example, if you choose to decrement the month segment of a Date value by a
unit of 2, 03/20/2008 13:45:00 becomes 01/20/2008 13:45:00.
increment Increases the specified date in the Date field by the unit value entered. For
example, if you choose to increment the year segment of a Date value by a unit
of 1, 03/20/2008 13:45:00 becomes 03/20/2009 13:45:00.
now The current date, as of when this Utility activity is processed at run-time, is
assigned to the Output context.
Date utilities: before and after
The after and before operations are used to compare two user-defined dates. The
comparison result is a value of true or false. Usually, at least one of the values would
be defined as a context item.
To configure a Utility activity that compares two dates with an operation of
before or after
1 Select date from the menu for the utility type field.
2 Select either before or after from the Operation type menu.
3 Click the button next to the output field to launch the Context Browser.
4 Select the context item for the result.
5 Enter the dates to be compared in the Date 1 and Date 2 fields.
Date 1 will be compared to Date 2 using the selected operation. When you select
Date, the calendar button appears.
6 Click the calendar button and select the date.
7 Click OK to close the Calendar.
Note
The values for Date fields are stored as epoch time. The Date and Time fields can
only be modified using the Calendar utility.
8 When all the data has been entered, click OK.
Utility activity
Date utilities: between
Use the between operation to determine if a specified date falls between the values
defined for two additional dates. The comparison result is a Boolean value of true or
false.
To configure a Utility activity that compares two dates to a third date with an
operation of between
1 Select a date from the Utility type menu.
2 Select between from the menu for the operation type.
3 Enter the date to be evaluated in the date field.
This date will be compared to the dates in date 1 and date 2 to determine if it falls
between those dates.
When you select date, the calendar button appears.
5 Click OK to close the calendar.
Note
The values for date fields are stored as epoch time. The date and time fields can
6 Enter the dates to be compared in the date 1 and date 2 fields. Select the inclusive
box to the right of the date field to indicate that the date to be evaluated can be
equal to date 1 or date 2 and still generate an output value of true.
When you have assigned values to the date fields, a context item must be selected
to contain the results of the comparison.
7 Click the browse button below the output field to launch the Context Browser.
Date utilities: decrement and increment
The decrement and increment operations are used to decrement/increment the year,
month, day, hour, minute or second segment of a specified date by a defined value.
The result is the modified date.
Utility activity
To configure a Utility activity to modify a date with an operation of increment
or decrement
1 Select date from the Utility type field menu.
2 Select either increment or decrement from the Operation type menu for the
operation type.
3 Enter the date to be modified in the Date field.
When you select date, the calendar button appears.
5 Click OK to close the calendar.
Note
The values for date fields are stored as epoch time. The date and time fields can
6 Enter the value to be used to modify the specified date.
7 The value for increment and decrement can be defined as a Numeric value or a
Context item using the menu to the right of the field.
With the selection of Numeric, a numeric value can be entered in the increment/
decrement field.
8 Use the date field menu to select the date segment for the increment/decrement
field.
Once the values have been assigned for the date modification, a context item must
be selected to contain the resulting date.
9 Click the browse button below the output field to launch the context browser.
Date utilities: now
The now operation is used to store the current date in a specified Context item.
Utility activity
To configure a Utility activity to save the current date to a context item using
a now operation
1 Select date from the Utility type field menu.
2 Select now from the Operation type menu for the operation type.
3 Click Browse below the output field to launch the context browser.
4 Select the context item for the current date.
Numeric utilities
There are six operations that can be performed with a numeric utility: add, div,
divide, modulus, multiply, and subtract.
Table 30: Utility operations - numeric
add Adds two numeric values.
div This function returns the quotient of two numeric arguments. The function will
not return a value if the arguments are not both numeric (decimal or integer)
values.
Note: Using a divisor of 0 will result in failure and compensation will be called.
divide Divides two numeric values and returns the result.
Note: Using a divisor of 0 will result in failure and compensation will be called.
modulus Divides two integer values and returns the remainder (for example, 5 mod 3 =
2). This function divides the first argument by the second and returns only the
remainder. The function will not return a value if the arguments are not both
numeric (decimal or integer) values.
Note: Using a divisor of 0 results in failure and a compensation call.
multiply Multiplies two numeric values and returns the result.
subtract Subtracts two numeric values.
Using numeric utilities
Each of the operations that can be selected for a numeric type utility uses the same
screen layout. You define a value for the First Operand and the second operand and
the operation to be performed with these values.
Utility activity
To configure a Utility activity for any operation of a numeric type utility
1 Select numeric from the Utility type field menu.
2 Select the operation from the Operation type menu.
4 Select the Context item for the result.
5 Enter the value for the First Operand.
6 Define the value for the First Operand as a Numeric value using the menu to the
right of the field.
7 Enter a numeric value in the First Operand field.
Using string type utilities
There are five operations that can be performed with a string utility: concat,
substring, lowercase, uppercase, and regex.
Table 31: Utility operations - string
concat Concatenates two or more String values.
substring Returns a String that is a specified segment of the value in the String
parameter.
lowercase Returns a String where all alphabetic characters have been converted to
lowercase.
uppercase Returns a String where all alphabetic characters have been converted to
uppercase.
regex Allows you to evaluate a simple string and return a true/false condition
or to substitute string values for a given context item. BMC Atrium
Orchestrator supports Java regular expressions.
String utilities: concat
Use the concat operation to concatenate two or more strings.
Utility activity
To configure a Utility activity to concatenate two or more strings
1 Select string from the Utility type field menu.
2 Select concat from the Operation type menu.
3 Launch the context browser.
4 Select the context item for the resulting string.
5 Enter the string to which another string will be appended.
6 Click the Add button to the right of the Input field.
An input row will be added to the Properties.
7 Enter the string to be appended to the previous input.
This step can be repeated as many times as is necessary to identify all the strings
to be concatenated.
String utilities: substring
Use the substring operation to extract a segment from a specified string.
To configure a Utility activity to extract a specific segment from a string
1 Select string from the Utility type field menu.
2 Select substring from the Operation type menu.
3 Launch the context browser.
4 Select the Context item for the resulting string.
5 Enter the string from which a segment will be extracted.
6 Launch the context browser, and then select the Context item.
If the value contained in the Context item is not in the correct format, it can be
transformed using the Basic or Advanced transform.
7 Enter a value for the Start Index.
Utility activity
The Start Index is a zero-based index of the input string and is inclusive.
Note
The definition of a Start Index is optional. If no Start Index is defined, an index of
0 will be used, starting at the beginning of the string.
8 Enter a value for the end Index.
The end Index is a zero-based index of the Input String and is non-inclusive.
Note
The definition of an end index is optional. If no end index is defined, then a
substring starting from the defined Start Index to the end of the string will be
returned.
String utilities: lowercase and uppercase
In the Operator dialog activity the String utility uses the lowercase and uppercase
operations to convert the case of characters in a string.
To convert alphabetic characters in a string
1 Select string from the Utility Type field menu.
2 Select lowercase or uppercase from the Operation menu.
4 Select the context item for the resulting string.
5 Enter the string to be converted.
String utility: regex
The String utility uses the regex utility to check for patterns in strings or perform
substitution on strings.
The regex utility evaluates or modifies a simple string using the Regex Transform
Editor. If you select evaluate, the String utility evaluates the input string and
indicates whether the search pattern is contained in the string. The output value of
the evaluation is either true or false. If you select modify, the String utility searches
the input string for the search text and substitutes that text with the replacement text.
Utility activity
You can use the String utility to evaluate strings with regular expressions, or to
substitute a string with a regular expression.
Metrics activity
Use the Metrics activity to record information such as status, category, descriptions,
and parameters about the process. This information is also called business metrics.
When a process runs on a grid, information about the process, such as context items,
status, parameters, category, and descriptions, can be collected and stored in a
database. Before it can be saved to the database, you must use Grid Manager to
configure the environment. For information on how to configure the environment so
that data can be collected and sent to the database, see BMC Atrium Orchestrator
System Administration Guide.
Use the Metrics activity to specify the business metrics you want to collect when the
process runs. The Metrics activity only sends data to the database when the process
runs on a grid. Data is not sent to the database when the process is tested in BMC
Atrium Orchestrator Development Studio.
Note
If a context item has no value at the time the metric is recorded, a null is recorded
and a message is written to the processes.log on the peer that is executing the
process. The message is assigned a log level of INFO.
Collecting business metrics
Metrics data is recorded in the process metrics database configured and designated
in Grid Manager.
The business metrics that are collected by the Metrics activity are different from the
standard process metrics. The standard process metrics are collected if you set
Record Metrics to true in the Process Properties dialog box.
To configure the Metrics activity and populate the metric value field with a
context item
1 On the Design canvas, double-click the Metrics activity.
2 On the Properties tab, type values for the Category, Description and Status fields
Metrics activity
BMC recommends that you do not assign Foundation as the category, because
that is the category assigned to the standard process metrics collected if you set
Record Metrics to true.
4 Select the context item that has the information you want to collect.
5 Enter a value in the Metric Name field.
6 (optional) Transform the value if necessary.
a Click the Transform button to launch the Transform Editor.
b Enter the expression to be used to transform the value of the context item.
c When the expression is complete, click Save and Exit to close the Transform
Editor.
7 (optional) To collect another metric, click Add and repeat steps 4 through 6..
8 After you have entered all of the metrics information, click OK.
Pause activity
The Pause activity suspends a process for a specific amount of time.
A pause activity can be used to wait for an external system to perform a function and
return a status, as in the case of validating the success of a remediation process.
The properties panel for the Pause activity contains three tabs: Properties, Logging,
and Metadata. The properties panel has only one field, Pause Interval.
Note
If the timeout for the process is less then the pause time then the process will time
out and a compensation will execute.
To set the pause interval
1 In the properties panel for the pause activity type the time in milliseconds to
suspend the process.
2 Click OK to save the value.
Pause activity
Script activity
The Script activity enables you to use Perl or Jython scripts referenced in or written
in the activity through a script adapter. Some configuration in Grid Manager and
other files is necessary to configure the activity.
The Script activity enables you to use Perl or Jython scripts with the activity. This
activity provides an alternative to using the Call Adapter activity with a Script
adapter. The Perl or Jython scripts are either written in the activity or referenced by a
path. If a script is referenced, it must exist in the same location on each peer that can
be called to run the process.
To use the script adapter, you must first edit the dumper.pm file and then create a
script actor adapter, named ScriptAdapter, in Grid Manager. In Grid Manager, you
must enable the ScriptAdapter on all peers that will run a process containing a Script
activity.
The Property Panel for a Script activity consists of three tabs: Properties, Logging,
and Metadata. The Logging and Metadata tabs follow the standard layout and
principles. The Properties tab is organized into three panes: the Script Source, Script
Input Tokens, and Script Output Tokens. The choices for Script Source are the
following:
Embedded: Allows you to enter a script within the Script activity in Perl or
Jython. With the selection of Embedded, the View/Edit Script button will be
available.
File: Allows you to designate the location of a file containing a script to be
executed. With the selection of File, the Location and Script Language fields will
be available.
To execute scripts with the script adapter
1 Locate the Dumper.pm file within the ActivePerl installation directory. The
default location is C:/Perl/lib/Data/Dumper.pm.
2 Open the Dumper.pm file in Notepad.
3 Make line 113 the following a comment, by adding # at the beginning of the line.
# sprintf our $refaddr_format, Scalar::Util::refaddr(shift) ;
4 Save the changes to the file and close Notepad.
5 Create the Script Adapter and enable it on a peer using Grid Manager.
Script activity
To create an embedded script
1 In the Properties panel for the Script activity, select the Embedded option to
designate the Script Source.
2 Click the View/Edit Script button and use the Scripting Language menu to select
the scripting language.
3 Click the Enter Script field and type the script to be executed.
4 Click OK to save the changes to the script and to return to the Properties tab.
5 Click OK to save the changes to the Properties tab.
To use a script from an external file
1 In the Properties panel for the Script activity, select the File option to designate
the script source.
2 In the Location field, click the Search button to launch the file browser.
3 Navigate to the location of the script file, and then click Open to select it.
Note
This script file must exist in the same location on every Peer that has the Script
adapter enabled.
4 Select the scripting language.
5 Map the input and output values.
6 Click OK to save the changes to the Properties tab.
Script parameters
Script parameters define variables for embedded or file scripts.
To map a value from a process to a variable in a script
1 Within the Script Input Tokens pane, click the Add button.
2 In the input pane, use the menu to select the parameter type.
Script activity
Table 32: Script parameters
Input type Description
String Allows for the assignment of your defined string value in the value field
(below the input type).
Numeric Allows for the assignment of your defined numeric value in the value field
(below the input type).
Date Allows for the assignment of your defined date value. The calendar button
to the right of the Value field must be used to populate the field. All dates
are stored as epoch values.
XML Allows for the assignment of user defined XML in the value field. With the
selection of 'XML', the value field will be extended.
Context item Allows for the assignment of the value from another context item to this
input token. Click the Browse button to the left of the value field to launch
the context browser and select a context item.
Module Configuration Allows for the assignment of the value from a module configuration item
or group to this Input Token.
Expand the tree to expose the module configuration item or Group and
click to highlight the selection.
Dynamic Context Allows for the assignment of the value of a previously defined dynamic
context to this Token. The Browse button must be used to populate the value.
3 If you need to transform the value before it is assigned to the token, click the
Transform button and define the transformation.
5 Double-click the context item to select it.
Tip
Context items can be added rapidly using the Add Context button within the
Context Browser.
6 Click OK to save the script input token.
To map the value from a variable in a script to a context item
1 In the Script Output Tokens pane, click the Add button.
3 Double-click the context item that matches the name of the variable used in the
script.
Script activity
Tip
Context items can be added rapidly using the Add Context button within the
Context Browser.
4 In the Output pane, use the drop-down menu to select the context type.
6 Select the context name by double-clicking it.
7 Click OK to save this script output token.
Call Adapter activity
Adapters are used to interact with external systems. Each actor adapter is configured
in Grid Manager and then used within a workflow process using a Call Adapter
activity. The Call Adapter activity executes an adapter request and, when available,
assigns the adapter's response to a context item for use in subsequent activities. The
format of the request and response is specific to the adapter being called.
The Property Panel for a Call Adapter activity consists of three tabs: Properties,
Logging, and Metadata. The Logging and Metadata tabs follow the standard layout
and principles. There are two options for designating the Adapter Data Source: Static
Value and Context Key. Each option has its own Properties tab fields, as described in
the following sections.
The fields associated with the Call Adapter activity are the same for both static value
and context key adapter data sources.
To use a static value as an adapter data source
1 In the properties panel of the Call adapter activity, click the Static Value option
for the Adapter Data Source.
2 Complete the fields.
3 When all fields have been completed, click OK to save the information.
To use a context key as an adapter data source
1 In the properties panel of the Call adapter activity, click the Context Key option
for the adapter data source.
2 Complete the fields.
3 When all fields have been completed, click OK to save the information.
Integration Mapping activity
The Integration Mapping activity allows BMC Atrium Orchestrator Development
Studio to query and examine adapters that are active at run time.
This activity provides adapter information, and details the domain model used by
the target system. It assists BMC Atrium Orchestrator Development Studio in using
this information to create processes that map data between the data models. The
Integration Mapping activity lists the operations for active adapters.
Note
BMC Remedy AR and BMC HP ServiceCenter adapters support the Integration
Mapping activity.
When you use the Integration Mapping activity, the Integration Mapping Wizard
launches and queries the system to map data to and from context items. The
Integration Mapping Wizard automates operations on applications through BMC
Atrium Orchestrator Development Studio. This feature reduces development time
when building workflows against custom schemas. The Integration Mapping Wizard
has the following steps:
1 Select system/adapter
2 Select operation
3 Map inputs
4 Map outputs
Creating a new mapping
This scenario describes creating a mapping for a customized Remedy adapter called
Customer Support Remedy using the SD:CreateCust form. The purpose of this
mapping is to load new customer information quickly to a custom Remedy ITSM
system.
Before you begin
1 This scenario assumes that you created a new workflow that gathers customer
information from the registration database and loads it to Customer Support's
Remedy ITSM system.
2 From the BMC Atrium Orchestrator Development Studio activity palette, you
select the Integration Mapping activity and connect it to the end of the current
workflow.
To create a new mapping
1 Double-click the Integration Mapping activity and select a target system.
Tip
The options consist of the Remedy adapters enabled on this grid, but not the other
system adapters enabled on the same grid.
If BMC Atrium Orchestrator Development Studio is not connected to a grid, the
login window appears.
2 Select the name of the adapter connected to a Remedy system.
3 Select the operation.
4 Select the SD:CreateCust form.
5 Define the required inputs.
Column Description
Target field Displays a list of all of the fields available for the form
Required Specifies if the target field is required
Type Indicates the attribute type.
Sample values: Date/Time, Text
Input value Specifies the value for the input.
6 Define the required outputs.
Column Description
Source field Displays a list of all of the fields available for the form
Type Indicates the attribute type. Sample values: Date/Time, Text
Output context item Specifies the context item. By default, the context item is the same name
as the Source Field. You can display the context item Browser with a
list of all available context items and select another context item, or
create a new context item whose name is different than Source field.
7 Define a context item.
Editing a mapping
When you double-click the integration mapping activity, the properties panel
appears. The properties panel contains the System, Inputs, and Output tabs. The
System tab displays the adapter properties.
The Inputs and Output tabs contain the mappings names and values. You can edit a
mapping by double-clicking the mapping.
Updating a mapping
For this scenario, the mapping must be updated to reflect the changes in the Remedy
system. A new field called Instant_Message is now part of the SD:CreateCust form in
the Customer Support Remedy System. The workflow designer has modified the
first part of the workflow to collect the IM value from the registration database and
assign it to a context item called IM_CI.
To update a mapping
1 In the existing workflow, select the Integration Mapping activity containing the
mappings to the SD:CreateCust form.
2 Query the list of available fields from the SD:CreateCust form from the target
Remedy system. If you are not logged on to the system, you will be prompted to
enter your credentials.
3 Add the Instant_Message field to the Input Mapping table.
4 Associate the Instant_Message field to the IM_CI context item.
5 Click Save.
Comment activity
The Comment activity allows you to place additional text information on the process
canvas in "sticky notes." Comments can be used to clarify the function of the
activities in a process to make it easier for another user to follow the logic of the
workflow.
Comment activity
To add a Comment activity
1 Double-click the Comment activity to open the Edit Comment window.
2 Enter or update the text in the Edit box; then click OK to save.
To resize a Comment activity
1 Click once on the Comment activity to display the drag handles.
2 Click and drag the green drag handles to resize the comment box.
Comment activity
Context item overview
A context item is a variable defined within BMC Atrium Orchestrator Development
Studio. Local context items exist only within the context of process execution. Global
context items can be shared across process executions, and are persisted, so their
values remain unaffected by grid restarts or upgrades.
Context items are variables in a process. These variables can be different each time
the process executes, but the actions performed with the variables remain constant.
In a process, context items hold values to use in subsequent activities. For example, a
context item can hold an error message, such as Port 80 failure, that populates
the subject line of an email message when a port failure alert is generated. Each time
the process executes, the error message can be different, but it always populates the
subject line of an email message. Context items can be:
Local, existing within the context of a single process execution
Global, persisting within a grid and used by any process on that grid
Mapped to parameters
Input parameters are mapped to context items to provide a process with values
prior to execution.
Output parameters are mapped to context items to allow a value to pass from a
process executed as a Call Process activity to the calling process.
Context Browser
The Context Browser manages context items in BMC Atrium Orchestrator
Development Studio. This window is accessible wherever context items are used.
The Context Browser is launched with the Browse button, located either below a
context item entry field or in the top right toolbar of an activity Properties tab, or by
double-clicking a table cell in which a context item is expected. Global context items
are displayed in the top pane and local context items appear in the bottom pane of
the Context Browser.
10
To create and insert a context item
1 Double-click an activity displayed in the process canvas.
2 In the Input area of the Properties tab, type the information for the input and double-
click in the Context field.
3 In the Context Browser window, click the New button.
4 In the Create Context Data window, enter the context name.
Field Description
Context Name Contains the name of the context item. This name can contain an unlimited number
of characters, but no special characters (!@#$,.).
Time-To-Live Specifies the time, in milliseconds, that a context item persists before it expires.
This time begins when a context item is called in a process. If Time-To-Live is left
blank, the context item will not expire.
Is Global Indicates whether the context item persists within the grid or within the local
process. If this box is checked, the context item is global, persisting within the grid.
5 In the Context Browser window, click Select to use the item that you created.
6 Click OK to save.
Search for a context item
You can search for context items in the Context Browser.
You create the filter to use for search. The search function is case-sensitive. Values
entered as search criteria are matched exactly in any part of the context name. The
search returns only the context items containing the exact string entered in the
Search field.
To search for a context item in the Context Browser
1 Click the Browse button located below a context item's entry field or in the upper
toolbar of an activity's Properties tab to open the Context Browser.
2 Type the text to use for the search, and then press Enter.
Tip
To remove the filter and display all context items, delete the text in the search
field and press Enter.
Context Browser
Dynamic contexts
In addition to context items, processes can also use dynamic contexts to store values.
Dynamic contexts provide you with a method to store data in a container that can
have a variable name. With a context item, a value is assigned to a specifically
named container. When using a dynamic context item, the name of the container is
the value of a specific context item.
For example, if you need to store information about a help ticket and want to
reference that ticket ID to retrieve the stored information, a dynamic context could
be used. A one-time use context item would not be required to store the information,
and the process can be reused many times.
A dynamic context is typically used to hold an XML document that contains
multiple values used for reference in multiple processes that can be executed over
time. These values can be used to cross-reference other systems or hold other data
that cannot have a specific storage location in a database but would be valuable in
subsequent processes.
Dynamic contexts are designed to hold small amounts of reference data. They are
designed to be used when there is not a convenient location to store reference
information. Using dynamic contexts increases disk and memory usage and
increases network traffic.
Table 33: Dynamic context sample data
Type of context Name Value
Context item Ticket ID CM0901
Dynamic context CM0901
<event>
<problem-id>P1234</problem-id>
<cmr-id>C5678</cmr-id>
<event-id>90745</event-id>
</event>
Dynamic context scenario
The following procedure illustrates how data can be stored for a ticket in one process
and retrieved using the ticket ID after an event triggers a second process.
When running this process in your environment, the value of the dynamic context
item is extracted by a transform expression from the event that triggered the process.
You trigger the event by performing an intervening step. To clearly illustrate this
point, the example in the following procedure depicts an input value that is a fixed
value. In practice, this input value would create a context item populated by a
preceding activity in the process.
Dynamic contexts
1 In an Assign activity in a process, assign the value CM0901 to the context item
Ticket ID.
2 Compile the data associated with ticket CM0901.
3 Assign the data to an output with a parameter type dynamic context.
4 Use the Context Browser to select the TicketID context item.
This assigns the data to a dynamic context named CM0901.
5 Create a second process.
6 In this process, populate a context item named EventIDs with the value CM0901.
7 Create an assign statement with an input of dynamic context, using the Context
Browser to select the TicketID context item.
The output should be a new context item, used to hold the data captured for the
ticket in the previous process. This sample assigns the value of the dynamic
context to a context item named EventIDs.
This EventIDs context item can be used by other activities in the process as needed
to work with the stored ticket data.
System parameters
System parameters are used to assign a variable value to a context item. The value
for a system parameter is determined at the process run time.
There are three types of system parameters: JOB_EXECUTOR_USERID,
JOB_EXECUTOR_CREDENTIALS, ROOT_JOB_ID. These parameters eliminate the
need to prompt for input with an Operator Dialog activity within an operator
process, or to define additional activities to capture this data within a standard process.
Table 34: Types of system parameters
Input Description
JOB_EXECUTOR_USERID Specifies the user ID of the person who initiated the process
execution. When you are testing a process in BMC Atrium
Orchestrator Development Studio, the default value of SYSTEM is used.
JOB_EXECUTOR_CREDENTIALS This parameter is always empty.
System parameters
Input Description
ROOT_JOB_ID Specifies the Job ID of the top-level process that triggered the
currently executing process. If there are multiple levels of called
processes, this might not be the ID of the process that called the
currently executing process. This ID is for the top-most process.
To assign a system parameter value to a context item
1 From the property panel of an Assign activity, select System Parameter from the
Parameter Type menu in the Input pane.
2 Select the system parameter from the Name menu.
3 Define the context item to which the selected system parameter is assigned in the
output pane.
Concepts
A concept is a special type of context item that enables you to store multiple values
in a single context item. You must use a concept to provide the input information
required for the Operations Actions utilities modules.
The Operations Actions in the utilities modules (Application, Common, Directory
Services, File, Network, Operating System and Physical Device) use either a
command line, SSH, Telnet, or Windows command adapter to execute the central
command for the process. For each of these processes, you must use a concept to
provide the information required to create the adapter request that executes the
central command.
A concept is an XML document containing specific elements used to assign multiple
values to a single context item. Each value is associated with an element of the
concept. The connection details input required by each of the Operations Actions
uses the ConnectionDetails concept (AutoPilotOACommon_Utilities:
ConnectionDetails). The different adapters require different sets of elements in the
concept.
Use an Assign activity to create the concept. Create a separate assign statement for
each element of the ConnectionDetails concept. Each assign statement is mapped to
the same context item, and BMC Atrium Orchestrator Development Studio creates
the concept XML document. An example of creating a concept is included in the
"How to create a workflow" chapter.
For more information about using concepts, see the BMC Atrium Orchestrator
Development Studio Help.
Concepts
Concepts
Testing and debugging processes
The debugger tool enables you to step through the testing of a process to ensure that
the anticipated outcome is achieved with the process. You can execute the process,
follow the execution paths, and see the context values assigned throughout the process.
Breakpoints can be established on individual activities. A breakpoint is used by the
debugger tool to pause the testing of a process on a specific activity. Breakpoints
permit you to perform more in-depth examination of the process at that point.
Testing a process
When you use the Test Process function in BMC Atrium Orchestrator Development
Studio, you can test a process before or after exporting it to the grid or recording
metrics.
The Test Process function can be accessed by right-clicking on the process to be
tested in the Project Navigator and selecting Test process from the menu. This will
open the selected process in the process canvas and initiate the testing function.
To test a process, you must be logged in to (authenticated on) the grid and must
have a role of designer or administrator on that grid. A process test will time out
after 180 seconds if it is not able to initiate the test within that time period.
If one or more input parameters have been defined for the process, the input
parameters window is displayed. Required parameters are indicated with a red
check mark.
The process commences and the process Log tab displays the information to write to
the processes.log file on the executing peer.
If the process being tested has output parameters defined, they will be shown on the
Context Values tab with their values at the end of process execution.
A process can be retested by clicking Test in the Test Console pane.
11
Note
When a process is being tested within BMC Atrium Orchestrator Development
Studio, no records are written to the metrics database. Metrics are written only when
activated processes on a grid are executed.
To test a process
1 With a process displayed on the process canvas, click the Test Workflow button
in the main toolbar.
2 When testing is complete, click Close.
To enter parameter values to test a process
1 Select the value type from the Type menu, and then double-click the cell in the
Value column that corresponds with the parameter.
2 Enter the value; then click OK.
To enter a string as an input value to test a process
1 If an empty string is used as an input value, double-click the Value box to create
the empty string.
2 Click OK to begin testing.
Tip
Test results can be redisplayed for processes that are still present on the process
canvas by clicking Windows => Show Console in the menu bar.
The debugger tool
The debugger tool enables you to step through the testing of a process to ensure that
the anticipated outcome of the process is achieved.
When debugging a process, you must execute the process, follow the execution
paths, and see the context values assigned throughout the process. The debugger
tool uses breakpoints to pause testing at an activity so that you can perform more in-
depth examination of the process at that point.
To gain the benefits of the debugger tool, at least one breakpoint should be set in the
process. Without a breakpoint, the debugging will yield the same results as testing
the process. During the debugging function, no breakpoints are ever skipped; each
breakpoint is a stopping point for debugging.
The debugger tool
To open the debugger tool
1 Select one of the following actions:
With a process displayed on the process canvas in the process Designer or
Debugger view, click the Debug button in the main toolbar.
From the Project Navigator, in the Process Designer or Debugger view, right-
click on a process, and then select Debug Workflow.
Debugger view
In the debugger, you can delete and edit activities but you cannot add new activities
to a process.
The Debugger view consists of the following main sections: Execution Viewer,
process canvas, Test Console, and Context Viewer. A debugger toolbar is displayed
in this view.
The Activity Palette is not available. The Project Navigator is available for selecting a
process to debug. The Project Navigator menu options Debug and Add Breakpoint
are available.
Execution Viewer
The Execution Viewer displays information on concurrent threads and called process
hierarchy.
The Execution Viewer is displayed by default on the left side, on the Execution tab.
This tab contains information related to the process at the current breakpoint. There
are two panes, Flows and Path.
Flows paneDuring debugging, the Flows pane displays the number of
concurrent threads being executed at the current breakpoint. There is typically
one thread displayed in this pane. If a Spawn activity is present in the process
being debugged, a thread displays for each path of the Spawn activity. The thread
on which the current breakpoint resides is highlighted in blue.
Path paneThe Path pane displays the hierarchy of called processes for the
process being debugged. The most recently called process displays on the top,
with the parent and, if applicable, grandparent process displayed below. This
information is displayed when you step into a Call Process activity on which a
breakpoint has been set.
The debugger tool
Test console
The test console displays the process logs, activity properties, and context values for
the process being tested.
The test console pane consists of the Process Log, Activity Property, and Context
Values tabs. The Clear button clears the current information from the Process Log
tab. This is useful when debugging a process more than once. The data can be
cleared between each execution, or it can be saved, with the data from each
successive execution written below the previous data. The Close button closes the
test console.
Tip
To redisplay the test console for the displayed process, select Windows => Show
Console from the menu bar.
The Process Log tab displays the information that would be written to the
processes.log file on the executing peer if it were being executed from the grid. The
Activity Property tab displays the property panel for the current breakpoint activity.
Upon completion of the test, the tab displays the property panel for the last
breakpoint activity in the process. The Context Values tab displays the output
parameters defined for the current process, along with the corresponding values at
the end of process execution.
Context Viewer
The Context Viewer displays the current values of local and global context items at
the time the process was stopped at a breakpoint.
You can change these values during process debugging. To change a context value,
double-click the current value of the context item to be changed. Edit the current
value in the Edit Context Value window and click OK. The new value will be used
by subsequent activities that reference this context item.
Debugger toolbar
The debugger toolbar is displayed when you are in the Debugger view. It contains
buttons to access functions for testing and debugging processes as described in the
following table.
The debugger tool
Table 35: Debugger tools
Button Description
Step Into Enables you to examine details of certain activities. This function is available
for Assign, Switch, and Call Process activities.
Step Over Skips over the current activity and stops at the next activity, regardless of its
breakpoint setting.
Step Out If you have stepped into a called process, enables you to step out of the
current process and return to the calling process.
Pause Test Pauses the current process at the next available activity, regardless of
breakpoint setting on that activity.
Continue Test Resumes the testing.
Terminate Test Cancels the testing and stops debugging of the current process.
Using the Breakpoint Manager
The Breakpoint Manager can be used to activate, deactivate, or delete an established
breakpoint. From the Breakpoint Manager, you can select an established breakpoint
and view the activity within a process.
The Breakpoint Manager is available through the button in the main toolbar from
either the process Designer or Debugger view, and from the Tools menu using the
Breakpoint Manager menu command.
The Breakpoint Manager displays all breakpoints that have been created for
processes in the current environment. The Step column indicates the activity on
which the breakpoint was created. Through this tool, you can enable, disable, or
delete one or more established breakpoints.
These functions are available in the menu for an activity. The Breakpoint Manager
enables you to see all breakpoints and make group changes rather than individually
at the activity level.
The Enabled/Disabled column indicates the current breakpoint status. A check mark
indicates that the breakpoint is active, and an empty check box indicates that the
breakpoint is inactive. To change the current status of a breakpoint, click the check
box in the row of the activity to be changed. Within the process, the breakpoint
indicator on the activity will toggle between active and inactive.
One or more breakpoints can be deleted by selecting the rows of the breakpoints to
be deleted and clicking Delete.
Note
Breakpoints cannot be created through the Breakpoint Manager. If a breakpoint is
accidentally deleted, you must re-create it with the menu for the activity.
To view a breakpoint activity in its process, click the row of the breakpoint activity
to be viewed, and then click View. The process canvas for that activity's process will
be displayed and the selected breakpoint will be outlined in blue.
A breakpoint can be created through the menu for an activity while in either the
process Designer view or the Debugger view.
To create a breakpoint
1 With a process displayed on the process canvas, right-click the activity on which
to set a breakpoint.
2 Click Breakpoints => Create Breakpoint.
Note
A breakpoint cannot be set on a Start or an End activity.
Troubleshooting
This chapter provides information to help you resolve issues and problems with
BMC Atrium Orchestrator Development Studio.
Troubleshooting common issues
Many issues can be resolved using the common troubleshooting techniques.
BMC Atrium Orchestrator Development Studio will not
connect to an environment
For suggestions for resolving connection issues, see Chapter 2, "Configuring BMC
Atrium Orchestrator Development Studio."
Log files for troubleshooting
The grid.log and processes.log files are the primary tools used in troubleshooting
issues in BMC Atrium Orchestrator Development Studio. You should accurately
configure logging prior to submitting log files to BMC Customer Support for
assistance with an issue.
BMC Atrium Orchestrator Development Studio primarily uses the grid.log file and
the processes.log file to troubleshoot. The information contained in the log files
depends on the logging levels configured in Grid Manager for grid.log and BMC
Atrium Orchestrator Development Studio for processes.log.
The grid.log file
When troubleshooting issues, the grid.log is the most important log file in BMC
Atrium Orchestrator. The grid.log file is used for troubleshooting CDP issues,
adapter issues, and BMC Atrium Orchestrator Development Studio issues. When a
test scenario results in an issue being reported, it is crucial to have an excerpt of this
12
log, starting from the point that the test scenario started, to the point that the failure
occurred, in order to troubleshoot the problem.
The file is located in the [BAO_HOME]/tomcat/logs directory, where [BAO_HOME]
is the directory where the BMC Atrium Orchestrator server was installed. You can
use a text editor to view the file. In the following figure you can see a sample
grid.log file.
The grid.log file is created when you initially start the peer. If the file is not created
after the grid has been operational for more than five minutes, either the installation
was not successful or the logging parameters have been changed in Grid Manager.
The level of detail in the grid.log file depends on the logging level selected in Grid
Manager. By default the logging level is set to WARN. For troubleshooting issues,
the logging level should be set to DEBUG. The DEBUG setting can result in a
significantly larger file, because the grid.log file records more extensive information
about the grid and the components running on it. The maximum size of the grid.log
file is 10 MB. Once a grid.log file is 10 MB, BMC Atrium Orchestrator renames the
grid.log file to grid.log.# and creates a new grid.log file. It is possible for several
sequentially numbered grid.log.# files to exist.
Note
Contact BMC Customer Support to verify necessary logging levels prior to
troubleshooting an issue.
The processes.log file
In BMC Atrium Orchestrator Development Studio, the processes.log file contains
messages generated by testing or debugging processes and is located in the
[STUDIO_HOME]/logs directory, where [STUDIO_HOME] is the directory where
BMC Atrium Development Studio was installed. You create the processes.log file
when you set the logging properties for an activity in the Logging tab process
property panel in BMC Atrium Orchestrator Development Studio. The information
in the processes.log file is the same output displayed in the test console when you
test processes in BMC Atrium Orchestrator Development Studio.
An example of processes.log
This processes.log example recorded the Operator Dialog, and input and output
parameters. As you read through the log, you can see that some of the log
information was recorded after the activity executed. The log contains information
about the Operator Dialog activity.
Figure 62: An example of the processes.log
This example shows a processes.log with an error message generated by a missing
context item.
Figure 63: An example of a processes.log with an error
Impact of secure module configuration on
existing processes
In BMC Atrium Orchestrator 7.6, a new module configuration type, Secure, was
introduced. When secure data types are used where they are not expected, problems
can occur.
In BMC Atrium Orchestrator 7.5.xx and earlier, all module configuration items had
the type Static (text) or XML. The configuration items are often used for user IDs
and passwords, adapter names, commands, and other constant strings and XML. A
common way to use configuration items in transforms is to put them in a context
and then use that context as a token in the transform. This practice was acceptable as
long as the values in the configuration items, and thus context and token, did not
make the transform style sheets invalid. This practice was a common coding
technique in run books and modules supplied by BMC. However, it created the issue
of storing sensitive data as plain text.
To address this issue, in BMC Atrium Orchestrator 7.6,secure configuration items are
implemented as XML, similar to the following sample:
<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#"
Type="http://www.w3.org/2001/04/xmlenc#Content">
<CipherData>
<CipherValue>cGFzc3dvcmQK</CipherValue>
</CipherData>
</EncryptedData>
When a module configuration item type is changed from Static to Secure, processes
and transforms using that configuration item, even indirectly, might need to be
modified to avoid process failures.
The following problems have occurred when secure data types are used where they
are not expected:
Impact of secure module configuration on existing processes
An XSLT style sheet of a transform might become invalid, causing a process to
compensate.
In general, inserting a secure configuration item in a token into an XSLT transform
in select attributes of copy (CP), copy-of (CPO), or similar elements or into test
attributes of xsl:if elements (IF), invalidates the XSLT style sheet. An invalid XSLT
style sheet usually results in processes compensating with XSLT errors.
A secure configuration item might be escaped so that it is not recognized as
needing decryption before use.
Inserting a secure configuration item in a token into an XSLT transform in xsl:text
elements (TXT) can cause the secure configuration item XML to be converted into
a string in which all of the XML characters are escaped. When this situation
occurs, BMC Atrium Orchestrator will not recognize it as XML, and will not
decrypt it. This is a subtle error because most BMC Atrium Orchestrator logging
unescapes the string for logging, which hides the fact that the error happened.
This error usually causes connections to fail because of authentication errors,
regardless of the authentication credentials provided.
Before you use secure configuration items, BMC recommends that you thoroughly
test workflows, and if necessary, modify them for the use of secure configuration items.
Language enablement support for
Language enablement enables you to use multibyte data in user inputs. With a few
exceptions, the user interface for BMC Atrium Orchestrator is in English regardless
of the operating system language or locale where the components are installed.
BMC Atrium Orchestrator Development Studio and BMC Atrium Orchestrator
Operator Control Panel can support multibyte characters in user inputs. Grid
Manager and Access Manager are not completely language enabled, which puts
some limitations on using multibyte characters in BMC Atrium Orchestrator
Development Studio.
In BMC Atrium Orchestrator Development Studio, the Yes, No, OK, and Cancel
buttons on all error, warning, and confirmation message boxes are shown in the
language of the operating system or locale of the system. Also, dates are displayed in
the format of the operating system or locale of the system.
Limitations on using multibyte characters in
Do not use multibyte characters in the fields listed in the following table. They can
cause problems when the entries are used with Grid Manager or Access Manager.
Entry field Location
Module Name
New Module dialog box
Export Module to Disk dialog box
Import Module from Disk dialog box
Module Version Export Modules tab
Process Directory Name Process Directory dialog box
A
Entry field Location
Process Name
New Process dialog box
New Process from WSDL dialog box
Rename Process dialog box
Schedule Job Name Create New Job wizard
Adapter Name Static Value
and Action
Call Adapter activity Property Panel
Module configuration item
Name and Value
Item Details pane of Module Configuration panel
User name, Password,
Hostname/IP, Peer Context,
Port, User name, and
Password
BMC Atrium Orchestrator Development Studio Connections dialog box
User name and Password Any BMC Atrium Orchestrator Development Studio logon dialog box
When you integrate BMC Atrium Orchestrator Development Studio with a source
control management system, it is not certified for use with multibyte characters.
Do not use multibyte input methods to enter numbers in BMC Atrium Orchestrator
Development Studio. Numbers entered using multibyte methods appear as English
numbers but are actually stored as multibyte characters. When BMC Atrium
Orchestrator Development Studio processes multibyte numbers, errors can result.
Always use English to enter numbers in BMC Atrium Orchestrator Development
Studio.
Language enablement support for BMC
Atrium Orchestrator adapters
With language enablement, application and base adapters can support multibyte
and other encoded data, in addition to data in the ASCII format.
To use BMC Atrium Orchestrator language-enabled adapters in a multibyte
environment, you must set your system environment variables for locale and for
language appropriately for your operating system. For example, on Linux, the
following settings from the /etc/environment file are appropriate for a system with a
Japanese operating system and Japanese characters:
LANG="ja_JP.UTF-8"
SYSFONT="lat0-sun16"
Language enablement support for BMC Atrium Orchestrator adapters
When using multibyte characters with a language enabled adapter, you must use the
<character-set> tag in either the adapter configuration or the adapter request to
identify the character set to be used with the adapter. To determine whether to place
the <character-set> tag in an adapter configuration or the adapter request, see the
BMC Atrium Orchestrator Base Adapters User Guide and the user guides for the
individual application adapters.
Not all BMC Atrium Orchestrator adapters are language enabled. To determine
which adapters are language enabled, see the BMC Atrium Orchestrator Base Adapters
User Guide and the user guides for the individual application adapters.
Glossary
A
Access Manager
The security component of the BMC Atrium Orchestrator product. Access Manager is an
identity manager that provides single sign-on (SSO) services as well as authorization policy
administration and enforcement. It also provides an interface to manage configurations with
external LDAP directories.
activity
Low-level, specific, and discrete action that follows policy-based decision flow criteria and
forms the basis of a process.
Activity Palette
A palette available in the Designer view that contains the various activities that enable
development of a process by dragging and dropping the appropriate activity into the process
canvas.
activity peer (AP)
Server software for the execution of automated process. Similar to a configuration distribution
peer (CDP), the AP can host adapters, but it does not provide administrative services. When
you add an AP to the grid, the AP automatically downloads activated workflows from the CDP
to provide high-availability workflow load balancing. If a CDP became unavailable, the AP
would continue to process workflows with the other available peers in the same grid.
adapter
Interface for third-party applications or external systems that enables bidirectional
communication using standard protocols, such as JDBC, Telnet, SSH and JMS, as well as vendor-
specific APIs.
administrator
B
An account role. Administrators can add and edit grids and accounts, and can configure the
metrics database to enable auditing. Administrators are automatically granted all roles for
grids that they create.
application adapter
Adapter that is used as an interface for a specific third-party application.
Assign activity
An activity that assigns a value to a context item. Within the activity, source values that consist
of XML documents (input types of Context Item, Dynamic Context, XML, or Configuration
parameter) can be transformed by using XPath or XSLT before assigning the result to the target
context item.
attribute
A name/value pair associated with an XML element.
B
base adapter
Adapter that interfaces to a system by using standard protocols such as JDBC, Telnet, SSH, or
JMS.
An IT process automation platform that automates tasks across multiple functional areas,
systems, and geographic locations. Built on a high-availability and high-performance grid
architecture, BMC Atrium Orchestrator offers out-of-the-box workflows, leveraging your
existing systems (monitoring, service desk, BMC Atrium Configuration Management Database,
and others) to accelerate IT service execution across your enterprise.
A graphical authoring tool used to create, modify, and test workflows. It is a thick-client
application that can be installed on Windows and Mac operating systems. Using BMC Atrium
Orchestrator Development Studio, you can edit rules and schedules to trigger workflows
automatically by external events or at regular intervals. Your developers can maintain control
of workflows in their local BMC Atrium Orchestrator Development Studio environment or
through an external source code management (SCM) system.
A web-based interface that enables operators, such as service desk, network operators, and IT
technicians, to run workflows in a semi-automated mode. It enables operators to manually

launch a workflow, follow its progress in a graphical view, and provide input as required.
Using BMC Atrium Orchestrator Operator Control Panel, operators can fulfill IT services more
accurately and efficiently while maintaining full control of workflow execution.
breakpoint
A pause in the testing of a process in the Debugger tool. A breakpoint permits you to perform
more in-depth examination of the process at that point.
C
An activity that provides a mechanism to execute work on a preconfigured adapter within the
grid. Adapters communicate with external systems.
Comment activity
An activity that enables you to place information on the process canvas.
compensation
A defined process for handling or recovering from a failed process or activity.
configuration distribution peer (CDP)
The primary peer in the grid. It provides a central administration point and is a workflow
execution engine. The CDP houses the BMC Atrium Orchestrator Grid Manager application. It
can also host adapters and workflow modules, which are used by the grid to communicate
with external systems. Typical grid configurations include one CDP, although a grid can house
two CDPs in high-availability (HACDP) mode.
configuration file
File containing configuration information used to communicate with a CDP.
configuration item
Variable that persists across multiple modules within a grid. This value is defined within a
BMC Atrium Orchestrator Development Studio module using the module configuration editor.
The value for this variable can be modified within Grid Manager for active modules.
configuration node
The XML text entered in the Properties field during adapter configuration within Grid
Manager. This node contains specific information to allow an adapter to connect to a server,
database, or application to perform a function.

context item
Variable defined within BMC Atrium Orchestrator Development Studio. Context Item values
can persist across a single process (local) or can persist across a single grid (global).
D
Debugger
A BMC Atrium Orchestrator Development Studio tool that enables you to step through the
testing of a process, stopping at predefined breakpoints, to ensure that the anticipated outcome
is achieved with the process. You can execute the process, follow the execution paths, and see
the context values assigned throughout the process.
Designer
BMC Atrium Orchestrator Development Studio view used for designing, scheduling, and
testing processes.
designer (role)
Grid role for an account that enables you to export and import modules to and from a grid.
dynamic context
Variable that provides you with a method to store data in a container that can have a variable
name. With a context item, a value is assigned to a specifically named container. With a
dynamic context, the name of the container is the value of a specific context item.
E
element
Segment of an XML file. Each element can contain either a specific defined value or a set of
additional elements.
End activity
An activity that represents the end of a process. Only one End activity can be within a process
definition, and it cannot be deleted. All steps within the process end at this activity.
environment
A collection of grids and their peers, associated with one or more CDPs.

epoch time
Format for storing date and time data. The MM/DD/YYYY HH:MM:SS form is converted into
a value that represents the number of seconds elapsed since a fixed date and time, called an
epoch. The epoch varies by operating system.
F
fat command
Actor adapter request element used to contain a command or set of commands, using syntax
for execution in multiple operating systems. The command attributes contain the operating
system type and version. These attributes are matched against the target OS and version, with
the appropriate commands executed for that target.
For activity
An activity that initiates a loop of activities that enables iterative processing of data within a
process.
G
global context item
Variable defined within BMC Atrium Orchestrator Development Studio that is available to and
persists across the entire grid.
grid
A logical collection of peers, usually executing on different physical host computers. The peers
within the grid can communicate by using a variety of methods. The peers in a grid work as a
group, communicating concurrently with every other grid peer in the group, and can detect
which peers are running and the load on those peers. The core functions of the grids are:
Grid component provisioning, configuration, and management
Activity detection, initiation, and processing
Process scheduling
Dynamic load distribution
Corporate-wide metric and data aggregation
Grid Manager

A BMC Atrium Orchestrator component that resides on the CDP server and provides a user
interface to add and maintain grids, peers, adapters, and process schedules. It enables you to
manage module deployment and activation. You can also use BMC Atrium Orchestrator Grid
Manager to enable collection of metrics about grid and process performance.
grid performance metrics
A set of defined historical records of the grid and peer environment. Grid performance metrics
can be collected globally or configured to gather individual metrics data.
H
HTTPS
HTTPS (Hypertext Transfer Protocol over Secure Socket Layer, or HTTP over SSL) is a web
protocol developed by Netscape that encrypts and decrypts user page requests as well as the
pages that are returned by the web server.
I
An activity that launches the integration mapping wizard to query adapter schemas and forms
to map data to and from context items.
ITIL
A library of documents, developed by the UK government, that provides a foundation of best
practices for the Information Technology (IT) Services discipline. Composed of multiple
documents that address specific components of service support and service delivery, it is
considered the global standard for IT Service Management.
J
jar
A Java Archive (JAR) file; contains the class files and auxiliary resources associated with
applets and applications.
Java
A programming language expressly designed for use in the distributed environment of the
Internet. Java can be used to create complete applications that can run on a single computer or
be distributed among servers and clients in a network. It can be used to build a small

application module or applet for use as part of a web page. Applets make it possible for a web
page user to interact with the page.
JDBC
Java Database Connectivity (JDBC) is an application program interface (API) specification for
connecting programs written in Java to the data in popular databases. The API allows you to
encode access request statements in Structured Query Language (SQL) that are then passed to
the program that manages the database. It returns the results through a similar interface. JDBC
is very similar to the SQL Access Group's Open Database Connectivity (ODBC) and, with a
small "bridge" program, you can use the JDBC interface to access databases through the ODBC
interface.
JMS provider
An implementation of the Java Messaging Service (JMS), which is a standard for message
oriented middleware, or MOM, applications.
JNDI
Java Naming and Directory Interface; enables Java platform-based applications to access
multiple naming and directory services. Part of the Java Enterprise application programming
interface (API) set, JNDI makes it possible for developers to create portable applications that
are enabled for a number of different naming and directory services, including: file systems;
directory services such as Lightweight Directory Access Protocol (LDAP), Novell Directory
Services, and Network Information System (NIS); and distributed object systems such as the
Common Object Request Broker Architecture (CORBA), Java Remote Method Invocation
(RMI), and Enterprise JavaBeans (EJB).
JXTA
Juxtapose; an open source peer-to-peer protocol specification created by Sun Microsystems. It
is based on a set of open XML protocols that enable any connected computing devices on a
network to collaborate.
K
Kerberos
A network authentication protocol that enables individuals communicating over a nonsecure
network to prove their identity to one another in a secure manner.
L
Launch Job activity

An activity that spawns a new process and executes the existing process asynchronously.
LDAP
Lightweight Directory Access Protocol; an Internet protocol used to retrieve information from a
server via an encrypted SSL connection. LDAP defines the permissions to limit access to the
LDAP database and schema, which describes the format and attributes of data in the server.
M
Metrics activity
Activity that enables you to record business metrics for a process during execution. The current
state, category, description, and specified parameters can be recorded within the metric. After
the metric data is recorded, you can create reports to analyze the data.
metrics database
A database that contains process metrics, audit records, and grid performance metrics data
collected for a environment. One or more databases can be used as the metrics database.
module
A grouping of ITIL based processes, schedules, rules, and configuration items for specific
operational disciplines.
N
node
A component of an XSLT stylesheet used to describe a set of XML elements.
O
An activity that enables you to provide input to an operator process during execution.
operator process
A process that is manually executed in the BMC Atrium Orchestrator Operator Control Panel.

P
Pause activity
An activity that enables a process to be suspended for a specific amount of time. If the overall
process timeout is less than the pause time, the job will time out and compensation will be
executed in lieu of finishing the process.
PDL (process design language)
A tab within the BMC Atrium Orchestrator Development Studio process Designer that
displays a read-only view of the XML properties of a process.
peer
A logical instance of BMC Atrium Orchestrator software on the grid. A peer can be a
configuration distribution peer, an activity peer, or a lightweight activity peer.
process
A set of linked activities that perform a specific function. Processes can contain other processes.
process canvas
The area within the BMC Atrium Orchestrator Development Studio Designer where a process
is graphically designed.
Project Navigator
Palette available in the Designer and Debugger views that contains the environment, grid,
module, and process information for the active environment.
Property Panel
The area for specifying the details associated with each activity, containing tabs for properties,
logging, and metadata.
Q
qualified name (qname)
A name that must begin with an alpha character, an underscore, or a colon and can contain
alphanumeric characters, dashes, or underscores.

R
regular expression (regex)
An expression that can either evaluate the contents of a input string and return a Boolean value
or substitute a given string for text contained within an input string.
repository
Stores BMC Atrium Orchestrator content, such as adapters and workflow modules, in a central
location. As the source of record, the repository is accessed by a multitude of users, including
workflow developers, software testers, and system administrators. The repository enforces
versioning and keeps a history of workflow modules through their revisions. It also offers role-
based access control so that you can ensure that users can access only the appropriate content.
rules designer
A component of the BMC Atrium Orchestrator Development Studio Designer in which rules
are created. Rules in active modules on a grid cause a specified process to be executed upon
receipt of an event matching specified criteria.
S
schedule designer
A component in the BMC Atrium Orchestrator Development Studio Designer where processes
are scheduled. These schedules are activated when the module is activated on a grid.
Script activity
An activity that enables existing script files to be called within the native operating system, or
for new scripts to be written within the activity itself.
Spawn activity
An activity that enables two or more process paths to be executed in parallel.
Start activity
The activity that represents the start of a process. Only one Start activity can exist within a
process definition, and it cannot be deleted. All steps within the process follow this activity.
Switch activity
An activity that enables conditional process paths to be taken based on one or more conditions.
If no conditions are met, then the default path is taken.

sync point
A peer (CDP or AP) that is designated to upload metrics data to the metrics database.
T
token
A variable that facilitates the use of values contained in context items within XML documents.
In a Transform Editor, a token is used to reference a context items in an expression. Sample
values are assigned to tokens for use in the preview function of the Transform Editor.
Transform Editor
A Transformer Editor is used to create and test any XPath or XSLT transform applied against
an XML document, context items, dynamic context, or configuration item.
U
Utility activity
An activity that enables common actions on strings, numbers, and dates to be performed.
W
web service
A web service is a software application identified by a URI, whose interfaces and binding can
be defined, described, and discovered by XML artifacts and supports direct interactions with
other software applications using XML based messages via internet-based protocols.
WSDL
Web Services Description Language (WSDL); an XML-based language that provides a model
for describing web services.
WS-1
Organization that sets standards for SOAP communication.
X
XML schema

A means for defining the structure, content, and semantics of XML documents.
XPath
An expression language used by XSLT to access or refer to parts of an XML document. XPath is
used by the XML Linking specification.
XSL
A language for expressing style sheets. It consists of XSL Transformations (XSLT); the XML
Path Language (XPath); and XSL Formatting Objects. XSLT is a language for transforming XML
documents. XPath is an expression language used by XSLT to access or refer to parts of an
XML document (XPath is used by the XML Linking specification). XSL Formatting Objects is an
XML vocabulary for specifying formatting semantics. An XSL style sheet specifies the
presentation of a class of XML documents by describing how an instance of the class is
transformed into an XML document that uses the formatting vocabulary.
XSLT
XSL Transformations (XSLT); a language for transforming XML documents.

Index
A
about BMC Atrium Orchestrator 15
Access Manager
described 16
activities
Assign 183
Call Adapter 212
Comment 215
configuring logging for 125, 126
End 181
For 196
Integration Mapping 213
Launch Job 198
Metrics 207
Operator dialog 187
overview 179
Pause 208
Script 209
Spawn 197
Start 180
Switch 194
Utility 199
See also individual activity names
Activity Palette 20
activity peer. See AP
activity properties 124, 179
Activity property panel - Metadata tab 127
Activity property panel - Properties Tab 125
activity, Integration Mapping 215
activity, Metrics 207
activity, Script 210
adapters
language enabled 236
Add activities to a process 123
advanced search 139
Advanced transform editor 160
Document pane 158
example 87
Sample pane 156
Token pane 157
XPath Helpers 158
XPath transformations 155
See also XPath transform editor
Advanced transform editor copy node 173
Advanced transform editor node 174
AP
described 17
Append utility 31
architecture of platform 16
Assign activity 42, 53, 76, 87, 183
assign statement
create 184
delete 186
automapping context items 130
B
bao.options file 26
Basic transform editor 150
function sequence 151
functions 152
preview frame 150
Select resource pane 150
test frame 150
BMC Atrium Orchestrator Access Manager. See
Access Manager
described 16
overview 18
described 17
breakpoint manager 227
C
Call Adapter activity 48, 212
Called Process viewer 131
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index 251
Calling Process viewer 131
CDP
described 16
Command Line adapter 48
Comment activity 215
Compensations 128
compensations, add activity in a workflow process
128
compensations, adding to an activity 128
concepts 68, 221
configuration distribution peer. See CDP
configuration items 118, 119
creating 65
configuring
connections 23
connection details concept 68
connections
configuring 23
creating 23, 24
deleting 24
troubleshooting 26
Connections 19
Context Browser 217
context item 221
Context item overview 217
context items
automapping 130
context items, system parameters 220
Context Name 181
conventions, documentation 12
Copy Files example 76
Copy Files in Directory example 87, 104
Create an assign statement 184
creating
called processes 129
configuration items 65
modules 30, 39
processes 30, 39
workflows 30, 39, 76, 87
CVS 144
D
data types
secure 118, 119, 232
date formatter codes 152
date utilities
before and after 200
between 201
decrement and increment 201
now 202
operations 199
Debugger 21
debugger execution Viewer 225
debugger tool 224
Debugger Tool Bar 226
debugger tool, Context Viewer 226
Debugging a Process 225
Debugging, creating a breakpoint 227
delete an assign statement 186
Development Studio. See BMC Atrium Orchestrator
Development Studio
Directory list example 38, 39, 41, 42, 48, 51, 53, 61, 62
directory listing example 37, 41
dynamic context scenario 219
dynamic contexts 219
E
electronic documentation 11
End activity 61, 181
environments
configuring 23
example files
bao.options file 26
example transforms 87
example workflows
Copy Files 37, 76
Copy Files in Directory 37, 87, 104
Directory list 37
Directory List 38, 39, 41, 42, 48, 51, 53, 61, 62
directory listing 37, 41
Hello World 2931, 35
F
For activity 87, 196
Function sequence 151
G
graphing server
described 17
H
Hello World example 2931, 35
Help
online 11
I
importing a module from a disk 109
importing utilities 67
Index Term 229, 235
Input Parameter Name 181
Integration Mapping activity 213
creating 213
editing 215
updating 215
Integration mapping wizard 221
L
language enablement 236
LAP
described 17
Launch Job activity 198
Launch pad 18
Library Manager 19, 67, 107
lightweight activity peer. See LAP
logging
configuring 125, 126
M
Metrics activity 207
module archive file
.roar 109
modules 107
creating 30, 39
importing 107, 109
multibyte characters 235
N
numeric utilities
operations 203
O
OCP. See BMC Atrium Orchestrator Operator
Control
online Help 11
Operator Dialog activity 187
Boolean input 191
date input 190
list input dynamic values 193
list input static value 192
numeric input 189
password Input 188
string input 188
optional components described 17
overview 15
Overview, launch pad 18
P
Pause activity 208
PDFs, searching 12
Perforce 147
Preview frame 150
process canvas 20
process design 121
Process designer 20
process directories
creating 111
moving 111
renaming 132
process module, export 141
process properties 122
Process, add activities 123
process, add activities to 123
processes
called 129
creating 30, 39
renaming 132
Processes, create 121
Project Navigator 20
Project Navigator, advanced search results window
139
R
renaming
process directories 132
processes 132
repository 109
described 16
required components described 16
rules 112
S
schedules 115
SCM 143
CVS 144
Perforce 147
Subversion 146
Script activity 209
parameters 210
searching PDFs 12
secure data types
troubleshooting 232
SOAP 181
software configuration management. See SCM
Index 253
source control management 143
Spawn activity 197
Start activity 41, 76, 87, 180
Start activity properties 180
string utilities
concat 204
lowercase and uppercase 206
operations 204
regex 206
substring 205
Subversion 146
Switch activity 194
T
Test frame 150
Testing a process 223
testing processes, Test Console 226
testing workflows 35, 51, 62, 74, 104
transform editors 149
See also Advanced transform editor and Basic
transform editor
troubleshooting
connections 26
secure data types 232
TTL 181
U
utilities
importing 67
using 76, 87, 104
Utility activity 199
date utilities 199202
numeric utilities 203
string utilities 204206
V
view process properties 122
W
workflows
creating 30, 39, 76, 87
testing 35, 51, 62, 74, 104
WSDL 135
X
XPath Helpers 158
XPath transform editor 155, 178
XSLT Document pane 162
XSLT Parameter nodes 169
Param 169
Variable 169
with Param 170
XSLT process nodes 175
choose 177
for each 176
if 177
otherwise 178
sort 176
when 178
XSLT sample Pane 161
XSLT Source pane 162
XSLT Stylesheet template nodes 163
additional namespaces 164
apply template 166
call template 167
CDATA output 165
output 164
preserve space 168
strip space 167
Stylesheet 163
template 165
XSLT text nodes 170
attribute 171
comment 172
copy 173
copy of 172
decimal format 174
element 170
number 174
text 172
token 173
value of 173
XML comment 172
XSLT tokens pane 161
XSLT transform editor 155, 161, 162
Parameter nodes 169
process nodes 175
Stylesheet template nodes 163
text nodes 170
See also Advanced transform editor
49532
*194605*

BMC Atrium Orchestrator 7-6-02 Development Studio User Guide

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

BMC Atrium Orchestrator 7-6-02 Development Studio User Guide

Загружено:

Авторское право:

Доступные форматы

BMC Atrium Orchestrator

Development Studio User

Вам также может понравиться