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. UNPUBLISHED—RIGHTS 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 [email protected]. (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 [email protected].

■

Use the Customer Support website at http://www.bmc.com/support.

4


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 Panel—Properties tab ........................................................125 Activity Property Panel—Logging tab ...........................................................125 Activity Property Panel—Metadata 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

6


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 input—static values ...................................................................................192 List input—dynamic 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

8


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

10


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


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 semiautomated mode through a web-based user interface

About this Book 11

Searching across PDF documents in a folder and its subfolders

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:

12 BMC Atrium Orchestrator Development Studio User Guide

Conventions

■ 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.

About this Book

13

Conventions


1 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 bestpractice standards are met 100% of the time.

Chapter 1 Introduction to BMC Atrium Orchestrator Development Studio 15

BMC Atrium Orchestrator overview

Architecture overview BMC Atrium Orchestrator is built on a grid architecture that offers out-of-the-box highavailability, 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 signon (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 16 BMC Atrium Orchestrator Development Studio User Guide

BMC Atrium Orchestrator overview

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 thirdparty application. Chapter 1 Introduction to BMC Atrium Orchestrator Development Studio 17

BMC Atrium Orchestrator Development Studio overview

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



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.




2 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.

Chapter 2 Configuring BMC Atrium Orchestrator Development Studio 23

Connecting to an environment

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 -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J -J

installLocation=C:\Program Files\BMC Software\AO AO_INSTALL_TYPE=install_new AO_INSTALLING_FEATURES=CDP,WEBSERVER,OCP AO_REPOSITORY_URL=http://vm-w23-xyz010:8080/baorepo AO_CERT_PASSWORD= AO_CERT_PRINCIPAL=My Company Name AO_ENVIRONMENT_NAME=ENV1 AO_START_SERVER_ON_SUCCESS=true AO_OCP_DEPLOYMENT_CONTEXT=baoocp AO_AM_DEPLOYMENT_CONTEXT=baoam AO_GRAPH_DEPLOYMENT_CONTEXT=baograph AO_PEER_NAME=CDP1 AO_PEER_NET_CONFIG_VALIDATE=false AO_PEER_NET_CONFIG_CDP_CONTEXT=baocdp AO_PEER_NET_CONFIG_CDP_HOST=vm-w23-xyz010 AO_PEER_NET_CONFIG_CDP_PASSWORD= AO_PEER_NET_CONFIG_CDP_PORT=38080 AO_REPOSITORY_HOST=vm-w23-xyz010 AO_REPOSITORY_PORT=8080 AO_REPOSITORY_USER_NAME=admin AO_REPOSITORY_PASSWORD= AO_PEER_NET_CONFIG_CDP_USER=admin AO_PEER_NET_CONFIG_GRID_NAME=GRID1 AO_PEER_NET_CONFIG_PEER_NAME=CDP1 AO_PEER_NET_CONFIG_NEW_PEER_NAME=LAP1 AO_PEER_NET_CONFIG_PROTOCOL=http AO_SECURITY_ACTIVE=true AO_SECURITY_COMM_PORT=61616 AO_SECURITY_COMM_PROTOCOL=ssl AO_SECURITY_WEB_PORT=8080 AO_SECURITY_WEB_PROTOCOL=http AO_WEBSERVER_SSL_ENABLED=false AO_WEBSERVER_PORT=38080 AO_WEBSERVER_SHUTDOWN_PORT=8005 AO_PEER_COMM_PORT=8081 AO_WEBSERVER_DETECTED_OLD_SETTINGS=false AO_SERVER_STOP_SUCCCESSFUL=false AO_REPOSITORY_PROTOCOL=http




3 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.

Chapter 3 Creating the Hello World workflow 29

Before you begin to create the Hello World workflow

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.


Creating and configuring the Append utility for 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. Chapter 3 Creating the Hello World workflow 31


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. Figure 4: Design canvas with Start and End activities

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, doubleclick in the Input Name/Value field that corresponds to the adapter name Output Name.

Chapter 3 Creating the Hello World workflow 33


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. 34 BMC Atrium Orchestrator Development Studio User Guide

Running the Hello World workflow

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. Chapter 3 Creating the Hello World workflow 35

Running the Hello World workflow

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.


4 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.

Chapter 4 Creating a directory workflow 37

Before you begin to create a workflow

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.


Creating a module and 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.


Creating a module and a workflow

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

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.


Creating and configuring the first Assign 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: Figure 14: Design canvas with Start and End activities

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.



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 add a new assign statement.

to



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 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.



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 Context Browser.

to open the

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 name—as 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

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. 48 BMC Atrium Orchestrator Development Studio User Guide

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

Click


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

Click


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.


Testing the workflow and gathering sample data

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. 9 Save the workflow.

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. 50 BMC Atrium Orchestrator Development Studio User Guide


Before you begin To test the workflow, you must know the name that was assigned to the ro-adaptercommand-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

.

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; 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-adaptercommand-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. 8 Verify that the last line in the console window is The process terminated in the completed state.

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".


Creating and configuring the second Assign activity

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 to The transform editor that you use when creating the second Assign activity would treat 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



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 shown in Figure 27 on page 54. 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


to

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

Click


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, 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 to , 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 text and paste the adapter response text that you copied from the process_sample.txt file. Chapter 4 Creating a directory workflow 55


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

Click


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


to

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

Click


b In the Local Context area, click adapter response, and then click Select. c In the Insert Context/Configuration Element dialog box, click OK. 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 success . 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 //commandoutput/metadata/status/text( ) and click Generate Preview

.

i Verify that the Preview Drawer contains success . 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

Click


b In the Context Browser, click New. 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


to

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 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 because there are no errors in the sample directory listing. Chapter 4 Creating a directory workflow 59


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. 6 On the Properties tab of the Property Panel for the assign statement, click OK. 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

Click


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.


Configuring the End activity

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

6 Click OK to return to the design canvas. 7

Click


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


Testing the workflow

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. 5 Click OK to return to the design canvas. 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.




Note




.

2 In the Execution Mode dialog box, select Test as if triggered by a rule, schedule or SOAP, and then click OK. 3 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-adaptercommand-line adapter when it was configured on the grid.

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. This message indicates that the process that you created ran to completion. 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.

This message indicates that the process that you created ran to completion. 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= The system cannot find the path specified. ] 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 Name=:Samples:List directory] [Root Job Id=a43aa4c65dd03689:4ec77ace: 12a1f409a1d:-80001-1280431888363] [Job Id=a43aa4c65dd03689:4ec77ace: 12a1f409a1d:-80001-1280431888363] An error occurred that triggered compensation: Summary: Execution failed. Caused by: Summary: no peer with a running instance of commandLineadapter found INFO - [Current Time=Thu Jul 29 14:31:28 CDT 2010] [Process Name=:Samples:List directory] [Root Job Id=a43aa4c65dd03689:4ec77ace: 12a1f409a1d:-80001-1280431888363] [Job Id=a43aa4c65dd03689:4ec77ace: 12a1f409a1d:-80001-1280431888363] Stack Trace: procdef:Samples:List directory:start:call-adapter[1] INFO - [Current Time=Thu Jul 29 14:31:28 CDT 2010] [Process Name=:Samples:List directory] [Root Job Id=a43aa4c65dd03689:4ec77ace: 12a1f409a1d:-80001-1280431888363] [Job Id=a43aa4c65dd03689:4ec77ace: 12a1f409a1d:-80001-1280431888363] The process terminated in the compensated state.

10 In the console window, click Clear and then click Close. 11 Click File => Exit to close BMC Atrium Orchestrator Development Studio.


Creating the configuration items

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 Configuration pane.

at the top of the Module

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).


Creating the configuration items

The configuration item and value are displayed below the selected group as shown in Figure 33 on page 66. 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.

Type


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.

Type


Value

Enter copy.


Importing utilities modules

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-OACommon-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.


Creating the connection details concept

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. 68 BMC Atrium Orchestrator Development Studio User Guide


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. The new workflow name is added to the module in the Project Navigator, and the 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 1 On the design canvas, double-click the Start activity. 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. 9 Save the workflow.

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

Click


7 In the Context Browser, select the adapter context item.


to


8 In the output parameter section, use the Context Browser to create a new context item called connection details: a

Click


b In the Context Browser, click New. 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. Chapter 4 Creating a directory workflow 71


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


to

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-CommonUtilities: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 shown in Figure 39 on page 73. 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. 23 Save the workflow.

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. 6 Save the workflow.


Testing the Make connection details for Invoke Command workflow

Testing the Make connection details for Invoke Command workflow In this task, you verify that the workflow creates a connection details concept.


Note




.

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 workflow. 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, and then click OK. 4 In the Job Input Parameters dialog box, double-click in the Value field for the adapter parameter and type the name that was assigned to the ro-adaptercommand-line adapter when it was configured on the grid. 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

6 Verify that the last line in the console window is The process terminated in the completed state.

This message indicates that the workflow that you created ran to completion.

Note

Do not clear or close the console window. 7 (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 connection details concept is shown immediately after "After Execution".

To gather sample data 1 Open a text editor and create a blank document. 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: commandLineAdapter command-line


Creating the Copy File 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. 4 In the console window, click Clear and then click Close.

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 toplevel 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 1 In the Project Navigator tree, right-click Samples and select New Process.



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. The new workflow name is added to the module in the Project Navigator, and the design canvas displays the new workflow.

To configure the input parameters 1 On the design canvas, double-click the Start activity. 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. 6 Save the workflow.

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. 3 Double-click the Assign activity. 4


to

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

Click


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. 10 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 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. 12 Save the workflow.

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


.

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, and then click OK. 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. 6 In the Job Input Parameters dialog box, double-click in the Value field for the 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. 9 In the Job Input Parameters dialog box, double-click in the Value field for the 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. 11 In the Job Input Parameters dialog box, double-click in the Value field for the 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 Chapter 4 Creating a directory workflow 81


process canvas, the Create copy command and Invoke Command activities have brown boxes around them to indicate that they have been executed. 13 Verify that the last line in the console window is The process terminated in the completed state.


Note

Do not clear or close the console window. 14 (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. 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 and ends with . 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. 2 Double-click the Assign activity. 3


to

4 On the Properties tab of 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:



a

Click


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. 5 On the Properties tab on the Property Panel for the assign statement, click Basic to open the Basic transform editor. 6 Use the Basic transform editor to extract the status information from the adapter response: a

Click


The Select Resource dialog box is displayed. b



c In the File Name field of the Input dialog box, type sample command result, and then click OK. In the bottom pane of the Select Resource dialog box, is displayed. 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 to , including all of the angle brackets. f In the bottom pane of the Select Resource dialog box, delete the text and paste the command result text that you copied from the Sample_Command_Result.txt file. g

Click


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 success.

k

In the Basic transform editor, in the Function sequence area, click new function.

to add a

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. 7 On the Properties tab, for Output Context Type, select Context item. 8 Use the Context Browser to create a new context item called status: a

Click


b In the Context Browser, click New. 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 statement.

to add a new assign

11 On the Properties tab of 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.



12 On the Properties tab on the Property Panel for the assign statement, click Basic to open the Basic transform editor. 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 area; otherwise skip to step c.

to open a sample from the resource

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 . f

In the Basic transform editor, in the Function sequence area, click new function.

to add a

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. 14 On the Properties tab, for Output Context Type, select Context item. 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. 18 Save the workflow.



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 the After Execution tab. 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

Click


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. 86 BMC Atrium Orchestrator Development Studio User Guide

Creating the Copy Files in Directory workflow

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

5 Click OK to return to the design canvas. 6 Save the 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 1 In the Project Navigator tree, right-click Samples and select New Process. 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. The new workflow name is added to the module in the Project Navigator, and the 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

Click


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. 9 Save the workflow.

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. 4 In the Call process input mapping section of the Property Panel, double-click in 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. 9 In the Call process input mapping section of the Property Panel, double-click in 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



.


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 workflow. 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, and then click OK. 4 In the Job Input Parameters dialog box, double-click in the Value field for the 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. 7 Verify that the last line in the console window is The process terminated in the completed state.




Note Do not clear or close the console window. 8 (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.

To gather sample data In this procedure, you save results from the test of the workflow to use in subsequent tasks. 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 temp.txt. 4 Search temp.txt for directory list. 5 Copy the contents of the directory list, beginning with and ending with . 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 to The transform editor that you use in the subsequent activity would treat 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: Volume in drive C has no label. Volume Serial Number is 6850-9DBA Directory of c:\pictures 12/23/2010 04:52 PM . 12/23/2010 04:52 PM .. 12/14/2007 02:21 PM 33,063 IMG_0307.JPG 12/14/2007 02:21 PM 28,606 IMG_0308.JPG 12/14/2007 02:21 PM 24,724 IMG_0309.JPG


line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 12/14/2007 02:21 PM line> 22 File(s) 2 Dir(s) line>

31,945 IMG_0310.JPG 1,633,210,368 bytes free
9 In the console window, click Clear and then click Close.

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


b In the File Name field of the Input dialog box, type sample directory list, and then click OK. In the bottom pane of the Select Resource dialog box, is displayed. c Use a text editor to open the dir_list_sample.txt file and copy its entire contents. Copy from to , including all of the angle brackets. d In the bottom pane of the Select Resource dialog box, delete the 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 . 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. The Document entry field contains the following text: //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. The Document entry field contains the following text: //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. The Document entry field contains the following text: //line[ starts-with(., " ")

or contains(., "text")

]

l Delete text and type in its place. The Document entry field contains the following text: //line[ starts-with(., " ")

m

or contains(., "")

In the Document pane, click Generate Preview


.

]


This expression extracts the lines that do not contain file names, as shown in Figure 54 on page 99. 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. The Document entry field contains the following text: //line[ not(starts-with(., " ")

o

or contains(., ""))

In the Document pane, click Generate Preview

]

.



Now the expression extracts the lines that do contain file names, as shown in Figure 55 on page 100. 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


to

5 On the Properties tab for the assign statement, select Context item as the input 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

Click


The Select Resource dialog box is displayed. c



d In the File Name field of the Input dialog box, type directory item, and then click OK. In the bottom pane of the Select Resource dialog box, is displayed. e Use a text editor to open the dir_list_sample.txt file and copy one line that contains a file name. Copy from to , including all of the angle brackets. f In the bottom pane of the Select Resource dialog box, delete the text and paste the line that you copied. g

Click


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

On the Properties tab of the Property Panel for the Assign activity, click add another assign statement.

to

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. 18 Save the workflow.

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. 3 Save the workflow.


Testing the Copy Files in Directory process

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, doubleclick it. 2


.

3 In the Execution Mode dialog box, select Test as if triggered by a rule, schedule or SOAP, and then click OK. 4 In the Job Input Parameters dialog box, double-click in the Value field for the source dir parameter and type the name of the directory from which you want to copy the files. 104 BMC Atrium Orchestrator Development Studio User Guide


5 In the Job Input Parameters dialog box, 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. 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. This message indicates that the process that you created ran to completion. 8 Connect to the peer that executed the process, and verify that the files were copied into the destination directory.




5 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.

Chapter 5 Using modules

107

Library Manager

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 108 BMC Atrium Orchestrator Development Studio User Guide

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 1 Click Library Manager. 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.


109

Creating modules

To import and unbundle a module from a disk 1 Click Library Manager. 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.


Using process directories

■ 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.


111

Creating rules

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.


113

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 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 schedules

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. Chapter 5 Using modules

115

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

Run forever

Job starts immediately when the module or adapter activates and runs at selected frequency forever.

Run every

Stop on MM/DD/YYYY

XX minutes XX seconds

HH:MM:SS

Job starts immediately when the module or adapter activates and runs at selected frequency until designated stop time.

Run every

After N runs

Job starts immediately when the module or adapter activates and runs N times at the frequency selected.






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

Run every

Run forever

HH:MM:SS


Job starts at designated time and runs at selected frequency forever.

Start on MM/DD/YYYY

Run once every

After N runs

Job starts at designated time and runs N times at the frequency selected.

HH:MM:SS


117

Configuration items

Start

Frequency

Stop

Results

Start on MM/DD/YYYY

n/a

After 1 run

Job starts at designated time and runs once. The frequency options are not available.

HH:MM:SS

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

Add Module Configuration Item at the top of the Module Click 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


119

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.


6 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.

Chapter 6 Process design 121

Process properties

■ 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, rightclick 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.


Adding activities to a process

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. Chapter 6 Process design 123

Activity properties

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 Panel—Properties 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 Panel—Logging 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 After Execution tab. 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. 126 BMC Atrium Orchestrator Development Studio User Guide

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 c

Click Insert Context/Config Element

.

In the Insert Context/Configuration Element dialog box, click Context Browser.

to open the

d In the Context Browser, select the context item whose value you want to log. 7 Click OK.

Activity Property Panel—Metadata 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.


Compensations

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.


Called processes

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. Chapter 6 Process design 129

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.


Renaming a process or process directory

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. 132 BMC Atrium Orchestrator Development Studio User Guide

Operator processes

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 BMC

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 BMC

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


WSDL to workflow process generation wizard

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.


Searching for processes

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.


Searching for processes

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.


Generating process documentation

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 140 BMC Atrium Orchestrator Development Studio User Guide

Export the process module

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.


Export the process module

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.


7 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.

Chapter 7 Using software configuration management systems when creating workflows 143

Configuring BMC Atrium Orchestrator Development Studio to use CVS

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 A new module is created in CVS under the selected the selected module 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 Subversion

Configuring BMC Atrium Orchestrator Development Studio to use Subversion Use this task to configure BMC Atrium Orchestrator Development Studio to manage the workflows in a grid using the Subversion product.

Before you begin Before you can configure BMC Atrium Orchestrator Development Studio to 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 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 Subversion. 2 In the menu, select Team => Share Project. 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 Perforce

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.

Configuring BMC Atrium Orchestrator Development Studio to use Perforce Use this task to configure BMC Atrium Orchestrator Development Studio to manage the workflows in a grid using the Perforce product.

Before you begin Before you can configure BMC Atrium Orchestrator Development Studio to 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 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 Perforce. 2 In the menu, select Team => Share Project. 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


Configuring BMC Atrium Orchestrator Development Studio to use Perforce

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.


8 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.

Chapter 8 Using a transform editor 149

Basic transform editor

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). Chapter 8 Using a transform editor 151


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 Substring Before Text Substring After Text Length n/a Trim spaces n/a

Retrieves the substring of text that you specify.\ Retrieves the substring that is displayed before the specified text Retrieves the provided substring that is displayed after the specified text Retrieves the length of the string 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 Convert to Numeric n/a

Replaces the specified text with the provided text 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



Function

Operands Child at number Child Index

XML to Text (newlines) n/a

XML to Text n/a Items contents contain contains

Description Retrieves the child element at the specified position Extracts the text from all XML elements in the input. The text from each element is on a separate line Extracts the text from all XML elements in the input. The text is concatenated into one string 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, value attribute matches

Removes items from XML with a specific attribute matching the specified value

Remove elements whose attribute, value attribute contains

Removes elements, including sub-elements, that have a specific attribute whose value is contained within a specified numeric range. The first operand defines the name, and the second operand defines the range

Remove elements in attribute attribute, range range

Removes elements, including sub-elements, that have a specific attribute whose value is contained 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



Function

Operands

Description

Math Add number


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


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), Date/Time (to sec), Date/ Time (exact) US Date (format) Date/Time (to min), Date/Time (to sec), Date/ Time (exact) US Date (parse) Date/Time (to min), Date/Time (to sec), Date/ Time (exact) EU Date (format) Date/Time (to min), Date/Time (to sec), Date/ Time (exact) EU Date (parse) Date/Time (to min), Date/Time (to sec), Date/ 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.


Advanced transform editor overview

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. Chapter 8 Using a transform editor 155


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 .

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(.)



Group

Function

Description

Syntax

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


<

Operators

Greater than or equal


>=

Operators

Greater than


>

Operators

Equal


=

Operators

Not equal


!=

Operators

Multiply


*

Operators

Divide


div

Operators

Modulus


mod

Operators

Add


+

Operators

Subtract


-

Operators

And


and

Operators

Or


or

Position

Last

Returns the index of the last child node

last()

Position

Position

Returns the position of the current node, relative position() to the parent node

Position

Count

Counts the number of nodes

count(.) Chapter 8 Using a transform editor 159


Group

Function

Description

Syntax

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 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.



Field

Description

Required

Format

Defines the encoding format for the XML output. Common values No include: UTF-8, ISO-8859-1, Windows-1252 and UTF-16. If this field is left blank, an UTF-8 encoding value is assumed.

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.

NA

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. 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. Field

Description

Required

Name

Unique reference for this template.

Conditional

This value must be a qualified name (Qname), beginning A Template must contain a value for with a letter, colon or underscore and consisting of either the Name or Match field. A alphanumeric characters, underscores or dashes. value can be defined for both. XPath expression that defines a portion of the XML document on which the transforms in the Template's child nodes will be executed.

Conditional

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 No the order in which the template is called in the event there are multiple templates with the same Mode value.

Match

A Template must contain a value for either the Name or Match field. A value can be defined for both.

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. Field

Description

Required

Select

The XPath expression.

Yes



Field

Description

Required

Mode

An alphanumeric value, token or XPath expression that corresponds to the No value of the Mode field defined in a Template node. All templates for which an identical Mode value exists will be applied.

XPath Helpers (Groups / Functions)

The XPath helpers, Groups and Functions are used to facilitate the formation of basic XPath statements.

NA

The Property Panel configuration for each of the child nodes added with the Add 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. The Property Panel configuration for each of the child nodes added with the Add Nodes to Selection window must be completed individually.

Field

Description

Required

Name

Specifies the Name defined in the Template to be called.

Yes

Note: This value must be a qualified name (Qname), beginning with a letter, colon, or underscore and consisting of alphanumeric characters, underscores, or dashes.

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.

Field

Description

Required

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. 4 Double-click the record to enter the element name. 5 If necessary, double-click the element to edit and enter the element name. 6 Double-click the record to 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.

Field

Description

Required

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. 4 Double-click the record to enter the element name. 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 Field

Description

Required

Name

Parameter name for which a value will be defined.

Yes

This value must be a qualified name (Qname), beginning with a letter, colon or underscore and consisting of alphanumeric characters, underscores, or dashes. Select

The XPath expression used to define the parameter's value.

XPath Helpers

The XPath helpers, Groups and Functions are used to facilitate the (Groups / Functions) formation of basic XPath statements.

Yes 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 $ where is the value defined in the Name field of a Variable node. Table 7: Variable node properties Field

Description

Required

Name

Variable name for which a value will be defined.

Yes

This value must be a qualified name (Qname), beginning with a letter, colon or underscore and consisting of alphanumeric characters, underscores or dashes. Select

The XPath expression used to define the variable's value.

XPath Helpers

The XPath helpers, Groups and Functions, are used to facilitate the (Groups / Functions) formation of basic XPath statements.

Yes 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.

Field

Description

Name

Parameter name for which a value will be defined. This Name must match Yes the Name specified in the Param node of the Template being applied or called.

Required

This value must be a qualified name (Qname), beginning with a letter, colon or underscore and consisting of alphanumeric characters, underscores or dashes. Select

The XPath expression used to define the parameter's value.

Yes

XPath Helpers

The XPath helpers, Groups and Functions, are used to facilitate the formation of basic XPath statements.

NA

(Groups / Functions)

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 Field

Description

Required

Name

The name of the element to be created. Element names can consist Yes of alphanumeric characters and dashes.

Prefix

A previously defined Prefix. This value is defined using the No Additional Namespaces function, available in the Property Panel of the Stylesheet node. This is not typically defined for each element.

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. The Property Panel configuration for each of the child nodes added with the Add Nodes to Selection window must be completed individually.

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 Field

Description

Required

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

The Property Panel configuration for each of the child nodes added with the Add 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 Field

Description

Required

Comment

The comment to be written to the resulting XML document.

No

For example, a Comment of XXX will be output to the resulting XML document as

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 Field

Description

Required

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 Field

Description

Required

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.

NA

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.

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 Field

Description

Required

Select

The XPath expression used to define the segment of the source document to be written to the resulting XML document.

Yes



Field

Description

XPath Helpers

The XPath helpers, Groups and Functions, are used to facilitate the NA formation of basic XPath statements.


Required

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 Field

Description

Select

The XPath expression used to define the segment of the source document Yes to be written to the resulting XML document.

XPath Helpers


NA

Indicates whether XML special characters should be escaped in the resulting XML document or output exactly as extracted from the source document.

NA

(Groups / Functions) Disable output escaping

Required

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.

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 Field

Description

Required

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 Field

Description

Required

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 No character defined in the Grp Sep field, and will count from right to left to establish groups. The default value is 3.

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.

No

Valid values: single, multiple, any Format

Defines the output format for the number.

No

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) 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.

No

Valid values: alphabetic, traditional

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 formatnumber 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 Field

Description

Required

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 Field

Description

Required

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. The Property Panel configuration for each of the child nodes added with the Add Nodes to Selection window must be completed individually.

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 Field

Description

Required

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'.

No

Valid values: text, number 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



Field

Description

Required

XPath Helpers


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 Field

Description

Required

Test

The XPath expression used to determine if the child nodes should be processed.

Yes

XPath Helpers


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.



The Property Panel configuration for each of the child nodes added with the Add Nodes to Selection window must be completed individually. 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 Field

Description

Required

Test

The XPath expression used to determine if the child nodes should be executed.

Yes

XPath Helpers

The XPath helpers, Groups and Functions, are used to facilitate the NA formation of basic XPath statements.


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.


9 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.

Chapter 9 Activities 179

Start activity

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. 180 BMC Atrium Orchestrator Development Studio User Guide

End 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. 182 BMC Atrium Orchestrator Development Studio User Guide

Assign 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 nonleaf 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.


Operator Dialog 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. 188 BMC Atrium Orchestrator Development Studio User Guide


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. 11 When you have added all inputs, click OK.

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. 10 When you have added all inputs, click OK.



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. 3 Click the field in the Label column. 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. 12 When you have added all inputs, click OK. 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. 3 Click the field in the Label column. 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. 6 Click the field in the Context column. 7 Select the context item to which this input value will be mapped. See the Context Browser section for details on this feature. 8 Use steps 1 - 7 to create additional boolean inputs. 9 When you have added all inputs, click OK. 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 input—static 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: [first item selected by user] [second item selected by user] [third item selected by user]

If only one item is selected, the value would be mapped as shown in the following example: [item selected by user]

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. 3 Click the field in the Label column. 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: 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. 13 Click the field in the Context column. 14 Select the context item to which this input value will be mapped. 15 When you have added all inputs, click OK.

List input—dynamic 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.


Switch activity

2 After selecting the row and the field in the Type column, select List. 3 Click the field in the Label column. 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. 14 When you have added all inputs, click OK.

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. 194 BMC Atrium Orchestrator Development Studio User Guide

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.


For 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 elements will be processed by the activities in the For loop. value one value two value three

To configure a For activity 1 Select a Parameter type in the Input pane. 196 BMC Atrium Orchestrator Development Studio User Guide

Spawn 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.


Launch Job 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.


Utility 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

Operation

Description

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. 4 Click the calendar button and select the date. 5 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. 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. 8 Select the context item for the result. 9 When all the data has been entered, click OK.

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. Chapter 9 Activities 201

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. 4 Click the calendar button and select the date. 5 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. 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. 10 Select the context item for the result. 11 When all the data has been entered, click OK.

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. 5 When all the data has been entered, click OK.

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 Operation

Description

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. 3 Launch the Context Browser. 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. 8 When all the data has been entered, click OK.

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 Operation

Description

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. 8 When all the data has been entered, click OK.

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. 3 Launch the Context Browser. 4 Select the context item for the resulting string. 5 Enter the string to be converted. 6 When all the data has been entered, click OK.

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. 206 BMC Atrium Orchestrator Development Studio User Guide

Metrics 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


Pause 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. 3 Click the Browse button to launch the Context Browser. 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.


Script 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. 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.

Dynamic Context

3 If you need to transform the value before it is assigned to the token, click the Transform button and define the transformation. 4 Click the Browse button to launch the Context Browser. 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. 2 Click the Browse button to launch the Context Browser. 3 Double-click the context item that matches the name of the variable used in the script. Chapter 9 Activities 211

Call Adapter 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. 5 Click the Browse button to launch the Context Browser. 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. 212 BMC Atrium Orchestrator Development Studio User Guide

Integration Mapping activity

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


Integration Mapping activity

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.


Comment activity

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.


10 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.

Chapter 10 Context item overview 217

Context Browser

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 doubleclick 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.


Dynamic contexts

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

P1234 C5678 90745

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. Chapter 10 Context item overview 219

System parameters

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.


Concepts

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 (AutoPilot–OA–Common_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.

Chapter 10 Context item overview 221

Concepts


11 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.

Chapter 11 Testing and debugging processes 223

The debugger tool

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 indepth 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. 224 BMC Atrium Orchestrator Development Studio User Guide

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 pane—During 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 pane—The 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.


Using the Breakpoint Manager

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.


Using the Breakpoint Manager

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.


12 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 Chapter 12 Troubleshooting 229

Log files for troubleshooting

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.


Log files for troubleshooting

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

Chapter 12 Troubleshooting 231

Impact of secure module configuration on existing processes

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: cGFzc3dvcmQK

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: 232 BMC Atrium Orchestrator Development Studio User Guide


■ 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.

Chapter 12 Troubleshooting 233



A Language enablement support for BMC Atrium Orchestrator 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 BMC Atrium Orchestrator Development Studio 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 Module Name

Location ■ 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

Appendix A Language enablement support for BMC Atrium Orchestrator 235

Language enablement support for BMC Atrium Orchestrator adapters

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"



When using multibyte characters with a language enabled adapter, you must use the 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 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.

Appendix A Language enablement support for BMC Atrium Orchestrator 237



B 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 vendorspecific APIs.

administrator

Appendix B Glossary 239

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.

BMC Atrium Orchestrator 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 Development Studio 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.

BMC Atrium Orchestrator Operator Control Panel 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 240 BMC Atrium Orchestrator Development Studio User Guide

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 Call Adapter activity 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. Appendix B Glossary 241

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 Integration Mapping activity 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

Java

A Java Archive (JAR) file; contains the class files and auxiliary resources associated with applets and applications.

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 Appendix B Glossary 245

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 Operator Dialog activity 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 rolebased 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. 248 BMC Atrium Orchestrator Development Studio User Guide

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 Appendix B Glossary 249

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.


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 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 BMC Atrium Orchestrator Development Studio described 16 overview 18 BMC Atrium Orchestrator Operator Control Panel described 17 breakpoint manager 227

C Call Adapter activity 48, 212 Called Process viewer 131 Index

251

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 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

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 29–31, 35

F For activity 87, 196 Function sequence 151

G graphing server described 17

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

252

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

H Hello World example 29–31, 35 Help online 11

I importing a module from a disk 109


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 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

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 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 199–202 numeric utilities 203 string utilities 204–206

V view process properties 122

W workflows creating 30, 39, 76, 87 testing 35, 51, 62, 74, 104

254

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

Recommend Documents