Automation Director Service Builder - Hitachi Vantara … · · 2017-02-13Hitachi Command Suite Automation Director Service Builder ... This manual describes how to use Hitachi

Hitachi Command Suite

Automation Director Service BuilderUser Guide

MK-92HC222-08

© 2015, 2016, 2017 Hitachi, Ltd. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or by any means, electronicor mechanical, including copying and recording, or stored in a database or retrieval system forcommercial purposes without the express written permission of Hitachi, Ltd., or Hitachi Data SystemsCorporation (collectively “Hitachi”). Licensee may make copies of the Materials provided that any suchcopy is: (i) created as an essential step in utilization of the Software as licensed and is used in noother manner; or (ii) used for archival purposes. Licensee may not make any other copies of theMaterials. “Materials” mean text, data, photographs, graphics, audio, video and documents.

Hitachi reserves the right to make changes to this Material at any time without notice and assumesno responsibility for its use. The Materials contain the most current information available at the timeof publication.

Some of the features described in the Materials might not be currently available. Refer to the mostrecent product announcement for information about feature and product availability, or contactHitachi Data Systems Corporation at https://support.hds.com/en_us/contact-us.html.

Notice: Hitachi products and services can be ordered only under the terms and conditions of theapplicable Hitachi agreements. The use of Hitachi products is governed by the terms of youragreements with Hitachi Data Systems Corporation.

By using this software, you agree that you are responsible for:1. Acquiring the relevant consents as may be required under local privacy laws or otherwise from

authorized employees and other individuals to access relevant data; and2. Verifying that data continues to be held, retrieved, deleted, or otherwise processed in

accordance with relevant laws.

Notice on Export Controls. The technical data and technology inherent in this Document may besubject to U.S. export control laws, including the U.S. Export Administration Act and its associatedregulations, and may be subject to export or import regulations in other countries. Reader agrees tocomply strictly with all such regulations and acknowledges that Reader has the responsibility to obtainlicenses to export, re-export, or import the Document and any Compliant Products.

Hitachi is a registered trademark of Hitachi, Ltd., in the United States and other countries.

AIX, AS/400e, DB2, Domino, DS6000, DS8000, Enterprise Storage Server, eServer, FICON,FlashCopy, IBM, Lotus, MVS, OS/390, PowerPC, RS/6000, S/390, System z9, System z10, Tivoli,z/OS, z9, z10, z13, z/VM, and z/VSE are registered trademarks or trademarks of InternationalBusiness Machines Corporation.

Active Directory, ActiveX, Bing, Excel, Hyper-V, Internet Explorer, the Internet Explorer logo,Microsoft, the Microsoft Corporate Logo, MS-DOS, Outlook, PowerPoint, SharePoint, Silverlight,SmartScreen, SQL Server, Visual Basic, Visual C++, Visual Studio, Windows, the Windows logo,Windows Azure, Windows PowerShell, Windows Server, the Windows start button, and Windows Vistaare registered trademarks or trademarks of Microsoft Corporation. Microsoft product screen shots arereprinted with permission from Microsoft Corporation.

All other trademarks, service marks, and company names in this document or website are propertiesof their respective owners.

2Hitachi Automation Director Service Builder User Guide

https://support.hds.com/en_us/contact-us.html

Contents

Preface................................................................................................. 7Intended audience................................................................................................... 8Product version........................................................................................................8Release notes.......................................................................................................... 8Referenced documents.............................................................................................8Document conventions............................................................................................. 8Conventions for storage capacity values.....................................................................9Accessing product documentation........................................................................... 10Getting help...........................................................................................................10Comments.............................................................................................................10

1 Overview of Service Builder............................................................. 13Using Service Builder..............................................................................................15Key Concepts.........................................................................................................17Accessing Service Builder........................................................................................21Navigating the interface..........................................................................................21Getting started tips.................................................................................................26

2 Working with existing service templates............................................27Service template overview...................................................................................... 28Managing existing service templates........................................................................28

Viewing a service template................................................................................29Copying a service template................................................................................29Copy Service Template dialog box...................................................................... 30Editing a service template................................................................................. 30Deleting a service template............................................................................... 31Importing a service template.............................................................................32Import Service Template Package dialog box...................................................... 33Exporting a service template............................................................................. 33

3 Working with existing plug-ins..........................................................35Plug-ins overview...................................................................................................36


Select Plug-in dialog box.........................................................................................36Managing existing plug-ins......................................................................................37

Copying a plug-in............................................................................................. 37Editing a plug-in............................................................................................... 38Copy Custom Plug-in dialog box.........................................................................38Deleting a plug-in............................................................................................. 41

4 Creating a new service template.......................................................43Service template creation workflow......................................................................... 44Creating a new service template..............................................................................46Create Service Template dialog box......................................................................... 47Specifying the step flow..........................................................................................47

Creating the steps in a data flow........................................................................48Create/Edit Step Attributes dialog box................................................................ 49Specifying step properties................................................................................. 51Specify Component Input/Output Property Mapping Parameters dialog box...........53Establishing the flow of execution...................................................................... 54Creating a flow hierarchy...................................................................................56Creating a Next Step conditional branch in a flow ...............................................57Specify Execution Condition dialog box...............................................................59

Specifying the property settings.............................................................................. 62Selecting the service share properties................................................................ 62Select Service Share Property dialog box............................................................ 63Select Reference Property dialog box................................................................. 64Adding input properties.....................................................................................65Create/Edit Input Property for Service dialog box................................................ 65Create/Edit Domain Type Definition dialog box....................................................78Adding output properties...................................................................................83Create/Edit Output Property for Service dialog box..............................................83Adding variables............................................................................................... 84Create/Edit Variable dialog box.......................................................................... 85

Example of creating a new service template.............................................................86

5 Creating a new plug-in.................................................................... 91Plug-in creation workflow........................................................................................93Creating a plug-in.................................................................................................. 93Create/Edit Custom Plug-in dialog box..................................................................... 94About plug-in properties......................................................................................... 98Adding plug-in input properties............................................................................... 99Specify/Edit Input Property for Custom Plug-in dialog box......................................... 99Adding plug-in output properties........................................................................... 102Specify/Edit Output Property for Custom Plug-in dialog box..................................... 102Setting remote commands in plug-ins.................................................................... 103Setting environment variables............................................................................... 104Create/Edit Environment Variable dialog box.......................................................... 105Adding output filters.............................................................................................105Edit Output Filter dialog box..................................................................................107Creating a conditional branch using the branching plug-ins......................................107Generating an email............................................................................................. 111Example of creating a new plug-in ........................................................................112


6 Building, debugging and releasing.................................................. 123Debug and release workflow................................................................................. 125Building a service template................................................................................... 126Build/Release Result dialog box............................................................................. 127Running the debugger.......................................................................................... 128Perform Debugging dialog box.............................................................................. 130Editing service and request entries while debugging............................................... 132Working with the debugger...................................................................................133Examining debug details....................................................................................... 136Managing tasks during debugging......................................................................... 137

Controlling the processing flow of debug tasks..................................................137Handling interruptions of debug tasks.............................................................. 138Controlling the display of tasks in the Task List..................................................139

Checking the property mapping of a plug-in........................................................... 140Edit Step Property dialog box................................................................................ 141Importing property values.....................................................................................141Exporting property values..................................................................................... 143Releasing a service template................................................................................. 145

7 Advanced options..........................................................................147Editing the service template attributes................................................................... 148Edit Service Template Attributes dialog box............................................................ 148Creating property groups...................................................................................... 149

Create Property Group dialog box.....................................................................150Edit Property Group dialog box........................................................................ 152

Managing versions................................................................................................153Component Version Management dialog box.....................................................154

8 Reference information................................................................... 157List of built-in service templates............................................................................ 158List of built-in plug-ins.......................................................................................... 166List of reserved properties.....................................................................................183Locale settings for plug-ins....................................................................................186

9 Description of built-in plug-ins........................................................189General Command Plug-in.....................................................................................191File-Transfer Plug-in..............................................................................................201Repeated Execution Plug-in...................................................................................212Email Notification Plug-in...................................................................................... 218User-Response Wait Plug-in.................................................................................. 221Terminal Connect Plug-in...................................................................................... 228Terminal Command Plug-in................................................................................... 242Terminal Disconnect Plug-in.................................................................................. 252Flow Plug-in.........................................................................................................253Interval Plug-in.................................................................................................... 255Branch by ReturnCode Plug-in...............................................................................256Test Value Plug-in.................................................................................................260Abnormal-End Plug-in...........................................................................................266Branch by Property Value Plug-in...........................................................................267


File Export Plug-in................................................................................................ 272JavaScript Plug-in.................................................................................................274JavaScript Plug-in for Configuration Manager REST API........................................... 285LDEV ID Search Plug-in........................................................................................ 293Path Search Plug-in.............................................................................................. 295Web Client Plug-in................................................................................................297

Index................................................................................................ 307


PrefaceThis manual describes how to use Hitachi Automation Director ServiceBuilder.

□ Intended audience

□ Product version

□ Release notes

□ Referenced documents

□ Document conventions

□ Conventions for storage capacity values

□ Accessing product documentation

□ Getting help

□ Comments

Preface 7Hitachi Automation Director Service Builder User Guide

Intended audienceThis document is intended for storage administrators who use HitachiAutomation Director in the Admin or Developer role.

To use Service Builder, you should be familiar with the Hitachi AutomationDirector concepts, terminology, and functionality.

Product versionThis document revision applies to Hitachi Automation Director v8.5.1 or later.

Release notesRead the release notes before installing and using this product. They maycontain requirements or restrictions that are not fully described in thisdocument or updates or corrections to this document. Release notes areavailable on Hitachi Data Systems Support Connect: https://knowledge.hds.com/Documents.

Referenced documentsHitachi Automation Director documents:

Hitachi Automation Director User Guide, MK- 92HC205

Document conventionsThis document uses the following typographic conventions:

Convention Description

Bold • Indicates text in a window, including window titles, menus, menu options,buttons, fields, and labels. Example:Click OK.

• Indicates emphasized words in list items.

Italic • Indicates a document title or emphasized words in text.• Indicates a variable, which is a placeholder for actual text provided by the

user or for output by the system. Example:pairdisplay -g group(For exceptions to this convention for variables, see the entry for anglebrackets.)

Monospace Indicates text that is displayed on screen or entered by the user. Example:pairdisplay -g oradb

8 PrefaceHitachi Automation Director Service Builder User Guide

https://knowledge.hds.com/Documents


Convention Description

< > angle brackets Indicates variables in the following scenarios:• Variables are not clearly separated from the surrounding text or from

other variables. Example:Status-<report-name><file-version>.csv

• Variables in headings.

[ ] square brackets Indicates optional values. Example: [ a | b ] indicates that you can choose a,b, or nothing.

{ } braces Indicates required or expected values. Example: { a | b } indicates that youmust choose either a or b.

| vertical bar Indicates that you have a choice between two or more options or arguments.Examples:

[ a | b ] indicates that you can choose a, b, or nothing.

{ a | b } indicates that you must choose either a or b.

This document uses the following icons to draw attention to information:

Icon Label Description

Note Calls attention to important or additional information.

Tip Provides helpful information, guidelines, or suggestions for performingtasks more effectively.

Caution Warns the user of adverse conditions and/or consequences (forexample, disruptive operations, data loss, or a system crash).

WARNING Warns the user of a hazardous situation which, if not avoided, couldresult in death or serious injury.

Conventions for storage capacity valuesPhysical storage capacity values (for example, disk drive capacity) arecalculated based on the following values:

Physical capacity unit Value

1 kilobyte (KB) 1,000 (10 3) bytes

1 megabyte (MB) 1,000 KB or 1,0002 bytes

1 gigabyte (GB) 1,000 MB or 1,0003 bytes

1 terabyte (TB) 1,000 GB or 1,0004 bytes

1 petabyte (PB) 1,000 TB or 1,0005 bytes

1 exabyte (EB) 1,000 PB or 1,0006 bytes


Logical capacity values (for example, logical device capacity, cache memorycapacity) are calculated based on the following values:

Logical capacity unit Value

1 block 512 bytes

1 cylinder Mainframe: 870 KB

Open-systems:• OPEN-V: 960 KB• Others: 720 KB

1 KB 1,024 (210) bytes

1 MB 1,024 KB or 1,0242 bytes

1 GB 1,024 MB or 1,0243 bytes

1 TB 1,024 GB or 1,0244 bytes

1 PB 1,024 TB or 1,0245 bytes

1 EB 1,024 PB or 1,0246 bytes

Accessing product documentationProduct user documentation is available on Hitachi Data Systems SupportConnect: https://knowledge.hds.com/Documents. Check this site for themost current documentation, including important updates that may havebeen made after the release of the product.

Getting helpHitachi Data Systems Support Connect is the destination for technical supportof products and solutions sold by Hitachi Data Systems. To contact technicalsupport, log on to Hitachi Data Systems Support Connect for contactinformation: https://support.hds.com/en_us/contact-us.html.

Hitachi Data Systems Community is a global online community for HDScustomers, partners, independent software vendors, employees, andprospects. It is the destination to get answers, discover insights, and makeconnections. Join the conversation today! Go to community.hds.com,register, and complete your profile.

CommentsPlease send us your comments on this document to [email protected] the document title and number, including the revision level (forexample, -07), and refer to specific sections and paragraphs wheneverpossible. All comments become the property of Hitachi Data SystemsCorporation.



https://knowledge.hds.com/

https://support.hds.com/en_us/contact-us.html

https://community.hds.com/welcome

https://community.hds.com/welcome

mailto:[email protected]

Thank you!



1Overview of Service Builder

Hitachi Automation Director Service Builder provides a powerful interface formanaging and creating Service Templates that automate the execution oftasks and supply the necessary operating parameters required to provisionand allocate storage resources and automate IT processes for a givendatacenter.

The service templates are based on plug-ins that serve as the building blocksfor executing the scripts, issuing commands on a specified system, andsupplying the values for the input and output properties and variables usedduring the execution of tasks. The service templates and plug-ins can bestrung together as a series of steps that dictate the flow of operations for agiven set of tasks within the main service template.

As Service Builder is integrated with Automation Director, there is no need toinstall Automation Director on a separate test environment, and files andfolders remain in a central location. A feature allows you to test services,plug-ins, configuration files and mapping parameters before they arereleased so that quality and functionality are ensured.

A collection of pre-configured service templates and associated plug-ins areprovided that you can use as is, or with minimal modification to performmany of the more common tasks that are required in a typical datacenter. Ifthe canned service templates and plug-ins are not adequate for the needs ofyour site, you can build your own service templates and plug-ins and definewhat types of tasks are run. You can also specify how the operatingparameters, user information and connection settings are configured andcustomize elements of the user interface used by an operator whensubmitting a service.

Once you have prepared the template with the necessary plug-ins anddefined the settings for the input and output properties, Automation DirectorService Builder guides you through the final stages of running, debuggingand releasing the service templates for use in your datacenter.

This module covers:

□ Using Service Builder

Overview of Service Builder 13Hitachi Automation Director Service Builder User Guide

□ Key Concepts

□ Accessing Service Builder

□ Navigating the interface

□ Getting started tips

14 Overview of Service BuilderHitachi Automation Director Service Builder User Guide

Using Service BuilderService Builder enables you to create and manage the service templates andassociated plug-ins for automating datacenter tasks.

When working with service templates, you have the option of using one ofthe canned service templates as is, modifying an existing template to suityour needs, or you can create a new template that performs the specifictasks required for your environment. The service templates are composed ofa series of plug-ins that instigate the scripts, execute the commands andprovide the operational parameters required to accomplish the various tasks.

Service Builder can create a flow with plug-ins, and package these elementsinto a customized service template package. Service templates and plug-ins,both pre-packaged and customized, can be re-used thus saving valuabledevelopment time and effort.

Service Builder allows you to:

• Easily manage (copy, edit, delete, update, export) service templates andplug-ins through a convenient menu driven interface.

• Use or customize the provided service templates and plug-ins or createnew ones that are tailored specifically to run the scripts and issue thecommands required to perform the tasks for your particular site.

• Establish the flow of steps in which a series of plug-ins are executedaccording to their placement and by simply drawing connector linesbetween the components.

• Specify the values for the input and output properties associated with agiven plug-in that provides the host details, user information, connectionssettings, etc., that are required to instigate a service, perform thenecessary error handling, and generate alerts.

• Issue commands, execute scripts and make use of variables that aresupplied when a service is run.

• Categorize tasks according to a given user group or classification ofservice.

• Customize the GUI by controlling what type of icons and graphics aredisplayed, the types of instructions that are provided and what informationa user sees when supplying the details required to submit a service.

• Debug and test your service templates and eventually release them fordeployment in your datacenter.

• Import and export service templates and settings so that they can bereused as needed.

• Import and export property values that are stored in a file so that thesetting and values for a given service can be supplied quickly andconsistently from one session to the next.


The following drawing shows the general workflow when working with servicetemplates and their associated plug-ins:

This guide provides the instructions to design and create service templates,including the plug-ins that create the steps within a service template, usingService Builder.

The Automation Director Develop or Admin role is required in order to useService Builder. For more information on permissions and user roles, see theHitachi Command Suite Automation Director User Guide.


Related concepts

• Accessing Service Builder on page 21• Key Concepts on page 17• Navigating the interface on page 21

Key ConceptsBefore beginning to use Service Builder, you should be familiar with theterminology that is used to refer to the various components and have anunderstanding of how they are interrelated.

The following diagram shows the various Service Builder components andillustrates their relationship:


The following are definitions for each term:

Development and Active environmentsYou create and modify service templates while in the developmentenvironment until they have been tested and are deemed suitable forrelease. After you have debugged and tested a service template, youcan import it into the active environment where it is then available torun the appropriate tasks when submitted as a service by a user.

Service template


A service template is the framework that defines the various executableoperational procedures that are specified through the components (plug-ins and other service templates). Automation Director provides pre-packaged service templates that are created, modified and managedthrough Service Builder. When creating or modifying service templates,you specify the steps and flow and supply the relevant parameters whilein the development environment until the template has been fullydebugged and tested. Once a service template is functioning properlyand performs the desired tasks without errors, you can import it into theactive environment where it is made available as a service.

Developing service templateDeveloping service templates are used in the development environment.A service template is considered in development when the operationalparameters and logic are being specified through the component steps,during the testing, and until the template is finally released. Servicetemplates created by copying a release service template are alsoclassified as developing service templates.

Released service templateReleased service templates are used in the active environment. Aservice template is considered as released when its associated plug-inshave been defined and thoroughly tested and released for consumptionin the Active environment. The canned service templates provided withService Builder are also classified as released service templates. Once aservice template is released, it cannot be directly edited, but a new copymust be made and then put through the development process.

ComponentA component is a service template or plug-in that can be added as astep to a flow.

Plug-inA plug-in is a fundamental component of a service template. It consistsof script files, definition files, resource files, and an icon file to executeand carry out specific operations. A service template may containmultiple plug-ins that are strung together to perform a series of tasks.

Input/Output PropertiesInput properties specify the input settings and values required toinstigate a task while the output properties store execution results thatcan be used to confirm execution or generate alters. You can entervalues into plug-in input properties directly, or pass values to them bylinking them to a service input property or variable. By linking a serviceoutput property to a plug-in output property, you can review the


execution results of a plug-in. Linking properties in this way and passingvalues between them is called property mapping.

FlowThe flow defines the processing sequence tasks and is establishedaccording to the placement of the steps and the connectors that linkthem.

StepThe step is the executed unit of a flow and is established according tothe placement of the plug-in or service template component.Components are executed at each step of the flow. A step providesproperty information at the time of execution.

ServiceA service is a customized set of automated instructions and returnedoutput values that are defined by the flow of the component steps andtheir associated input and output properties in a service template.Services are generated from a pre-packaged or customized servicetemplate that is created using Service Builder.

TaskA task is the executed instance of a service. Tasks are configured andexecuted based on a schedule.

Build/ReleaseWhen all of the processes have been defined and configured throughService Builder, you initiate the build so that all the necessary files arepackaged into a functioning service template that can be tested anddebugged. Once a service template has been tested and debugged, itcan then be released as a service.

Import/ExportWhen a service template is released, it can be exported to a file so thatit can then be imported by a given Automation Director installationwhere it can then be submitted as a service.

Related concepts

• Using Service Builder on page 15• Accessing Service Builder on page 21• Navigating the interface on page 21


Accessing Service BuilderYou create, edit and manage the service templates that perform a givenservice from the Service Builder Home screen.

To access Service Builder, click on Service Builder from the Tools pull-downmenu.

Note: You must have a minimum role of Admin or Develop to view andaccess the Tools menu.

For more information on the Service Builder Home screen, see Navigating theinterface on page 21.

For more information on how to log in to Automation Director and other areasof the GUI, see the Hitachi Command Suite Automation Director User Guide.

Related concepts

• Using Service Builder on page 15• Key Concepts on page 17• Navigating the interface on page 21

Navigating the interfaceThe Service Builder graphical user interface (GUI) consists of the followingscreens and menu options.

Service Builder Home screen

From the Service Builder Home screen, you can search for and manageexisting service templates and plug-ins and create and edit new ones.


The Service Builder Home screen shows the service templates that havealready been created (Released) or those that are currently being worked on(Developing). From here, you can quickly access relevant details pertainingto a selected service template, perform management functions (view, copy,edit, delete, import, and export) and create new templates if required. It isalso from the Service Builder Home screen that you access the optionsavailable for working with and creating custom plug-ins that serve as theindividual building blocks upon which the functionality of the servicetemplates are built.

The text search box allows you to search for a given service template or youcan perform a search based on the tag grouping with which the servicetemplate is associated. You have the option of displaying the servicetemplates using the Card View or Table View.

To sort the listing of service templates, select Sort By: and choose theappropriate option:• Name• Vendor Name• Version• Description• Service Template Key Name• Vendor ID• Registered• Updated• Latest Version

Managing and Creating Service Templates

In many cases, you can use one of the existing service templates with somemodification, to perform the tasks required for your site. If none of thecanned service templates are suitable for your particular purposes, you cancreate a new one.

The following buttons are provided for managing and creating servicetemplates:• Import -- Imports one of the service templates that has already been

created but which is not automatically installed or one that has beencreated and saved on another system.

• Create -- Creates a brand new service template from scratch which caninclude the properties, commands, and scripts specifically designed foryour site.

• View -- Shows details for the selected service template from the• Copy and Edit -- Copies the selected service template and then makes the

new copy available for editing.• Service Details -- Provides all of the relevant details for the selected

service template.• More Actions -- The following actions are available:


○ Export -- Exports the contents of the selected service template to aspecified file.

○ Delete -- Deletes the selected service template.

Managing and Creating Plug-ins

You manage and create plug-ins by choosing the appropriate options fromthe Custom Plug-in pull-down menu:

• Create Plug-in -- Creates a new plug-in.• Edit Plug-in -- Modifies an existing plug-in that is in the Developing state.• Copy Plug-in -- Copies an existing plug-in that is in the Released or

Developing state.• Delete Plug-in -- Deletes a plug-in that is in the Released or Developing

state.

Service Builder Edit screen

You edit service templates from the Service Builder Edit screen where youcan select the appropriate plug-ins (or other service templates) and placethem in an execution flow where the logic and values required to complete agiven task are supplied through various input and output properties.

By clicking the appropriate tab, you can view and edit details and propertysettings for a given service template:• General Tab Provides general details regarding the selected service

template. By clicking the Edit button, you can edit and customize theservice template.

• Property Tab Shows the input and output properties associated with theselected service template.


By clicking on the Add pull-down menu, you have the following options forthe service template:• Property Group -- Adds new property groups to categorize various types of

properties.• Input Property -- Creates and edits new input properties for the service

template.• Output Property -- Creates and edits output properties for the service

template.• Variable -- Creates a new variable.• Service Share Property -- Provides access to a collection of commonly used

service share properties.

From the Preview pull-down menu, you can generate a preview thatsimulates how a certain property is processed for a given mode of execution(from the Create Service Window, Create Request Window, or Task DetailsWindow) when a service is run.

The More Actions pull-down menu provides the following additional options:• Set Visibility -- Controls whether the settings are visible when a service

template is executed.• Set Display Settings -- Specifies the following display settings:

○ Editable -- Allows the display settings to be edited.○ Read Only -- Sets the display settings to read only.○ Display -- Shows the display settings.○ Hide -- Hides the display settings.

• Flow Tab The following panels are provided:○ The panel on the left shows the available components (Released Plug-in,

Developing Plug-in and Service) that can be added to flow of the servicetemplate.

○ The upper right panel shows the plug-ins and service templatesassociated with currently selected service template.

○ The lower right panel shows the input and output properties availablefor the selected component step as well as general details for the step.– General -- Provides general details pertaining to the currently

selected component (plug-in step) and allows you to edit thisinformation for your particular site. Any Next Step Conditionassociated with the selected step is also shown.

– Property -- Shows the input and output properties associated withthe selected component which can be edited.

– Next Steps -- Allows the creation of conditional branches that affecthow the next step in the flow is executed.

○ The Flow Tree panel shows a structured view of the component stepsthat are currently added to the service template.

Note: By clicking the airplane icon (in the upper right of the Service BuilderEdit screen, when the Flow tab is selected), you can initiate a tour of the


general process of creating a service template. You can also access anoverview of steps in the flow by clicking the Mini Map icon in the upper rightof the flow panel.

Additional buttons at the top of the screen provide the following:• Close -- Returns to the Home screen.• Save -- Saves the service template in its current state.• Debug -- Builds the service template and provides access to the debugger

interface used to run through the tasks and simulate their execution tomake sure everything is functioning properly.

• Release -- Releases the debugged version of the service template where itcan then be submitted as a service by a user through the main AutomationDirector user interface.

• Actions -- Provides access to Component Version Management where youcan manage component versions.

For details, see: Specifying the step flow on page 47

Service Builder Debug Screen

You examine the flow of execution and debug a service template from theService Builder Debug screen.

The upper, center pane shows the flow in which the plug-ins (or other servicetemplates) are executed while the lower pane shows details depending onwhich of the following tabs you click:• Task Log -- Shows a log of executed tasks that can be downloaded

(Download) and refreshed on command (Refresh) or automatically(Refresh Automatically) on a periodic basis.


• Service Properties -- Shows the input and output properties defined for theservice template.

• Break Points -- Shows all of the breakpoints set for the current debuggingsession.

The pane on the far right shows a hierarchical view of the steps that areexecuted while the pane on the far left provides the debug controls.

For details, see: Working with the debugger on page 133

Related concepts

• Using Service Builder on page 15• Accessing Service Builder on page 21• Key Concepts on page 17

Getting started tipsTo assist you in initially learning how to accomplish some of the morecomplicated procedures, Service Builder provides an overlay on the screenthat visually guides you through the various steps.

For instance, when you first start to build a service template from the CreateFlow tab, a helpful "Getting Started Tips" overlay is provided that shows howyou can search for plug-ins, drag and drop a selected plug-in into the flow,and how to access the properties associated with the plug-in.

After initially viewing these hints, you can specify that they are not to beshown thereafter by checking the appropriate check box. If needed at somepoint, you can activate the hints again by selecting the Getting Started Tipsoption from the Help pull-down menu.


2Working with existing service templates

You manage exiting service templates by choosing the appropriate optionfrom the Service Builder Home screen.

Note: This section describes how to manage (e.g., view, copy, edit, export,import, and delete) existing service templates. For information on creating anew service template, please see: Creating a new service template onpage 46.

This module covers:

□ Service template overview

□ Managing existing service templates

Working with existing service templates 27Hitachi Automation Director Service Builder User Guide

Service template overviewA custom service template consists of plug-ins, (or even other servicetemplates) that execute the commands or scripts to automate particular setof tasks. The plug-ins and services are added as steps and arranged in asequence to form the operational flow. The service template also requiresmapping of input and output properties to define the data flow. Usingproperty groups and shared service properties can further assist in defining inthe input and output properties.

There are two versions of service templates that are available when youaccess the Service Builder Home screen:

Note: When creating a new service template, the service output propertyservice.errorMessage is added to the service template by default.

• Developing A newly created service template begins with a debugversion. Testing a service template includes the creation of services andtasks based upon the debug version of the service template. The servicetemplate resides in the Developing status and can be copied and modified.If a debug version of a service template is built again, the previous debugversion of the service template and its services are deleted, and therelated tasks are archived. When a Developing version of a servicetemplate is released, the debug version of the service template and all therelated services are deleted, and the tasks are archived.

• Released A released version of a service template has completed testingand is available under the Released status. New services and tasks can becreated and executed based upon a released service template. Releasedservice templates can not be edited, but can be copied and modified foruse in another service template.

You can click on the Developing or Released tabs from the Service BuilderHome screen to access the appropriate type of service templates. By clickingand highlighting a particular service template, either from the Card or Tableviews, you can access pertinent details and perform management functions(view, edit, copy, delete, import, or export) for a selected service template. Ifnecessary, you have the option of creating a new service template, eitherbased on one of the existing templates or from scratch, and then tailoring itfor your specific needs. See: Creating a new service template on page 46for complete details.

Managing existing service templatesYou can manage existing service templates from the Service Builder Homescreen.

28 Working with existing service templatesHitachi Automation Director Service Builder User Guide

The procedures for managing existing service templates are covered in thefollowing topics:

• Viewing a service template on page 29• Editing a service template on page 30• Copying a service template on page 29• Deleting a service template on page 31• Importing a service template on page 32• Exporting a service template on page 33

For details on creating and editing a new service template, please see: Creating a new service template on page 46 and Editing a service templateon page 30

Viewing a service templateYou view service templates that are in the Developing or Released state fromthe Service Builder Home screen.

To view an existing service template, follow these steps:

Procedure

1. From the Service Builder Home screen, select and highlight the desiredservice template from the Table or Card view to expose the availableactions.

Details regarding the selected service template are shown and buttonsare provided for the options that are available.

2. Click the View button.

ResultThe Service Builder View screen appears with the Flow tab selected showingthe flow for the selected service template. You can click on the General andProperty tabs to view more details regarding the selected service templateand its associated properties.

Copying a service templateYou copy and edit a service template to create a new version of an existingservice template that you can then modify for your particular operatingenvironment.

To copy an existing service template, follow these steps:

Procedure

1. From the Service Builder Home screen, select and highlight the desiredservice template from the Table or Card view to expose the availableactions.



2. Click the Copy and Edit button.The Copy Service Template dialog box appears.

3. In the Copy Service Template dialog box, enter the basic informationfor the service template, then click OK.A copy of the selected service template is created.

ResultThe Service Builder Edit view appears with the Flow tab selected showing theflow for the newly created service template. You can click on the General andProperty tabs to view more details regarding the selected service templateand its associated properties.

Related references

• Copy Service Template dialog box on page 30

Copy Service Template dialog boxThe Copy Service Template dialog box provides the details for a newly copiedservice template.

The following table describes the Copy Service Template dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.

Table 1 Copy Service Template dialog box

Field Subfield Description

Key Name: * - Specifies the key name for the copied service template.

Version * - Version of the service template.

Vendor ID: * - Vendor ID.

Display Name: * - Name of the service template that is displayed through theuser interface.

Vendor Name: - Vendor name, if applicable, for copied service template.

Description: - Description of the copied service template.

Tags: - Tag category associated with the service template.

As asterisk (*) indicates a required field.

Related tasks

• Copying a service template on page 29

Editing a service templateYou can edit an existing service template (one that has been copied and is inthe Developing state) to modify or add details.


Before you begin• Identify which components are required to accomplish the purpose of the

service template.• Have required components (Released or Developing plug-ins or other

Service Templates) available for use in the service template.

Procedure

1. From the Service Builder Home screen, select and highlight thetemplate to be edited from the Developing tab.

2. Click the Edit button.The Service Builder Edit screen appears with the Flow tab selectedshowing the components (Released or Developing plug-ins and otherService Templates) associated with the template to be edited. You canclick on the General or Property tabs to edit additional detailsregarding the selected service template.

Next steps

• Continue to edit the service template by adding or modifying components,providing the input and output step properties, and establishing the flow.

Related references

• Create Service Template dialog box on page 47

Deleting a service templateYou can delete any service template that is in the Developing state.

To delete a service template in Released status, run thedeleteservicetemplate CLI command. For instructions on running CLIcommands in Automation Director, see the Hitachi Command SuiteAutomation Director User Guide.

Before you beginBefore you delete a service template in the Developing state, complete thefollowing steps.

• Stop all the running tasks related to the service template.• Archive all the tasks related to the service template.• Delete all the services related to the service template.

Note: It is important to stop and archive all tasks related to the servicetemplate, and to delete all services related to the service template prior todeleting the service template. A deleted service template cannot berecovered.

For instructions on performing these steps, see the Hitachi Command SuiteAutomation Director User Guide.


Procedure

1. From the Service Builder Home view, select and highlight the desiredservice template from the Table or Card view to expose the availableactions.


2. From the More Actions pull-down, choose the Delete option.

The Delete menu appears requesting confirmation.3. Click OK to confirm deletion.

The Information menu appears indicating whether or not the specifiedtemplate has been deleted.

4. Click OK.

ResultThe specified service template is deleted.

Importing a service templateYou can import a service template to make use of its service on a givensystem.

Before you begin

The service template to be imported must be accessible either on the localsystem or via the network. You can export a service template from someother system in order to make it accessible for import.

Note: In addition to the service templates that are provided by default withHitachi Automation Director, there is a collection of other service templatesthat are available for import. These templates are in the released state andcan be used immediately without having to go through the build process. Fora listing of service templates, please see: List of built-in service templates onpage 158.

To import a service template, follow these steps:

Procedure

1. From the Developing tab of the Service Builder Home view, click theImport button.

The Import Service Template Package dialog appears.2. From the Import Service Template Package dialog box, click Browse

and specify the name and location of the template to import.3. After specifying the template name and location, click OK.


ResultThe specified service template is imported.

Note: When importing a service template package, a service componentwithin the service template is imported as a service template.

Related references

• Import Service Template Package dialog box on page 33

Import Service Template Package dialog boxYou can export a service template from one system and then import it to thecurrent system.

The following table describes the dialog box fields, subfields, and field groupsfor the Import Service Template Package dialog box. A field group is acollection of fields that are related to a specific action or configuration.

Table 2 Import Service Template Package dialog box


File Name - Click the Browse button to specify the location and filenameof the service template to be imported.

Related tasks

• Importing a service template on page 32

Exporting a service templateYou can export a service template to make its service available on anothersystem.

Before you begin

The service template to be exported must be accessible either on the localsystem or via the network.

Procedure

1. From the Developing tab of the Service Builder Home view, selectand highlight the desired service template from the Table or Card viewto expose the available actions.


2. Click More Actions and choose the Export option from the pull-downmenu.The Export menu appears.


3. Enter the name and location for the exported service template and clickOK.

ResultThe selected service template is exported.


3Working with existing plug-ins

Plug-ins are the fundamental building blocks upon which a service template iscreated. Each plug-in is designed with a specific purpose and their use andsequence within a service template determines the order in which specifictasks are executed.

Note: For information on creating a new plug-in or editing an existing plug-in, see:Creating a new plug-in on page 91 .

This module covers:

□ Plug-ins overview

□ Select Plug-in dialog box

□ Managing existing plug-ins

Working with existing plug-ins 35Hitachi Automation Director Service Builder User Guide

Plug-ins overviewOne or multiple plug-ins (or even other released service templates) can beinserted in a service template to execute a command or script. Input andoutput properties and remote commands can be set within a plug-in. Whenusing the remote command of a plug-in, the input property can be passed toa command or a script by specifying an input property as the argument of acommand or script. Plug-ins can be arranged within a service template tocreate the flow. Plug-ins are tested and released with the service template towhich they are assigned. In addition to the plug-ins, you also have the optionof adding other service templates to the flow of a given service template.

Types of plug-ins

The there are two types of plug-ins as described below:• Released. The released plug-ins include the custom plug-ins that have

been released within a service template. When a development servicetemplate has been released, plug-ins included in the service templatebecome released plug-ins. Released plug-ins cannot be edited, but can becopied and modified for use in other service templates. Released plug-insare listed under the Released Plug-in tab that is available from the Flowtab of the Service Builder Edit screen.

• Developing. Newly created plug-ins and plug-ins that have not completedbuild process and testing are in the Developing state. Plug-ins in theDeveloping state can be copied and modified to use in other servicetemplates. While in the creation or testing phase, plug-ins in theDeveloping state can be found under the Developing Plug-in tab that isavailable from the Flow tab of the Service Builder Edit screen.

In addition to the plug-ins, a service template can be added as componentsin the flow of another service template:• Service. A service component is a released service template that has been

imported into Automation Director. When a service is used as a componentand placed into the flow of another service template, the new servicetemplate can incorporate the flow of the service component. AutomationDirector provides a set of built-in service components along with its built-inservices. Service components can be found under the Services tab that isavailable from the Flow tab of the Service Builder Edit screen.

Related references

• Select Plug-in dialog box on page 36

Select Plug-in dialog boxThe Select Plug-in dialog box shows the plug-ins you can access for a givenoption, (copy, edit, or delete) from the Custom Plug-in pull-down menu. You

36 Working with existing plug-insHitachi Automation Director Service Builder User Guide

can search for an existing plug-in by entering some identifying text oraccording to the tags with which the plug-in is associated. You can manageplug-ins that already exist from the Released tab or you access plug-ins thatyou are currently working on from the Developing tab. You also have theoption of specifying how the plug-ins are listed and displayed on the screenby clicking either the Card View or Table View buttons.

The following table describes the dialog box fields, subfields, and fieldgroups. A field group is a collection of fields that are related to a specificaction or configuration.

Table 3 Select Plug-in dialog box


Vendor Name - Vendor name, if applicable, for the plug-in.

Version - Version of the plug-in.

Key Name - Key associated with the plug-in.

Vendor ID - Vendor ID associated with the plug-in.

Tags - Tag category associated with the plug-in.

Registered - Date and time when the plug-in was registered.

Last Updated - Date and time when the plug-in was last updated.

Related concepts

• Plug-ins overview on page 36• Plug-ins overview on page 36• Service template creation workflow on page 44

Managing existing plug-insYou can manage existing plug-ins from the Service Builder Home screen bychoosing the appropriate option from the Custom Plug-in pull-down menu.

The various plug-in management options are covered in the following topics:

• Copying a plug-in on page 37• Deleting a plug-in on page 41

For details on creating and editing an existing plug-in, please see: Creating aplug-in on page 93 and Editing a plug-in on page 38.

Copying a plug-inYou can make a copy of a plug-in and then make whatever modifications arenecessary to suit the specific requirements of your operating site.

Any plug-in that is in the Developing or Released state can be copied. Whencopying an existing plug-in, you need to assign a new vendor ID, plug-in keyname, or version number.


Procedure

1. From the Service Builder Home screen, choose the Copy Plug-inoption from the Custom Plug-in pull-down menu.The Custom Plug-in dialog box appears.

2. From the Select Plug-in dialog box, select and highlight the plug-in thatyou want to copy either from the Released or Developing tab, thenclick Copy and Edit.The Copy Custom Plug-in dialog box appears.

3. In the Copy Custom Plug-in dialog box, enter the applicable plug-ininformation from the General, Property, or Remote Command tabs,then click Save.A copy of the plug-in is created and made available from theDeveloping tab of the Select Plug-in dialog box.

Next steps

• If necessary, you can continue working with the copied plug-in by choosingthe Edit Plug-in option from the Custom Plug-in pull-down menu.

Related references

• Copy Custom Plug-in dialog box on page 38

Editing a plug-inYou can edit the input and output properties, variables, and remotecommands associated with a plug-in that is in the Developing state.

Procedure

1. From the Custom Plug-in pull-down menu of the Service BuilderHome screen, choose the Edit Plug-in option.The Select Plug-in dialog appears where you can select the plug-in toedit.

2. From the Select Plug-in dialog box, select the custom plug-in to editand click Edit.The Edit Custom Plug-in dialog box appears for the selected plug-in.

3. Edit the selected plug-in by choosing the settings from the appropriatetabs (General, Property, or Remote Command). Click Save when youhave completed the editing.A informational message appears indicating that the edited version of theplug-in has been saved.

Copy Custom Plug-in dialog boxThe Copy Custom Plug-in dialog box is used to provide the details whenmaking a copy of a plug-in.


The following tables describe the dialog box fields, subfields, and field groupsthat are available based on the tab that is currently selected. A field group isa collection of fields that are related to a specific action or configuration.

From the General tab, you can view and enter details regarding the selectedplug-in as follows:

Table 4 General Tab


Key Name: * - Specifies the key name for the copied plug-in.

Version * - Version of the plug-in.

Vendor ID: * - Vendor ID assigned to the plug-in.

Display Name: * - Plug-in name that is shown through the user interface.

Vendor Name: - Vendor name, if applicable, for copied plug-in.

Description: - Description of the copied plug-in.

Tags: - Tag category associated with the plug-in.

Icon: - Icon associated with the plug-in.

Note: When making a copy of a plug-in, you should change the Key Name orVendor ID to distinguish the copied version from the original.

From the Property tab, you can search for and view all of the input andoutput properties associated with the selected plug-in. You also have theoption of managing the properties by clicking the appropriate option. Forinstance, you can add a new input or output property by choosing the Addbutton, edit an existing property by selecting the Edit button, or delete aselected property by selecting the Delete button.

Table 5 Property Tab


Key Name - Specifies the key name for the input or output property.

Display Name - Specifies the display name for the input or output property.

Description - Provides a description of the input or output property and itsfunction.

Required - Indicates whether or not the input or output property isrequired (true) or not (false).

Default Value - Indicates any default value that is associated with the inputor output property.

From the Remote Command tab, you can choose the platform from which theremote command is to be executed by selecting the appropriate option fromthe Add Platform pull-down menu. You can also specify the Credential Typeby choosing either the Shared agentless setting or Service input property.


Other options for controlling how the remote command is to be executed areprovided depending on the selected platform.

Table 6 Remote Command Tab


Credential Type - Specifies the credential type required for the plug-in.

Select Shared agentless setting, if you want to use thecredential information in the agentless remote connectionsview under the HAD Administration tab when the service isexecuted. Shared agentless setting is the default CredentialType.

The following reserved plug-in property is automatically setfor the shared agentless setting credential type:

plugin.destinationHost Enter the target of an operation byIPv4 address, IPv6 address, or host name (up to 256characters).

Select Service input property to use the credentialinformation as an input property.

The following reserved plug-in properties are automaticallyset for the Service input property credential type:

• plugin.destinationHost

Enter the target of an operation by IPv4 address, IPv6address, or host name (up to 256 characters). If thedestination host is Automation Director Server(localhost), the user ID and the password are notnecessary.

• plugin.account

Enter the user ID for logging in to the target host (up to256 characters).

• plugin.password

Enter the password for logging in to the target host (upto 256 characters).

• plugin.suPassword

Enter the password of the root account used for loggingin to a target host in a Linux environment (up to 245characters). If the target is host is running the Windows,this property is ignored.

Options Run as systemaccount(Windows)

Runs the command using the system account.

Character SetAutoJudgement(SSH)

Character Set Auto Judgment (SSH) applies to UNIXoperating systems. If enabled, executes the script using thedefault locale ofthe user. If disabled, scripts are executedwith the LC_ALL=C locale. Default is enabled. For moredetails on Character Set Auto Judgement, see:Localesettings for plug-ins on page 186.



Executive withroot privileges(SSH)

Executes with root privileges.

Add Platform - Specifies the platform for the remote command (Windows,Linux, Solaris, HP-UX, AIX).

Import Settings - Specifies that the settings should be derived from anotheroperating system.

Execution Method: - Select Script name if based on a script, CLI Command ifusing a stored command, or N/A if no execution is required.

CLI Command: * - Enter the CLI command (up to 8,192 characters) for theremote command. Required if Script name or CLI Commandis selected for Execution Method. The Insert All InputProperties button inserts all input properties defined for theplug-in into the CLI command.

Script specificationmethod:

- Select Attachment if uploading a script file, or Type in todirectly enter the script information.

Use the following file format for a plug-in that executes ascript: <name-of-plug-in>.<extension>.

File* - Click the Browse button to specify the file that holds thecommand or script.

Mapping Definitionof Output Properties

- Specify the mapping definition of the output property for acommand or script. By selecting and highlighting a propertyin the list and then clicking Edit, you can access the EditOutput Filter dialog box where you can specify an outputfilter that controls the data that is passed to the outputproperty.

Execution Directory - Specify the execution directory.

EnvironmentVariables

- Select environmental variables for the command or script.When selecting this option, the Create/Edit EnvironmentVariable dialog box appears where you can enter theappropriate variable information.

Note: Fields marked with an asterisk (*) are required.

Related tasks

• Copying a plug-in on page 37• Copying a plug-in on page 37

Deleting a plug-inYou can delete a plug-in that is no longer needed. A deleted plug-in cannotbe recovered.

Procedure

1. From the Released or Developing tabs of the Service Builder Homescreen, choose the Delete Plug-in option from the Custom Plug-inpull-down menu.


The Custom Plug-in List dialog box appears.2. Click on and highlight the plug-in to be deleted from the either the Card

or Table view and then click Delete.The Delete dialog box appears to confirm your intention.

3. Click OK to confirm the deletion of the selected plug-in.

ResultThe plug-in is deleted and is no longer shown on the Service Builder Homescreen.

Related tasks

• Copying a plug-in on page 37


4Creating a new service template

Creating a custom service template involves creating a new template, orcopying and editing an existing template. The new or modified servicetemplate is then defined by the components (plug-ins or other servicetemplates), resource files, preset property definition files, an icon file, customfiles, a flow and service definitions.

Creating a service template consists of the steps provided in the followingsections.

□ Service template creation workflow

□ Creating a new service template

□ Create Service Template dialog box

□ Specifying the step flow

□ Specifying the property settings

□ Example of creating a new service template

Creating a new service template 43Hitachi Automation Director Service Builder User Guide

Service template creation workflowYou manage and create new service templates from the Service Builder Homescreen. (You can also manage and create new plug-ins from the CustomPlug-in pull-down menu.)

To manage an existing service template (e.g., edit, view, copy, import, orexport), select the service template (either from the Developing or Releasedtab) and then click the appropriate button for the type of action you want toperform. To examine the details related to a given service template, click onthe Service Details button.

When creating a new service template, you need to do some planning andthen go through the various phases described in the following workflow:

Phase 1 - Preparation• Decide on the need and purpose of the service template. Consider the

steps involved in automating the process and determine if the stepsrequire creating a new template or modifying an existing template.

• Prepare to create the service template. This involves identifying existingcomponents, or creating new components, preparing icon files, and settingdefinition, resource files, preset property definition files, custom files andflow.

Phase 2 - Creation• Create a new service template or copy and modify an existing service

template if it suits your needs. Enter the basic information such as thename, ID, vendor name, and description. At this stage, the servicetemplate is in the Developing state.

• Create new plug-ins or use the existing plug-ins if they are sufficient foryour purposes.

• Define the flow for the service template by arranging the templates andplug-ins as steps and then connect them in the order in which they are tobe executed.

• Define the data flow by mapping the input and output properties of thecomponent with the input and output properties of the service template.

• Set the service definitions with the input and output properties of theservice template. Add shared service properties, property groupinformation and variables.

Phase 3 - Testing• Build the service template for testing.• Perform testing. Create services based on the debug configuration of the

service template.• Make corrections as the result of testing.• Rebuild and retest the service template until it performs properly.

44 Creating a new service templateHitachi Automation Director Service Builder User Guide

Phase 4 - Releasing• Release the service template. A service template must be in Released

status in order to submit the service template to the operatingenvironment.

The following figure shows the typical steps you follow when creating orediting a service template:


Note: This chapter covers the steps of creating a service template. Fordetails on testing and releasing a service template, please see Building,debugging and releasing on page 123.

Related references

• Select Plug-in dialog box on page 36

Creating a new service templateYou can create a new service template to create a customized service thatautomates a series of tasks for a particular type of user.

Before you begin• Identify which components are required to accomplish the purpose of the

service template.• Have components (Released or Developing) available for use in the service

template.

Note: Although the procedure for creating a new service template isdescribed here, you can usually just copy one of the existing servicetemplates to use as a model and then make whatever modification arenecessary for your particular operating environment.

Procedure

1. Choose one of the following methods to create a new service template:• To create a new service template from scratch, click the Create button

from the Developing tab of the Service Builder Home screen.• To create a new service template based on an existing template, click

the Copy and Edit button from either the Developing or Releasedtabs of the Service Builder Home screen.

If you are creating a service template from scratch, the Create ServiceTemplate dialog appears. If the service template is based on an existingone, the Copy service template dialog appears.

2. Enter the information for the new service template (and select any tagswith which you want the template associated) and click OK.The Service Builder Edit screen appears with the Flow tab selected.

ResultFrom here, you can begin searching for and dragging the desired components(Released or Developing plug-ins and other Service Templates) into the flowaccording to the order in which they are to be executed.


Next steps

• Continue to provide the input and output step properties, and establishingthe flow and, when done, you can debug and release the service template.

Related references

• Create Service Template dialog box on page 47

Create Service Template dialog boxWhen creating a new service template, you supply the relevant details fromthe Create Service Template dialog box.


If the information you enter is deemed invalid, a short description regardingany errors appear at the top of the box.

Table 7 Create Service Template dialog box


Key Name * - A unique key name is assigned to each service template foreasy access and tracking.

Version * - A version number for the new service template.

Vendor ID * - An ID associated with the vendor.

Display Name: * - Name of the new service template that is shown throughthe user interface.

Vendor Name: - Vendor name, if applicable.

Description: - Description of the new service template.

Tags: - Specifies any tags categories with which the template isassociated.

Fields with an asterisk (*) are required.

Related tasks

• Creating a new service template on page 46• Editing a service template on page 30

Specifying the step flowYou specify the steps for a service template by adding the components (plug-ins or other service templates) and establishing the order in which they areexecuted from the Flow tab.


When establishing the flow of steps in a service template, you need to addthe appropriate plug-in (or service template) steps from the Flow view andthen draw connectors to establish the order in which they are to be executed.You then need to specify the mapping for the input and output properties.

The following figure shows the typical flow for a service template:

When you first start to build a service template from the Flow tab, a helpful"Tour" option leading your through the process of searching for plug-ins, dragand drop a selected plug-in into the flow, and how to access the propertiesassociated with the plug-in. After initially viewing this tour, you can specifythat they are not to be shown thereafter by checking the appropriate checkbox. If needed at some point, you can activate the tour again.

• Creating the steps in a data flow on page 48• Specifying step properties on page 51• Establishing the flow of execution on page 54• Creating a flow hierarchy on page 56

Creating the steps in a data flowYou create the steps in a service template from the Flow tab of the ServiceBuilder Edit screen by specifying the appropriate components for a givenservice.

Before you begin• A service template must be open and in the Developing status for editing

or creation.• Identify which plug-ins are required to accomplish the purpose of the

service template.• Have components (Released or Developing) available for use in the service

template.


Procedure

1. From the Flow tab of the Service Builder Edit screen, click on acomponent and drag it to the Flow view and release.The Create Steps Attributes dialog box appears.

2. Enter the information for the step, and click OK.The component icon appears in the Flow view as a step and detailsregarding the step, including its related properties, can be accessed fromthe General or Property tabs.

3. Continue to add steps as needed.• To edit, copy, cut, or delete a step, right click on the component and

select the appropriate option. When copying a component, you canpaste it into another service template.

• To select multiple steps, drag the mouse to create a rectangleencompassing the targeted steps, or click each step icon whilepressing the Control key to add to the selection.

• To move a step, click the target step icon and drag it to the targetedarea of the Flow view and release.

• To add a second flow, right click on the target flow in the Flow Treeview and click Create Flow.

• To exit the Service Builder Edit window, click the Close button.

4. Click Save.

ResultSteps are added and saved to the service template.

Next steps

• Continue to edit the service template and add a flow that shows the orderin which the steps are executed.

Related references

• Create/Edit Step Attributes dialog box on page 49

Create/Edit Step Attributes dialog boxYou can enter the details associated with a component for a given step in aservice template from the Create/Edit Step Attributes dialog box.

Note: You can click on the View button to get specific details regarding astep component.

The following table describes the dialog box fields, subfields, and field groupsfor the Create/Edit Step Attributes dialog box. A field group is a collection offields that are related to a specific action or configuration.


As you enter information in a dialog box, if the information is incorrect, errorsthat include a description of the problem appear at the top of the box.

Table 8 Create/Edit Step Attributes dialog box


Step ID* The ID of the step.

Display Name* The name of the step.

Description A short description of the step.

Component Vendor Name The vendor Name associated with the component.

Version The version of the plug-in. Click the drop-down box todisplay choices if more than one version exists.

Key Name The key name associated with the component.

Vendor ID The vendor name of the plug-in.

Tags The tag categories associated with the step.

Registered The date and time when the step was originallyregistered.

Last Updated The date and time when the step was last updated.

Next StepConditions

Condition: Sets instructions on when to execute the next step.The choices are:• Determine the return value based on the

thresholdExecute the next step when the Error Threshold isexceeded. If the return value is more than theError Threshold, this step will terminate with anerror status.

• Always succeed regardless of return valueAlways execute the next step.

• Always fail regardless of return valueAlways terminate at the end of this step with anerror status.

Error Threshold:* Set a whole number from 0-255 that establishes thethreshold value at which a given conditional step isexecuted.

Use Warnings: If enabled, executes next step with an error statuswhen exceeding the Use Warnings.

Warning Threshold: Required if the Flow condition in case of error isenabled. Set a whole number from 0-255. If thereturn value is less than the Warning Threshold andthe Error Threshold, then proceed to execute the nextstep. If the return value is equal to or more than theWarning Threshold, but equal to or less than the ErrorThreshold, then the task status reflects "AbnormalDetection" while running and "Failed" when the task iscomplete. The Warning Threshold number cannot belarger than the Error Threshold.

An asterisk (*) indicates a required field.

Related tasks

• Creating the steps in a data flow on page 48


Specifying step propertiesYou need to specify the various input and output properties that perform thetasks associated with a given component (plug-in or other service template).

A service template defines a generic operating procedure. For this reason,properties that store the input values required to execute the service, such ashost names and resource limits, are defined when services are added from aservice template. These are called service input properties. The executionresults of a service are output to the HAD user interface as the values ofservice output properties. Input properties that store the input valuesrequired for execution of a step and output properties that store executionresults are defined through the plug-ins. You can enter values into plug-ininput properties directly, or pass values to them by linking them to a serviceinput property or variable. By linking a service output property to a plug-inoutput property, you can review the execution results of a plug-in from theHAD user interface. Linking properties in this way and passing valuesbetween them is called property mapping.

It is necessary to map the input and output properties of the components forevery step with the input and output properties and variables of the servicetemplate. The input properties of the components used in a service templateshould be associated with the input properties or variables, or outputproperties of other component steps associated with a service template. Theservice template input properties store the input values required to execute aservice. The service template output properties store the execution results ofthe service.

The value of the plug-in input property can be the value that has beenpreviously set for the property, or directly set for the service template. Theinput property can also be a variable. Service share properties can be appliedto the input properties.

The output property content depends on the type of component. The result ofexecuting a step can be stored as output properties. Variables temporarilyhold the values that are passed between components.

The input and output properties of the components are set from the PropertyTab in the lower right window of the Service Builder Edit screen. The inputand output properties and variables for the service template are set in theProperty tab of the Service Builder Edit screen.

The following figure shows a typical mapping between the service templateproperties and their corresponding plug-in step properties:


In this example, the value input to Input property 1 of the service is input toInput property 1 of Plug-in A. The value input to Input property 2 of theservice is input to Input property 2 of Plug-in B. The unmapped Inputproperty 2 of Plug-in A is assigned the value entered when the servicetemplate was created or edited. Notice that Output property 1 of Plug-in A ismapped to Variable 1, and Variable 1 is mapped to Input property 1 of Plug-in B. Values output as Output property 1 of Plug-in A are stored in Variable 1then input to Input property 1 of Plugin B. This passes the execution resultsof Plug-in A to an input property of Plug-in B, allowing it to be used in theprocessing of Plug-in. As a result of this mapping, the following results areachieved:• The execution results of Plug-in A (command standard output and

standard error output, and output properties) output as Output property 2of Plug-in A are also output to Output property 2 of the service. This allowsyou to review the execution results of Plug-in A through the HAD userinterface.

• The execution results of Plug-in B (command standard output andstandard error output, and output properties) output as Output property 1of Plug-in B are also output to Output property 1 of the service. You canthen review the execution results of Plug-in B through the HAD userinterface.


Before you beginA service template in the Developing state must exist with steps added to theFlow view.

Procedure

1. From the Flow tab of the Service Builder Edit screen, click andhighlight a step in the flow.A listing of properties associated with the selected component (plug-in orother service template) are shown from the Property tab. You can eitherview the input properties or the output properties by clicking on theappropriate icon next to the search box that allows you to enter a textsearch to locate specific properties in a long listing.

2. With input properties icon selected, enter the input properties for thestep:• Enter the details directly in the Value column of the table.• Click the pencil icon to enter the details using the Specify

Component Input Property Mapping Parameters dialog box.3. With the output properties icon selected, click the pencil icon to enter

the details of the output properties using the Specify ComponentOutput Property Mapping Parameters dialog box and then click OK.You can add new output properties by clicking the Add Output Propertybutton and you can add variables by clicking the Add Variable button.

4. Continue to enter the input and output properties as needed.5. If necessary, you can check the GUI Setting checkbox that determines

whether or not the selected input property is visible for Modify/Submitusers.

Next steps

• Set the service definitions of the service template.

Related references

• Specify Component Input/Output Property Mapping Parameters dialog boxon page 53

Specify Component Input/Output Property Mapping Parametersdialog box

You can specify the mapping of input and output properties for thecomponents incorporated in a service template through the SpecifyComponent Input/Output Property for Mapping Parameters dialog box.




Table 9 Specify Component Input/Output Property for MappingParameters dialog box


Key: - The input or output property key.

Display Name: - The name of the input or output property.

Description: - The description of the input or output property.

Data Type: - Shows data type of the property: string, boolean, integer,double, date, password, composite. Various option arepresented depending on which of the options are chosen.

When dealing with arrays, you can check the Array of optionto have the data type treated as an array. In this way, a setof the properties of the same type ( Number of elements isvariable) can be handled as a single property thus makingdata mapping easier, especially when passing data betweena Service and the Plug-ins.

Setting Method: - The setting method can be View Property, Direct Input, orNone. When entering a direct input value, you can click theInsert Property button to have the value from the specifiedproperty inserted as the value.

Value: - Shows the direct input value associated with a givenproperty.

When specifying component input properties, you can view a listing of plug-insteps shown under Step Tree for the currently selected component.

Depending on whether you are working with input or output properties, youcan click the Add Input Property or Add Output Property buttons to add aninput or output property, or Add Variable button to add a variable to aspecified property group.

Establishing the flow of executionMapping the process flow of a service template is performed from the Flowtab of the Service Builder Edit screen. Use the Flow view to connect the stepsicons and establish a flow.

You establish each unit of processing in a flow by dragging plug-ins from thePlug-in view to the Flow view. Each plug-in dropped into the Flow view iscalled a step. A flow is created by placing the steps required to execute atask and connecting them with relational lines as shown in the followingfigure:


The flow can contain one step that connects to two or more steps andsimilarly, two or more steps can connect to one step. In this case, the nextstep is executed only after every connected step has finished executing. Youcan also use the flow plug-in and Repeated-execution plug-in to define a flowwithin another flow.

Follow these steps to establish the flow of steps for a service template:


Procedure

1. From the Flow tab of the Service Builder Edit screen, drag and add thenecessary plug-ins (or services) into the Flow view according to therelative order in which the steps are to be executed by the service.

2. To establish the order in which the steps in the flow are executed, clickand hold the node associated with the step that is to be executed first,drag the connector line across to the step that is to be executed next,then release.A connection line appears indicating the steps are connected. The arrowindicates the direction of the flow.

3. Continue to add connections to steps as needed.• To delete a connection, click on the targeted connection line and click

the Delete button.

Next steps

• Define the input and output properties and enter the mapping parameters.

Related tasks

• Specifying step properties on page 51


Creating a flow hierarchyYou can create a flow hierarchy in a service template by defining a flow withinanother existing flow. The Flow Tree view displays the hierarchy of the flow.

You can create a flow hierarchy by deploying flow plug-ins, and repeating aunit of processing that consists of several steps by deploying repeated-execution plug-ins as shown in the following figure:

The following table shows the plug-in roles and their relationship to thevarious steps in the flow:

Dragged & dropped plug-in Type of step Role

Flow plug-in Hierarchical step Creates a flow hierarchy.

Repeated Execution plug-in Repeated step Repeats execution of thespecified flow. If you want toimpose a hierarchy on a flowsubordinate to the repeatedstep, you must use a flow plug-in. You cannot place arepeated-execution plug-in intoa flow that is subordinate to arepeated step. Also, if youattempt to impose a hierarchyon a flow you have copied andpasted that includes a repeatedstep, an error occurs. TheRepeated Execution plug-in can


Dragged & dropped plug-in Type of step Role

be used to create a nested loopto a maximum of three levels.

Other plug-ins Ordinary step Executes the plug-in in thenormal manner.

You can view a list of the steps in a flow from the Flow Tree view where itshows the name of the service template as the first step of the flow. Lowerlevels are represented by the step name associated with the step thatexecutes the flow plug-in or repeated-execution plug-in. When you execute aservice template that includes a hierarchical flow, only the top-level steps inthe flow appear in the Task Details dialog box. Steps in subordinate flows andin flow plug-ins and repeated-execution plug-ins are not displayed.

Follow these steps to establish the flow of steps for a service template:


Procedure

1. From the Flow tab of the Service Builder Edit screen, drag theappropriate plug-ins to be executed into the Flow view to establish thehierarchy of execution for the other plug-ins in the flow.

2. To repeat execution of the specified flow, select the Repeated-executionplug-in and drag it into the appropriate position.

3. Add connections to steps as needed.• To delete a connection, click on the targeted connection line and click

the Delete button.

Creating a Next Step conditional branch in a flowYou can create a conditional branch to control the flow of steps that areexecuted depending on when a particular condition is met.

A Next Step conditional branch is useful for executing a given step in a flowbased on a particular condition.

You specify next step conditions from the Next Steps tab when establishingthe flow of execution in a service template.


The step names and conditional settings associated with any of the steps inthe execution flow are shown:• Step Name -- Name of the step for which the condition is defined.• Arrow Condition Name -- Name of the conditional expression that is to be

evaluated. By default, this is the next step name.• Condition Type -- Type of condition (ALWAYS, IF, OTHER) that must be met

for a next step to be executed. When selecting [OTHER], there should bean item with a conditional expression of type [IF].

• Condition -- Specifies the condition using valid expressions that are appliedto service properties.

• Descriptions -- Provides a brief description of the condition that is beingevaluated.

To add a Next Step condition:

1. Drag the step you want to include in the conditional flow in the flow areaof the screen.

2. Connect a line between the preceding step in the conditional flow and thenext step that is to be executed if the condition occurs.

3. From the Next Steps tab, click on the appropriate Condition Type(ALWAYS, IF, OTHER) from the pull-down list. If you choose ALWAYS, thestep is always executed just as it normally would be default. Since IF andOTHER must be used together, your only other choice is IF.

4. Click on the pencil icon to access the Specify Execution Condition dialogwhere you can enter the value for the condition. See valid operators fordetails.

5. Click OK when you have entered the conditional value. If you like, youcan enter a description for the next step condition.


When finished, the condition is set as indicated by a conditional icon on theexecution flow line arrow.

To create a more complex conditional branching, you can use multiple Branchby Returncode Plug-ins so that one step is executed when a particularcondition is met and another step is executed when the condition is not met.

Specify Execution Condition dialog boxYou can specify which steps are executed next in a flow based on a specifiedcondition.



Table 10 Specify Execution Condition dialog box

Name Description Editability

Step Name Name of thestep for whichthe condition isdefined.

Not Allowed

Condition Name Name of theconditionalexpression thatis to beevaluated. Bydefault, this isthe next stepname.

Allowed

Description Provides a briefdescription ofthe conditionthat is beingevaluated.

Allowed

Value Specifies thecondition usingvalidexpressionsthat areapplied toserviceproperties.

Allowed

Here are the valid operators:


Table 11 Operators

Symbol/String Meaning Notes

OR Logical OR • The operator can be upperor lower case.

• A space is required oneither side of the ORoperator.

• A mixing of logical AND isnot allowed. But, logical ORis allowed.

AND Logical AND • The operator can be upperor lower case.

• A space is required oneither side of the ANDoperator.

• A mixing of logical OR is notallowed. But, logical AND isallowed.

= Equal sign • The operator can be eitherstring or numeric value.

• A space is required oneither side of the =operator.

• A full-widths number isconsidered a string.

!= Inequality sign • The operator can be eitherstring or numeric value.

• A space is required oneither side of the !=operator.

• A full-widths number isconsidered a string.

<= Less than or equal • Only numerical values areallowed.

• A space is required oneither side of the <=operator.

• A full-widths number is notallowed.

>= Greater than or equal • Only numerical values areallowed.

• A space is required oneither side of the >=operator.


< Less than • Only numeric values areallowed.

• A space is required oneither side of the <operator.



Symbol/String Meaning Notes

> Greater than • Only numeric values areallowed.

• A space is required oneither side of the >operator.


equals Equal sign • Only string values areallowed.

• The operator can be upperor lower case.

• A space is required oneither side of the "equals"operator.

not equals Inequality sign • Only string values areallowed.


• A space is required oneither side of the "notequals" operator.

contains Contain • Only string values areallowed.


• A space is required oneither side of the "contains"operator.

not contains Does not contain • Only string values areallowed.


• A space is required oneither side of the "notcontains" operator.

\ Escape • Interprets and distinguishesan operator symbol as astring.

• Insert the escape operatorbefore each word in anexpression that is to betreated as a string (eg., "a\not\equals b").

• If treating a doublequotation mark (") as astring, specify (\").

• If treating a backslash as astring, specify (\\).


Specifying the property settingsYou specify the input and output properties, service share properties, andvariables for a service template from the Property tab of the Service BuilderEdit screen. These settings affect how the various parameters associated witha given template are presented to the user.

From the Property tab, you can perform the following tasks by selecting theappropriate button:• Open/Close All Groups -- displays or collapses the display of the property

groups.• Add -- Provides the following options:

○ Property Group -- Adds a property group for organizing the display ofproperties.

○ Input Property -- Creates a new input property for the selected servicetemplate.

○ Output Property -- Creates a new output property for the selectedservice template.

○ Variable -- Creates a new variable for the selected service template.○ Service Share Property -- Adds a service share property.

• Edit -- Edits details for the selected property.• Delete -- Deletes the selected property.• Preview -- Previews the use of the property from the Create Service

Window, Create Request Window, or Task Details Window.• More Actions Provides the following options:

○ Set Visibility -- Specifies whether or not these items are visible to theuser from the Create Service window only or from the Create Serviceand Create Request windows.

○ Set Display Settings -- Sets the display settings so that they can bemodified by the user Editable, only read Read-only, or are hidden Hide.

In some cases, you may want to customize the service template by changingthe default icon or the text and graphics that is displayed for the ServiceDetails dialog and the overview associated with the service.

For more information on the options available from the Property tab, see thefollowing topics:

• Selecting the service share properties on page 62• Adding input properties on page 65• Adding output properties on page 83• Adding variables on page 84

Selecting the service share propertiesYou can add service share properties to a service template to performcommonly used (predefined) functions.



Procedure

1. From the Property tab of the Service Builder Edit screen, choose theShared Property option from the Add pull-down menu.• The Select Service Share Property dialog appears. A list of share

properties that can be assigned to a given property group are providedfor the current service template.

2. Select the service share property to add to the service template from theprovided list and click OK.• The selected service share property is added to the service template.

Next steps

• To set the value for the selected service share property, access the AddInput Property dialog.

• In addition, you can add a service share property to a particular propertygroup by selecting the Property Group option from the Add pull-downmenu and then supplying the appropriate attributes.

Related references

• Select Service Share Property dialog box on page 63

Select Service Share Property dialog boxYou select the service share properties for a given Property Group from theSelect Service Share Property dialog box.

The following table describes the Select Service Share Property dialog boxfields, subfields, and field groups. A field group is a collection of fields thatare related to a specific action or configuration.


Table 12 Select Service Share Property dialog box


Display Name: - Display name assigned to the selected property.

Key Name: - Key name associated with the service share property.

Description: - Description of the function performed by the service shareproperty.

Property Group: - Specifies the property group to which the service shareproperty is to be assigned.


You can set values for service share properties by selecting the InputProperty option from the Add pull-down menu.

Related tasks

• Selecting the service share properties on page 62

Select Reference Property dialog boxYou select the reference properties from the Select Reference Property dialogbox.

The following table describes the Select Reference Property dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.


Table 13 Select Reference Property dialog box


Step Tree Area - Display the list of steps defined in a template. Informationin the Step Tree Area is highlighted by the following icons:• RESERVED PROPERTY:• Service Template:• Service plug-in:• Flow plug-in:• Repeated Execution plug-in:• Others:

Properties List - Shows the Display Name and Key Name of propertiesdefined for the group selected in the Step Tree Area. At theinitial display, only the Step whose execution order is earlierthan the Step of Property being edited is displayed.

Show All Steps - When set to ON, all the steps defined in Template aredisplayed. The initial display is OFF. All steps are not shownwhen the Param Mode of the Property being edited is out.

ReservedProperties:

- When the Repeated Execution Plug-in is selected in the StepTree Area, the reserved properties related to the plug-in aredisplayed. This item is displayed only when the RepeatedExecution Plug-in is selected in the Step Tree Area

The selectable repeated execution input value (reserved.loop.input,reserved.loop.input N ) and repeated execution loop index(reserved.loop.index , reserved.loop.index N ) are displayed in a pull-down,and they are displayed together in one line. In order to make it easy tounderstand the relationship between repeated execution input value &repeated execution loop index and the corresponding Repeated ExecutionPlug-in, the step name of the Repeated Execution Plug-in corresponding tothe Display Name is also described in parentheses.

The following are reserved properties:


Table 14 Reserved Properties

Property Display Condition Display Name and Format

reserved.loop.input When selecting RepeatedExecution Plug-in that is onelevel above the base step asseen from the plug-in wherethis dialog is launched, in [StepTree Area].

Input for repeated execution 1level above (corresponding stepname)

reserved.loop.index Loop index 1 level above(corresponding step name)

reserved.loop.input N When selecting RepeatedExecution Plug-in that is N levelabove the base step as seenfrom the plug-in where thisdialog is launched, in [Step TreeArea].

Input for repeated execution Nlevels above (correspondingstep name)

reserved.loop.index N Loop index N levels above(corresponding step name)

Adding input propertiesYou can specify the input properties for a given property group associatedwith a service template.


Procedure

1. From the Property tab of the Service Builder Edit screen, choose theInput Property option from the Add pull-down menu. You can also addinput properties from the Specify Component Input PropertyMapping Parameters dialog box under the Flow tab, by clicking ... inthe Value field of the Step Properties area of the screen.• The Create Input Property for Service dialog appears.

2. Enter the relevant details for the input properties.3. Click OK to save the specified input property details.

The specified input properties are subsequently reflected in the inputproperty list.

Related references

• Create/Edit Input Property for Service dialog box on page 65

Create/Edit Input Property for Service dialog boxThe following table describes the Create/Edit Input Property for Servicedialog box fields, subfields, and field groups. A field group is a collection offields that are related to a specific action or configuration.



Table 15 Create/Edit Input Property for Service dialog box


Key: * - The input property key name.

Display Name: * - The name of the input property.

Description: - The description of the input property.

Property Group: - Select the property group to which the property belongs.

You can also choose (Create New Property Group) to createa new property group.

Visibility: - Chose whether to have the input property displayed on boththe Edit and Submit windows [Edit and Submit Window], orjust on the Edit window [Edit Window Only].

Display Settings: - Specifies the display setting for the input property. Thechoices are:• Editable• Read only• Hide

Service ShareProperty:

- Enable Service Share Property to add the service as aService plugin after the release process.

Required: - Specifies that the property is required when this checkbox ischecked.

Data Type: - Select a data type of the property: string, boolean, integer,double, date, password, composite. Various option arepresented for specifying restrictions on the data entrydepending on which of the options are chosen.


Content Type: - Select the content type:• application/json• application/javascript• application/xml• text/html• text/plain• text/csv• application/octet-stream

Domain Type: - Enter the domain type from the pull-down list or add a newdomain type by clicking on the plus sign and entering therelevant details from the Create Domain Type Definitiondialog box. This option is available when choosingcomposite for the Data Type and application/json for theContent Type.

Validation Script: - A validation script that specifies the conditions that restrict

the property value.



Presentation: - Specifies options that determine how the property selectionis presented depending on the Data Type that is selected.

Default Value: - Specifies whether the default value for the property is trueor false.

When specifying the Array of option, the default value hasto be written as a comma-separated string valuesurrounded by brackets.

Example: ["1","2","3"]

Data Source: - Specifies whether the data is Static or Dynamic and derivedfrom an external resource provider.

ExternalResources:

- Specifies the external resource provider when the datasource for the property is derived dynamically (whenchoosing the Dynamic option for the Data Source.

In the pull-down list, you can also add, edit, upload, ordelete for the Domain Type.

Extra Path - Specifies an additional path that can be specified when anexternal resource can be accessed through an alternatepath to modify responses.

Query Param: - Specifies the query parameter for the external resourceprovider. The serviceID and serviceTemplateID parametersare added automatically. You can specify{$ref:<keyName>} to embed the property value of otherproperties. For a JSON value, you can specify{$ref:<keyName>#<json path>}.

Name Field: - Specifies the field name of the object collection to use the

label of the selection. If omitted, uses the name field.

Value Field: - Specifies the field name of the object collection to use the

label of the selection. If omitted, uses the instance ID field.

Show If: - Show the property entry if the specified conditions are met.

Enable If: - Enable the property if the specified conditions are met.

Minimum Value/Length:

- Specifies the minimum value for an integer and double. . Ifthe data type is string or password, then enter theminimum length of the property. If the data type is date,then enter the earliest date.

Maximum Value/Length:

- Specifies the maximum value for an integer and double. . Ifthe data type is string or password, then enter theminimum length of the property. If the data type is date,then enter the latest date.

RestrictedCharacter:

- If the data type is string or password, then enter theallowed characters by using a regular expression.

Example: ^[0-9a-zA-Z\.\-]*$

Minimum ArrayLength:

- Specifies the minimum length of array elements.

Maximum ArrayLength:

- Specifies the maximum length of array elements.



Validation: - Validates the property based on the associated javascriptcode.


Creating a validator script for checking an input property

If the provided validation options are not adequate for your purposes, youcan create a script to perform the necessary checking. Following is anexample of a validator script written in JavaScript that checks if a valueentered by the user is a number and is less than the maximum allowablevalue of 1024:

function(propertyValue, lang, displayType){ var jObject = JSON.parse(propertyValue.value); if(displayType == "config"){ if( jObject.luSize > 10){ return "lu size should be under 10" } if( jObject.blockSize > 2){ return "block size should be under 2"; } } return}The following table shows the validator script specifications for the inputproperty:

# Name Description

1 Script format function (arg1, arg2, arg3) {

//code

}

2 Arguments of validator arg1:

Property value in string format

arg2:

Locale string. e.g., ja, en

arg3:

Operating information when script is running (Operationwith task creation: exec, Editing operation of properties:config)

3 Return value of validator Success:

undefined, null


# Name Description

Failure:

Error message in array or string format

If the value is not a number or is larger than the specified maximum, then amessage is output through the user interface.

Using Dynamic Data for Input Properties

When creating an input property, you can include a link to an external list toan external list that a user selects from when they edit and submit a service.The listing can be provided through an external resource such as script or aREST API. There is two ways to designate a list item as a dynamic link. Werecommend using the first one because it's easy to use.1. Create an external resource provider through Service Builder and then

reference the data.2. Create the file manually and then reference the data.

To Create an external resource provider using Service Builder

To designate a list item as dynamic data link, choose an external resource inthe pull-down list of external resource providers. You can create a newexternal resource provider by clicking "Add New External Resource Provider"at the bottom of the pull-down list. The Create External Resource Providerdialog box comes up.

In the creation dialog box, enter the following information.• Name: Name assigned to the newly created resource provider.• Version: A version number is assigned.• Content Type: Select either application/json or text/csv for the content

type.• Schema ID: If there is a domain type corresponding to the returned value

of the external resource provider, enter the schema ID. It helps usersselect an external resource provider in the property for service/plug-insetting dialog boxes; in the pull-down list of external resource providers,ones having a same schema ID as the editing property are highlighted inblue.

• Description: Provides a description for the resource provider.• Type: Select either Javascript, Command Line, or File. Depending on your

selection, enter the appropriate information in the provided field as shown:

When Specifying Javascript for the Type option:

The following table shows the Javascript specifications for the externalresource provider:


Name Description

Script format function fn (requestPath, queryParamMap,properties) { // code }

Arguments of script requestPath:A value of Extra Path which is specified in theCreate/Edit Input Property for Service dialogbox. queryParamMap:

A JSON object including key-value maps which isspecified as Query Param in the Create/EditInput Property for Service dialog box.

properties:

A JSON object including shared properties andreserved properties which is related to externalresource provider. The reserved properties arethe following:• reserved.exteranl.hcmds.dir• reserved.external.path• reserved.external.query• reserved.external.resource.dir• reserved.external.userName

You can obtain the value of the property usingproperties["<property key>"].

Return value of script Return an array of JSON objects which are listedin the pull-down. The array to be returned has tobe set to a property named "data".

In the script, you can use one of the following utility functions:• Built-in CM-REST methods• env function• auto util library

Using the Built-in CM-REST methods

You can use the modules which is available in the JavaScript Plug-in forConfiguration Manager REST API as follows:• ConfigurationManager._01_51_00.api• ConfigurationManager._01_51_00.model• ConfigurationManager._01_51_00.enum• ConfigurationManager._01_51_00.lib

Note: "_01_51_00" is corresponding to the version of the JavaScript Plug-infor Configuration Manager REST API. See the specification of the JavaScriptPlug-in for Configuration Manager REST API for details.

Using env functions


You can use "env" functions to get context information. The following tableshows the specification of the functions of the env object.

Function Description

env.getWebServiceConnections(category) Get a listing of Web Service Connections.Input parameters:

category: Category name of Web ServiceConnection.

Return value:

A listing of JSON objects of Web ServiceConnections whose category name is the onespecified as an input parameter. When theexternal resource provider is called by a service,Web Service Connections which are accessibleby the service are obtained by considering thedefined relation between Service, Service Group,Infrastructure Group, and Web ServiceConnection.

env.setWebServiceConnection(apiObject,category, name, basePath)

Set the Web Service Connection to theapiObject. The specified Web Service Connectionis used in the external connection by thespecified apiObject.Input parameters:• apiObject: Instance of ObjectsApi of the

built-in CM-REST module.• category: Category name of Web Service

Connection.• name: Name of Web Service Connection• basePath: A path following a port number in

the URL, which start with "/".

Return value:

No return value.

env.setHTTPProxy(apiObject, host, port,authenticationSchema, userName, password)

When you don't use a Web Service Connection,set the HTTP Proxy settings to the apiObject.Input parameters:• apiObject: Instance of ObjectsApi of the

built-in CM-REST module.• host: Host name or URL of the proxy server.• port: Port number of the proxy server• authenticationSchema: basic or digest• userName: User name to authenticate.• password: Password to authenticate.

Return value:

No return value.

getServiceTemplate() Get an ID of service template calling theexternal resource provider.Input parameters:

No input parameters. Return value: Servicetemplate ID


getService() Get an ID of service calling the external resourceprovider.Input parameters:

No input parameters. Return value: Service ID

Using the auto util library

You can also use the auto util library. See the specification of the auto utillibrary for details.

Here is an example using the env function and the built-in CM-RESTmethods:function fn(requestPath, queryParamMap, properties) { //Step 1. Instantiate the API Client. var client = new ConfigurationManager._01_51_00.api.ObjectsApi(); //Step 2. Specify the User Credentials. There are two methods for specifying user credentials. You can use either method, but the first one is recommended. //Method 1. Specify credentials by using the Web Service Connection (recommended). //Get accessible Web Service Connections by specifying a category name, and specify it. You do not need to specify credentials in a script. var wsc = env.getWebServiceConnections("ConfigurationManager"); env.setWebServiceConnection(client, wsc[0].productName, wsc[0].name, "/ConfigurationManager"); //Method 2. Specify credentials directly. //You can pass arguments by using the plug-in input properties or you can specify them directly in a script. For example, you can pass url and port number through the query parameters (queryParamMap). //client.getApiClient().setUsername(queryParamMap.username); //client.getApiClient().setPassword(queryParamMap.password); //client.getApiClient().setBasePath(“http://” + queryParamMap.url + “:” + queryParamMap.port + “/ConfigurationManager/”); //Step 3. Get Session //You can pass arguments by using the plug-in input properties or you can specify them directly in a script. For example, you can pass the device ID through the query parameters (queryParamMap). var responseBody = client.v1.objects.storages.storageDeviceID.sessions.post(queryParamMap.deviceId, null, null); var token = responseBody.getToken(); var sId = responseBody.getSessionId(); //Step 4. Call the API that is associated with your use case based on the session obtained in Step 3. client.getApiClient().setApiKeyPrefix("Session"); client.getApiClient().setApiKey(token); var pools = client.v1.objects.storages.storageDeviceID.pools.get(queryParamMap.deviceId, "DP", null, null); //Step 5. Make an array containing the required information.


//An array to be returned has to be set to a property named "data". var ret = { "data": [] }; var p; for (var i = 0; i < pools.getData().length; i++) { p = pools.getData()[i]; ret.data.push({ "Pool ID": p.getPoolId(), "Pool Type": p.getPoolType(), "Num of LDEVs": p.getNumOfLdevs() }); } //Final Step. Discard Session. client.v1.objects.storages.storageDeviceID.sessions.sessionId.delete(queryParamMap.deviceId, sId, null, null, null);

return ret;}

Also, in the pull-down list of external resource providers, you can edit, uploadfile, and delete an existing external resource provider.

When Specifying Command Line for the Type option:

Enter the command line to be executed. Files used by the command line canbe uploaded as described next.

When Specifying File for the Type option:

Enter the path of the file to be read as described in the following.

To upload a file to an external resource provider:

You can upload files to an external resource provider by clicking the uploadbutton in the pull-down list of external resource provider. A .zip archive filecan be updated. After updating files, you can specify it by the relative pathname in command line and as a file path.

Deleting an external resource provider

You can delete an external resource provider by clicking the delete button inthe pull-down list of external resource providers. When clicking the button,the delete confirmation dialog box comes up. The dialog box lists the servicetemplates and plug-ins using the external resource provider you are going todelete. When you confirmed there is no related service templates and plug-ins, then click the OK button and the external resource will be deleted. If youdelete an external resource provider which is used by a service template, theexternal resource provider of the service template doesn't work.

To Manually Create an External Resource

When creating an input property, you can include a link to an external listthat a user selects from when they submit a service. The listing can be


provided through an external resource such as script or a REST API. Todesignate a list item as a dynamic data link, you precede the address with adollar sign ($) and inclose the URL in quotes ({}}.

Here are the valid description formats:

Description format 1:

${url:data-url}


${url:content-type,data-url}


${url:content-type;name-mapping,data-url}


${url:content-type;value-mapping,data-url}


${url:content-type;name-mapping;value-mapping,data-url}

The following table shows setting items in the description format:

# Setting Item Description

1 content-type Should be either "application/

json" or "text/csv". If omitted,

"application/json" is assumed.

2 name-mapping Specifies the label of the

choices of the list box as

“name=” format. If omitted,

“name=name” is assumed.

3 value-mapping Specifies the value when

selected on the list box as

“value=” format. If omitted,

“value=instanceID” is assumed.

4 data-url Specifies the URL of HAD REST-

API or URL of the dynamic data

resource. The URL of HAD

REST-API is “/Automation/v1/

objects/…” format, and the URL

of the dynamic data resource is

“/Automation/v1/objects/

ExternalResources/…” format.


Note:• If the content-type is "text/csv", and the column corresponding to name-

mapping or value-mapping does not exist, the 1st column of csv formatbecomes the value of name-mapping value-mapping respectively.

• If there is no data corresponding to name-mapping, the values of value-mapping are displayed on the choices.

• If there is no data corresponding to value-mapping, the choicesthemselves are not displayed.

Here are some examples:• To display the instanceID of hosts acquired from Device Manager -- $

{url:/Automation/v1/objects/Hosts}• To display the HostName of hosts acquired from Device Manager (Define

name and value) -- ${url:application/json;name=hostName;value=instanceID,/Automation/v1/objects/Hosts}

• To display a list item by referring to a dynamic data resource (json format)-- ${url:/Automation/v1/objects/ExternalResources/VirtualMachines}

• To display a list item by referring to a dynamic data resource (csv format)-- ${url:text/csv,/Automation/v1/objects/ExternalResources/IPAddresses}

Note: When specifying dynamic data, do not enter anything for the DefaultValue option.

Here are the steps you would follow to access an external resource:1. In the Property List that is accessible from the GUI Settings tab, choose

the Add Input Property option. The Create Input Property for Servicedialog is displayed.

2. For the Data Type option, choose List from the pull-down menu.3. For the Specify List Items option, enter a URL to the external list.4. Click OK to complete the creation of input property.5. When you complete the service template (debugged and released)

containing the input property, a user can then choose from the list ofdynamically updated hosts when creating or submitting the service.

Preparing a resource file

When creating a resource file, you create the code (e.g., a script file) fordisplaying and populating your list of dynamic entires and save it in a folderthat can be accessed through a URL. In the case of a non-clusterconfiguration, the file location for every resource file is as follows:<Installation directory of product>\contents\ExternalResources.For a cluster configuration, the file location is as follows: <Shared folderpath>\contents\ExternalResources. The resource files with your


executable code and dynamic data are located directly below one of these filepath locations.

Note: In a Linux environment, make sure that the permission levels are setappropriately (chmod+x etc.,) so that the files can be accessed for execution.

The schema definition of config.json is as follows:

{ “properties”:{ “id”: { “type”: “string”, “minimum”: 0 }, oneOf: [ { “commandLine”: { “type”: “string”, “minimum”: 0 }, “file”: { “type”: “string”, “minimum”: 0 } }] }}The following table describes the entries in the config file:

Property Description

id Specifies the ID of a resource. An error occurs ifthe ID for the specified resource is inconsistent.

commandLine If used, specifies a command line for execution.An error is generated if the return value of thecommand is not 0. The upper limit for standardoutput is 30 MB and an error is generated if thislimit is exceeded. Here are some additionalguidelines:• When specifying a script file (etc.,) use the

absolute path since the current path is notspecified.

• The service share property and the reservedproperty can be included in a command line.If including a service share property or areserved property, surround a property keyby "${" and "}".

• The character set at the time of reading astandard output assumes the character set ofthe system and the associated user. (Forexample, in the case of Japanese Windows,MS-932, and in the case of Linux, the userwho executed the start command.)


Property Description

file Specifies the input file. The service shareproperty and the reserved property can beincluded in the path of a file. If including aservice share property or a reserved property,surround a property key by "${" and "}".

Data Formatting

Here is how a json list is formatted:{"data":[ Object 1, Object 2, ... ]} Here is how a csv list is formatted:Header line Record 1 Record 2 ... The following example shows how host names are acquired through aprogram such as powershell, and are then displayed in a list:Prerequisites: Location of a resource file <Installation directory of product>\contents\ExternalResources └ Hosts ├getHosts.ps1 └ META-INF └ config.json

config.json { "id": "Hosts", "commandLine": "powershell.exe \"& '${reserved.external.resource.dir}\\getHosts.ps1' ${reserved.external.hcmds.dir} ${reserved.external.userName}\"" }

Output of a command line:name,instanceID host1,123 host2,124 host3,125 host4,126 host5,127

"List display value" of a service property: ${url:text/csv,/Automation/v1/objects/ExternalResources/Hosts}

The list item displayed on the Config/Submit window of the service


host1 host2 host3 host4 host5 In this example, the host information is derived from a JSON file and outputby some other application:PrerequisitesAn arrangement of a resource file <Installation directory of product> \contents\ExternalResources └ VirtualMachines ├ vm.json └ META-INF └ config.json

config.json { "id": "VirtualMachines", "file": "${reserved.external.resource.dir}\\vm.json" }

Contents of vm.json:{ "data" : [ { "instanceID" : 127, "name" : "test1" }, { "instanceID" : 128, "name" : "test2" } ] }

"List display value" of a service property: ${url:/Automation/v1/objects/ExternalResources/VirtualMachines}

The list item displayed on the Config/Submit window of the service test1 test2

Related tasks

• Adding input properties on page 65

Create/Edit Domain Type Definition dialog boxYou can edit the schema for a selected domain type by selecting the DomainType option available from the Create/Edit Input/Output Property for Servicedialog box and then clicking the plus sign or wrench icon next to the domaintype.

The following table describes the Edit Domain Type Definition dialog boxfields, subfields, and field groups. A field group is a collection of fields thatare related to a specific action or configuration.



Table 16 Edit Domain Type Definition dialog box


Domain TypeName:

- Specifies the name for the domain type.

Domain Type ID: - Specifies an ID (address) for the domain type.

Domain TypeSchema:

- Specifies the schema for the domain type.

The format conforms to the JSON shcema. (http://json-schema.org/)

Generate Template(Button):

- Generates a GUI Definition based on the Domain TypeSchema. You don’t need to enter the GUI Definition fromscratch as the basic structure is the same as for the DomainType ID.

GUI Definition ID: - Specifies GUI definition ID.

GUI Definition: - Specifies the GUI definition.


The following table shows the attributes for the property definition in the GUIDefinition

Key Description

diplayName Display name of property

description Description of property

presentation Presentation type of property. "input","textarea", "url", "select", "radio", "checkbox","spinbox", "capacity", "capacityInKB","capacityInMB", "capacityInGB", "datePicker",password", or "file"

permission Permission of property; "exec" or "config"

visibility Visibility of property; "lock", "unlock" or "hidden"

required Required or not; true or false.

pattern Accepsted regular expression pattern of propertyvalue.

validationScript Validation script of property value.

showIf Display condition of property

enableIf Activate condition of property

enum Specifies an array. You can define JSON objectsin it.


enumDataSource Specifies an external resource provider. Here isan example:"enumDataSource": {"url":"/Automation/v1/objects/ExternalResources/1eb39858-48b5-4d3a-b82a-9af5c91af8c4","contentType": "application/json","nameField": "hostGroupName","valueField": "id"}

contentType Content type of composite type; "application/json", "application/javascript", "application/xml","text/html", "text/plain", "text/csv", or"application/octet-stream"

Following are examples of the Domain Type Schema and GUI Definitionrepresenting a Volume Setting in the built-in Allocate Volume service.

Domain Type Schema

{ "type": "object", "properties": { "values": { "type": "array", "title": "Volume Settings", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "usage": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9 ~!@#\\$%\\^&()_\\+\\-=\\{\\}\\[\\]'\\.`]*$", "default": "" }, "numberOfVolumes": { "type": "integer", "minimum": 1, "maximum": 500, "default": 2 }, "capacity": { "type": "integer", "minimum": 10, "maximum": 200, "default": 50 }, "storageProfile": { "type": "string", "enum": [ "Gold Write", "Silver Write" ],


"default": "Gold Write" }, "ldevLabel": { "type": "string", "minLength": 0, "maxLength": 64, "pattern": "^[A-Za-z0-9 ~!@#\\$%\\^&\\*()_\\+\\-=\\{\\}\\[\\]\\|:;'<>\\.\\?\\/`]*$", "default": "" }, "ldevSetting": { "type": "object", "properties": { "fullAllocation": { "type": "string", "enum": [ "Enable", "Disable" ], "default": "Disable" } } }, "lunSetting": { "type": "object", "properties": { "lunStartsFrom": { "type": "integer", "description": "Enter a value in hex format.", "default": 0, "minimum": 0, "maximum": 2047 } } } } } } }}GUI Definition

{ "displayName": "Volume Settings", "properties": { "values": { "displayName": "Volume Settings", "showLabel": false, "permission": "locked", "visibility": "exec", "items": { "displayName": "Volume Setting", "properties": { "usage": { "displayName": "Volume Usage", "permission": "unlocked", "visibility": "exec",


"required": true }, "numberOfVolumes": { "displayName": "Number of Volumes", "permission": "unlocked", "visibility": "exec", "required": true }, "capacity": { "displayName": "Volume Capacity", "permission": "unlocked", "visibility": "exec", "required": true, "presentation": "capacityInGB" }, "storageProfile": { "displayName": "Storage Profile", "permission": "unlocked", "visibility": "exec", "required": true, "presentation": "select" }, "ldevLabel": { "displayName": "Volume Label", "permission": "unlocked", "visibility": "exec", "required": false }, "ldevSetting": { "displayName": "LDEV Setting", "permission": "unlocked", "visibility": "exec", "properties": { "fullAllocation": { "displayName": "Full Allocation", "visibility": "exec", "permission": "unlocked", "required": true, "presentation": "select" } } }, "lunSetting": { "displayName": "LUN Setting", "permission": "unlocked", "visibility": "exec", "properties": { "lunStartsFrom": { "displayName": "LUN Starts From", "visibility": "exec", "permission": "unlocked", "required": true } } } } } }


}}

Adding output propertiesYou can specify the output properties for a given property group associatedwith a service template.

A list of properties is shown.

Before you beginA service template in the Developing state must exist with steps added to theFlow View.

Procedure

1. From the Property tab of the Service Builder Edit screen, choose theOutput Property option from the Add pull-down menu. You can alsoadd output properties from the Specify Component Output PropertyMapping Parameters dialog box under the Flow tab, by clicking ... inthe Value field of the Step Properties area of the screen.• The Create Output Property for Service dialog appears.

2. Enter the relevant details for the output properties.3. Click OK to save the specified output property details.

The specified output properties are subsequently reflected in the outputproperty list.

Related references

• Create/Edit Output Property for Service dialog box on page 83

Create/Edit Output Property for Service dialog boxYou can add output properties for a service template from the Create/EditOutput Property for Service dialog box.

The following table describes the Create/Edit Output Property for Servicedialog box fields, subfields, and field groups. A field group is a collection offields that are related to a specific action or configuration.


Table 17 Create/Edit Output Property for Service dialog box


Key * - The output property key.

Display Name:* - The name of the output property.

Description: - The description of the output property.



Property Group: - Select the property group to which the property belongs, oruse reserved.defaultGroup.

Display/Hide: - Specifies the display setting for the output property. Thechoices are:• Display• Hide

Data Type: - Select a data type of the property: string, password, orcomposite. Various option are presented depending onwhich of the options are chosen.



Presentation: - Specifies how the property selection is presented dependingon the Data Type that is selected.


Show If: - Show if the conditions are met.

Enable If: - Enable if the conditions are met.

Fields with an asterisk are required.

Related tasks

• Adding output properties on page 83

Adding variablesYou can add variables for a given property group associated with a servicetemplate.

A list of current properties for a given Property Group are shown from theProperty tab.



Procedure

1. From the Property tab of the Service Builder Edit screen, chooseVariable from the Add pull-down menu.The Create Variable dialog box appears.

2. Enter the details for the variable to be added. You can add a serviceshare property to a particular property group from the Property Grouppull down menu. You can also specify the data type and associateddefault value.

3. Click OK.The specified variable is added to the service template.

Next steps

• Make sure to map the variable to the appropriate output value.

Related references

• Create/Edit Variable dialog box on page 85

Create/Edit Variable dialog boxYou can enter or edit a variable property for a service template from theCreate/Edit Variable dialog box.

The following table describes the dialog box fields, subfields, and field groupsfor the Create/Edit Variable dialog box. A field group is a collection of fieldsthat are related to a specific action or configuration.


Table 18 Create/Edit Variable dialog box


Key Name:* - Specifies the variable key name.

Display Name:* - The variable name.

Description: - The variable description.

Property Group: - Select a property group for the variable being added.

Data Type: - Select a data type of the property: string, boolean, integer,double, date, password, composite. Various option arepresented depending on which option is chosen. Forinstance, if you chose the date option, a calender interfaceis provided.


Content Type: - Select the content type:



• application/json• application/javascript• application/xml• text/html• text/plain• text/csv• application/octet-stream

Domain Type: - Enter the domain type from the pull-down list or add a newdomain type by clicking on the plus sign and entering therelevant details from the Create Domain Type Definitiondialog box.

Default Value: - Enter the default value of the variable.


Related tasks

• Adding variables on page 84

Example of creating a new service templateThis section describes the process of customizing a service template thatprovisions volumes for a given platform and adds a component step thatgenerates an email notification indicating whether the volume allocation hasbeen successful.

During this example, you will complete the following procedures:• Make a copy of an existing service template and provide the details for the

new service template• Add an email notification plug-in and modify it for your environment• Establish the flow for the component steps• Test the new service template

Note: The example assumes that the service administrator has consideredthe system's architecture and performed the calculations necessary to createa service based on the desired storage size, configuration, and I/O profile.Although the values in the template are based on the best practices, thevalues you set may differ depending on your specific needs.

To begin this example, you must first access the Service Builder Homescreen by choosing Service Builder from the Tools pull-down menu. TheService Builder Home screen provides all of the Service Builder options forcreating and managing service templates and their associated plug-ins.

Making a copy of an existing service template

The following steps are performed by a service administrator with theDevelop role.


1. From the Released tab of the Service Builder Home screen, select andhighlight the template to copy either from the Card or Table view. For thepurpose of this example, please select the "Allocate Volumes and Add toOracle Database" service template.

2. Click the Copy and Edit button to access the Copy Service Templatedialog.

3. In the Copy Service Template dialog box, enter the basic information ofthe service template, as shown in the following table:

Table 19 Copy Service Template dialog box

Parameters Description Values

Key Name: * - Specifies the key name for the copied service template.For the purpose of this example, enter a unique ID suchas "NewTemplate".

Version * - Version of the service template. This should already befilled in for the copied service template.

Vendor ID: * - Enter some name that identifies the vendor.

Display Name: * - Name assigned to the copied version of the servicetemplate. This should already be filled in for the copiedservice template.

Vendor Name: - Vendor name, if applicable, for the copied servicetemplate.

Description: - Description of the copied service template.

Tags: - Tag category associated with the service template. The"Add New Storage" and "Oracle" tags should already beselected for the copied service template.

Note: Fields with an asterisk (*) are required.

4. Click OK and the new service template is created with the modifieddetails. The components (plug-ins and possibly other service templates)associated with the copied template are shown from the Flow tab of theService Builder Edit screen.

Notice that the existing plug-in has already been added as a step to the flowfrom the original service template that you copied. If you click on this step,you can examine the input and output properties associated with the step.

Adding email notification for the service template

After you have made a copy of the service template, you can begin makingthe necessary modifications from the Service Builder screen.

Follow these steps to add the mail transmission plug-in:1. From the component listing, locate the Email Notification Plug-in and

drag it into the flow area of the screen on the right. If necessary, you can


use the search box to locate the plug-in. The Create Step Attributesdialog box appears.

2. In the Create Step Attributes dialog box, enter the appropriate detailsfor the plug-in step, as shown in the following table:

Table 20 Create Step dialog box


ID: * - Specifies the ID for the email notification plug-in. Thisshould already be filled in.

Display Name: * - Name assigned to the plug-in step. This should alreadybe filled in for the plug-in.

Description: - Description of the copied service template. You can entera description here if you like.

3. Click OK to add the selected plug-in. A graphic for the newly added plug-in step is shown in the flow area of the screen.

4. Specify the order of execution for the newly added plug-in step byclicking on the existing plug-in graphic and the dragging the arrow overthe email plug-in step. An arrow shows the direction in which the plug-insteps are processed by the service template when the service isexecuted.

5. Specify the input properties for the newly added plug-in step. Forinstance, you can enter a subject for the Subject property or add contentfor the message body. Since the values for email notification are differentfor each user, you may want to check the GUI Visibility checkbox for the"To Addressed" property so a user is then able to enter a relevant emailaddress from the Edit or Submit windows when running the service.

6. Establish the processing flow for the newly added email notification plug-in by clicking on the dot next to the existing provisioning plug-in stepand dragging it to connect the arrow with the email notification plug-instep.

Debugging, building, testing and releasing the new service template

After creating and adding the required plug-ins, you can build the servicetemplate and then release it when all the bugs are ironed out.1. Click on the Debug tab and then click OK to build the service template

with the added plug-ins. The Build/Release Result dialog appearsshowing any errors that may have occurred during the building of theservice template. Continue to troubleshoot any errors until the buildcompletes successfully then click Close to exit the Build/ReleaseResult dialog box. If the build is successful, the Perform Debuggingdialog box appears.

2. At this point, you are going to want to make sure that the servicetemplate is functioning correctly. You can choose the From CreateService Window or From Request Service Window options from theEditpull-down menu.


3. On the Services tab, select "NewTemplate" in Developing status andclick Create Request.

4. In the Submit Service Request window, in the Settings pane, retainthe values for the Volume Settings. Enter the following information:


Host Settings

Target Hosts The number of target hosts Single Host

Host Detail The host name or IP address from

Device Manager

Enter the host name or

IP address

Task Settings

Task Name The name of the task NewTemplate

Description A brief description of the task A task to generate an

email for the service.

Schedule Type The time when the task executes Immediate

5. When you have supplied all the required values, click OK to access theService Builder Debug screen where you can debug the service templatefrom the Task Log, Service Properties, or Break Point tabs.

6. After testing the service template to see that the new plug-in isfunctioning correctly and is properly extracting the LDEV information, youcan return to the Service Builder Edit screen and click on the Release tabto make the template available for users to submit.

Related concepts

• Service template creation workflow on page 44

Related tasks

• Creating a new service template on page 46• Creating the steps in a data flow on page 48• Adding input properties on page 65• Adding output properties on page 83



5Creating a new plug-in

You have the choice of making a copy of an existing plug-in and thenmodifying it for your needs or you can create a new plug-in from scratch thatissue the commands, runs the scripts, and performs the fundamental tasksfor a given service template.

Each plug-in is designed with a specific purpose and their use and sequencewithin a service template is an important part of the service templateoperation.

This module covers:

□ Plug-in creation workflow

□ Creating a plug-in

□ Create/Edit Custom Plug-in dialog box

□ About plug-in properties

□ Adding plug-in input properties

□ Specify/Edit Input Property for Custom Plug-in dialog box

□ Adding plug-in output properties

□ Specify/Edit Output Property for Custom Plug-in dialog box

□ Setting remote commands in plug-ins

□ Setting environment variables

□ Create/Edit Environment Variable dialog box

□ Adding output filters

Creating a new plug-in 91Hitachi Automation Director Service Builder User Guide

□ Edit Output Filter dialog box

□ Creating a conditional branch using the branching plug-ins

□ Generating an email

□ Example of creating a new plug-in

92 Creating a new plug-inHitachi Automation Director Service Builder User Guide

Plug-in creation workflowYou manage and create new plug-ins from the Custom Plug-in pull-downmenu of the Service Builder HomeRelease screen.

By choosing the appropriate option from the Custom Plug-in pull-down menu,you can edit, copy, or delete an existing plug-in.

To create a new plug-in, you must go through the various phases described inthe following workflow:

Phase 1 - Preparation• Decide on the need and purpose of the plug-in. Consider the functional

steps involved to automate the process to determine if the one or moreplug-ins are required, or if creating a new plug-in or modifying an existingplug-in is needed.

• Prepare to create the plug-in. This involves defining the plug-in, its iconfile, preparing any commands or scripts to complete its tasks, andpreparing resource files.

Phase 2 - Creation• Create a new plug-in, or copy and modify an existing plug-in from the

Service Builder Home screen. The plug-in begins in the Developing state.• Enter the basic information, and set input and output properties.• Set the remote commands and environment variables, if needed.

Phase 3 - Testing• Place the plug-in into the flow during the development of a service

template.• Build the service template for testing.• Perform testing and make any necessary corrections until the plug-in

performs properly within its designated service template.

Phase 4 - Releasing• When testing is complete, release the service template. The status of the

service template and the related plug-ins is changed to Released.

Related tasks

• Creating a plug-in on page 93

Creating a plug-inYou can create a plug-in based on one of the existing (canned) plug-ins, oryou can create a new plug-in from scratch that will execute the commands orscripts for a given step in a service template.


Note: A plug-in with the same Plug-in key name, Vendor ID, and VersionNumber cannot be duplicated. For more information on versions, see Managing versions on page 153.

Before you begin• Determine how to handle the input properties of a script and the method

to deliver an output property from a script.• If executing a script by file, have the script files prepared and ready.

Procedure

1. From the Service Builder Home screen, from the Custom Plug-inpull-down menu, choose either Copy Plug-in to use one of the existingplug-ins as a model or Create Plug-in to create a new plug-in fromscratch.The Copy Custom Plug-in or Create Custom Plug-in dialog box opensdepending on your choice of creation methods.

2. From the General tab, enter the basic information for the plug-in.3. From the Property tab, click on the input or output property icons and

then add the input and output properties associated with the plug-in. Youcan add multiple input properties and drag and drop within the section tochange the order of the input properties.

4. From the Remote Command tab, click the Add Platform button toselect an Operating System. You can then specify the Credential Typeand other details that are relevant for the plug-in.For more information on setting remote commands, see Setting remotecommands in plug-ins on page 103.

5. If environment variables are required to execute the remote command orscript, click Details and then click Add to enter the name (required) andvalue of the environment variable.

6. When you are finished, click Save.

ResultA new plug-in is created and is in the Developing state which can then beaccessed from the Flow tab of the Service Builder Edit screen.

Related references

• Create/Edit Custom Plug-in dialog box on page 94

Create/Edit Custom Plug-in dialog boxWhen creating a new plug-in, you supply the relevant details from theGeneral, Property, or Remote Command tabs from the Create/Edit CustomPlug-in dialog box.


General Tab

From the General tab, you can view and edit general details regarding thecurrently selected service template.

The following table describes the options available from the General tab.

Table 21 Create/Edit Custom Plug-in General Tab


Key Name * - The key name for the plug-in (up to 64 characters).The combination of the Key Name and Vendor IDcannot exceed 115 characters.

Version * - The version number of the plug-in. For more detailsabout versioning, see Managing versions onpage 153.

Vendor ID * - The vendor ID of the plug-in (up to 64 characters).The combination of the ID and Vendor ID cannotexceed 115 characters.

Display Name - The name of the plug-in (up to 64 characters).

Vendor Name - The vendor name of the plug-in (up to 64characters).

Description - A brief description of the plug-in (up to 1,024characters).

Tags - The assigned Tag category for the plug-in. Click onthe plus sign to add tag categories for the plug-in.

Icon - Specifies the icon graphic (a 48 pixels x 48 pixelsPNG file) associated with the plug-in.

A default image is provided that can be changed byclicking the change button and then supplying theappropriate filename. You can revert back to theoriginal icon at any time by choosing the RestoreDefault Icon button.

Note: As you enter information in a dialog box, if the information is incorrect,errors that include a description of the problem appear at the top of the box.

Property Tab

From the Property tab, you can search for and view the input and outputproperties associated with a given service template. You can search for agiven property through the text search box for a given property. Click theinput or output buttons, (next to search box), to switch between the listingsfor input and output properties. You can also edit a selected property byclicking on the edit pencil.

The following table describes the options available from the Property tab.


Table 22 Create/Edit Custom Plug-in Property Tab


Key Name - Display the key associated with the property.

Display Name - Display name associated with the property.

Description - Provides a description for the property.

Required - Indicate whether the property is required (ture) or not(false).

Default Value - Specifies any default value if necessary.

Remote Command Tab

From the Remote Command tab, you can set up remote commands that areexecuted during the processing of a service template.

To begin adding a remote command, click Add Platform then provide therelevant details for the selected operating environment.

The following table describes the options available from the RemoteCommand tab.

Note: As you enter information in a dialog box, if the information is incorrect,errors that include a description of the problem appear at the top of the box.

Table 23 Create/Edit Custom Plug-in Remote Command Tab


Credential Type - Specifies the credential type required for the plug-in.

Select Shared agentless setting, if you want to use thecredential information in the agentless remote connectionsview under the HAD Administration tab when the service isexecuted. Shared agentless setting is the default CredentialType.

The following reserved plug-in property is automatically setfor the shared agentless setting credential type:

plugin.destinationHost Enter the target of an operation byIPv4 address, IPv6 address, or host name (up to 256characters).

Select Service input property to use the credentialinformation as an input property.

The following reserved plug-in properties are automaticallyset for the Service input property credential type:


Enter the target of an operation by IPv4 address, IPv6address, or host name (up to 256 characters). If the



destination host is HAD Server (localhost), the user IDand the password are not necessary.

• plugin.account

Enter the user ID for logging in to the target host (up to256 characters).

• plugin.password

Enter the password for logging in to the target host (upto 256 characters).


Enter the password of the root account used for loggingin to a target host in a Linux environment (up to 245characters). If the target is host is running the Windows,this property is ignored.

Options Run as systemaccount(Windows)

Runs the command using the system account.

Character SetAutoJudgement(SSH)

Character Set Auto Judgment (SSH) applies to UNIXoperating systems. If enabled, executes the script using thedefault locale ofthe user. If disabled, scripts are executedwith the LC_ALL=C locale. Default is enabled. For moredetails on Character Set Auto Judgement, see:Localesettings for plug-ins on page 186.

Executive withroot privileges(SSH)


Add Platform - Specifies the platform for the remote command (Windows,Linux, Solaris, HP-UX, AIX).

Import Settings - Specifies that the settings should be derived from anotheroperating system.

Execution Method: - Select Script name if based on a script, CLI Command ifusing a stored command, or N/A if no execution is required.

CLI Command: * - Enter the CLI command (up to 8,192 characters) for theremote command. Required if Script name or CLI Commandis selected for Execution Method. The Insert All InputProperties button inserts all input properties defined for theplug-in into the CLI command.

Type in: - Select By attachment if uploading a script file, or Type in todirectly enter the script information.


File* - Click the Browse button to specify the file that holds thecommand or script.

Mapping Definitionof Output Properties

- Specify the mapping definition of the output property for acommand or script. By selecting and highlighting a propertyin the list and then clicking Edit, you can access the EditOutput Filter dialog box where you can specify an outputfilter that controls the data that is passed to the outputproperty.

Execution Directory - Specify the execution directory.



EnvironmentVariables

- Select environmental variables for the command or script.When selecting this option, the Create/Edit EnvironmentVariable dialog box appears where you can enter theappropriate variable information.


Related tasks

• Creating a plug-in on page 93

About plug-in propertiesYou define input and output properties for plug-ins to specify the parametersrequired during the execution of a task and to process the results.

You need to map the input and output properties of the components for everystep with the input and output properties and variables of the servicetemplate. The input properties of the components used in a service templateshould be associated with the input properties or variables, or outputproperties of other component steps associated with a service template. Theservice template input properties store the input values required to execute aservice. The service template output properties store the execution results ofthe service.

The value of the plug-in input property can be the value that has beenpreviously set for the property, or directly set for the service template. Theinput property can also be a variable. Service share properties can be appliedto the input properties.

The output property content depends on the type of component. The result ofexecuting a step can be stored as output properties. Variables temporarilyhold the values that are passed between components.

The input and output properties of the components are set from the Flow tabof the of the Service Builder Edit screen. The input and output properties andvariables for the service template are set in the Property tab of the ServiceBuilder Edit screen.

Input and output properties can store a maximum of 1,024 characters unlessyou specify "composite" as the data type for the Input/Output property. Ifyou specify a value that is longer than 1,024 characters without specifyingthe composite data type, the first 1,024 characters are stored as the propertyvalue and the remainder are discarded. If you reference the value of aproperty key in the format ?dna_property-key?, the referenced value istruncated if it is longer than 1,024 characters.


A plug-in property whose property key and purpose are determined inadvance is called a reserved plug-in property. These properties specifycredential information and the execution-target hosts of remote commands.

Note: Please see: Specifying step properties on page 51 for more details onthe mapping of service template properties and plug-in properties.

Adding plug-in input propertiesThe input properties store the values that plug-ins require during execution,such as the arguments for remote commands or the target host of theoperation. The input properties are created and defined from the CreateCustom Plug-in or Edit Custom Plug-in dialog boxes.

From the Service Builder Home screen, choose either Create Plug-in or EditPlug-in option from the Custom Plug-in pull-down menu.

Note: You can also enter properties from the Specify Input Property forCustom Plug-in dialog box that is accessed by clicking ... in the Value field ofan existing property from the Flow tab of the Service Builder Edit screen.

From the Property tab of the Edit Custom Plug-in dialog, make sure that theinput listing is selected (by clicking on the input property icon) and then clickthe Add button to enter the necessary input properties. You can add multipleinput properties and drag and drop from within the section to change theorder of the input properties.

Continue to enter the properties and remote commands of the plug-in.

Related references

• Specify/Edit Input Property for Custom Plug-in dialog box on page 99

Specify/Edit Input Property for Custom Plug-in dialog boxThe following table describes the Specify/Edit Input Property for CustomPlug-in dialog box fields, subfields, and field groups. A field group is acollection of fields that are related to a specific action or configuration.


Table 24 Specify/Edit Input Property for Custom Plug-in dialog box


Key: * - The input property key name.

Display Name: * - The name of the input property.



Description: - The description of the input property.

Property Group: - Select the property group to which the property belongs.

You can also choose (Create New Property Group) to createa new property group.

Visibility: - Chose whether to have the input property displayed on boththe Edit and Submit windows [Edit and Submit Window], orjust on the Edit window [Edit Window Only].

Display Settings: - Specifies the display setting for the input property. Thechoices are:• Editable• Read only• Hide

Service ShareProperty:

- Enable Service Share Property to add the service as aService plugin after the release process.

Required: - Specifies that the property is required when this checkbox ischecked.

Data Type: - Select a data type of the property: string, boolean, integer,double, date, password, composite. Various option arepresented for specifying restrictions on the data entrydepending on which of the options are chosen.



Domain Type: - Enter the domain type from the pull-down list or add a newdomain type by clicking on the plus sign and entering therelevant details from the Create Domain Type Definitiondialog box. This option is available when choosingcomposite for the Data Type and application/json for theContent Type.

Validation Script: - A validation script that specifies the conditions that restrict

the property value.

Presentation: - Specifies options that determine how the property selectionis presented depending on the Data Type that is selected.


When specifying the Array of option, the default value hasto be written as a comma-separated string valuesurrounded by brackets.



Example: ["1","2","3"]

Data Source: - Specifies whether the data is Static or Dynamic and derivedfrom an external resource provider.

ExternalResources:

- Specifies the external resource provider when the datasource for the property is derived dynamically (whenchoosing the Dynamic option for the Data Source.

In the pull-down list, you can also add, edit, upload, ordelete for the Domain Type.

Extra Path - Specifies an additional path that can be specified when anexternal resource can be accessed through an alternatepath to modify responses.

Query Param: - Specifies the query parameter for the external resourceprovider. The serviceID and serviceTemplateID parametersare added automatically. You can specify{$ref:<keyName>} to embed the property value of otherproperties. For a JSON value, you can specify{$ref:<keyName>#<json path>}.

Name Field: - Specifies the field name of the object collection to use the

label of the selection. If omitted, uses the name field.

Value Field: - Specifies the field name of the object collection to use the

label of the selection. If omitted, uses the instance ID field.

Show If: - Show the property entry if the specified conditions are met.

Enable If: - Enable the property if the specified conditions are met.

Minimum Value/Length:

- Specifies the minimum value for an integer and double. . Ifthe data type is string or password, then enter theminimum length of the property. If the data type is date,then enter the earliest date.

Maximum Value/Length:

- Specifies the maximum value for an integer and double. . Ifthe data type is string or password, then enter theminimum length of the property. If the data type is date,then enter the latest date.

RestrictedCharacter:

- If the data type is string or password, then enter theallowed characters by using a regular expression.

Example: ^[0-9a-zA-Z\.\-]*$

Minimum ArrayLength:

- Specifies the minimum length of array elements.

Maximum ArrayLength:

- Specifies the maximum length of array elements.

Validation: - Validates the property based on the associated javascriptcode.

File Reference: - Specifies that the value of the property is expressed as thefile path when this checkbox is checked. The value of theproperty is automatically stored in a file, and you canretrieve the path of the file as an input property. Forexample, you can use a file path in the command lineinstead of a direct value.



Related concepts

• Adding plug-in input properties on page 99

Adding plug-in output propertiesThe output properties store the values that plug-ins require during execution,such as the arguments for remote commands or the target host of theoperation. The output properties are created and defined from the CreateCustom Plug-in or Edit Custom Plug-in dialog boxes.

From the Service Builder Home screen, choose either Create Plug-in or EditPlug-in option from the Custom Plug-in pull-down menu.

Note: You can also enter properties from the Specify Output Property forCustom Plug-in dialog box that is accessed by clicking ... in the Value field ofan existing property from the Flow tab of the Service Builder Edit screen.

From the Property tab of the Edit Custom Plug-in dialog, make sure that theoutput listing is selected (by clicking on the output property icon) and thenclick the Add button to enter the necessary output properties. You can addmultiple output properties and drag and drop from within the section tochange the order of the output properties.

Continue to enter the input and output properties and remote commands forthe plug-in.

Related references

• Specify/Edit Output Property for Custom Plug-in dialog box on page 102

Specify/Edit Output Property for Custom Plug-in dialog boxYou can add or modify output properties for a service template.

The following table describes the Specify/Edit Output Property for CustomPlug-in dialog box fields, subfields, and field groups. A field group is acollection of fields that are related to a specific action or configuration.


Table 25 Specify/Edit Output Property for Custom Plug-in dialog box


Key * - The output property key.

Display Name:* - The name of the output property.

Description: - The description of the output property.



Property Group: - Select the property group to which the property belongs, oruse reserved.defaultGroup.

Display/Hide: - Specifies the display setting for the output property. Thechoices are:• Display• Hide

Data Type: - Select a data type of the property: string, password, orcomposite. Various option are presented depending onwhich of the options are chosen.



Presentation: - Specifies how the property selection is presented dependingon the Data Type that is selected.


Show If: - Show if the conditions are met.

Enable If: - Enable if the conditions are met.

File Reference: - Specifies that the value of the property is expressed as a filepath when this checkbox is checked. The value of theproperty is automatically stored in a file, and you canreceive the path of the file as an input property. Forexample, you can use a file path in a command line insteadof entering a direct value.


Related concepts

• Adding plug-in output properties on page 102

Setting remote commands in plug-insPlug-ins use remote commands to pass an input property to a script orcommand. Remote commands are also used to filter an output property fromthe standard result output. Set an output filter to store the value you wantfrom the standard output. A plug-in requires one or more remote commands.Environment variables are set through remote commands.


Procedure

1. From the Service Builder Home screen, choose either Create Plug-inor Edit Plug-in option from the Custom Plug-in pull-down menu. If youare editing an existing plug-in, select the plug-in from the card or tableview and click Edit.The Create/Edit Custom Plug-in dialog appears.

2. From the Remote Command tab, click the Add Platform button toselect the appropriate operating environmentA choice of operating platforms is provided.

3. Chose the appropriate platforms from the list and then enter the relevantdetails.Options are provided depending on the platform you have chosen.

4. Enter all of the relevant details for the remote command and then clickSave.The remote command is created for the selected plug-in

Setting environment variablesEnvironment variables can be set when a remote command of a plug-in isexecuted.

To set an environment variable:

You can set environmental variables when creating or editing a plug-in fromthe Remote Command tab of the Create/Edit Custom Plug-in dialog.

Procedure

1. From the Service Builder Home screen, choose the Create Plug-in orEdit Plug-in option from the Custom Plug-in pull-down menu.After you have entered the details for a new plug-in, or have selected anexisting plug-in to edit from the Select Plug-in pane, the Create/EditCustom Plug-in dialog appears.

2. From the Details section of the Remote Command tab, under theEnvironmental Variables box, click Add.The Create Environmental Variable dialog box appears.

3. Enter the relevant attributes (name and value) for the environmentalvariable, then click OK.The defined environmental variable and its associated value is shown.You can continue to add more environmental variables or edit existingones as needed.

Related references

• Create/Edit Environment Variable dialog box on page 105


Create/Edit Environment Variable dialog boxYou can enter or modify environment variables for a remote command fromthe Details section of the Remote Command tab that is accessed from theCreate/Edit Custom Plug-in dialog box.

The following table describes the Create/Edit Environment Variable dialog boxfields, subfields, and field groups. A field group is a collection of fields thatare related to a specific action or configuration.


Table 26 Create/Edit Environment Variable dialog box


Name: * - Name of the environment variable.

Value: - Value of the variable.

Related tasks

• Setting environment variables on page 104

Adding output filtersStandard output and standard error output are stored in the output property.Therefore, it is recommended to set filters on the standard output results toobtain the value you want by using regular expressions in the remotecommands.

Example

To obtain the disk ID from the standard output property results, follow thesteps below:

1. Set a filter on the output property:diskid:n is the output method as the result of a scriptdiskid:(.+) is the regular expression to filter the output property

2. Create a script to pass the results.3. Use a remote command to set an output filter where:

diskid:(.+) is the output filterdiskid:1 is the standard output stringblank is the value of the output property

Executing the script will result in:

diskid:1 is the standard output string


1 is the value of the output property

You specify output filters from the Remote Command tab that is accessedfrom the Copy/Edit Custom Plug-in dialog box.

To set an output filter:

From the Mapping Definition of Output Properties box, select and highlightthe line of the output property and click the edit (pencil) icon. Enter therelevant details in the Edit Output Filter dialog box.

Continue to set environment variables, if needed.

Note: When specifying multiple groups in a regular expression, only valuesthat match the first group are stored in the output property. In addition, Ifthe regular expression applies to multiple value ranges, only the first range ofvalues is stored in the output property.

Note: Regular expressions are evaluated in the multiline mode. To eliminateunwanted characters (including the line feed), you must write the regularexpression specifying the single-line mode. The single-line mode is describedas "(?s)" in the regular expression. The cutout by the regular expression isthe part grouped by the parentheses. The first group becomes the target ofthe cutout if multiple groups exist. Here are some examples of cutting outthe standard output using a regular expression.

Example of extracting the string from a single line:Standard outputserver:sv001CPU - 89%Memory - 77%

Regular expression server:(.*)

Result of cutoutsv001

Example of extracting the string with multiple lines - 1:Standard outputserver:sv001CPU - 89%Memory - 77%

Regular expressionserver:(?s)(.*)

Result of cutoutsv001CPU - 89%Memory - 77%


Example of extracting the string with multiple lines - 2:Standard outputserver:sv001CPU - 89%Memory - 77%

Regular expression server:(?s)(.*)\sMemory

Result of cutoutsv001CPU - 89%Related references

• Edit Output Filter dialog box on page 107

Edit Output Filter dialog boxYou can specify an output filter using a regular expression to control the datathat is processed by the output property. If the output filter is empty,standard output and standard error output is stored directly in the outputproperty.

The following table describes the Edit Output Filter dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.


Table 27 Edit Output Filter dialog box


Output Filter: - Enter a regular expression to filter the data stored by theoutput property.

Verification of theOutput Filter

- Performs the processing and verifies that the filter isprocessing the data in the manner you intended. Thestandard output details are shown as well as the results.

Related tasks

• Adding output filters on page 105

Creating a conditional branch using the branching plug-insYou can create a conditional branch so that a step within a service template isexecuted only when a particular condition is met.


A conditional branch is useful for executing the appropriate steps based on acondition that occurs during the processing of a previous step.

The following plug-ins are provided for the purpose of creating a conditionalbranch:• Branch by Property Value Plug-in -- compares a particular service property

with a specified value (or if necessary, can also be compared with avariable or step property) and then acts accordingly.

• Branch by ReturnCode Plug-in -- compares the Return Code generated bya previous step with a specified value and then acts accordingly.

To create a conditional branch:

1. Insert the appropriate judging plug-in at the point in the flow after thestep where the branch is to occur.

2. Position the step that is to be executed if the condition is met below thebranch and the position of the subsequent steps.

3. Draw connectors between the steps to define the flow of execution.4. Set the input and output values to define the condition and specify the

appropriate values.

The following figure shows an example of using the Branch by Property ValuePlug-in to set up a conditional branch when a step property generated by aprevious step equals a given value:


In this example, "Step A", is executed only when "out0" from the previousstep equals "test".

The following figure shows an example of using the Branch by ReturnCodePlug-in to set up a conditional branch when a return code generated by aprevious step meets a specified criteria:


In this example, "Step A" is executed only when the return code from theprevious step equal "0".

To create a more complex conditional branching, you can use multiple Branchby Returncode Plug-ins so that one step is executed when a particularcondition is met and another step is executed when the condition is not met.


Generating an emailDuring the processing of a service template, you can generate an email witha specified notification or the contents of some output by using theappropriate plug-ins.

You can use the Email Notification Plug-in to send an email to specifiedrecipients notifying them when a particular condition occurs and that includesinformation that has been output from a task or process. For example, youcould send the result of a LUN path configuration associated with the AllocateVolume Service to a specified email address. When using this plug-in, youspecify the address for the recipient, a subject line and the body of the emailwhich can consists of a predefined message or the output from a previousstep. You also have the ability to specify the encoding for the formatting ofthe email.

Details regarding the email sender are defined in the SMTP server settings.Before using the Email Notification Plug-in to send an email, you need to


specify the correct email details from the E-Mail settings, accessed throughthe System Settings available from the Administration tab.

To generate an email:

1. Insert the Email Notification Plug-in step at the point in the flow after thestep that has the information for the email notification.

2. Draw connectors between the steps to define the flow of execution.3. Click on the Email Notification Plug-in step and enter the appropriate

values for the input properties specifying the recipients address,encoding and subject.

4. In the Body field of the Email Notification Plug-in, enter the key for theoutput property in the plug-in step that is generating the content of theemail.

In some cases, you may want to send some output that is not in the defaultJSON format which you must first convert before sending the email. Toaccomplish this, you can either use one of the following supplied plug-ins:• JavaScript Plug-in -- This plug-in can treat JSON input data as an object

that can then be converted through a JavaScript script to whatever formatis required.

• File Adapter Plug-in -- This plug-in can fetch values from JSON input.

For more details on how to generate an email notification, see the step-by-step directions provided in Example of creating a new plug-in on page 112.

Example of creating a new plug-inThis example describes the process of customizing a service template with anew plug-in that maps the serial number and device ID of a provisionedvolume.

During this example, you will complete the following steps:• Make a copy of an existing service template.• Create a script based plug-in that performs the LDEV mapping.• Add the newly create plug-in and an adapter plug-in as steps in the service

template, establish the flow of execution, and provide the relevant inputproperty values.

• Build and release the service template with the newly created plug-in.

Note: You must have Develop role authority to access the features describedin this example. Although the values in the template are based on the bestpractices, the values you set may differ depending on the specific needs ofyour operating environment. For instance, the plug-in created in this exampleis specifically designed for the AIX operating environment, though it mightalso work in a Linux or Solaris environment.


To begin this example, you must first access the Service Builder Home screenby choosing Service Builder from the Tools pull-down menu. The ServiceBuilder Home screen provides all of the options for creating and managingservice templates and their associated plug-ins.

Making a copy of an existing service template

Perform the following steps to create a copy of an existing service templatethat you can then edit to include the newly created plug-in.1. From the Released tab of the Service Builder Home screen, select and

highlight the template to copy either from the Card or Table view. For thepurpose of this example, please select the "Allocate Volumes for OracleDatabase" service template.

2. Click the Copy and Edit button to access the Copy Service Templatedialog.

3. In the Copy Service Template dialog, enter the basic information for theservice template, as shown in the following table:

Table 28 Copy Service Template Parameters

Parameters Description

Key Name: * Specifies the ID for the copied service template. For the purpose ofthis example, enter a unique ID such as "PluginExample".

Version * This is the version number of the service template. This shouldalready be filled in for the copied service template.

Vendor ID: * Enter some information that identifies your company or organization.

Display Name: * Name assigned to the copied version of the service template. Thisshould already be filled in for the copied service template.

Vendor Name: Vendor name for the copied service template.

Description: Enter a short description for the copied service template.

Tags: Tag category associated with the service template. The "Add NewStorage" and "Oracle" tags should already be selected for the copiedservice template.

4. Click OK and the new service template is created with the modifieddetails. The components (plug-ins and possibly other service templates)associated with the copied template are shown from the Flow tab of theService Builder Edit screen.

Notice that a step has already been included and added to the Flow view forthe plug-in that was included in the original service template that you copied.If you click on this plug-in step, you can examine the input and outputproperties associated with this existing plug-in.

Creating a script based plug-in

After you have made a copy of the service template, you can begin makingthe necessary modifications from the Service Builder Edit screen to createyour new plug-in.


In this part of the example, you will be relying on a prepared shell script thatmakes use of the cfgmgr and iscfg commands to derive the LDEV ID andstorage serial number for the provisioned volume. The content of the shellscript is shown here:. . . . . . . . . . . . . . . . . . . . . . targetHostname=`/usr/bin/hostnameècho "HostName:${targetHostname}"

if [ $# -ne 0 ] ; then returnCode=$PLUGIN_INSUFFICIENT_PARAMETERS echo $STR_ERR_MSG_MAP$ERR_MSG_MISSING_PARAM_COUNT echo ${INF_FINISH}$returnCode exit $returnCodefi

command="/usr/sbin/cfgmgr"if [ ! -x ${command} ] ; then returnCode=$COMMAND_NOT_FOUND_ERROR echo $STR_ERR_MSG_MAP$ERR_MSG_COMMAND_NOT_FOUND$command echo ${INF_FINISH}$returnCode exit $returnCodefi

echo "Command:${command}"${command}> result.log 2>&1returnValue=$?if [ -f result.log ] ; then ${BIN_PATH}cat result.log ${BIN_PATH}rm -f result.log> /dev/null 2>&1fiecho "CommandExitCode:$returnValue"

if [ $returnValue -ne 0 ] ; then returnCode=$OTHER_ERROR echo ${STR_ERR_MSG_MAP}${ERR_FIND_DEVICE}fi

echo ${INF_FINISH}$returnCode. . . . . . . . . . . . . . . . . . . . . . . Follow these steps to create a new plug-in that calls the script to perform theLDEV mapping functions:1. Click on the Close button to return to the Service Builder Home screen

where you can begin creating the new plug-in.2. Choose the Create Plug-in option from the Custom Plug-in pull-down

menu. The Create Custom Plug-in dialog box appears.3. From the General tab of the In the Create Custom Plug-in dialog box,

enter the appropriate details for the plug-in, as shown in the followingtable:


Table 29 Create/Edit Custom Plug-in General Tab

Tab Subfield Description

General Key Name * The key name for the plug-in (up to 64characters). The combination of the Key Nameand Vendor ID cannot exceed 115 characters.For the purpose of this example, enter"PluginExample".

Version * The version number of the plug-in. For moredetails about versioning, see Managing versionson page 153.

Vendor ID * The vendor ID of the plug-in (up to 64characters). The combination of the ID andVendor ID cannot exceed 115 characters.

Enter whatever vendor ID is appropriate for yourparticular organization.

Display Name The name of the plug-in (up to 64 characters).

For the purpose of this example, enter"PluginExample".

Vendor Name The vendor name of the plug-in (up to 64characters). You can enter a name to identifyyour company or organization, though thisparameter is optional.

Description A brief description of the plug-in (up to 1,024characters).

For this example, enter something like "Performmapping of LDEV functions for the target host".

Tags The assigned Tag category for the plug-in. Clickon the plus sign to add tag categories for theplug-in.

Tags are already assigned based on the originaltemplate. If you like, click on the plus sign toadd tag categories that determine under whichproperty groups this plug-in is categorized.

Icon Specifies the icon graphic (a 48 pixels x 48pixels PNG file) associated with the plug-in.

You have the option of specifying some othericon if you like.

4. From the Property tab, choose the Input Property option from the Addpull-down menu to access the Specify Input Property for Custom Plug-indialog. To extract the serial number and volume ID information from theadapter, you need to specify two input properties for the plug-in asshown in the following table:

Table 30 Create/Edit Custom Plug-in Property Tab


Key: * Enter a key value for each input property as follows:



storageSystemSerialNumber

deviceId

Display Name: * Enter a name for each of the input properties as follows:

Storage Serial Number

LDEV ID

Description: Enter a description for the input properties as follows:

Specifies a serial number for the volume.

Species a device ID for the target volume.

Required: * Check the Required box when creating both input properties toindicate that the input property is required to run the service.

Default Value You can leave this value blank since we are deriving the values fromthe script.

5. Provide the relevant details for each of the required input propertiesshown in the table and then click OK. When done, you are returned tothe Create Custom Plug-in dialog where you can see that the inputproperties you created are now included in the input property listing.

6. From the Remote Command tab of the Create Custom Plug-in dialog box,click Add Platform to specify your particular OS environment (AIX for thisexample). Enter the relevant details as instructed in the following table:

Table 31 Create/Edit Custom Plug-in Remote Connection Tab


Credential Type Specifies the credential type required for the plug-in.

Select Shared agentless setting, if you want to use the credentialinformation in the agentless remote connections view under the HADAdministration tab when the service is executed. Shared agentlesssetting is the default Credential Type.

The following reserved plug-in property is automatically set for theShared agentless setting credential type:

plugin.destinationHost Enter the target of an operation by IPv4address, IPv6 address, or host name (up to 256 characters).

Select Service input property to use the credential information as aninput property.

The following reserved plug-in properties are automatically set forthe Service input property credential type:


Enter the target of an operation by IPv4 address, IPv6 address,or host name (up to 256 characters).

• plugin.account

Enter the user ID for logging in to the target host (up to 256characters).



• plugin.password

Enter the password for logging in to the target host (up to 256characters).


Enter the password of the root account used for logging in to atarget host in a Linux environment (up to 245 characters). If thetarget is host is running the Windows, this property is ignored.

Character Set AutoJudgement (SSH)

Character Set Auto Judgment (SSH) applies to UNIX operatingsystems. If enabled, executes the script using the default localeofthe user. If disabled, scripts are executed with the LC_ALL=Clocale. Default is enabled. Make sure this option is enabled for thisexample.

For more details on Character Set Auto Judgement, see:Localesettings for plug-ins on page 186.

Execute with rootprivileges (SSH)


For this example, do not select this option.

Import Settings: Enter the OS platform. For the purpose of this example, you shouldbe using AIX.

Execution Method: Choose the Script name button to indicate that the commands are tobe derived from a script.

CLI Command:* Enter "verify_LDEV.sh.zip" to specify the command used to executethe script file. Click on Insert All Input Properties to extract all of theinput properties that have been created for the plug-in into the CLICommand field. You should see the input properties you created "?dna_StorageSerialNumber?" and "?dna_deviceID?" along with thedefault input property "?dna_plugin.destination.Host?" that wasalready defined for the plug-in, and which you need to remove fromthe list.

Type in: Choose the Attachment button.

File Click the Browse button. Enter the location and name of the scriptfile for the plug-in and then click Open. For the purpose of thisexample, a script file called verify_LDEV.sh.zip has already beencreated and is included with Hitachi Automation Director.

Mapping definition ofOutput Properties

You can leave this blank.

7. To specify the proper credentials required to execute the remotecommand script for the new plug-in, you can determine the credentialsthat are needed by consulting Agentless Remote Connections option fromthe Administration tab in the main Hitachi Automation Director userinterface. If the credentials are already defined, you can choose theShared agentless setting option for the Credential Type. If the credentialsare not defined, you can choose the Service Input property option andthe specified credential input properties are used to query the user at thetime the service is run for the appropriate credentials.


Appending the plug-ins and establishing the step flow

After creating the new plug-in, you need to append the File Adapter plug-inand the newly created PluginExample plug-in as steps and establish the flowof execution for the service template. The AllocationStep Plug-in (already inthe flow from the copied template) collects and outputs the storageinformation, the File Adapter plug-in extracts the LDEV ID and serial numbersand outputs this information to the Verify LDEV plug-in which captures thevolume mapping details for subsequent examination of the provisionedvolumes.1. Locate the FileAdapterPlugin plugin, shown in the list under the Released

tab, and drag it after the existing AllocationStep step in the flow area ofthe screen. The Create Step Attributes dialog box appears where you canenter some relevant step details. Click OK to accept the default values.

2. Click on the Developing tab, locate the newly created plug-in(PluginExample), and drag it after the other two plug-ins in the flow areaof the screen. Once again, the Create Step Attributes dialog appearswhere you can enter some details for the plug-in step. Click OK to acceptthe default values.

3. Specify the order of execution for the newly added plug-in steps byclicking the dot on the right of the AllocationStep plug-in icon and thendragging the arrow over the FileAdapter icon. Draw a similar arrowbetween the FileAdapterPlugin step and the PluginExample step. Thesearrows show the direction in which the plug-in steps are processed bythe service template when the service is executed.

4. Click on the FileAdapterPlugin step and you can see that there are someinput properties that are flagged with warning icons indicating somemissing values.

5. For each of the missing step input values, enter the appropriate values asshown in the following table:

Table 32 Step Input properties for FileAdapterPlugin

Step Input Property Value

Input File Identifies the input file.

AllocationStep: Task Results Raw DataLDEVs

Input Key Identifies the input key.

values

Output Key Identifies the output key.

storageSystemSerialNumber,deviceId

The value for the first input property is the input property from theAllocationStep plug-in which you can derive by clicking on the edit pencilin the value field and accessing the Specify Component Input PropertyMapping Parameters dialog box that lists properties for all steps in the


flow. The output value in the Output tab associated with thestorageSystemSerialNumber and DeviceId are mapped to theresult.output1 and output2 output properties.

6. Click on the PluginExample plug-in step to see the input properties thatrequire values as indicated by the accompanying warning icons. For eachof the missing step input values, enter the appropriate values as shownin the following table:

Table 33 Step Input properties for PluginExample

Step Input Property Value

Destination host For this credential setting, check the GUIVisibility checkbox to have this valuesupplied by the user when submitting andexecuting the service.

Storage Serial Number Specifies the source of the storage serialnumber.

OUTPUT1

LDEV ID Specifies the source of the device ID.

OUTPUT2

User ID For this credential setting, check the GUIVisibility checkbox to have this valuesupplied by the user when submitting andexecuting the service.

Password For this credential setting, check the GUIVisibility checkbox to have this valuesupplied by the user when submitting andexecuting the service.

Superuser password For this credential setting, check the GUIVisibility checkbox to have this valuesupplied by the user when submitting andexecuting the service.

7. As a final step, click on the AllocationStep plug-in step in the flow, clickon the output properties icon, choose the Task Results Raw Data LDEVsoutput property, then click the edit pencil in the Value field to access theassociated Specify Component Output Property Mapping Parametersdialog box.

Note: For this example to work, you must change the Setting Method to theNone option in order to build the service template with your new plug-in. Inaddition, to see the values, you must change the visibility for this propertyfrom Private to Display Details.

Building, testing and releasing the plug-in

After creating and adding the required plug-ins, you can build the servicetemplate and then release it when all the bugs are ironed out.1. Click on the Build tab and then click OK to build the service template with

the added plug-ins. The Build/Release Result dialog appears showing any


errors that may have occurred during the building of the servicetemplate. Continue to troubleshoot any errors until the build completessuccessfully then click Close to exit the Build/Release Result dialog box.The Perform Debugging dialog appears.

2. From the Perform Debugging dialog, you can perform any debugging andthen click OK when you are done.

3. At this point, you are going to want to make sure that the servicetemplate with the newly created plug-in are functioning correctly. Inorder to accomplish this, you need to return to the main HitachiAutomation Director GUI where you can create a request and submit theservice request for the service template.

4. On the Services tab, select the PluginExample service in Developingstatus and click Create Request.

5. In the Submit Service Request window, in the Settings pane, retain thevalues for the Volume Settings. Enter the following information:


Host Settings

Target Hosts The number of target hosts Single Host

Host Detail The host name or IP address from

Device Manager

Enter the host name or

IP address

Task Settings

Task Name The name of the task PluginExample

Description A brief description of the task A task to perform LDEV

mapping.

Schedule Type The time when the task executes Immediate

6. Click Submit.7. In the Submit Service confirmation dialog box, click OK.8. On the Tasks tab, in the Debug view, select the "PluginExample" task and

click Show Details to view the task summary, details, result, log, andnotes.

9. After testing the service template to see that the new plug-in isfunctioning correctly and is properly extracting the LDEV information, youcan return to the Service Builder interface and click on the Release tab tomake the template and plug-in available for users to submit.

Related concepts

• Adding plug-in input properties on page 99• Adding plug-in output properties on page 102

Related tasks

• Creating a plug-in on page 93• Setting remote commands in plug-ins on page 103


• Setting environment variables on page 104• Adding output filters on page 105



6Building, debugging and releasingAfter specifying the steps and establishing the flow for a new or modifiedservice template, you need to access the Debug tab to generate a build. Oncea build is successfully completed, you can use the built-in debugger to runthrough the steps and correct any problems with the execution flow orproperty mapping. When the service template is functioning properly, youcan release it into the operating environment where it can then be used tocreate services.

The following sections provide the steps to debug and release servicetemplates and plug-ins.

□ Debug and release workflow

□ Building a service template

□ Build/Release Result dialog box

□ Running the debugger

□ Perform Debugging dialog box

□ Editing service and request entries while debugging

□ Working with the debugger

□ Examining debug details

□ Managing tasks during debugging

□ Checking the property mapping of a plug-in

□ Edit Step Property dialog box

□ Importing property values

Building, debugging and releasing 123Hitachi Automation Director Service Builder User Guide

□ Exporting property values

□ Releasing a service template

124 Building, debugging and releasingHitachi Automation Director Service Builder User Guide

Debug and release workflowAfter creating or modifying a service template, you can build and then debugthe service according to the following phases:

Phase 1 - Preparing• Prior to building the service template, make sure that the service template

details have been specified, that the appropriate plug-in steps arearranged in the order of their execution, and that values for the input andoutput properties have been properly defined.

Phase 2 - Building• Initiate the building of the service template by clicking on the Debug tab.• Observe the information returned by the Build/Release dialog to see if any

errors are generated.• If there are errors, hover the cursor over the error message to see details

pertaining to the error.• Make whatever corrections are necessary and continue to rebuild the

service template until it completes building successfully.

Phase 3 - Debugging• Once a service template has been successfully built, you can perform any

necessary debugging.• Correct any errors and continue re-building the service template until all

errors are resolved.• After all issues have been resolved, conduct an operation test by adding

and executing the service in the development environment.

Phase 4 - Releasing• When the service template is functioning properly and there are no further

issues, you can release the service template. A service template must bein Released status in order to submit the service template to the operatingenvironment.

• Create a service from the released service template.• Check the execution results of the task. If any issues are identified, amend

the affected service template or plug-in and repeat the debug process.

The following figure shows the typical steps you follow when debugging,testing and releasing a service template:


Building a service templateAfter a service template is created and is in the Developing status, the nextstep is to build and debug the service template and its related plug-ins.

Here are the steps for initiating the building and debugging of a servicetemplate:

Before you beginA service template in the Developing state must exist.


Procedure

1. From the Service Builder Edit screen, click the Debug tab.After confirming your intention to perform the debug, the Build/Release Results dialog appears and the service template undergoes thebuild process. If any errors are generated, error icons and error linkbuttons are displayed and warning icons appear when you have failed toenter a required property.

2. Make the necessary corrections where indications appear or adjustmentsto the operation as needed.

3. Repeat the build process until the service template is free of errors.

Result

Once you build a service template, the following processing occurs:• Services added from the debug version of the service template will be

deleted, and tasks executed from the service will be archived.• The debug task executed from the debug version of the service template

will be deleted.• The debug version of the imported service template will be deleted and

then re-imported.

Upon successful completion of the build process, the Perform Debuggingdialog appears where you can check the flow of execution and make anyadjustments that are necessary before releasing the service template.

Next steps

• Access the debugger to check the flow of steps and to make any requiredmodifications.

• Create services and tasks based on the debug configuration of the servicetemplate. For more information on creating services, see the HitachiCommand Suite Automation Director User Guide.

• Provided the service template works properly and has passed the buildprocess, proceed to release the service template. For more information onreleasing a service template, see Releasing a service template onpage 145.

Related references

• Build/Release Result dialog box on page 127

Build/Release Result dialog boxYou initially check the results when building and releasing a service templatefrom the Build/Release Result dialog box.


The following table describes the Build/Release Result dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.


Table 34 Build/Release Result dialog box


Results Summary Build/ReleaseResult

Displays the results of the service template build.

Status Displays the current status for the service template.

Status Details Type Indicates the type of status message.

Message ID Shows the message ID.


Message Provides the content of the status message.

After the service template builds successfully, you can initiate the debuggingprocess from the Perform Debugging dialog.

Related tasks

• Building a service template on page 126• Releasing a service template on page 145

Running the debuggerOnce you have successfully built a service template, you can run the built-indebugger by clicking OK from the Perform Debugging dialog box. Beforeaccessing the debug interface, you need to specify the appropriate details forthe debug service and tasks from the Perform Debugging dialog box. You canalso examine and edit the service properties or make changes from theCreate Service or Create Request windows.

You can use the built-in debugger to make sure the plug-ins and flow of aservice template are working as intended. During a debugging session, youcan:• Control the execution of steps in the flow of a service template to isolate

and correct any issues.• Execute and manage debug tasks while checking the flow transitions at all

hierarchical levels.• Confirm that property mapping is set correctly and that the conditions for

executing subsequent steps flow in the intended way.• Modify input and output properties for currently running tasks.• Set breakpoints to have the processing start from or end before a specified

step in the flow.


• Skip the processing of specified plug-ins (script/command, repeat, wait foruser response) so that it appears to the next step as though the process ofthe plug-in has executed, thus allowing the flow to continue according tothe execution condition of the next step.

• Displays the results of a repeated-execution flow (for each executiontime).

• Consult a running log of executing tasks.• Edit entries in the config and submit windows to simulate processing of the

service template.• If you detect an issue with a plug-in, you can assign an arbitrary property

value or return value to the plug-in and execute it again. This allows youto see the effect a given property value or return value has on the plug-inprocessing and flow transitions.

You can debug a service template any number of times.

When you debug a service template, Automation Director creates a debugservice and debug task.

Debug service

A debug service is a service that is generated and executed when debugginga service template. One debug service is generated per service template.When you debug a service template that has already been through a debugprocess, Automation Director deletes the existing debug service and createsa new one. Note that debug services appear in the Service Name column inthe Debug-Tasks view, but do not appear in the Services window.

Debug task

A debug task is a task generated for a debug service when debugging aservice template. When you debug a service template that has already beenthrough a debug process, Automation Director deletes the existing debugtask and creates a new one. Debug tasks appear in the service templateDebugging view and Debug-Tasks view. Only users assigned the Admin orDevelop role can view and work with debug tasks. Note that debug tasks donot appear in the task summary.

Note: You cannot edit the definition of a service template or plug-in from thedebugger view. Instead, when a defect is detected during debugging, youneed to stop debugging and return to the Editor window to make thenecessary correction.

Limitations on concurrent debugging operations and associated tasks

A maximum of one debug service and one debug task can be generated forthe same service template, and the same service template cannot bedebugged by multiple users at the same time. The same service templatecannot be edited by multiple users at the same time (because the last


operation to save the template takes precedence, and thus multiple problemscannot be fixed in parallel).

If a debug service and a debug task already exist for a service template thatis being debugged, when you execute the build or release operation, thedebug service and debug task are deleted automatically, and a new debugservice and debug task are created when debugging re-starts.

After the debug task finishes, if you perform debugging again without firstclosing the Debug view, the created debug service and the finished debugtask are deleted automatically and a new debug service and debug task aregenerated.

Before you begin

Follow these steps to initiate a debugging session:• A Developing version of the service template to be debugged must have

successfully completed the build process.

Procedure

1. Enter the appropriate details from the Perform Debugging dialog.2. For the Service Name field, accept the original name appended with

[DEBUG] or specify some other name of your choosing.3. Examine, and if necessary, modify the relevant details for the other

service and task related fields4. For the Task Log Level, specify the level of details that are to be stored

in the task log file.5. If necessary, you can supply the values that would normally be specified

by the user who is configuring and submitting the service by clicking onthe Edit pull-down menu and either selecting From Create ServiceWindow or From Create Request Window.

6. Click OK to access the debugger user interface.

ResultThe debug interface is accessed where you can begin the debugging process.

Related references

• Perform Debugging dialog box on page 130

Perform Debugging dialog boxAfter successfully building a service template, you can specify the relevantdetails for the debugging session through the Perform Debugging dialog box.

The following table describes the Perform Debugging dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.



Table 35 Perform Debugging dialog box


Service Name: * - Specifies the name assigned to the servicetemplate. The debug version has "[DEBUG]appended to the name.

Tags: - Specifies the tag groups with which the service isassociated.

Task Name: - Specifies the assigned task name. The debugversion has "[DEBUG] appended to the name.

Task Description: - Provides an optional short description for the task.

Service Group:* - Specifies the service group with which the task isassociated. Since the target device operated by thedebug task affects the agentless connection-destination definition, a service group must bespecified.

Task Log Level: - Specifies the level of information that is output tothe task log during the debug process.• Severe• Information• Fine• Finer• Debug (default)

Properties

The followingdetails are providedfor the listing ofproperties:• Display Name• Key Name• Value• Description• Scope

Edit Allows you to edit the service from the Modify andSubmit user's perspective.• From Create Service Window• From Create Request Window

See: Editing service and request entries whiledebugging on page 132 for details.

Restore Default Restores the default values of properties whenbuilding the Service Template.

Import Imports a properties file. This can be useful forimporting a properties file with known settings fromanother service template or that was saved at somepoint for the current service template that is beingdebugged.

Export Exports a properties file. This can be useful forsaving the properties for a given service templateto a file before making any changes, thus allowingthe original property settings to be imported ifnecessary at some point during the debuggingprocess.

Related tasks

• Running the debugger on page 128• Working with the debugger on page 133


Editing service and request entries while debuggingBesides specifying the service and task details for the debugging from thePerform Debugging dialog box, you can also examine and edit the serviceproperties to supply the config and submit values from the Create Service orCreate Request windows.

The properties section shows a listing of service properties implemented forthe service template. It shows the Display Name, Key Name, Value,Description and Scope.

Before proceeding to the debugger interface, you often need to first specifythe values that would normally be supplied by the Modify and Submit userswhen running a service. The following messages indicate that you need tosupply values for the specified properties before continuing with thedebugging session:

Information is not complete. Please edit properties from [CreateService Window]

Information is not complete. Please edit properties form [CreateRequest Window]

To edit the properties from either the Create Service or Create Requestwindows, follow these steps:

1. From the Properties section of the Perform Debugging dialog, click Edit.2. Choose From Create Service Window or From Create Request Window

depending on which interface you want to edit.3. Click on the category of settings (marked in red and with a warning (!)

icon) and enter the missing values for all fields that are marked with ared asterisk (*), until the section turns blue indicating that all requiredfields have been filled in. Then click OK.

4. After specifying the service and task details for the debug session, andsupplying any of the required values for the properties, click OK toaccess the debugger interface where you can begin debugging theservice template.

While editing the service properties, you can also click on the Import buttonto restore properties from a previous debugging session or the Export buttonto save the properties from the current session. In some cases, you mightwant to use this import capability to save time by loading all of the propertyvalues at one time, or possibly to restore property values that you previouslyexported. You can also click Restore Default to restore all default values.


Working with the debuggerAfter successfully building a service template in preparation for its release,and supplying the required service and task details from the PerformDebugging dialog box, you can use the Debugger interface to debug theservice template.

The Service Builder Debug screen has the following operational panels:• Debugger -- This area allows you to control debug operations associated

with the currently selected step.• Flow -- Shows the placement and flow of steps associated with the service

template.• Flow Tree -- Shows the hierarchical flow of steps.• Task Log -- Selecting this tab shows a listing of task entries. You can

refresh the listing to see the current state of executed tasks or downloadthe listing to a file for subsequent reference.

• Service Properties -- Selecting this tab shows the Display Name of theservice properties associated with the service template along with itsassigned Key Name and Value.

• Break Points -- Selecting this tab shows any currently set breakpointsalong with their Flow Hierarchy and Display Name. You can remove allcurrently set breakpoints by clicking the Remove All Break Points.

Debugger

The debugger provides a convenient method of controlling the execution oftasks for a debug operation. The following options are provided:

• Input Response -- Requests an input response for a waiting task.

• (Retry Debug) -- Retries the debugging as follows:○ Retry Debug -- Retries the debugging process from the beginning of the

service template.○ Retry the Task Starting from the Failed Step -- Retries the task

beginning from the last failed step.○ Retry the Task Starting from the Step after the Failed Step -- Retries the

task just after the last failed step.

• (Resume Debug Operation) -- Resumes the debugging operation fromthe last failed step.

• (Interrupt Debug Operation) -- Interrupts the debug operation at thecurrent task.


• (Forcibly Stop Debug Operation) -- Forcibly stops the debug operationat the current task.

• (Execution of Step Into) -- Runs the task to the next interruptible step.

• (Execution of Step Over) -- Runs the task to the first interruptible pointin the next step.

• (Execution of Step Return) -- Runs the task to the first interruptiblepoint in the upper hierarchy.

• (Set/Unset Breakpoint) -- Sets (or removes) a breakpoint that causesthe execution tasks to pause after the specified step.

Note: A system generated breakpoint is set automatically by the systemwhen choosing the step-into, step-over, or step-return option to control theexecution of tasks during a debug session.

Debug Modes:• Run plugin in execution mode -- Runs the plug-in in execution mode.• Run plugin in dry-run mode -- Runs the plug-in in dry-run mode.

Task Status:

The status for a debug task can be one of the following:

• Waiting -- Indicates that the task is waiting for execution.

• Interrupted -- Indicates that the execution of the task has beeninterrupted by the step execution feature.

• In Progress -- Indicates that the debug task is currently in progress.

• Waiting for Input -- Indicates that the task is waiting for user input.

• In Progress (with Error) -- Indicates that the task has detected aprocessing error.

• In Progress (Terminating) -- Indicates that the task has received a stopoperation or forcibly stop operation instruction, and is terminating theprocessing.

• Completed -- Indicates that the execution of the task has completedsuccessfully.


• Failed -- Indicates that the execution of the debug task has failed.

Conditional Expressions in a Next Step Flow

When using conditional expressions in a next step flow, the line indicating theflow of execution shows the arrow conditional expression ( ) icon indicatingits current status:• Green Icon -- TRUE• Dark Grey Icon -- FALSE• Dark Grey Icon -- NOT YET (not yet executed)

By mousing over the arrow with the conditional expression icon attached, thearrow condition name, status, type, and description are displayed as a tooltip.

Step Information

Step information provides details for a given step as follows:• ID -- Shows the name of the currently selected step.• Display Name -- Shows the display name of the step.• Status -- Shows the status of the debug operation for the currently

selected step.

Step Properties

The Step Properties view shows the input and output properties associatedwith a given step as well as any variables that may be used along with thecurrent values.

The following icons indicate the type of property or variable:

• Indicates an Output property

• Indicates an Input property

• Indicates a Variable

You can edit the property values directly by clicking on the pencil icon thataccesses the Edit Step Property dialog box where you can make anynecessary changes.

While examining the step property values, you can click on the Edit buttonand select either From Create Service Window or From Create RequestWindow to specify the values for the properties normally supplied by theModify and Submit users.

You can also click on the Import or Export buttons to save or retrieveproperty values from a specified file.


The Task Log, Service Properties, and Break Point tabs provide additionallyuseful information about the current debugging session. Please see: Examining debug details on page 136 for complete details.

Related references

• Examining debug details on page 136

Examining debug detailsWhile debugging a service template, you can examine details regarding tasksthat have been executed, current service properties, and breakpoints thathave been set.

During a debug session, you can access relevant details from the followingtabs:

Task Log

By clicking the Task Log tab, you can access a listing of tasks that have beenexecuted during the current debugging session. To update the task listingwith the latest task activity, click Refresh or you can check the RefreshAutomatically check box to have the task listing automatically updated.

If you would like to keep a record of the executed tasks for a debug session,click Download and then specify the location for the log file. You specify thelevel of detail for a log file when starting the debugger.

Service Properties

By clicking the Service Properties tab, you can view all of the serviceproperties associated with the service template. This is useful for checkingthe mapping between the input and output properties and variablesassociated with a given step and the service properties for a servicetemplate. The following fields are provided:• Display Name -- Display name assigned to the service property.• Key Name -- Key name assigned to the service property.• Value -- Value currently assigned to the selected service property.

Break Points

From the Break Points tab, you can see all of the breakpoints that have beenset for the current debugging session. The following details are shown:• Flow Hierarchy -- Shows the hierarchy of flow usually indicated by a

backslash (/).• Display Name -- Shows the display name assigned to the step.

You can set a breakpoint to have the execution flow halted at a particularstep, by selecting the step and then clicking on the breakpoint icon control.


When no longer needed, remove all currently set breakpoints by clickingRemove All Break Points.

Managing tasks during debuggingYou can control the execution and flow of tasks during the debuggingprocess.

For more information on the options available from the Debugger view, seethe following topics:

• Controlling the processing flow of debug tasks on page 137• Handling interruptions of debug tasks on page 138• Controlling the display of tasks in the Task List on page 139

Controlling the processing flow of debug tasksWhen debugging a service template, you can control how the flow of tasksare executed

The following describes the general procedure for debugging a servicetemplate:


Procedure

1. If you do not expect any issues when executing the plug-ins in theservice template, the first step of the debug process is to execute thedebug task without pausing between steps. In the Debug view or theservice template debugging view, make sure that there are no issueswith the flow transitions or the processing of the plug-ins. If the servicetemplate contains plug-ins that you would prefer not to execute at thistime, skip this step and move on directly to step 2.

2. If you identify an issue with a flow transition or the processing of a plug-in, execute the steps in the debug task individually to identify the preciselocation and nature of the problem. You can also test the behavior of theplug-ins by assigning unexpected values to input and output properties.• Click on the Step Into icon to execute the currently selected step.• Click on the Step Over icon to execute the next step.• Click on the Step Return icon to execute the step in the upper flow

after completing the execution of steps in the current flow.• Click the debug arrow, and choose Retry the Task Starting from

the Failed Step to have the debugging process start again from thefailed step. By retrying from a failed step, you can resume the debugtask with the same task ID and the original property values. You canuse this approach when the cause of the failure has been resolved. Forexample, a step that fails due to a temporary problem with the


network can be retried when the network connection is availableagain.

• Click the debug arrow, and choose Retry the Task Starting fromthe Step after the Failed Step to have the debugging process startagain from the step after the failed step. By retrying from the stepafter the failed step, you can resume the debug task with the sametask ID and the original property values. This approach is appropriatein situations where there is no need to execute the failed step. Whenyou retry a task from the step after the failed step, processing of thetask continues as if the failed step had ended normally. You can usethis approach when you encounter an issue in a step, but want tocontinue executing the debug task and deal with the issue later.

Handling interruptions of debug tasksUnder certain circumstances, the execution of tasks may be interrupted orterminated in unexpected ways during a debugging session.

The steps in the debug task appear in the Flow view of the service templatedebugging view, in the order in which they are executed. The icon of the stepindicates the status of the step. You should be aware of how tasks areaffected when the debugging process is interrupted.

Handling of debug tasks when the Automation Director server stops

If the Automation Director server stops during debugging, the debug taskthat is running is forcibly stopped. Therefore, before stopping the AutomationDirector server, wait for all debug tasks that are still running (not yetcompleted) to finish or stop the debug tasks. This is the same as thehandling of tasks generated when normal services are executed.

Handling of debug tasks when a failover of the cluster occurs

When a cluster failover (switchover of the system) occurs during debugging,the debug task is forcibly stopped. This is the same as the handling of tasksgenerated when normal services are executed.

Handling of debug tasks when the user logs out during debugging

When performing an explicit operation for logging out during debugging, aconfirmation dialog box is displayed asking for confirmation before loggingout. If you choose to log out, the debug task is forcibly stopped.

Handling of debug tasks when the browser is closed

When the browser is closed during debugging, the debug task continuesrunning as-is. If the task is being executed step-by-step, the task remains atthe step where it stopped. To stop the debug task, you need to log in againand then stop the debug task from the Debug Task List view.


Controlling the display of tasks in the Task ListWhile debugging tasks, you can specify how the listing of tasks are managedin the Task List.

You can specify the period of time to retain tasks before they are archivedand no longer shown in the Task List. Once tasks have been archived (andbecome history entries), the detailed information about the tasks is deleted,and therefore cannot be returned to the Tasks List view again.

You can have the archival of tasks performed automatically by specifying theappropriate value through one of the following properties:

Property key Description Minimum valueMaximumvalue

Default

tasklist.autoarchive.taskRemainingPeriod

Specifies the period,expressed in days, toretain completed tasks inthe task list. When thespecified period haspassed, the tasks areautomatically archived.The automatic archivingof tasks takes place oncea day according to thetime specified throughthetasklist.autoarchive.executeTime property.

1 90 7

tasklist.debugger.autodelete.taskRemainingPeriod

Specifies the period,expressed in days,before debug tasks areautomatically deleted.

1 90 7

tasklist.autoarchive.maxTasks

Specifies the maximumcombined number oftasks and debug tasks toretain in the Tasks List.When the maximumnumber of tasks in theTasks List is exceeded,the excess tasks areautomatically archived,starting from those withthe oldest end date andtime. The archived tasksare managed as historyentries. Debug tasks aredeleted automaticallyand are not retained inhistory. Automatic

100 5000 5000


Property key Description Minimum valueMaximumvalue

Default

archiving and automaticdeletion take place oncea day at the timespecified by thetasklist.autoarchive.executeTime property.

When there are moretasks than the specifiedvalue, attempting toexecute a new serviceresults in a "maximumexceeded" error, and notask is generated.Periodic tasks that havebeen executed once arenot subject to this limitand can generate newtasks. Therefore, toallow new services to beexecuted, you mustestimate the number ofexecutions that takeplace per day in order tospecify thetasklist.autoarchive.taskRemainingPeriodproperty.

Checking the property mapping of a plug-inWhen debugging a service template, you can control how the flow of tasksare executed

The following describes the general procedure for checking the propertymapping of a plug-in.


Procedure

1. In the Flow view, select the step whose plug-in property values youwant to check. The Debug view displays the input properties and outputproperties of the step you selected.

2. Click the Service Properties tab at the bottom of the service templatedebugging view. The values of the service properties are displayed.

3. In the Debugger view, review the contents of the Step Properties forthe plug-in property you want to check, and identify the service propertyto which it is mapped.


4. In the Key Name column of the Service Properties tab, find theservice property you identified in step 3.

5. In the Debugger view and the Service Properties view, make surethat the same value appears in the Value columns for the plug-inproperty and the mapped service property. If a service property is notmapped to the intended plug-in property or the values of the plug-inproperty and the service property differ, fix the problem in the servicetemplate editing view by clicking on the pencil icon and then supplyingthe correct value through the Edit Step Property dialog box. You canalso change the values of the plug-in properties. By doing so, you cantest the plug-in processing when property mapping is configuredcorrectly to see how the processing of subsequent steps and the flowtransitions change with an assortment of values.

Related references

• Edit Step Property dialog box on page 141

Edit Step Property dialog boxDuring the debugging process, you can edit a step property if necessary.

The following table describes the Edit Step Property dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.


Table 36 Edit Step Property dialog box


Name: - Shows the property name.

Display Name: - Shows the display name for the property.

Description: - Shows a description for the property.

Multiline: Yes/No Indicates whether multiline value is required for theproperty.

Value * - Shows the current value for the property.

Related tasks

• Checking the property mapping of a plug-in on page 140

Importing property valuesWhile debugging a service template, you can import property values to aspecified property file.


Importing property values

Follow these steps to import property values to a specified file.

Procedure

1. From the debugger interface, click the Import button. The Import dialogbox appears requesting that you specify the name of the file where theproperty values are to be stored.

2. Enter the name of the property file, or use the browser to search for thespecified file then click OK.The property values are imported from the specified file.

When the importing has completed, notifications about the propertyvalues that have and have not been imported are temporarily displayedas follows:• Properties to which the values are applied.• Properties for which the values are not applied. These are properties

for which the attribute values cannot be changed and for which thevalues are not applied due to the property value definitions .

• Non-existent properties. These are properties that are defined in thefile but do not exist in the target service.

When importing a properties file from the debugger, (or the Config andSubmit windows), the JSON or key=value format is supported.

When accessing the import capability from the CLI, the additional formatkey@FILE=file-path is also supported.

The conditions that must be met to apply property values during animport are shown in following table.

PropertyGroupAttribute

Property Attribute

hidden paramMode visibility reference hidden readOnly

False in config false false false

False in exec false -- --

If the properties do not meet these conditions, or their are nocorresponding properties defined in the service, the values contained inthe definition file are not applied. The values are also not applied if the"value field" is not defined or is set to null.

Note: If the length of keyName exceeds the limit, the property isclassified as a property that does not exist in the service.


If an error occurs during an import, the error dialog box is displayed, andthe import is canceled thus leaving all property values unchanged. Anerror occurs when the specified file does not exist or the property filedefinitions are invalid.

Related references

• Exporting property values on page 143

Exporting property valuesWhile debugging a service template, you can export property files

While debugging, you can export property values to a property file. Thisallows you to save multiple property values in a file for subsequent reference.

Exporting property values

Follow these steps to export property values to a specified file.1. From the debugger interface, click the Export button.2. Access the browser to locate the property file or specifically enter its

name and click OK.

The property values are exported to the specified file. The property valuesare exported in the Json format and, by default, are saved to theservice_properties.json file.

Format

In the property file specified as a command argument, the property key andvalue used by the executed services can be defined in JSON, key=value, andkey@FILE=value formats.

JSON format{"properties": [ { "keyName": "property-key", "displayName" : "property-display-name" "description" : "description-of-property" "type" : "property-type" "value": "property-value" }, { "keyName": "property-key", "displayName" : "property-display-name" "description" : "description-of-property" "type" : "property-type" "value": "property-value" },...


]}Following are definition details for the JSON format:• The displayName, description and type fields are optional.• When you specify the value field, set an empty value for the property

value.• The value for the password type property can be in plain text or encrypted.

Note that the "value" field of the password type property is not exportedfor security reasons. The defined value is imported as is, and the REST APIdetermines whether it is in plain text or encrypted.

• In the definition file, define only properties for which you want to setvalues. The values of properties that are not defined in the imported fileremain unchanged. When exporting step properties, the type field is onlyoutput for the service component.

key=value format:

To specify property values for a key=value property file, use the followingformat:property-key=property-value [line break]Following are definition details of the key=value format:• Specify a property name and a property value on each line.• Lines starting with a hash mark (#) are handled as comment lines.• Lines that do not contain an equal mark "=" are handled as comment

lines.• A line break needs to be added at the end of each property setting line.• Do not add line breaks in the middle of the property name and property

value lines.• Characters are case-sensitive.• Even when a "\" is contained in strings like service and plug-in resource

files, you do not need to type "\\".• "\" is handled as a "\".• The characters at the beginning of a line up to the first equal sign (=) are

treated as a property name. Do not trim lines before and after theproperty setting line.

• The characters after the equal sign (=) after the property name, until theend of the line are treated as the property value. Do not trim lines beforeand after the property setting line.

• The end-of-line character at the end of the property file (EOF) is optional.• Empty lines (lines containing line breaks only) are ignored.• Both CR+LF and LF can be used as line breaks.• When using the property-key = [line break] format, set an empty

value for the property value.

key@FILE=file-path format


In this format, the property key is stored in the property file, and theproperty value is stored in the property value file and referenced separately.Note that this format can be used together with the key=value format in theproperty file:property-key@FILE=absolute-path-of-the-property-value-file or relative-path-from-the-property-file [line break]The definitions in the key@FILE=file-path format are the same as thekey=value format. The differences from the key=value format are as follows:• The absolute path of the property value file or the relative path from the

property file must always be specified or an error occurs.• If the specified file does not contain a property value, an error occurs.• The property value file can contain end-of-line characters. However, if a

property value file that contains an end-of-line character is specified for aproperty for which end-of-line characters must not be set, an error occurs.

Related references

• Importing property values on page 141

Releasing a service templateThe final step to complete a service template is the release process. Therelease operation changes the configuration type of a service template and itsrelated plug-ins to Released. New services and tasks can be created from aservice template in Released status.

In Released status, the service template appears in Automation Director asan available service template from which services can be created.

Note: The release operation can be performed only once.

Before you beginA service template in the Developing state that has completed the buildprocess with no errors and performs as designed.

Procedure

From the Service Builder screen, click Release.The service template undergoes the release process and its configurationtype changes to Released status.

ResultUpon successful completion of the release process, the service template isavailable under the Services tab with the Released configuration type.• The service template is removed from the Developing state and appears

under the Released tab when viewing available service templates.


• Any services created while the template was in Developing status aredeleted.

• Any tasks executed from the template while in Developing status arearchived.

• The service template appears in the Service Template list when creating anew service.

• The related plug-ins appear under the Released tab of the Componentview.

• If specified in the service definitions, a service component is created andlocated under the Service tab of the Component view.

Next steps

• Create a new service using the released service template. For moreinformation on creating services, see the Hitachi Command SuiteAutomation Director User Guide.

Related references

• Build/Release Result dialog box on page 127


7Advanced options

This module covers the other functions available in managing servicetemplates and plug-ins.

□ Editing the service template attributes

□ Edit Service Template Attributes dialog box

□ Creating property groups

□ Managing versions

Advanced options 147Hitachi Automation Director Service Builder User Guide

Editing the service template attributesYou can view and customize the details associated with a service templateand specify the custom files that affect how it is presented and scheduled forexecution from the Edit Service Template Attributes dialog.

Before you begin• The service template must be in the Released or in the Developing state.

Procedure

1. From the General tab of the Service Builder Edit screen, click the Editbutton.The Edit Service Template Attributes dialog opens.

2. Enter the information for the service template, and click OK.The Edit Service Template Attributes dialog is closed.

ResultAny changes you specify are reflected in the updated service template.

Next steps

Continue to edit the service template by selecting the plug-ins from the list,providing the input and output step properties, and establishing the flow.

Related references

• Edit Service Template Attributes dialog box on page 148

Edit Service Template Attributes dialog boxWhen editing or creating a service template, you can view and specifyadditional details for the service template.

The following table describes the dialog box fields, subfields, and field groupsfrom the Edit Service Template Attributes dialog box. A field group is acollection of fields that are related to a specific action or configuration.


Table 37 Edit Service Template Attributes dialog box


Key Name - The key name for the service template.

Version - The version of the service template.

148 Advanced optionsHitachi Automation Director Service Builder User Guide


Vendor ID - The vendor ID of the service template.

Display Name* - The name of the service template that is displayed tothe user.

Vendor Name - The vendor name of the service template.

Description - The description of the service template.

Tags - Tags associated with the service template.

AdvancedOptions

Icon An image file (48 pixels x 48 pixels) using PNGformat. A default image is provided but you canchange the icon by clicking the Change button. Youcan return to the default icon by clicking the RestoreDefault Icon button.

Custom File/Custom Filepackage

The custom files provides information that isdisplayed for the Service Details dialog and theoverview associated with the service. Click Browse toupload a file in .html, .js, .css, .swf, or .jpeg format.If for some reason, you want to delete the customfile associated with template, click Delete.

Service Details File Name Specifies the name of the file that provides theinformation for the Service Details Dialog.

Service Overview FileName

Specifies the name of the file that contains theinformation for the overview associated with theservice template that is presented to the user.

Available SchedulingOptions:

The schedule for executing the task can be:Immediate, Schedule, or Recurrence.

Available Action: You can choose to allow the user to Forcibly Stop theexecution of a service when the processing a stephangs for some reason or allow the user to Retry theprocessing of the service template from a failed step,or from the point just after the last failed step.

Fields with a asterisk (*) are required.

Related tasks

• Editing the service template attributes on page 148

Creating property groupsYou can create property groups to categorize the properties associated with aservice template.

The input and output properties of a service template can be assigned to acustom property group. If no property group is required, then the defaultreserved.defaultGroup is used. If a property group is created, the input andoutput properties are displayed according to the custom property group nameto which they are assigned.

Before you beginA service template in Developing status must exist.


Procedure

1. From the Property tab of the Service Builder Edit screen, choose theProperty Group option from the Add pull-down menu.The Create Property Group dialog appears where you can enter thedetails for the new property group.

2. Enter the relevant details for the property group and then click OK.The newly added group is added to the property list.

3. When creating properties or variables, you can then add them to thenewly created group. You also have the option of selecting and movingexisting properties from the property listing to the appropriate group.

Related references

• Create Property Group dialog box on page 150• Edit Property Group dialog box on page 152

Create Property Group dialog boxYou can create a new property group for a service template from the CreateProperty Group dialog box.

The following table describes the Create Property Group dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.


Table 38 Create Property Group dialog box


ID* - Specifies the ID for the new property group.

Display Name* - Name of the new property group shown through the userinterface.

Description: - A optional description for the new property group.

Display/Hide: - Specifies whether to display or hide the property group.

Custom File package: - Specifies a custom file for the property group.

Validation Script: - Generates a validation file for the property group.

Custom File Name forEdit Service(Navigation):

- Specifies a custom file for the edit service from theNavigation menu.

Custom File Name forEdit Service(Settings):

- Specifies a custom file for the edit service from the Settingsmenu.

Custom File Name forSubmit Service(Navigation):

- Specifies a custom file for the submit service from theNavigation menu.



Custom File Name forSubmit ServiceSettings):

- Specifies a custom file for the submit service from theSettings menu.

Custom File Name forTask Details:

- Specifies a custom file for the task details.


Creating a validator script for checking property group entries

If the provided validation options are not adequate for your purposes, youcan create a script to perform the necessary checking. Following is anexample of a validator script written in JavaScript that checks if a valueentered by the user is a number and is less than the maximum allowablevalue of 2048:

function (properties, lang, displayType) { var message = []; var hasError = false;

if (displayType == "exec") { _.each(properties, function(property) { if (isNaN(property.value)) { message.push( "value must be a number:" + property.keyName + "=" + property.value); hasError = true; }

if (property.value >= 2048) { message.push ("value must be less than 2048:" + property.keyName + "=" + property.value); hasError = true; } }); } if (hasError) { return message; } else { return } }The following table shows the validator script specifications for the inputproperty:

# Name Description

1 Script format function (arg1, arg2, arg3) {

//code


# Name Description

}

2 Arguments of validator arg1:

A listing of property values in Property Group. Eachelement is an object that has the following properties:• keyName: The name of the property in string format.• value: The value of the property in string format.

arg2:

Locale string. e.g., ja, en

arg3:

Operating information when script is running (Operationwith task creation: exec, Editing operation of properties:config)

3 Return value of validator Success:

undefined or null

Failure:

Error message in array or string format

If the value is not a number or is larger than the specified maximum, then amessage is output through the user interface.

Related tasks

• Creating property groups on page 149

Edit Property Group dialog boxYou can edit an existing property group for a service template from the EditProperty Group dialog box

The following table describes the Edit Property Group dialog box fields,subfields, and field groups. A field group is a collection of fields that arerelated to a specific action or configuration.


Table 39 Edit Property Group dialog box


ID: - Specifies the ID for the property group.

Display Name: - Name of the property group as displayed through the userinterface.

Description: - A optional description for the property group.



Display/Hide: - Specifies whether the property group is displayed or hidden.

Custom Filespackage:

- Specifies a custom files for the property group.

Validation: - Specifies a validation file for the property group.

Custom File Namefor Edit Service(Settings):

- Specifies a custom file for the edit service from the Settingsmenu.

Custom File Namefor Submit Service(Navigation):

- Specifies a custom file for the submit service from theNavigation menu.

Custom File Namefor Submit ServiceSettings):

- Specifies a custom file for the submit service from theSettings menu.

Custom File Namefor Task Details:

- Specifies a custom file for the task details.


Related tasks

• Creating property groups on page 149

Managing versionsService Builder applies the same method of managing versions to bothservice templates and plug-ins. A version number is assigned when a newservice template or plug-in is created.

All service templates and plug-ins require a version number in nn.nn.nnformat (major-version-number.minor-version-number.revision-number).Specify each of the numbers in the range from 00 to 99.

When a service template or plug-in with the same Key Name and Vendor IDis copied, then the new copy must be assigned a new version number. Aservice template or plug-in with the same Plug-in key name, Vendor ID, andVersion Number cannot be duplicated.

If two or more service templates with same service template key name andVendor ID exists, only the latest version of service template is displayed.Similarly, if two or more plug-ins with same Plug-in key name and Vendor IDexists, only the latest version of the component is displayed.

Under some conditions, when plug-ins are updated, a service template canend up with older versions that need to be updated to the most recentversions. In this case, you can update individual plug-ins or all the plug-insfor a given service template by following these steps:


1. From the Service Builder Edit screen, choose the Component VersionManagement option from the Actions pull-down menu. The ComponentVersion Management dialog box appears.

2. If you want to update all of the plug-ins associated with the currentservice template to their latest versions, select the All Apply tab. You cansee all of the plug-in component steps that are to be upgraded byclicking Step list to be applied. If you prefer to individually specify eachof the plug-in components that you want to update, select the IndividualApply tab and then select the version to apply for a given componentstep.

3. After selecting the components to be updated, click Apply and a messageconfirms that the selected version has been applied.

4. When done updating the version, click Close.

Note: After updating a plug-in version, you need to save the plug-in to retainany modifications that you make.

Note: A service template must be in the Released state and all existing tasksassociated with the service must be archived or deleted before updating theservice.

Related references

• Component Version Management dialog box on page 154

Component Version Management dialog boxYou can manage versions of the component steps associated with a servicetemplate to ensure that you are using the most current version of a givencomponent. You have a choice of updating all of the components, or you canselect specific components.

The following table describes the Component Version Management dialog boxfields, subfields, and field groups. A field group is a collection of fields thatare related to a specific action or configuration.


Table 40 Component Version Management dialog box


Apply to All - Collectively updates all step components to the latestversion.

Individual apply - Selectively specifies specific step components that areupdated to the latest version. When choosing this option, alist of components is shown along with details associatedwith the component and a step list where you can choosethe components to be updated from the Versions pull-down



menu. To see more details for the component, click Moreand to see all of the properties associated with thecomponent, click List.

Step list to be applied - Shows the step list that includes the Step Name, CurrentComponent Name, Latest Version, Latest Component Name,and Status. Information for the component to be applied isshown in the lower portion of the dialog box. You can alsoclick More to see more details for the specified componentor click List to see all of the properties associated with thecomponent.

Related concepts

• Managing versions on page 153



8Reference information

This module covers the following:

□ List of built-in service templates

□ List of built-in plug-ins

□ List of reserved properties

□ Locale settings for plug-ins

Reference information 157Hitachi Automation Director Service Builder User Guide

List of built-in service templatesA collection of pre-configured service templates are provided with HitachiAutomation Director.

The following service templates are provided by default and are immediatelyavailable for submitting services:

Name Description

Allocate Like Volumes Allocates an identical volume for the selected server

and volume within the associated infrastructure

group.

Allocate Like Volumes for Symmetric Cluster

Server from 2 Storage Systems

Allocate an identical volume for the selected

clustered servers and volume within the associated

infrastructure group.

Allocate Like Volumes and Add to Oracle

Database for AIX

Allocates an identical volume for the selected server

and volume, and adds the volume to the disk group

for Oracle ASM for AIX.


Database for Linux



for Oracle ASM for Linux.


Database for Solaris



for Oracle ASM for Solaris.


Database for Windows



for Oracle ASM for Windows.

Allocate Like Volumes and Create Datastore

on VMware vSphere

Allocates and creates an identical datastore for the

selected ESX server and datastore within the

associated infrastructure group.

Allocate Like Replicated Volumes on Existing

Copy Topology

Allocates identical volumes for the selected server

and volume within the associated infrastructure

group and configures copy settings on the existing

copy topology for remote replication.

Allocate Volumes and Add to Oracle

Database for AIX

Provisions a disk at storage system and adds a disk

to a disk group for the Oracle ASM for AIX.


Database for Linux

Creates a volume on a storage system, and adds the

volume to the disk group for Oracle ASM for Linux.


Database for Solaris

Provisions a disk at storage system and adds a disk

to a disk group for the Oracle ASM for Solaris.

158 Reference informationHitachi Automation Director Service Builder User Guide

Name Description


Database for Windows

Creates a volume on a storage system, and adds the

volume to the disk group for Oracle ASM for

Windows.

Allocate Volumes and Create Datastore on

VMware vSphere

Intelligent allocate volumes service that allocates

volumes for a selected VMware vSphere server from

the associated infrastructure group and creates a

datastore instance on the vSphere server.

Allocate Volumes for Citrix XenDesktop on

Microsoft Hyper-V

Intelligent allocation service that uses sets of

volumes from the associated infrastructure group to

be consumed by server(s) running XenDesktop on

Microsoft Hyper-V.

Allocate Volumes for Citrix XenDesktop on

VMware vSphere



be consumed by server(s) running XenDesktop on

VMware vSphere.

Allocate Volumes for Generic Application Intelligent allocation service that uses sets of


be consumed by server(s) running a generic

application.

Allocate Volumes for Microsoft Exchange

Server



be consumed by server(s) running Microsoft

Exchange.

Allocate Volumes for Microsoft SQL Server Intelligent allocation service that uses sets of


be consumed by server(s) running Microsoft SQL.

Allocate Volumes for Oracle Database Intelligent allocation service that uses sets of


be consumed by server(s) running Oracle ASM.

Allocate Volumes for Symmetric Cluster

Server from 2 Storage Systems

Symmetric allocation service that uses sets of

volumes from two storage systems based on

resource criteria to be consumed by a cluster server

running a generic application.

Allocate Volumes with Clone for Citrix

XenDesktop on Microsoft Hyper-V


volumes with in-system shadow image replication

from the associated infrastructure group to be

consumed by server(s) running XenDesktop on

Microsoft Hyper-V.

Allocate Volumes with Clone for Citrix

XenDesktop on VMware vSphere




Name Description


consumed by server(s) running XenDesktop on

VMware vSphere.

Allocate Volumes with Clone for Generic

Application




consumed by server(s) running a generic

application.

Allocate Volumes with Clone for Microsoft

Exchange Server




consumed by server(s) running Microsoft Exchange.

Allocate Volumes with Clone for Microsoft

SQL Server




consumed by server(s) running Microsoft SQL.

Allocate Volumes with Clone for Oracle

Database




consumed by server(s) running Oracle ASM.

Allocate Volumes with Snapshot for Citrix

XenDesktop on Microsoft Hyper-V


volumes with in-system replication (Delta backup,

Thin Image) from the associated infrastructure

group to be consumed by server(s) running

XenDesktop on Microsoft Hyper-V.

Allocate Volumes with Snapshot for Citrix

XenDesktop on VMware vSphere





XenDesktop on VMware vSphere.

Allocate Volumes with Snapshot for Generic

Application




group to be consumed by server(s) running a

generic application.

Allocate Volumes with Snapshot for Microsoft

Exchange Server





Microsoft Exchange.


Name Description

Allocate Volumes with Snapshot for Microsoft

SQL Server





Microsoft SQL.

Allocate Volumes with Snapshot for Oracle

Database




group to be consumed by server(s) running Oracle

ASM.

Allocate Replicated Volumes on Existing

Copy Topology


volumes from the associated infrastructure group for

use by server(s) running a generic application and

configures copy settings on the existing copy

topology for remote replication.

Allocate Replicated Volumes on New Copy

Topology


volumes from the associated infrastructure group for

use by server(s) running a generic application and

creates a new copy topology for remote replication.

Allocate Flash Volumes for Generic

Application

Intelligent allocation service that uses sets of flash


be consumed by server(s) running a generic

application.

Add Host A service for adding hosts for Device Manager.

Create File Share Intelligent provisioning service to add CIFS Share or

NFS Export capabilities.

Allocate Fabric Aware Volumes for Generic

Application

Intelligent allocation service that uses sets ofvolumes from the associated infrastructure group tobe consumed by server(s) running a genericapplication.

This service accesses the Brocade Network Advisor(BNA) and acquires existing fabric configuration andzoning information when allocating new volumes tothe host.

Collect Fabric and Zoning Information Accesses the switch management server to obtain

fabric configuration and zoning information.

Configure WWN Zoning Accesses the switch management server and

updates zoning information.

The following additional service templates are imported by default. However,to use these service templates, you must create an appropriate service foryour operating environment.


Note: If you used any of these additional service templates in AutomationDirector v8.2.0 (or earlier), and have subsequently upgraded to AutomationDirector to v8.2.1 (or later), you cannot use the service version up wizard toupgrade to the latest version. Instead, you need to re-create the servicesfrom new version of service templates.

Table 41 Additional service templates

Category Template name Description

vSphere Modify Virtual Machine Configuration Modifies the virtual serverconfiguration in the VMwarevSphere environment.

Clone Virtual Machine Creates a clone of a virtualserver in the VMware vSphereenvironment.

Delete Cloned Virtual Machine Deletes a clone of a virtualserver in the VMware vSphereenvironment.

Delete Datastore on VMware vSphere Deletes a data store and alogical unit in an environmentthat includes VMware vSphereand Device Manager.

Migrate Virtual Machine Migrates multiple virtual serversin a VMware vSphereenvironment.

Stop Virtual Machine Stops multiple virtual servers ina VMware vSphereenvironment.

Start Virtual Machine Starts multiple virtual servers ina VMware vSphereenvironment.

Restart Virtual Machine Restarts multiple virtual serversin a VMware vSphereenvironment.

Create Snapshot of Virtual Machine Creates a snapshot of thevirtual machine for updating thestatus of a virtual server.

Get List of Storage Systems from DeviceManager

Acquires a list of storagedevices registered in DeviceManager.

Add Virtual Disk to Virtual Machine Adds a disk to a virtual serverin a VMware vSphereenvironment.

Remove Virtual Disk from Virtual Machine Deletes a virtual server in aVMware vSphere environment.



Delete Virtual Machine Deletes a virtual server in aVMware vSphere environment.

Deploy and Setup OS on Virtual Machine Creates a virtual server in aVMware vSphere environment.

Get List of Virtual Machines from VMwarevSphere

Acquires a list of VMwarevSphere virtual servers.

Create Datastore on VMware vSphere Creates a logical unit and adata store in an environmentthat includes VMware vSphereand Device Manager.

Pre-check for Datastore Creation on VMwarevSphere

Checks the environmentprerequisites for adding avirtual server (creation of LUand data store)

Script execution through the vCenter server In a VMware vSphereenvironment, transmits thespecified non-interactive scriptfile from the target server tothe guest OS on the virtualserver, and then executes thescript file on the guest OS.Scripts can be deleted afterexecution.

Pre-check for OS Deployment on Virtual Machine Checks the environmentprerequisites for adding avirtual server (deployment andOS initialization)

OS Get List of Users from Server Obtains a list of Windows orLinux OS users from a specifichost.

Get Lists of Users from Multiple Servers Obtains a list of Windows orLinux OS users from multiplehosts.

Execute Remote Command Executes a command on theremote execution target server.

Windows update program installation Automatically installs updateprograms by using the WindowsUpdate function.

Openstack Addition of a virtual server (deployment/OSinitial setup)

Creates a virtual server in aKVM environment managed byOpenStack. (In OpenStack, thisis called "starting an instance".)

Add virtual server (virtual disk) Adds a volume to an instance ina KVM environment managedby OpenStack.



Back up volumes Backs up volumes in a KVMenvironment managed byOpenStack.

Delete a virtual server Deletes instances in a KVMenvironment that is controlledby OpenStack. In addition, iffloating IP addresses are set forinstances, the floating IPaddresses assignments arereleased.

Delete a virtual server (virtual disk) In a KVM environment that iscontrolled by OpenStack, thisservice template disconnectsvolumes that are connected toinstances.

Start virtual server Starts an instance in KVMmanaged by OpenStack.

Obtain a virtual server information list Acquires an instanceinformation list contained in thespecified project in a KVMenvironment that is controlledby OpenStack.

AWS Add a virtual server (deploy) Creates a virtual server in anAmazon EC2 environment. (InAmazon EC2, this is referred toas "starting an instance".)

Delete a virtual server Deletes an instance from anAmazon EC2 environment. Inaddition, all network interfacesconnected to the instance aredeleted.

Start virtual servers Starts instances in an AmazonEC2 environment.

Stop virtual servers Stops instances in an AmazonEC2 environment.

Hyper-V 2012 Add a virtual server (deploy/OS initial settings) Creates a virtual server in aHyper-V 2012 environment.

Change virtual server specifications (CPU andmemory)

Changes the values of virtualserver specifications (CPU andmemory) in a Hyper-V 2012environment.

Delete virtual server This service template deletesvirtual servers in a Hyper-V2012 environment.



Add virtual server (virtual disk) This service template creates avirtual disk in a Hyper-V2012environment and then adds thatvirtual disk to a virtual server.

Start virtual server Starts multiple virtual servers ina Hyper-V 2012 environment.

Stop virtual server Shuts down multiple virtualservers in a Hyper-V 2012environment.

Restart virtual server This service template restartsmultiple virtual servers in aHyper-V2012 environment.

Obtain virtual server information list This service template obtains alist of information about virtualservers in a Hyper-V2012environment.

Plug-inComponentsfor Developers

AWS components Do not create or execute anyservice from this servicetemplate. This service templatecontains plug-ins for servicetemplate developers.

HCS Components Do not create or execute anyservice from this servicetemplate. This service templatecontains plug-ins for servicetemplate developers.

Hyper-V2012 Components Do not create or execute anyservice from this servicetemplate. This service templatecontains plug-ins for servicetemplate developers.

OpenStack Components Do not create or execute anyservice from this servicetemplate. This service templatecontains plug-ins for servicetemplate developers.

Oracle Components Do not create or execute anyservice from this servicetemplate. This service templatecontains plug-ins for servicetemplate developers.

vSphere Components Do not create or execute anyservice from this servicetemplate. This service template



contains plug-ins for servicetemplate developers.

Note: The File type properties for these service templates include connectiondetails for various components and should not be changed as the templatesmay no longer function properly.

Warning: Some properties associated with the built-in service templatesinclude internal data as indicated by "Do not change". Please do not changethese properties.

List of built-in plug-insA collection of plug-ins are provided with Automation Director that you canuse to create customized service templates.

The following plug-ins are included by default:

Plug-in Name Description

Abnormal-End Plug-in Manages abnormal termination of executing flows, tasks,

hierarchical flows, and repeatedly executed flows.

Add Host/Get Storage Information Runs Add Host/Get Storage Information.

Allocate CIFS File Storage Creates a CIFS file share.

Allocate Like Volumes Plug-in Allocates identical newly added volumes and existing volumes

for the selected server and volume.

Allocate NFS File Storage Creates a NFS file share.

Allocate Volumes Plug-in Executes the intelligent allocation of newly added volumes and

existing volumes.

Branch by Property Value Plug-in Creates a conditional branch that compares and determines

service property values to branch the flow of processing.

Branch by ReturnCode Plug-in Creates a conditional branch that compares and determines

the return value of the previous step to branch the flow of

processing.

Create CopyTopology Plugin Creates a copy topology.

Create Datastore Plug-in Creates a datastore instance on VMware vSphere server.

DeviceManager Search Plugin Searches DeviceManager information from an external server

connection.



Display CopyGroup Info Generate

Plugin

Displays copy group information.

Email Notification Plug-in Connects to an SMTP server and sends emails to the specified

destination.

Expand CopyTopology Plugin Expands a given copy topology.

External Server Connection

Collector Plug-in

Obtains information for Device Manager Connections and

connections to VMware vCenter from within Automation

Director.

File Export Plug-in Exports the input content to the specified output file in a

format you can define by using VTL (Velocify Template

Language).

File-Transfer Plug-in Sends a file or a folder to a remote host, or receives a file or a

folder from a remote host. FTP and SCP are used as the

transfer protocol.

File System Selection Selects a file system.

FileAdapterPlugin Extracts a specified value from the data in JSON format. The

input data is compatible with the file-type data output by the

Allocate Volumes, Allocate Like Volumes, and Replication plug-

ins.

Find Host Plug-in Obtains host information from Device Manager.

Flow Plug-in Creates a flow that has a hierarchy defined by nested flows.

General Command Plug-in Executes a command line on a remote destination host.

Generate CopyGroup Display Info

Plugin

Displays copy group information.

Get canonical name of SCSI LUN Acquires the canonical name of the SCSI LUN recognized by

VMware vSphere ESXi (or VMware ESX Server)

Get CopyTopology Plugin Obtains the copy topology information.

Interval Plug-in Controls the interval between steps by specifying the wait

time.

JavaScript Plug-in Runs any script written in JavaScript.

JavaScript Plug-in for

Configuration Manager REST API

Runs any script written in JavaScript and also includes built-in

methods for accessing the Configuration Manager REST API.

You can easily write a script to access the Configuration

Manager REST API by using this plug-in.

LDEV ID Search Plug-in Searches for and outputs a listing of LDEV ID's.

Pair Configuration Plug-in Creates a pair for Shadow Image and Thin Image.



Pair Info Search Plug-in Searches pair information.

Path Search Plug-in Searches for path details based on a given search criteria.

Repeated Execution Plug-in Executes a specific flow repeatedly. You can use this plug-in to

implement loop processing.

Replication Plug-in Executes allocation of newly added secondary volumes with in-

system replication.

Standard Output Plug-in Outputs a specified value to the standard output. Do not use

this plug-in for a new service template because this plug-in is a

compatibility plug-in with the service template that was

created with the former procedure.

S-Vol Provisioning Plug-in Executes the allocation of newly added secondary volumes

with in-system replication.

Task Submit Time Plug-in Acquires the submit time of the task.

Terminal Command Plug-in Executes a command line on the remote destination host that

is connected with Telnet or SSH using the Terminal Connect

Plug-in.

Terminal Connect Plug-in Enables terminal connections with the remote destination hosts

using Telnet or SSH authentication.

Terminal Disconnect Plug-in Disconnects the terminal from the remote destination host,

which was connected with Telnet or SSH using the Terminal

Connect Plug-in.

Test Value Plug-in Compares service property values and returns 0 if the values

match the specified conditions.

Thin Image Pool Selection Plug-in Selects a Thin Image pool.

User-Response Wait Plug-in Suspends processing and waits for a user response. Using this

plug-in, the operator manually selects whether to continue

processing.

Validate CopyPairSettings Plug-in Validates the Copy Pair Settings property.

VolumeReport Plug-in Reports volume information to Replication Manager.

V-Vol Provisioning Plug-in Performs the allocation of newly added secondary virtual

volumes.

Web Client Plug-in Sends HTTP request messages such as GET/POST and receives

HTTP response messages. When requested, it accesses the

server through a proxy to complete server and proxy

authentication. For example, you can use this plug-in when

connecting to the Web using the REST API.

allocateOracleASMDG Allocates a specified volume to the Oracle ASM disk group.



allocateOracleASMDGLinux Allocates a specified volume to the disk group of Oracle ASM.

allocateOracleASMDGWindows Allocates a specified volume to the disk group of Oracle ASM.

changeDeviceAttributeAIX Changes device attributes.

changeDevicePermissionsAIX Changes the permission of the owner and group on the device.

changeDevicePermissionsSolaris Changes the owner and group permissions for a device.

changeDeviceSliceNoSolaris Changes the slice number of the volume.

checkAutoMountStatusWindows Checks whether the disk automount function in the Windows

settings is enabled.

checkMultiPathStatusAIX Checks whether the path status is normal.

checkMultiPathStatusLinux Checks whether the path status is normal.

checkMultiPathStatusSolaris Checks whether the path status is normal.

checkMultiPathStatusWindows Checks whether the path status is normal.

checkOracleASMDisk Checks the disks in Oracle ASM.

checkOracleASMDiskLinux Checks the disk for Oracle ASM within.

checkOracleASMDiskWindows Checks the disk for Oracle ASM within.

checkOracleServerStatus Checks the specified DB Server to determine if an Oracle DB is

installed. If an Oracle DB is installed, the plug-in checks

whether it is for an Oracle RAC or Single instance

configuration.

checkOracleServerStatusLinux Checks the specified DB Server to determine if an Oracle DB is



configuration.

checkOracleServerStatusWindows Checks the specified DB Server to determine if an Oracle DB is



configuration.

checkSUDOCommand Checks whether the sudo command can be used.

createAsmDiskPartitionWindows Creates partitions to allow the disk to be used in Oracle ASM.

createPasswordFile Creates a password file.

deleteDirectory Deletes a directory.

deleteDirectoryWindows Deletes a directory.

deleteFileOracleServer Deletes a file on the remote server.

deletePasswordFile Deletes password file.

formatDeviceEFISolaris Changes the volume format to the EFI format.



getOracleDiskGroupList Outputs a list of the disks in the disk group assigned to Oracle

ASM.

getOracleDiskGroupListLinux Outputs the list of disks in the disk group that is assigned to

Oracle ASM.

getOracleDiskGroupListWindows Outputs a list of the disks in the disk group assigned to Oracle

ASM.

makeDirectory Creates a directory.

makeDirectoryName Generated a directory with the specified name on a given

target server.

makeDirectoryNameWindows Generated a directory with the specified name on a given

target server.

makeDirectoryWindows Creates a directory.

mapDeviceAIX Maps device information to devices recognized by the OS.

mapDeviceLinux Maps device information to devices recognized by the OS.

mapDeviceSolaris Maps device information to devices recognized by the OS.

mapDeviceWindows Maps device information to devices recognized by the OS.

markAsmDiskPartitionWindows Attaches labels to partitions to allow the disk to be used in

Oracle ASM.

outputDeviceAttributeAIX Outputs volume attributes to a text file.

outputDevicePermissionsAIX Outputs a list of device permissions to a text file.

outputDevicePermissionsLinux Outputs a list of device permissions to a text file.

outputDevicePermissionsSolaris Outputs a list of device permissions to a text file.

Pair Configuration Plug-in Creates a pair for Shadow Image and Thin Image.

recognizeDeviceAIX Performs the processing to re-recognize volumes and detect

devices.

recognizeDeviceLinux Performs the processing to re-recognize volumes and detect

devices.

recognizeDeviceSolaris Performs the processing to re-recognize volumes and detect

devices.

recognizeDeviceWindows Performs the processing to re-recognize volumes and detect

devices.

setMultipathFileAndRawDevice Performs the multi-path setting for a volume recognized by the

OS, and registers the volume as a RAW device.

setPermissionToFile Sets the permission on the file.


Create a virtual server Creates a virtual serverin an Amazon EC2environment. (InAmazon EC2, this isreferred to as "startinginstances".)

AWS

Delete a virtual server Deletes an instancefrom an Amazon EC2environment.

AWS

Start a virtual server Starts an instance in anAmazon EC2environment.

AWS

Shut down a virtual server Shuts down a virtualserver an the AmazonEC2 environment. (InAmazon EC2, this isreferred to as "stoppinginstances".)

AWS

Obtain status of virtual server Obtains the status ofan instance in anAmazon EC2environment.

AWS

Creating a snapshot A snapshot is createdas a backup for thevolume managed in theAmazon EBSenvironment.

AWS

Deleting a snapshot A snapshot managed inthe Amazon EBSenvironment is deleted.

AWS

Acquiring a list of information about snapshots A list of snapshotsmanaged in theAmazon EBSenvironment is outputto a file in CSV format.

AWS

Uploading a file A file in the Amazon S3environment isuploaded.

AWS

Downloading a file A file in the Amazon S3environment isdownloaded.

AWS

Deleting a file A file managed in theAmazon S3environment is deleted.

AWS


AMI creation Creates an AMI from aninstance in the AmazonEC2 environment

AWS

Virtual server resources configuration Changes the instancetype of an instance inthe Amazon EC2environment

AWS

Virtual server information list Outputs a list ofinstance informationmanaged in theAmazon EC2environment to a file inCSV format

AWS

Stack creation Creates a stack from atemplate file in theAWS CloudFormationenvironment

AWS

Stack deletion Delete a stack in theAWS CloudFormationenvironment

AWS

Stack information list Outputs a list of stacksmanaged in the AWSCloudFormationenvironment to a file inCSV format

AWS

Create a virtual server Creates a virtual serverfrom an exportedvirtual server in theHyper-V 2012environment.

HyperV-2012

Virtual server virtual switch settings Specifies a virtualswitch in the virtualserver in the Hyper-V2012 environment.

HyperV-2012

Create a response file Creates a response fileto initialize the OS andset the IP address forthe virtual server(Windows) in theHyper-V 2012environment.

HyperV-2012

Mount a virtual disk Mounts a virtual diskon the Hyper-V 2012server.

HyperV-2012

Unmount a virtual disk Unmounts a virtual diskfrom the Hyper-V 2012server.

HyperV-2012


Start a virtual server Starts a virtual serverin the Hyper-V 2012environment.

HyperV-2012

Shut down a virtual server Performs a forcedshutdown of the virtualserver OS in the Hyper-V 2012 environment.

HyperV-2012

Obtain Status of Virtual Server Obtain the status of avirtual server in aHyper-V 2012environment.

HyperV-2012

Obtain IP Address of Virtual Server Obtain the IP address(IPv4) of a virtualserver in a Hyper-V2012 environment.

HyperV-2012

Change CPU Settings of Virtual Server Change the CPUsettings of a virtualserver in a Hyper-V2012 environment.

HyperV-2012

Change Memory Settings of Virtual Server Change the memorysettings of a virtualserver in a Hyper-V2012 environment.

HyperV-2012

Delete Virtual Servers Deletes the virtualservers in a Hyper-V2012 environment.

HyperV-2012

Obtain the virtual server information list Exports virtual serverinformation to atemporary file on theHyper-V server in aHyper-V 2012environment.

HyperV-2012

Create Virtual Disk Creates a virtual disk ina Hyper-V 2012environment.

HyperV-2012

Connect Virtual Disk Connects a virtual diskto a virtual server in aHyper-V 2012environment.

HyperV-2012

Initial OS settings (Linux) Configures the initialOS settings (hostname, time zone, DNSsuffix).

OS

Set static route Sets a static route in aWindows or Linuxtarget server.

OS


Obtain the MAC address of an NIC Obtains the MACaddress of the NIC.

OS

Windows network settings Sets the IP address forthe NIC.

OS

Send ICMP echo request message Sends an ICMP echorequest message to thespecified IP address inthe Windows or UNIXexecution target server.

OS

Send ICMP echo request message (confirm noresponse)

Sends an ICMP echorequest message to thespecified IP address inthe Windows executiontarget server. Confirmsthat there is noresponse.

OS

Execution Wait Controls the intervalsbetween steps bywaiting for the numberof seconds specified ina property.

OS

Output OS type Outputs to standardoutput the type of OSof the specifiedWindows or UNIXexecution target server.

OS

Get list of OS users Acquires a list of OSusers from Windows/UNIX.

OS

Delete file Deletes the specifiedfile in a Windows orUNIX target server.

OS

Acquisition of column data from a CSV/Excel file Acquires the data inthe specified columnfrom a CSV or Excelfile.

OS

Acquisition of row data from a CSV/Excel file From a CSV/Excel file,acquire the data in therow that matches thespecified key value.

OS

Install the Windows updates On the Windowsenvironment,automatically installsthe updates throughthe Windows Update.

OS

Start an Oracle DB instance On the execution targetserver in a Windows or

Oracle


UNIX environment,start SQL*Plus andexecute the STARTUPcommand to start theinstance.

Stop an Oracle DB instance On the execution targetserver in a Windows orUNIX environment,start SQL*Plus andexecute theSHUTDOWN commandto stop the instance.

Oracle

Add an Oracle DB user (Windows) On the execution targetserver in a Windowsenvironment, startSQL*Plus and executethe CREATE USERstatement to add adatabase user.

Oracle

Add an Oracle DB user (UNIX) On the execution targetserver in a UNIXenvironment, startSQL*Plus and executethe CREATE USERstatement to add adatabase user.

Oracle

Delete an Oracle DB user On the execution targetserver in a Windows orUNIX environment,start SQL*Plus andexecute the DROPUSER statement todelete the databaseuser.

Oracle

Get power status of virtual server Acquires the powerstatus of the virtualserver in a VMwarevSphere environment.

vSphere

Start virtual server Starts the virtualserver in a VMwarevSphere environment.

vSphere

Shut down virtual server Performs a shutdown ofthe virtual server andsets its power status toOFF in a VMwarevSphere environment.

vSphere

Get virtual server IP address Acquires the IP addressof the virtual server in

vSphere


a VMware vSphereenvironment.

Set virtual server resources Changes the allocationof resources (numberof CPUs, memory size)of the virtual server ina VMware vSphereenvironment.

vSphere

Migrate virtual server Migrates the virtualserver to the specifiedmigration destination ina VMware vSphereenvironment.

vSphere

Recognize LUN Recognizes an added ordeleted LUN in VMwarevSphere ESXi (orVMware ESX Server).

vSphere

Create data store Adds a data store inVMware vSphere ESXi(or VMware ESXServer).

vSphere

Delete data store Deletes a data storefrom VMware vSphereESXi (or VMware ESXServer)

vSphere

Set FC path priority Sets the FC path to"preferred" for thespecified data store inVMware vSphere ESXi(or VMware ESXServer)

vSphere

Add virtual disk to virtual server Adds a virtual disk to avirtual server in aVMware vSphereenvironment.

vSphere

Delete virtual disk Deletes a virtual diskfrom the virtual serverin a VMware vSphereenvironment.

vSphere

Get canonical name of SCSI LUN Acquires the canonicalname of the SCSI LUNrecognized by VMwarevSphere ESXi (orVMware ESX Server)

vSphere

Create virtual server Creates a virtual serverfrom a template in aVMware vSphereenvironment.

vSphere


Delete virtual server Deletes the specifiedvirtual server in aVMware vSphereenvironment.

vSphere

Set OS init. settings and IP addr. of virtualservers (Windows)

For a virtual server(Windows) in theVMware vSphereenvironment, performthe initial OS settingsand the IP addresssettings.

vSphere

Set OS init. settings and IP addr. of virtualservers (Linux)

For a virtual server(Linux) in the VMwarevSphere environment,perform the initial OSsettings and the IPaddress settings.

vSphere

Change virtual machine port group Changes the port groupconnected to a virtualserver in a VMwarevSphere environment.

vSphere

Check data store creation Determines whether ornot a data store can beadded.

vSphere

Check virtual server creation Determines whether ornot a virtual server canbe created from thespecified template.

vSphere

Check VMware vCenter Server connectivity Determines whether ornot a connection to thevCenter server can beestablished.

vSphere

Get list of virtual server information Outputs a list of virtualserver information to atemporary file on theVMware vCentercontrol server.

vSphere

Creating a virtual server snapshot Creates a snapshot of avirtual server in theVMware vSphereenvironment.

vSphere

Moving a virtual server snapshot Moves a snapshot usedby a virtual server to aspecified snapshot on adifferent virtual serverin the VMware vSphereenvironment.

vSphere


Deletion of a virtual server snapshot Deletes a snapshot of avirtual server in theVMware vSphereenvironment.

vSphere

Creating a virtual server clone Creates a clone of avirtual server in theVMware vSphereenvironment.

vSphere

Deletion of a virtual server clone Deletes a virtual serverclone in the VMwarevSphere environment.

vSphere

Resource configuration setting of the virtualserver

Changes the CPU,memory, or disk I/Oresource configurationsfor the virtual serverthat is managed byVMware vCenterServer.

vSphere

Pre-evaluation of resource changes in virtualserver

Performs a pre-evaluation beforechanging CPU ormemory resources forthe virtual server thatis managed by VMwarevCenter Server.

vSphere

Pre-eval. of resource configuration changes invirtual server

Performs a pre-evaluation beforechanging CPU,memory, or disk I/Oresource configurationsfor the virtual serverthat is managed byVMware vCenterServer.

vSphere

Set the physical adapter Sets the status of thephysical adapterconnected to thestandard virtual switchin the VMware vSphereenvironment.

vSphere

Get the physical adapter information list Outputs informationabout the physicaladapter connected tothe ESX server in theVMware vSphereenvironment.

vSphere

Set virtual server options for the HA cluster Sets the options thatdefine the behavior of

vSphere


the virtual server forthe vSphere HA clusterin the VMware vSphereenvironment.

Set host DRS group Adds or deletes an ESXserver for the host DRSgroup set for thevSphere DRS cluster inthe VMware vSphereenvironment.

vSphere

Move the ESX server Moves the ESX serverin the VMware vSphereenvironment.

vSphere

Set maintenance mode for the ESX server Enables or disablesmaintenance mode forthe ESX server in theVMware vSphereenvironment.

vSphere

Extend a virtual disk Extends the capacity ofthe virtual disk set forthe virtual server in theVMware vSphereenvironment.

vSphere

Add a network adapter Adds a network adapterto the virtual server inthe VMware vSphereenvironment.

vSphere

Change the network adapter settings Changes the settings ofthe network adapterallocated to the virtualserver in the VMwarevSphere environment.

vSphere

Add a port group to the standard virtual switch Adds a port group tothe standard virtualswitch in the VMwarevSphere environment.

vSphere

Set traffic shaping policy for the port group Sets the traffic shapingpolicy for the portgroup of the standardvirtual switch in theVMware vSphereenvironment.

vSphere

Create a template Creates a templatefrom the virtual serverin the VMware vSphereenvironment.

vSphere


Delete a template Deletes a virtual servertemplate in the VMwarevSphere environment.

vSphere

Set the virtual server DRS group Adds or deletes avirtual server for thevirtual server DRSgroup set for thevSphere DRS cluster inthe VMware vSphereenvironment.

vSphere

Add a DRS rule (from virtual server to host) Adds a DRS rule for thevSphere DRS cluster(from the virtual serverto the host) in theVMware vSphereenvironment.

vSphere

Monitoring settings for the virtual server in theHA cluster

In the VMware vSphereenvironment, specifiesthe monitoring settingsfor the virtual serverbelonging to thevSphere HA cluster.

vSphere

DRS automation level setting for the DRSclusters

In the VMware vSphereenvironment, specifiesthe DRS automationlevel setting for thevirtual server belongingto the vSphere DRScluster.

vSphere

File transmission through the vCenter server In the VMware vSphereenvironment, transmitsthe specified file fromthe execution targetserver to the guest OSon the virtual server.

vSphere

Folder transmission through the vCenter server In the VMware vSphereenvironment, transmitsthe specified folderfrom the executiontarget server to theguest OS on the virtualserver.

vSphere

Script execution through the vCenter server In the VMware vSphereenvironment, executesa non-interactive scriptthat is placed in theguest OS on the virtualserver.

vSphere


File deletion through the vCenter server In the VMware vSphereenvironment, deletesthe specified file in theguest OS on the virtualserver.

vSphere

Folder deletion through the vCenter server In the VMware vSphereenvironment, deletesthe specified folder inthe guest OS on thevirtual server.

vSphere

Create DP volume Creates the specifiedDP volume in thestorage systemmanaged by the DeviceManager.

HCS

Delete DP volume Deletes the specifiedDP volume in thestorage systemmanaged by the DeviceManager.

HCS

Register LU in host group Registers the specifiedLU in the host group inthe storage systemmanaged by the DeviceManager.

HCS

Delete LU from host group Deletes the specifiedLU from the host groupin the storage systemmanaged by the DeviceManager.

HCS

Check HDvM connectivity Determines whether ornot a connection to theDevice Manager servercan be established.

HCS

Check LU creation Determines whether ornot the DP volume (LU)can be created.

HCS

Get storage information list Outputs a list ofstorage information toa temporary file in theDevice Manager CLIserver.

HCS

Create a virtual server Creates a virtual serverfrom an image (called"Run an instance" onOpenStack).

OpenStack

Create Volume Create a volume in aKVM environment being

OpenStack


managed byOpenStack.

Connect Volume Connect a volume to aninstance in a KVMenvironment beingmanaged byOpenStack.

OpenStack

Obtain Status of Virtual Server Obtain the status of aninstance in a KVMenvironment beingmanaged byOpenStack.

OpenStack

Activate Virtual Server Activate an instance ina KVM environmentbeing managed byOpenStack.

OpenStack

Obtain IP Address of Virtual Server Obtain the IP address(IPv4) configured to allNICs of an instance in aKVM environment beingmanaged byOpenStack.

OpenStack

Create Temporary Volume Create a temporaryvolume based on avolume being managedby OpenStack.

OpenStack

Backup Volume Obtain the backup of avolume being managedby OpenStack.

OpenStack

Delete Volume Delete a volume beingmanaged byOpenStack.

OpenStack

Disconnect volume Disconnect the volumeconnected to theinstance in the KVMenvironment managedby OpenStack.

OpenStack

Delete virtual server Delete the instance inthe KVM environmentmanaged byOpenStack. If a floatingIP address is set to theinstance, that floatingIP address isunassigned.

OpenStack

Get list of virtual server information Output a list ofinstance informationcontained in the

OpenStack


specified project to afile on the OpenStackcontrol server(execution targetserver) in the KVMenvironment managedby OpenStack.

List of reserved propertiesA reserved property is a special service property whose property key has aspecific definition or purpose in Automation Director.

The property key of a reserved property begins with reserved.. You can usereserved properties by mapping them to plug-in properties in the SpecifyPlug-in Input Properties for Mapping dialog box or the Specify Plug-in OutputProperties for Mapping dialog box. Users cannot define or assign values toreserved properties.

When you map a reserved property to an input property, the value of thereserved property is assigned to a plug-in property when the plug-in isexecuted. Alternatively, select the Direct Input option, and in the MappingParameter field, specify the reserved property in the format ?dna_reserved-property-key?. In this case, the value of the reserved property supplies partof the value of the plug-in properties at plug-in execution.

When you use a reserved property as an output property, the reservedproperty stores the value of a designated plug-in property. By selecting theSelect a Property from Service Properties option in the Specify Plug-in OutputProperties for Mapping dialog box, you can specify a reserved property towhich the value of the output property is passed.

Following is a list of reserved properties:

Reserved Property Key Description

reserved.debugger.exitCode Stores the return codes for steps executed while in debugging

mode. This property can only be used in the debugger window.

reserved.external.hcmds.dir Indicates the directory of Hitachi Command Suite.

Example:

C:\Program Files\Hitachi\HiCommand

reserved.external.path Indicates the path of the REST API in order to access the

dynamic data. For example, in the case of "http://localhost:

22015/Automation/v1/objects/ExternalResources/IPAddresses?



host=myHost&type=vm", the value becomes "/IPAddresses".

The query parameter is not included.

reserved.external.query Indicates the query parameter of the path passing to REST

API. For example, in the case of "http://localhost:22015/

Automation/v1/objects/ExternalResources/IPAddresses?

host=myHost&type=vm", the value becomes

"host=myHost&type=vm".

reserved.external.resource.dir Indicates the resource directory of the external resource of the

dynamic data.

reserved.external.userName The user name who is logged in to Automation Director from

REST API.

reserved.loop.index

reserved.loop.indexN

References a numerical value from 1 to 99 that indicates how

many times a Repeated Execution Plugin, that is one (or N)

levels above the base step, has repeated.

reserved.loop.input

reserved.loop.inputN

References the value of the inputProperties input property of a

repeated execution plug-in that is one (or N) levels above the

base step. Of the comma-delimited values specified in the

input properties of the repeated execution plug-in, this

property stores the value of the element that corresponds to

the current iteration of the flow. For example, if the input

property is A,B,C, the values A, B, and C are input in the order

corresponding to the repetition count of the flow. The repeated

execution plug-in can be executed a maximum of 99 times.

reserved.loop.output Passes values to the outputProperties output property of a

repeated execution plug-in. The values output to this property

are assigned to the output property as a comma-separated

value. For example, if the values of the output property of the

plug-in are X, Y, and Z for successive iterations, the value X,Y,Z

is assigned to the output property.

reserved.service.name References the name of the service from which a task was

generated. To reference this reserved property, specify the

property key in the format ?dna_reserved.service.name?. You

can use this property in any plug-in to which service properties

can be mapped.

reserved.service.serviceGroupNam

e

References the service group in which the service from which a

task was generated is registered. To reference this reserved

property, specify the property key in the format ?

dna_reserved.service.serviceGroupName?. You can use this

property in any plug-in to which service properties can be

mapped.



reserved.step.path References the ID of the step that is currently being executed.

To reference this reserved property, specify the property key in

the format ?dna_reserved.step.path?. The value of this

property is the same as the step ID displayed in the messages

output to the task log when plug-in execution begins and ends.

You can use this property in any plug-in to which service

properties can be mapped.

reserved.step.prevReturnCode Supplies the return value of the preceding step (the step that

is the origin of the relational line connected to the plug-in). To

reference this reserved property, specify the property key in

the format ?dna_reserved.step.prevReturnCode?. If there are

multiple preceding steps, the property is assigned the logical

sum of all the return values. If there is no preceding step, 0 is

assigned. You can use this property in any plug-in to which

service properties can be mapped. If you retry a task from a

step that references this reserved property without executing

the preceding step, the return value from the last time the

preceding step was executed is set in this reserved property as

the return value of the preceding step.

reserved.task.description Supplies the description of a task. To reference this reserved

property, specify the property key in the format ?

dna_reserved.task.description?. You can use this property in

any plug-in to which service properties can be mapped.

reserved.task.dir Supplies the path of the temporary data folder created during

task execution. This property provides a unique folder path at

execution of each task. The folder referenced by this property

is created on the Automation Director server when the task is

executed, and deleted when the task is archived. Note that

files and folders that start with task are reserved in

Automation Director, and cannot be created by the user.

reserved.task.id Supplies the task ID. To reference this reserved property,

specify the property key in the format ?dna_reserved.task.id?.



reserved.task.name Supplies the task name. To reference this reserved property,

specify the property key in the format ?

dna_reserved.task.name?. You can use this property in any

plug-in to which service properties can be mapped.

reserved.task.submitter Supplies the user ID of the user who submitted the task for

execution. If the task was retried, this property references the

user ID of the user who submitted the task, not the user who



retried the task. To reference this reserved property, specify

the property key in the format ?dna_reserved.task.submitter?.



reserved.task.tags A reserved property to reference the tags set for a task.

reserved.task.url Supplies the URL for accessing the Task Details dialog box. To

reference this reserved property, specify the property key in

the format ?dna_reserved.task.url?. You can use this property

in any plug-in to which service properties can be mapped.

reserved.terminal.account References the user ID used by a terminal connect plug-in.

This property is used by the commandLine input property of a

terminal command plug-in. It stores the login name of the user

account used to connect to the terminal.

reserved.terminal.password References the password used by a terminal connect plug-in.

This property is used by the commandLine input property of a

terminal command plug-in. It stores the password of the user

account used to connect to the terminal.

reserved.terminal.suPassword References the administrator password used by the terminal

connect plug-in. This property is used by the commandLine

input property of a terminal command plug-in. It stores the

password of the superuser used to connect to the terminal.

Locale settings for plug-insThe locale setting that applies to a device on which an operation is performedby a plug-in depends on the operating system. The following describes thelocale settings applied when plug-ins are executed in each operating system.

In Windows

When a script or command is executed on a target device, the locale andcharacter set of the target device should match those of Automation Director.The locale and character set are determined by the settings in the Regionand Language area of the Windows Control Panel that govern date andtime formats, user-level display languages, system-level display languages,and system locale settings.

In UNIX

The locale setting applied during plug-in execution depends on theCharacter Set Auto Judgment (SSH) setting in the Create Custom Plug-indialog box or the Edit Custom Plug-in dialog box.


• If the check box is disabled, scripts are executed with the LC_ALL=C locale.Make sure that commands and command parameters consist only of ASCIIcharacters. If a command parameter, standard output, or standard erroroutput contains non-ASCII characters, the characters might becomegarbled and prevent the command from executing normally.

• If the check box is enabled, the script is executed using the default localeof the connecting user. When executing a script or command on anoperation target device, the environment variable LC_ALL and LANG are setto the default locale of the connecting user. No other environmentvariables are changed.

When executing a script or a command the locale is assigned in the followingorder of priority:

Priority Environment variable

1 Value of LC_ALL

2 Value of LC_CTYPE

3 Value of LANG



9Description of built-in plug-ins

This module covers the following:

□ General Command Plug-in

□ File-Transfer Plug-in

□ Repeated Execution Plug-in

□ Email Notification Plug-in

□ User-Response Wait Plug-in

□ Terminal Connect Plug-in

□ Terminal Command Plug-in

□ Terminal Disconnect Plug-in

□ Flow Plug-in

□ Interval Plug-in

□ Branch by ReturnCode Plug-in

□ Test Value Plug-in

□ Abnormal-End Plug-in

□ Branch by Property Value Plug-in

□ File Export Plug-in

Description of built-in plug-ins 189Hitachi Automation Director Service Builder User Guide

□ JavaScript Plug-in

□ JavaScript Plug-in for Configuration Manager REST API

□ LDEV ID Search Plug-in

□ Path Search Plug-in

□ Web Client Plug-in

190 Description of built-in plug-insHitachi Automation Director Service Builder User Guide

General Command Plug-inThe General Command Plug-in executes a command line on the destinationhost.

If you have pre-set authentication information in the Agentless RemoteConnections view, you can execute commands by specifying the followinginformation in the general command plug-in:• The device on which to execute the command (destinationHost property)• Command to be executed (commandLine property)• Command arguments (commandLineParameter property)

If destination host is a Automation Director Server (localhost), the user IDand the password are unnecessary.

For the command to be executed on the operation target device, specifycharacters that can be used in commands in the operating systems of theAutomation Director server and the operation target device. For example, ifthe Automation Director server and the operation target device both run theJapanese version of Windows, characters in the MS932 character set can bespecified.

When local execution function is enabled and the OS of the local host isWindows, the command runs with System account privileges. If the OS isLinux, the command runs with root user privileges. The execution directoryfrom the command is specified as follows:• When the connection destination is running Windows: Admin$\Hitachi

\CMALib\HAD\home Admin$ is the directory specified in the windirenvironment variable.

• When the connection destination is running UNIX and true is specified forthe elevatePrivileges property: The home directory of the root user

• When the connection destination is running UNIX and false is specified forthe elevatePrivileges property: The home directory of the connection user

Prerequisites for execution

Certain commands must be installed on the operating system of theoperation target device before you use the general command plug-in.

To use the general command plug-in when the operation target device isrunning Windows, administrative sharing must be enabled.

Cautionary notes• IPv6 is not supported when Automation Director is running on Linux and

the destination host is Windows.• The locale and character set at the time of execution depend on the OS of

the operation target device.


• If the execution of a task is stopped while the plug-in is executing, thestatus of the task becomes Failed or Completed when the processing of thegeneral command plug-in finishes. The status of steps and tasks afterplug-in execution has finished depends on the return code of the step andthe condition for executing subsequent steps. You can set a Subsequent-step Execution Condition in the Create Step dialog box or the Edit Stepdialog box.

• The execution method differs depending on the OS of the operation targetdevice. The command is executed by SMB and RPC in Windows, and SSHin UNIX. Therefore, the SSH server must be set up on UNIX-basedoperation target devices.

• The port number used by SSH can be set in connection-destinationproperty file (connection-destinationname. properties) or theproperty file (config_user.properties).

• When the operation target device is running Windows, user profiles are notinherited. This means a plug-in can produce different execution resultsfrom a command or script executed on the desktop. To avoid this issue, donot reference settings in user profiles, such as user environment variables,registry entries, and Internet Explorer settings, when executing a plug-in.If a command or script references an element of a user profile, thecommand or script might not behave as expected. For example, when youexecute a command or script that references Internet Explorer proxysettings, the command or script might fail with a communication error.This might occur in scenarios such as implementing a Windows Updateusing a script.

• If the operation target device is running UNIX, and you need to specifynon-ASCII characters in the commandLine or commandLineParameterproperty, see the following table where "Y" indicates that the setting isrequired and "N" indicates that the setting is not required:

Plug-inOS of operation targetdevice

Login script setting .bashrc setting

General commandplug-in

File-transfer plug-in

Content plug-in

AIX Y N

HPUX Y N

Linux Y N

Solaris Y N

Terminal commandplug-in

UNIX Y N

Note: Applies only to the File-transfer plug-in when a non-ASCII character isincluded in the value of the remoteFilePath property.

Return codes

The following return codes are generated by the General Command Plug-in:


Return Code Description

0-63 The return code (0 to 63) of the command or script is returned

as the return code of the plug-in. The meaning of the

command or script depends on the command or script.

64 If the return code of the specified command or script is 64 or

higher, 64 is returned as the return code of the plugin.

65 The connection with the Automation Director server failed. For

example, the Automation Director server might have stopped

while the plugin was being executed.

66 The following user is mapped to the Automation Director user:• A user who does not belong to the Administrators group.• A user other than the built-in Administrator who belongs to

the Administrators group, in an environment with UACenabled.

68 There is no information about the target job execution ID.

69 An environment variable of the task-processing engine could

not be acquired.

70 The connection with the operation target device failed.

71 Command execution failed.

72 The execution status of the command could not be acquired.

76 The connection timed out.

77 The host name of the operation target device could not be

resolved.

78 Authentication with the operation target device failed for one

of the following reasons:• Password authentication failed.• Public key authentication has not been set up on the

operation target device.• When the public key was being authenticated, the private

key did not match the pass phrase.• When the public key was being authenticated, the private

key did not correspond to the public key registered in theoperation target device.

• When the public key was being authenticated, an invalidprivate key was used.

80 Task execution has stopped.

81 The plug-in was called in an invalid status.

82 The request message from the task-processing engine could

not be correctly parsed.

83 The environment of the Automation Director server is

corrupted.



84 Information about the specified plug-in could not be obtained.

86 The specified property value is invalid.

127 Another error has occurred.

Property list

The following properties are available for the General Command plug-in:

Property key Property name DescriptionDefaultvalue

I/Otype

Required

destinationHost Destination Host Specify the IPv4 address, IPv6address, or host name of theoperation target device. The hostname should be within 1,024characters. The AutomationDirector server and the operationtarget device must be connectedby a network. Note that multiple IPaddresses or host names cannot bespecified.

-- Input R

credentialType Credentials Type As the authentication type to useduring command or scriptexecution, specify either of thefollowing:DestinationSpecify this option to use theauthentication information set inthe Agentless Remote Connectionsview. Specifying destination appliesthe authentication information setfor Windows or SSH in theconnection destination definitionaccording to the IP address of theAutomation Director login user. Youcan omit the specification ofproperties relating toauthentication information(account, password, suPassword,publicKeyAuthentication), andkeyboardInteractiveAuthentication.

PropertySpecify this option to use thevalues specified in the followingproperties as authenticationinformation:

-- Input R



I/Otype

Required

• account• password• suPassword• publicKeyAuthentication• keyboardInteractiveAuthenticati

on

account User ID Specify the user ID to use to log into the operation target device,using a maximum of 256characters.You can also specify a domain userin either of the following formats:• domain-name \ user-name• user-name @ domain-name

-- Input O

password Password Specify the password to use to login to the operation target device,using a maximum of 256characters. You can omit thisproperty when the operation targetdevice is running UNIX and true isspecified for thepublicKeyAuthentication property.

-- Input O

suPassword Root Password If the OS of the operation targetdevice is UNIX, specify the rootpassword using a maximum of 256characters. If the OS is Windows,this property does not need to bespecified. You can also omit thisproperty when the operation targetdevice is running Windows, orwhen false is specified for theelevatePrivileges property.

-- Input O

runAsSystem Run as systemaccount

When running on a Windows host,you can specify true to run thecommand using the systemaccount or false to allow thecommand to run using anotherconnected user. The connecteduser becomes the user specifiedfor Agentless Remote Connectionsor plug-in properties, regardless ofthe specification of this property.The values are not case sensitive.If you do not specify a value, falseis assumed. If the OS of the

false Input O



I/Otype

Required

destination host is not Windows,this value is ignored.

publicKeyAuthentication

SSH public keyauthenticationsetting

If the OS of the operation targetdevice is UNIX, specify either ofthe following depending onwhether you want to use publickey authentication. The values arenot case sensitive. If you do notspecify a value, false is assumed.You can omit this property whenthe operation target device isrunning Windows.true

Specify this option to use publickey authentication.

false

Specify this option to use passwordor keyboard interactiveauthentication.

false Input O

keyboardInteractiveAuthentication

SSH KeyboardInteractiveAuthentication

Controls whether or not to use SSHkeyboard interactive authenticationfor the Linux/UNIX environment. Ifthe operating system of thedestination is Linux/UNIX, thesystem toggles between using andnot using keyboard interactiveauthentication. If the property isset to true, keyboard interactiveauthentication is used. If theproperty is set to false, keyboardinteractive authentication is notused. This property is not case-sensitive. This property is validonly when publicKeyAuthenticationis set to false. If this property doesnot exist (which is true for aprevious plug-in version) or if novalue is specified, false is assumedfor the property.

false Input O

elevatePrivileges ElevatePrivileges

If the OS of the operation targetdevice is UNIX, specify either ofthe following depending onwhether you want to elevate theuser to root privileges. The valuesare not case sensitive. If you donot specify a value, true is

false Input O



I/Otype

Required

assumed. You can omit thisproperty when the operation targetdevice is running Windows.true

Specify this option to executecommands as a user with rootprivileges.

false

Specify this option to executecommands without elevating theuser to root. Commands areexecuted with the privileges of theconnection user.

commandLine Command Line Specify the absolute path of thecommand or script to be executedon the operation target device,using a maximum of 256characters. In Windows, theexecution user is changedaccording to the specification ofthe plug-in property"runAsSystem". Special charactersthat represent environmentvariables in the command line arenot escaped. To handle a specialcharacter as a character string,escape the character with apercent sign (%) in Windows, anda backslash (\) in UNIX. Thecommand or script is executedsubject to the privileges of thefollowing user:When the operation target deviceis running Windows• If destination is specified for

the credentialType property, thecommand is executed with theprivileges of the user set in theAgentless Remote Connectionsview.

• If property is specified for thecredentialType property, thecommand is executed with theprivileges of the user specifiedin the account property.

When the operation target deviceis running UNIX

-- Input R



I/Otype

Required

• If destination is specified forthe credentialType property, thecommand is executed with theprivileges of the root user orthe user set in the AgentlessRemote Connections view,depending on the value of theelevatePrivileges property.

• If property is specified for thecredentialType property, thecommand is executed with theprivileges of the root user orthe user specified in theaccount property, depending onthe value of theelevatePrivileges property.

commandLineParameter

Command LineParameter

Specify the arguments of thecommand or script using amaximum of 1,024 characters.

As the command line parameters,specify characters that can beentered in command lines in theOSs of the Automation Directorserver and the operation targetdevice. Special characters thatrepresent environment variables inthe command line are not scaped.To handle a special character as acharacter string, escape thecharacter with a percent sign (%)in Windows, and a backslash (\) inUNIX. You can also specify anenvironment variable as the valueof a command line parameter. Thespecification format depends onthe OS of the operation targetdevice.

If the operation target device isrunning Windows:

% environment-variable %

If the operation target device isrunning UNIX:

$ environment-variable

-- Input O

outputCondition OutputCondition

Specifies a condition to be outputto the standard output property1-3. You can specify the followingvalues:• - always -- Outputs a null

character even if it does notmatch the specified pattern.

Always Input O



I/Otype

Required

• - patternMatch -- Outputs onlywhen matching the standardoutput pattern 1-3.

If there is no output in outputproperties, mapped serviceproperties are also not updated.

stdoutProperty1 Standard OutputProperty 1

The character string extracted bythe stdoutPattern1 property isoutput to this property.

-- Output O

stdoutPattern1 Standard OutputPattern 1

Specify the regular expressionpattern of the standard output tooutput to the stdoutProperty1property, using a maximum of1,024 characters. Specify theregular expression pattern in aPCRE-compliant format. If youspecify the key of a serviceproperty in the stdoutProperty1property but do not specify thestdoutPattern1 property, the entirestandard output and standard erroroutput of the command or scriptspecified in the commandLineproperty is assigned to the serviceproperty.

Input



-- Output O



Input O



I/Otype

Required



-- Output O



Input O

The standard output or standard error output of the commands or scriptsspecified in these properties are output as the standard output of the step inAutomation Director. However, processing for which the total standard outputand standard error output of the command or script exceeds 100 KB isoutside the scope of product support. Execute the command or script inadvance to make sure that the total standard output and standard erroroutput does not exceed 100 KB.

If the operation target device is running Windows, the content specified inthe commandLine and commandLineParameter properties are made into abatch file and executed on the operation target device. Therefore, the resultof this action might differ from the result if the same command and scriptwere executed from the command prompt.

If the operation target device is running UNIX, linefeed codes in standardoutput and standard error output are changed as follows:• CR(0x0d) is changed to LF(0x0a)• CR+LF(0x0d0a) is changed to LF+LF(0x0a0a)

In addition, if the character string at the end of the standard output andstandard error output is not a linefeed code (CR, LF, or CR+LF), LF(0x0a) isadded to the end.


Usage example of stdoutPattern and stdoutProperty properties

By using the stdoutPattern property, you can extract the value output tostandard output and store it in the stdoutProperty property. The followingfigure shows the data flow when specifying aaabbb(.*) in stdoutPattern1.

As defined in stdoutPattern1, for the standard output aaabbbccc, the valueafter aaabbb (in this case ccc) is extracted. The extracted value is stored inthe stdoutProperty1 property.

Specifying the SSH port number

You can specify a port number when using SSH to connect to the operationtarget device. The following table describes how to specify the port numberand priority of each method.

Priority

Set in Property keyDefaultvalue

1 Connection-destination property file (connection-destination-name.properties)

ssh.port --

2 Property file (config_user.properties) ssh.port.number 22

File-Transfer Plug-inThe File-Transfer Plug-in transfers a file or folder to or from a remote host.

If you have pre-set authentication information in the Agentless RemoteConnections view, you can execute the File-Transfer Plug-in by specifying thefollowing information:• Operation target device (remoteHost property)• Transfer mode (transferMode property)• Path of a file or folder on the Automation Director server (localFilePath

property)• Path of a file or folder on the operation target device (remoteFilePath

property)


In the file path for forwarding to the agentless connection destination, specifycharacters that can be used in commands in the operating systems of theAutomation Director server and the operation target device. For example, ifthe Automation Director server and the operation target device are bothrunning the Japanese version of Windows, characters in the MS932 characterset can be specified.

If destination host is a Automation Director server (localhost), the user IDand the password are unnecessary.

If the operation target device is running Windows, the file is transferred bythe user set in the authentication information.

If the operation target device is running UNIX, the file is transferred subjectto the privileges of the root user or the connection user, depending on thevalue of the elevatePrivileges property.

Note: If the local execution function is enabled, the file is not forwarded. Ifthe OS of the local host is Windows, the file is copied to the local host withthe privileges of the System account. If the OS of the local host is Linux, thefile is copied to the local host with root user privileges.


Depending on the OS of the operation target device, configure theenvironment as follows:

For Windows• Make sure that the Automation Director server and operation target device

are able to communicate using the appropriate ports.• Before executing the file-forwarding plug-in, enable administrative sharing

on the operation target device.

For Unix• You can set the port number used by SSH in the connection-destination

property file (connection-destination-name.properties) or theproperties file (config_user.properties).

• On the operation target device, install a SSH server that supports SCP.

Certain commands must be installed in the operating system of the operationtarget device before you use the File-Transfer Plug-in.

Cautionary notes• IPv6 is not supported when Automation Director is running on Linux and

the destination host is Windows.• The execution method differs depending on the OS of the operation target

device. File transfer is implemented by RPC and CIFS (SMB) in Windows,and SSH and SCP in UNIX. When selecting a protocol in the definition of an


agentless connection destination, select Windows in Windows and SSH inUNIX.

• The maximum total size of all transferred files is 4 GB.• The maximum number of files and folders that can be transferred at a time

is 10,000.• If a received file has the same name as a file that exists locally, the system

might attempt to overwrite the file. However, if the file to be overwrittenhas the attribute Read only, Hidden file, or System file, the file cannot beoverwritten and file transfer fails.

• You cannot specify a Windows UNC path or a network drive as the sourceor destination of a file transfer.

• On the machine where Automation Director is installed and theconnection-destination host, in addition to the free space needed for thefiles and folders themselves, an amount of free space equivalent to twicethe size of the transferred files is required as a temporary work area. Thetemporary work area is as follows:○ For the machine where Automation Director is installed (non-cluster

environment): The drive where Automation Director is installed.○ For the machine where Automation Director is installed (cluster

environment): The shared disk.○ When the connection-destination is running Windows: The system drive.○ When the connection-destination is running UNIX: The folder specified

in the plugin.remoteCommand.workDirectory.ssh key in the property fileconfig_user.properties).

• The limitations of the operating system override those set in theAutomation Director system. Examples of these limitations include themaximum size of a file, the number of files per folder, the length of file andfolder names, and the resources available to the user. File forwarding thatexceeds the limitations of the operating system is outside the scope ofproduct support. The operating systems whose limitations affectAutomation Director operation are those on the Automation Director serverand on operation target devices. The OS limitations that govern whichresources are available to users are those set for the connection user andfor users with root privileges. Limitations for users with root privileges onlyapply in UNIX.

• When you specify a folder on a host running UNIX as the file-transferingdestination, the process might fail if the total size of the files in the folderexceeds the maximum permitted size for one file. The maximum size forone file is governed by file system restrictions and OS limitations thatapply to the resources available to the user. Automation Director archivesfiles before sending them, which means that the limits of the destinationhost might be exceeded despite the individual files in the archive beingsmaller than the maximum size. In this scenario, either reduce the totalsize of the files in the folder you are sending, or increase the limits at thedestination.


• If execution of a task is stopped during plug-in execution, the status of thetask becomes Failed or Completed when the processing of the File-TransferPlug-in has finished. The status of steps and tasks after plug-in executionhas finished depends on the return code of the step and the condition forexecuting subsequent steps. You can set Subsequent-step ExecutionCondition in the Create Step dialog box or the Edit Step dialog box.

Return codes

The following return codes are generated by the File-Transfer Plug-in:


0 Ended normally.



while the plug-in was executing.





not be acquired.


71 An attempt to call a command on the operation target device

failed.

72 The execution status of the command could not be acquired.

73 The file or folder could not be transferred.



resolved.

78 Authentication with the operation target device failed for one

of the following reasons:• Password authentication failed.• Public key authentication has not been set up on the

operation target device.• When the public key was being authenticated, the private

key did not match the pass phrase.• When the public key was being authenticated, the private

key did not correspond to the public key registered in theoperation target device.

• When the public key was being authenticated, an invalidprivate key was used.








corrupted.




Property list

The following properties are available for the File-Transfer Plug-in:

Property keyPropertyname

DescriptionDefaultvalue

I/Otype

Required

remoteHost Remote Host Specify the IPv4 address, IPv6address, or host name of theoperation target device. The hostname should be within 1,024characters. The AutomationDirector server and the operationtarget device must be connectedby a network. Note that multipleIP addresses or host namescannot be specified.

-- Input R

credentialType CredentialsType

As the authentication type to useduring command or scriptexecution, specify either of thefollowing:DestinationSpecify this option to use theauthentication information set inthe Agentless RemoteConnections view. Specifyingdestination applies theauthentication information set forWindows or SSH in theconnection destination definitionaccording to the IP address ofthe Automation Director loginuser. You can omit thespecification of propertiesrelating to authentication

destination Input R




I/Otype

Required

information (account, password,suPassword,publicKeyAuthentication), andkeyboardInteractiveAuthentication.

PropertySpecify this option to use thevalues specified in the followingproperties as authenticationinformation:• account• password• suPassword• publicKeyAuthentication• keyboardInteractiveAuthentic

ation

account User ID Specify the user ID to use to login to the operation target device,using a maximum of 256characters.You can also specify a domainuser in either of the followingformats:• domain-name \ user-name• user-name @ domain-name

-- Input O

password Password Specify the password to use tolog in to the operation targetdevice, using a maximum of 256characters. You can omit thisproperty when the operationtarget device is running UNIXand true is specified for thepublicKeyAuthentication property.

-- Input O

suPassword RootPassword

If the OS of the operation targetdevice is UNIX, specify the rootpassword using a maximum of256 characters. If the OS isWindows, this property does notneed to be specified. You canalso omit this property when theoperation target device isrunning Windows, or when falseis specified for theelevatePrivileges property.

-- Input O


SSH publickeyauthentication setting

If the OS of the operation targetdevice is UNIX, specify either ofthe following depending onwhether you want to use public

false Input O




I/Otype

Required

key authentication. The valuesare not case sensitive. If you donot specify a value, false isassumed. You can omit thisproperty when the operationtarget device is runningWindows.true

Specify this option to use publickey authentication.

false

Specify this option to usepassword or keyboard interactiveauthentication.


SSHKeyboardInteractiveAuthentication

Controls whether or not to useSSH keyboard interactiveauthentication for the Linux/UNIXenvironment. If the operatingsystem of the destination isLinux/UNIX, the system togglesbetween using and not usingkeyboard interactiveauthentication. If the property isset to true, keyboard interactiveauthentication is used. If theproperty is set to false, keyboardinteractive authentication is notused. This property is not case-sensitive. This property is validonly whenpublicKeyAuthentication is set tofalse. If this property does notexist (which is true for a previousplug-in version) or if no value isspecified, false is assumed forthe property.

false Input O

elevatePrivileges ElevatePrivileges

If the OS of the operation targetdevice is UNIX, specify either ofthe following depending onwhether you want to elevate theuser to root privileges. Thevalues are not case sensitive. Ifyou do not specify a value, trueis assumed. You can omit thisproperty when the operationtarget device is runningWindows.

false Input O




I/Otype

Required

true

Specify this option to executecommands as a user with rootprivileges.

false

Specify this option to executecommands without elevating theuser to root. Commands areexecuted with the privileges ofthe connection user.

transferMode TransferMode

Specify either of the following asthe transfer mode:send

Specify this option whentransferring a file or folder fromthe Automation Director server tothe operation target device.When you specify a file path inthe localFilePath property, thesame path must be specified inthe remoteFilePath property.When transferring a single file, ifyou specify different file namesin the localFilePath andremoteFilePath properties, thefile name specified in theremoteFilePath property applies.

receive

Specify this option whentransferring a file or folder fromthe operation target device to theAutomation Director server.When you specify a file path inthe remoteFilePath property, thesame path must be specified inthe localFilePath property. Whentransferring a single file, if youspecify different file names in theremoteFilePath and localFilePathproperties, the file namespecified in the localFilePathproperty applies.

send Input R

localFilePath Local FilePath

Specify the absolute path of thefile or folder on the AutomationDirector server using no morethan 256 characters. In thelocalFilePath property, specifycharacters that can be used incommands in the operatingsystems of the AutomationDirector server and the operation

-- Input R




I/Otype

Required

target device. If there is a file orfolder with the same name in thedestination folder, the file orfolder is overwritten. For thisreason, we recommend that youspecify a unique name. If thedestination folder does not exist,the folder will be created in thespecified configuration.

remoteFilePath Remote FilePath

Specify the absolute path of thefile or folder on the operationtarget host in no more than 256characters. In the remoteFilePathproperty, specify characters thatcan be used in commands in theoperating systems of theAutomation Director server andthe operation target device. Ifthe OS of the operation targetdevice is UNIX, make sure thatthe names of the files and foldersyou are transferring are encodedin the same character set usedby the connection user. If there isa file or folder with the samename in the destination folder,the file or folder is overwritten.For this reason, we recommendthat you specify a unique name.If the destination folder does notexist, the folder will be created inthe specified configuration.

-- Input R

When specifying file paths, use characters that can be used in commands inthe operating systems of the Automation Director server and the operationtarget device. When specifying a file name in the localFilePath property, alsospecify a file name in the remoteFilePath property. When specifying a foldername in the localFilePath property, also specify a folder name in theremoteFilePath property.

Restrictions apply to the files and folders you can specify in the localFilePathand remoteFilePath properties.

If the operation target device is running Windows and a file with the Windowsfile attribute "Encrypt contents to secure data" is included among thetransferred files, the transfer of the file fails, causing an error in theprocessing of the plug-in.


Restrictions on the names of transferred files and folders

The following table lists the restrictions that apply to the names oftransferred files and folders when the connection destination is Windows,Linux, or Solaris:

Note: Exceptions for AIX and HP-UX are shown in parentheses.

Sending orreceiving

File orfolder

HADside ordestination hostside

Property Restrictions

Sending File HAD localFilePath File names can be a maximum of 127characters.

Destination host

remoteFilePath File names can be a maximum of 127characters (or 96 bytes for AIX or HP-UX).

Folder HAD localFilePath The longest absolute path of the file or folderin the transferred folder can contain no morethan 256 characters.

The longest path from the folder beingtransferred to a file or folder under that foldermust be no longer than 127 characters (or 96bytes for AIX or HP-UX).

Destination host

remoteFilePath The longest absolute path of the file or folderin the transferred folder can contain no morethan 256 characters.

The longest path from the folder beingtransferred to a file or folder under that foldermust be no longer than 127 characters.

Receiving

File HAD localFilePath File names can be a maximum of 127characters.

Destination host

remoteFilePath File names can be a maximum of 127characters (or 96 bytes for AIX or HP-UX).

Folder HAD localFilePath The longest absolute path of the file or folderin the transferred folder can contain no morethan 256 characters.

The longest path from the folder beingtransferred to a file or folder under that foldermust be no longer than 127 characters.

Destination host

remoteFilePath The longest absolute path of the file or folderin the transferred folder can contain no morethan 256 characters.

The longest path from the folder beingtransferred to a file or folder under that foldermust be no longer than 127 characters (or 96bytes for AIX or HP-UX).


Specifying the SSH port number

You can specify a port number when using SSH to connect to the operationtarget device. The following table describes how to specify the port numberand the priority of each method.

Priority Set in Property key Default value

1 Connection-destinationproperty file(connectiondestination-name.properties)

ssh.port --

2 Property file(config_user.properties)

ssh.port.number 22

Handling of forwarded files

Forwarded files are handled differently depending on the OS of the operationtarget device and the value specified in the transferMode property. Thefollowing table describes how forwarded files are handled:

ItemWindows

sendreceive

Unix

sendreceive

Time stampof forwardedfile

Whencreating afile

Creationdate andtime

Date andtime offorwarding




Update dateand time

Update dateand time ofsource file




Access dateand time





Whenoverwritinga file

Creationdate andtime

Creationdate andtime ofoverwrittenfile




Update dateand time





Access dateand time

Access dateand time ofoverwrittenfile




Access permissions required for sourcefile

Systemaccount readprivilege



Readprivilege of


ItemWindows

sendreceive

Unix

sendreceive

connectionuser

Access permissions required for parentfolder of destination file

Writeprivilege ofthe user setin theauthenticationinformation

Systemaccountwriteprivilege

Writeprivilege ofconnectionuser


Access permissions required fordestination file when overwriting the file

Writeprivilege ofthe user setin theauthenticationinformation


Writeprivilege ofconnectionuser


Accesspermissionassigned todestinationfile

Whencreating afile

Inheritsprivilege ofparent folder

Inheritsprivilege ofparent folder

Uses theumask valueof root ortheconnectionuser

Inheritsprivilege ofparentfolder

Whenoverwritinga file

Inheritsprivilege ofoverwrittenfile




Repeated Execution Plug-inThe Repeated execution plug-in executes a specific flow repeatedly.

You can execute a service with a value specified in the Input Properties(inputProperties) for each iteration of the flow. This is useful, for example,when you want to execute the same processing on different servers. Notethat the execution methods for a flow include concurrent execution thatexecutes flows in parallel, and sequential execution that executes the nextflow when the current flow has finished executing. In addition, RepeatedExecution Plug-in can have a nested structure, and it is possible to define thenest of Repeated Execution Plug-in up to 3 levels. When used in thecombination with the Flow Plug-in, up to 25 levels can be defined togetherwith the Flow Plug-in.

The Repeated Execution Plug-in can have a nested structure, and it ispossible to define the nest of Repeated Execution Plug-in up to 3 levels.


When used in the combination with the Flow Plug-in, up to 25 levels can bedefined together.

Cautionary notes• If the parallel option is specified in the foreachMode property, the value of

the properties (service properties, plug-in output properties, variables)referenced or updated in the context of a repeated task are only valid forthe same repeated task (the nth flow). Additionally, the value of theproperty (service property, plug-in output property, variable) cannot beshared with concurrently processed, repeated tasks (except for the nthflow) or shared with the repeated tasks of a lower level.

The following figure shows how the plug-ins in each level reference an outputproperty updated by plug-in Z.


Restrictions on the number of flows

The maximum number of flows that can be specified for a RepeatedExecution Plug-in is set through the inputProperties property and cannotexceed 10,000 per service. Note that the total number of flows does notinclude the number of flows executed in the top-level flow or the flowsassociated with the Flow Plug-in.

If the number of flows under repetition in the service increases, the responsemay be delayed or could even cause the browser to crash. Therefore, theupper limit is set for the number of flows under repetition in the service.

The flow included in the count is only for the Repeated Execution Plug-in,while the flow for the Flow Plug-in is excluded from the counting target.

Type Counting Target

Flow under Repeated Execution Plug-in Yes

Flow by Flow Plug-in Yes

Other flows No

In the following example, the inputProperties properties of the RepeatedExecution Plug-in is set to repeat plug-in N twice, plug-in M twice, and plug-in Z a total of ten times. Thus, the total number of flows is calculated asfollows: N+N*M+Z (2+2*2+10) = 16.


The input values and loop index for the Repeated Execution plug-in a nestedconfiguration that derives the input values and loop index values using thefollowing reserved properties:• reserved.loop.inputN• reserved.loop.indexN

Note: If the Repeated Execution Plug-in is nested, you could encounterbrowser problems during debugging, in which case, you should reduce thevalue set for the property " inputProperties " for each Repeated ExecutionPlug-in, and then repeat the debugging.

Note: Set the property "inputProperties" for each Repeated Execution Plug-inso that the total number of flows does not exceed 10000. The flows for theFlow Plug-in are not included in the number of flows calculation.

Return Codes

Following are return codes generated by the Repeated Execution Plug-in:



0 Ended normally.

1 Some of the repeated processing failed.

2 All of the repeated processing failed.

3 The total number of flows under the Repeated Execution Plug-in in the service exceeds the upper limit.

65 The connection with the Automation Director server failed. Forexample, the Automation Director server might have stoppedwhile the plugin was being executed.




69 An environment variable of the task-processing engine couldnot be acquired.



82 The request message from the task-processing engine couldnot be correctly parsed.

83 The environment of the Automation Director server iscorrupted.




Property list

Following are the properties for the Repeated Execution Plug-in:



I/O typeRequired

ForeachTask RepeatedlyExecuted Task

Specifies the absolutepathname of the flow to berepeatedly executed. (Thespecified absolute path mustbe a path in the environmentwhere a service template iscreated.) The RepeatedExecution Plug-in cannot be

-- Input R




I/O typeRequired

called recursively inside therepeatedly executed flow.In the editor, specify the stepIF of the Repeated ExecutionPlug-in placed in the flowchart.As the step ID is known, theuser does not need to enter it.If an existing service templateis reused or replicated, the unitname of the RepeatedExecution Plug-in (custom job)is set as the step ID. The nameof the target jobnet is notdisplayed.

inputProperties InputProperties

Specifies an input propertyvalue for each repetition of theflow, using no more than 1,024characters. You can specify adifferent property for eachrepetition. Use a comma toseparate properties. Commascan only be used as delimitingcharacters. The maximumnumber of repetitions is 99.You cannot specify 100 ormore comma separated values.

-- Input R

outputProperties

OutputProperties

Outputs the value of the outputproperty for the number ofrepetitions. The total output is1,024 characters or less. Ateach repetition, one propertyvalue is output separated by acomma in the order specifiedin the inputProperties property.Use a comma as the delimitingcharacter.

-- Output O

outputResult Results The execution result of eachflow is output, separated bycommas.true

Output when the flow isexecuted successfully.

false

Output when execution of theflow fails.

-- Output O

foreachMode Mode Specify the execution methodfor the repeated flow.parallel

parallel Input R




I/O typeRequired

Repeated flows are executed inparallel.

A maximum of 99 flows can beexecuted in parallel. If themaximum is exceeded, theexcess flows are executedwhen the number of executingflows falls below themaximum. You can change thenumber of concurrentlyexecutable flows between 1and 99 using theforeach.max_value key in theproperties file(config_user.properties).Even if an error occurs, all theunexecuted flows will beexecuted.

serial

Repeated flows are executedsequentially. If an error occurs,unexecuted repeated flows arenot executed.

Email Notification Plug-inThe Email notification plug-in sends emails to the specified destination.

This plug-in enables the connection to the SMTP server to transmit email withthe specified recipient, subject, and body.


The following information is obtained from built-in shared service properties.Therefore, set the values for these items in advance in the System Settingsview.• Address of the SMTP server• Port number• User ID• Password• Originator of the notification email

Cautionary notes• Even if you do not specify the toAddress, ccAddress, and bccAddress

properties, the return code will be 0.


• The mail address to be specified differs from the value of the built-inshared service properties. Therefore, make sure that you specify at leastone of the toAddress, ccAddress, and bccAddress properties.

• If any of the toAddress, ccAddress, and bccAddress properties has aninvalid email address specified, email transmission will fail to all theaddresses.

• If you use machine-dependent characters or characters that areincompatible between character sets in the mailSubject or mailBodyproperty, the characters are replaced with question marks (?) or othercharacters. In this scenario, either change the characters in the email, orchange the encoding.

• The following characters might not be converted correctly:

• If the execution of a task is stopped while the plug-in is executing, the

status of the task becomes Failed or Completed when the processing of theemail notification plug-in finishes. The status of steps and tasks after plug-in execution has finished depends on the return code of the step and thecondition for executing subsequent steps. You can set a Subsequent-stepExecution Condition in the Create Step dialog box or the Edit Step dialogbox.

Return codes

The following return codes are generated by the Email Notification Plug-in:


0 Ended normally.








not be acquired.

70 The connection with the SMTP server failed.

78 Authentication failed.



79 Email transmission failed.






corrupted.




Property list

The following properties are available for the Email Notification Plug-in:



I/O typeRequired

toAddress To Addresses Specify the email addresses ofrecipients to enter in the TOattribute, using no more than1,024 characters. Whenspecifying multiple addresses,separate them with commas.

-- Input O

ccAddress Cc Addresses Specify the email addresses ofrecipients to enter in the CCattribute, using no more than1,024 characters. Whenspecifying multiple addresses,separate them with commas.

-- Input O

bccAddress Bcc Addresses Specify the email addresses ofrecipients to enter in the BCCattribute, using no more than1,024 characters. Whenspecifying multiple addresses,separate them with commas.

-- Input O

encodeType Encoding Specify the encoding of theemail as one of the following:• us-ascii• iso-2022-jp• shift_jis• euc-jp• utf-8

utf-8 Input R




I/O typeRequired

mailSubject Subject Specify the subject line of theemail using no more than 256characters.

-- Input R

mailBody Body Specify the body text of theemail using no more than 1,024characters.

-- Input O

User-Response Wait Plug-inThe User-Response Wait Plug-in enables the operator to select the processingof the succeeding step during the execution of the service. .

To select the processing, the operator uses the Respond dialog box. You canalso set up email notification to notify the operator that a task is waiting for aresponse.

The methods of accessing the Respond dialog box are as follows:• Linking from the URL in the response wait notification mail• Linking from the Tasks view


The following information is obtained from built-in shared service properties.Therefore, if you want the operator to be notified when a task is waiting for aresponse, set the values for these items in advance in the System Settingsview.• Address of the SMTP server• Port number• User ID• Password• Originator of the notification email

Cautionary notes• The email reporting that a task is waiting for a user response is not sent if

any of the following applies:○ No value is set in the built-in shared service property○ SMTP has not been set up○ None of the toAddress, ccAddress, and bccAddress properties are

specified○ An invalid email address is specified in any of the toAddress, ccAddress,

and bccAddress properties• The mail address to be specified differs from the value of the built-in

shared service properties. Therefore, make sure that you specify at leastone of the toAddress, ccAddress, and bccAddress properties.


• Do not stop the execution of the user-response wait plug-in while theRespond dialog box is displayed and waiting for operator response.Stopping the execution causes an error even if the operator selects theprocessing for the subsequent step.

• A URL that links to the Respond dialog box is automatically entered in thebody of the notification email. If more than one step in a given task iswaiting for a response, each step that executes the user-response waitplug-in will have a different URL, with each URL displaying the Responddialog box for that step.

• You cannot change the layout of the Respond dialog box.• Any return code from the properties labelButton1 to labelButton9 is

considered an abnormal end, and error information is output to the tasklog. For the labelButton0 property and the properties labelButton1 tolabelButton9, if the output log level is 10 or 20, the details to be output inthe task log differ depending on the response result.

• If you use machine-dependent characters or characters that areincompatible between character sets in the mailSubject or mailBodyproperty, the characters are replaced with question marks (?) or othercharacters. In this scenario, either change the characters in the email, orchange the encoding.

• The following characters might not be converted correctly:

Return codes

The following return codes are generated by the User-Response Wait Plug-in:


0-9 Returns the return code corresponding to the labelButton1 to

labelButton9 properties. If a timeout occurs while waiting for a

response, the value specified in the timeOutDefault property is

returned as the return code. Therefore, the meaning of the

return code depends on the service template that is using the

plug-in.

10-63 If a timeout occurs while waiting for a response, the value

specified in the timeOutDefault property is returned as the

return code.




66 The following user is mapped to the Automation Director user:• A user who does not belong to the Administrators group.



• A user other than the built-in Administrator who belongs tothe Administrators group, in an environment with UACenabled.



not be acquired.






corrupted.


86 The value set for the mapping parameter in the Response

Input dialog is contrary to the property restriction.


Property list

The following properties are available from the User-Response Wait Plug-in:



I/O typeRequired

toAddress To Addresses Specify the email addresses ofrecipients to enter in the TOattribute, using no more than1,024 characters. Whenspecifying multiple addresses,separate them with commas.

-- Input O

ccAddress Cc Addresses Specify the email addresses ofrecipients to enter in the CCattribute, using no more than1,024 characters. Whenspecifying multiple addresses,separate them with commas.

-- Input O

bccAddress Bcc Addresses Specify the email addresses ofrecipients to enter in the BCCattribute, using no more than1,024 characters. Whenspecifying multiple addresses,separate them with commas.

-- Input O




I/O typeRequired

mailSubject Subject Specify the subject line of theemail using no more than 256characters.

-- Input O

mailBody Body Specify the body text of theemail using no more than1,024 characters.

-- Input O

encodeType Encoding Specify the encoding of theemail as one of the following:• us-ascii• iso-2022-jp• shift_jis• euc-jp• utf-8

utf-8 Input O

dialogText ResponseInput DialogBox

Specify the information todisplay in the Respond dialogbox. You can specify theinformation in text or HTMLformat.

-- Input R

responseTimeOut

ResponseTimeout

Specify the time period,between 1 and 20,160 (inminutes), before timeoutoccurs while waiting for aresponse.

1440 Input R

timeOutDefault

Default ReturnValue

Specify the return code toreturn when a timeout occurswhile waiting for a response.When the timeout period haspassed, this value is returnedas the return code. Forexample, when 0 is specifiedand the timeout periodelapses, the processingcorresponding to the buttonassociated with thelabelButton0 property will beexecuted. Specify a returncode in the range from 0 to 63.

0 Input R

labelButton0 Label Button 0 Specify the button label for theresponse that generates returncode 0, using a maximum of256 characters. You can displaybuttons that meets the user'soperational needs in theRespond dialog box.

-- Input O

labelButton1 Label Button 1 Specify the button label for theresponse that generates return

-- Input O




I/O typeRequired

code 1, using a maximum of256 characters. You can displaybuttons that meets the user'soperational needs in theRespond dialog box. If youomit this property, thecorresponding button is notdisplayed.

labelButton2 Label Button 2 Specify the button label for theresponse that generates returncode 2, using a maximum of256 characters. You can displaybuttons that meets the user'soperational needs in theRespond dialog box. If youomit this property, thecorresponding button is notdisplayed.

-- Input O


-- Input O


-- Input O

labelButton5 Label Button 5 Specify the button label for theresponse that generates returncode 5, using a maximum of256 characters. You can displaybuttons that meets the user'soperational needs in theRespond dialog box. If youomit this property, the

-- Input O




I/O typeRequired

corresponding button is notdisplayed.


-- Input O


-- Input O


-- Input O


-- Input O

HTML tags and attributes that can be specified in the dialogText property

When specifying the display contents in the dialogText property in HTMLformat, use the tags listed in the following table:


Tag Attribute Notes and restrictions

Anchor tag (<a>) When using the <a> tag, thetarget attribute must be leftblank. If this tag is notspecified, a page is loaded intothe Response Input dialogbox.

href -

target Specify "_blank."

Bold tag (<b>) -

Break tag (<br>) -

Font tag (<font>) color -

face -

size -

Italic tag (<i>) -

Underline tag (<u>) -

Form tag (<form>) -

Input tag (<input>) It is common to be enclosedwith form tags, but since it isnot required to be sent, there isno need to be enclosed withform tags.

name If you specify the serviceproperty key, you can changethe mapping parameter of theservice property specified in theResponse Input dialog whilewaiting for a response.

type "text", "checkbox", "radio" canbe specified.

value When the type attribute is"checkbox", "radio", set thevalue attribute. The value set inthe value attribute of the itemchecked with the check box orthe radio button becomes themapping parameter of theservice property specified bythe name attribute.

Select tag (<select>) name If you specify the serviceproperty key, you can changethe mapping parameter of theservice property specified in the


Tag Attribute Notes and restrictions

Response Input dialog whilewaiting for a response.

Option tag (<option>) Use select tags to enclose.

value The value set in the valueattribute of the item selected inthe select menu or the list boxbecomes the mappingparameter of the serviceproperty specified by the nameattribute of the select tag.

Terminal Connect Plug-inAllows terminals to establish connections.

The Terminal Connect Plug-in allows you to connect to an operation targetdevice by using Telnet or SSH and perform authentication.

When connecting by Telnet, set the user ID and password as needed. ForSSH connections, you can select password authentication, public keyauthentication, or keyboard interactive authentication as the authenticationmethod. You need to set the following information in the plug-in properties orfrom the Agentless Remote Connections view.• Authentication method (password authentication, public key authentication

or keyboard interactive authentication)• Information required for password authentication (user ID and password)• Information required for public key authentication (user ID)• Information required for keyboard interactive authentication (user ID and

password)

The commands specified in the terminal command plug-in are executed withthe privileges of the user authenticated by the terminal connect plug-in. Toexecute a command with administrator privileges, you need to execute thecommand in the terminal command plug-in that elevates the user toadministrator privileges.

Prerequisites for execution• The plug-in uses the protocol specified in the protocol property to

communicate with the Automation Director server.• When connecting by Telnet, the plug-in detects when the operation target

device is prompting the operator for a user ID and password. Set one ofthe following files as needed. If you set both files, Automation Directoruses the values set in the connection-destination property file(connection-destination-name.properties).


○ telnet.prompt.account and telnet.prompt.password in the connection-destination property file (connection-destination-name.properties)

○ plugin.terminal.prompt.account and plugin.terminal.prompt.password inthe properties file (config_user.properties)

Cautionary notes• The plug-in waits for standard output for the length of time specified in the

readWaitTime property. If the time specified in readWaitTime elapses afteroutput to standard output has ceased, plug-in execution ends in an error.Make sure that the value of the readWaitTime property is appropriatebefore using the plug-in.

• If the value output to standard output matches the regular expressionpattern specified in the promptPattern property, the plug-in terminatesimmediately.

• After using Telnet to establish a connection to an operation target device,the plug-in waits for standard output and standard error output for thelength of time set in the telnet.connect.wait property in the properties file(config_user.properties). If the connection destination service is a Webserver or other entity that does not produce standard output or standarderror output, set the port number of the service in thetelnet.noStdout.port.list property of the connection-destination propertyfile (connection-destinationname.properties). If you set the portnumber, the plug-in finishes executing without waiting for standard outputor standard error output.

• If the execution of a task is stopped while the plug-in is executing, thestatus of the task becomes Failed or Completed when the processing of theterminal connect plug-in finishes. The session and token are thendiscarded. The status of steps and tasks after plug-in execution hasfinished depends on the return code of the step and the condition forexecuting subsequent steps. You can set a Subsequent-step ExecutionCondition in the Create Step dialog box or the Edit Step dialog box.

• The terminal connect plug-in maintains the connection even if Telnetauthentication fails. To terminate the connection, you need to execute aterminal disconnect plug-in. However, if the task enters Failed orCompleted status, the connection is terminated automatically and you donot need to execute the terminal disconnect plug-in.

• The standard output and standard error output of a terminal connect plug-in is output as the standard output of the Automation Director step. Thesize of the standard output and standard error output is the total numberof bytes received by Automation Director. If the Telnet server or SSHserver is configured to replace the linefeed character LF with CR+LF, allowtwo bytes for each linefeed character. The results of processing whose totalstandard output and standard error output exceeds 100 KB is outside thescope of product support. Make sure that the total standard output andstandard error output does not exceed 100 KB.


• The terminal connect plug-in cannot detect authentication errors in Telnetconnections. For this reason, specify a regular expression pattern thatdetects authentication errors in standard output and standard error outputin any of stdoutPattern1 to stdoutPattern3.

• When the Terminal Connect Plug-in version is less than 02.00.00,"patternMatch" is set in "outputCondition" . But, the default value of"outputCondition" is "always" in the case of version 02.00.00. When youupgrade Terminal Connect Plug-in, please keep this in mind.

Return codes

The following return codes are generated by the Terminal Connect Plug-in:


0 - 63 If standard output or standard error output matches the

regular expression pattern specified in the returnCodePattern

property, the plug-in returns the return code specified in the

returnCode property. If standard output and standard error

output do not match the pattern specified in the

returnCodePattern property, the plug-in returns the return

code specified in the defaultReturnCode property. Therefore,

the meaning of the return code depends on the service

template that is using the plug-in.








not be acquired.




resolved.

78 When connecting by SSH, authentication on the operation

target device failed.








corrupted.



87 Standard output and standard error output have timed out.

88 The maximum number of tokens (99 per task) has been

reached. The total standard output and standard error output

has exceeded 100 KB.


Property list

The following properties are available for the Terminal Connect Plug-in:


Description

Defaultvalue

I/O typeRequired

destinationHost DestinationHost

Specify the IPv4 address,IPv6 address, or host name ofthe operation target deviceusing no more than 1,024characters. Multiple IPaddresses or host namescannot be specified.

-- Input R

protocol Protocol Specify the protocol to usewhen connection to theoperating target device. Youcan specify the followingprotocols:• Telnet• SSH

Telnet

Input O

credentialType CredentialsType

As the authentication type touse during command or scriptexecution, specify either ofthe following:DestinationSpecify this option to use theauthentication information setin the Agentless Remote

-- Input R



Description

Defaultvalue

I/O typeRequired

Connections view. Specifyingdestination applies theauthentication information setfor Telnet or SSH in theconnection destinationdefinition according to the IPaddress of the AutomationDirector login user. You canomit the specification ofproperties relating toauthentication information(account, password,suPassword,publicKeyAuthentication, andkeyboardInteractiveAuthentication).

PropertySpecify this option to use thevalues specified in thefollowing properties asauthentication information:• account• password• suPassword• publicKeyAuthentication• keyboardInteractiveAuthe

ntication

account User ID Specify the user ID to use tolog in to the operation targetdevice, using a maximum of256 characters.This property is required ifboth of the following are true:• SSH is specified in the

protocol property.• property is specified in the

credentialType property.

-- Input O

password Password Specify the password to useto log in to the operationtarget device, using amaximum of 256 characters.This property is required if allof the following conditions aremet:• SSH is specified in the

protocol property.

-- Input O



Description

Defaultvalue

I/O typeRequired

• property is specified in thecredentialType property.

• false is specified in thepublicKeyAuthenticationproperty.

If the OS of the operationtarget device is UNIX and trueis specified for thepublicKeyAuthenticationproperty, any value youspecify is ignored. You can,however, set a value for thereserved.terminal.passwordreserved property toreference.

suPassword Administrator Password

Specify the password requiredto elevate the user toadministrator privilege, usinga maximum of 256characters. The value of thesuPassword property isassigned to thereserved.terminal.suPasswordproperty when you specify thelatter in the command line ora terminal command plug-in.

-- Input O


SSH publickeyauthentication setting

If the OS of the operationtarget device is UNIX, specifyeither of the followingdepending on whether youwant to use public keyauthentication. The values arenot case sensitive. If you donot specify a value, false isassumed. You can omit thisproperty when the operationtarget device is runningWindows.true

Specify this option to usepublic key authentication.

false

Specify this option to usepassword authentication orkeyboard interactiveauthentication.

false Input O



Description

Defaultvalue

I/O typeRequired


SSHKeyboardInteractiveAuthentication

Controls whether or not touse SSH keyboard interactiveauthentication for the Linux/UNIX environment. If theoperating system of thedestination is Linux/UNIX, thesystem toggles between usingand not using keyboardinteractive authentication. Ifthe property is set to true,keyboard interactiveauthentication is used. If theproperty is set to false,keyboard interactiveauthentication is not used.This property is not case-sensitive. This property isvalid only whenpublicKeyAuthentication is setto false. If this property doesnot exist (which is true for aprevious plug-in version) or ifno value is specified, false isassumed for the property.

false Input O

Port Port Number Specify the port number touse when connecting to theoperating target device.

-- Input O

charset CharacterSet

Specify the character set touse when writing to thestandard input of theoperation target device andreading from standard outputand standard error output.Specify the same characterset as that of the user whologs in to the operationtarget. The names ofcharacter sets are not casesensitive. You can specify thefollowing character sets:• EUC-JP• eucjp• ibm-943C• ISO-8859-1• MS932• PCK

-- Input O



Description

Defaultvalue

I/O typeRequired

• Shift_JIS• UTF-8• windows-31j

lineEnd NewlineCharacter

When Telnet is specified inthe protocol property of theterminal connect plug-in,specify the newline characterto append to the valuesspecified in the account andpassword properties. You canspecify the following:• CR• LF• CRLF

To use 0x0D as the newlinecharacter, specify CR. To use0x0A, specify LF, and to use0x0D0A, specify CRLF.

CR Input O

promptPattern PromptPattern

Specify the regular expressionpattern to use to detectprompts in standard outputand standard error output,using no more than 1,024characters. This property isused to detect when theoperation target device isready to execute commandsafter the connection isestablished. Specify thepattern in a PCRE-compliantformat. When the outputmatches the specified regularexpression pattern, the plug-in ends immediately. If theoutput does not match thepattern, the plug-in ends inan error when the time set inthe readWaitTime propertyhas elapsed since the lastoutput to standard output orstandard error output.

-- Input R

readWaitTime StandardOutput WaitTime

When logging in to anoperation target device,specify how long to wait afteroutput to standard output orstandard error output until

60000

Input O



Description

Defaultvalue

I/O typeRequired

the next output. Specify thetimeout time in a range from1 to 86,400,000 (inmilliseconds).

token Token String The token string thatidentifies the session isoutput to this property. Youcan specify the characterstring output to this propertyin the token property ofterminal command plug-insand terminal disconnect plug-ins.

-- Output O


Specifies a condition to beoutput to the standard outputproperty 1-3. You can specifythe following values:• - always -- Outputs a null

character even if it doesnot match the specifiedpattern.

• - patternMatch -- Outputsonly when matching thestandard output pattern1-3.

If there is no output in outputproperties, mapped serviceproperties are also notupdated.

Always

Input O

stdoutPattern1 StandardOutputPattern 1

Specify the regular expressionpattern of the standardoutput and standard erroroutput to output thestdoutProperty property,using a maximum of 1,024characters. Specify thepattern in a PCRE-compliantformat.If you use more than 1,024characters, the 1,025th andsubsequent characters arediscarded.

-- Input O

stdoutProperty1 StandardOutputProperty 2

The character string extractedby the stdoutPattern1property is output to thisproperty.

-- Output O



Description

Defaultvalue

I/O typeRequired



Input O



-- Output O



-- Input O



-- Output

defaultReturnCode DefaultReturn Code

Specify the value to return asthe return code whenstandard output and standarderror output do not match theregular expression patternspecified in thereturnCodePattern property.Specify a value in the rangefrom 0 to 63.

0 Input O

returnCodePattern Return CodePattern

Specify the regular expressionpattern for standard outputand standard error output,

-- Input O



Description

Defaultvalue

I/O typeRequired

using a maximum of 1,024characters. Specify thepattern in a PCRE compliantformat. If standard outputand standard error outputmatch the specified pattern,the plug-in returns the valuespecified in the returnCodeproperty.

returnCode Return Code Specify the return code to bereturned by the plug-in whenstandard output and standarderror output match thepattern set in thereturnCodePattern property.You can specify a value in therange from 0 to 63. If youomit this property, the plug-inreturns the value specified inthe defaultReturnCodeproperty.

-- Input O

Usage example of stdoutPattern and stdoutProperty properties

By using the stdoutPattern property, you can extract the value output tostandard output and store it in the stdoutProperty property. The followingfigure shows the data flow when specifying aaabbb(.*) in stdoutPattern1.

Following is a usage example of stdoutPattern and stdoutProperty properties:

As defined in stdoutPattern1, for the standard output aaabbbccc, the valueafter aaabbb (in this case ccc) is extracted. The extracted value is stored inthe stdoutProperty1 property.


Priority when plug-in properties are set in several locations

Information related to plug-in properties can also be set in a connectiondestination properties file (connection destination-name.properties) or theproperty file (config_user.properties). When a value is set for a givenproperty in multiple locations, the following priority applies:

Setting Location Property key Priority Default value

Telnet portnumber

Plug-in property port 1 --

Connectiondestinationproperties file(connection-destination-name.properties)

telnet.port 2 --

Property file(config_user.properties)

telnet.port.number

3 23

SSH port number Plug-in property port 1 --


ssh.port 2 --

Property file(config_user.properties)

ssh.port.number 3 22

Character setname

Plug-in property charset 1 --


terminal.charset 2 --

If no value is set in the plug-in property or the connection destinationproperties file (connection-destination-name.properties), UTF-8 is set.

Usage examples of terminal connect plug-in

Example of judging Telnet authentication errors

The following describes an example of using plug-in properties to realize thefollowing processing:• Return 0 when login is successful.• Return 1 when login fails.


• When login is successful, store the date and time of the last login andinformation about the connection source in the stdoutProperty1 property.

The following table describes examples of the values you can specify in plug-in properties to achieve this processing.

Property key Example of specified value Meaning of specified value

promptPattern ^\[prompt\]|^Login incorrect If the contents of standardoutput matches [prompt] orLogin incorrect, the plug-interminates and determines thereturn code.

stdoutPattern1 ^Last login:(.*) The character string followingLast login: in standard output isstored in the stdoutProperty1property.

defaultReturnCode 0 If the contents of standardoutput do not match the valuespecified in thereturnCodePattern property, 0is returned.

returnCodePattern ^ Login incorrect If the contents of standardoutput match Login incorrect,the plug-in returns the returncode specified in thereturnCode property.

returnCode 1 If the contents of standardoutput matches the valuespecified in thereturnCodePattern property, theplug-in returns 1.

The following describes the operation of a plug-in with the above propertieswhen it encounters the following standard output:

This is an example when the login is successful.


Because the contents of standard output match the value specified in thepromptPattern property, the terminal connect plug-in determines the returncode. In this case, because the standard output does not match the valuespecified in the returnCodePattern property, the plug-in returns code (0), thevalue specified in the defaultReturnCode property.

The character string extracted by the stdoutPattern1 property (Mon Mar 1813:21:13 2013 fromServerA) is stored in the stdoutProperty1 property.

This is an example when the login fails.

Because the contents of standard output match the value specified in thepromptPattern property, the return code of the terminal connect plug-in isdetermined. In this case, because the return code matches the valuespecified in the returnCodePattern property, the plug-in returns code (1), thevalue specified in the returnCodeproperty.

Checking whether an authentication error has occurred when using SSH

When using SSH as the protocol, you can check whether an authenticationerror has occurred by reviewing the return code of the terminal connect plug-in.

Authentication errors are detected using the authentication information set inthe Agentless Remote Connections view or the authentication-relatedproperties of the terminal connect plug-in (account, password, andpublicKeyAuthentication). This process does not use the superuser passwordset in the Agentless Remote Connections view or the suPassword property ofthe terminal connect plug-in.

If an authentication error is detected, the plug-in returns code 78. Note thatthe return code of the plug-in will be 70 if destination is specified for thecredentialType property and the authentication information in the AgentlessRemote Connections view is set incorrectly.

Example of connecting to a service such as an HTTP server that does notproduce standard output

The following describes an example of connecting to a service that does notproduce standard output. This example assumes that 80 is specified in thetelnet.noStdout.port.list property in the connection-destination property file(connection-destination-name.properties).


In this case, the values specified in the following properties are ignored, andthe plug-in returns code 0.• credentialType• account• password• suPassword• publicKeyAuthentication• keyboardInteractiveAuthentication• charset• lineEnd• promptPattern• readWaitTime• stdoutPattern1 to stdoutPattern3• defaultReturnCode• returnCodePattern• returnCode

Terminal Command Plug-inThe Terminal Command Plug-in executes commands on the destination hostconnected to by the Terminal Connect Plug-in.

Function

This plug-in allows you to execute a specified command on an operationtarget device connected to by a terminal connect plug-in. The commandsspecified in the terminal command plug-in are executed with the privileges ofthe user authenticated by the terminal connect plug-in. To execute acommand with administrator privileges, the terminal command plug-in mustexecute the command that elevates the user to administrator privileges.

Prerequisites for execution• The protocol specified in the protocol property of the terminal connect

plug-in is used to communicate with the Automation Director server.• A connection must have been established with the operation target device

by a terminal connect plug-in.

Cautionary notes• The plug-in waits for standard output for the length of time specified in the

readWaitTime property. If the time specified in readWaitTime elapses afteroutput to standard output has ceased, plug-in execution ends in an error.Make sure that the value of the readWaitTime property is appropriatebefore using the plug-in. Any information output after the plug-in hastimed out is discarded.


• If the value output to standard output matches the regular expressionpattern specified in the promptPattern property, the plug-in terminatesimmediately.

• If the command outputs information one page at a time, the systemassumes that standard output has ceased. If the time period specified inthe readWaitTime property then passes, the plug-in ends with an error.Make sure that the command executed by the terminal command plug-inis not configured to output results one page at a time.

• Echoed command lines are also output to standard output. When needed,configure the command to not echo back.

• If execution of a task is stopped during plug-in execution, the status of thetask becomes Failed or Completed when the processing of the terminalcommand plug-in has finished. The session and token are then discarded.The status of steps and tasks after plug-in execution has finished dependson the return code of the step and the condition for executing subsequentsteps. You can set Subsequent-step Execution Condition in the Create Stepdialog box or the Edit Step dialog box.

• The standard output and standard error output of the terminal commandplug-in is output as the standard output of the Automation Director step.The size of the standard output and standard error output is the totalnumber of bytes received by Automation Director. If the Telnet server orSSH server is configured to replace the linefeed character LF with CR+LF,allow two bytes for each linefeed character. The results of processingwhose total standard output and standard error output exceeds 100 KB isoutside the scope of product support. Make sure that the total standardoutput and standard error output does not exceed 100 KB.

• If you intend to specify non-ASCII characters in the commandLineproperty, see General Command Plug-in on page 191.

• When the Terminal Connect Plug-in version is less than 02.00.00,"patternMatch" is set in "outputCondition" . But, the default value of"outputCondition" is "always" in the case of version 02.00.00. When youupgrade Terminal Connect Plug-in, please keep this in mind.

Return codes

The following return codes are generated by the Terminal Command Plug-in:


0-63 If standard output and standard error output match the regularexpression pattern specified in the returnCodePattern property,the plug-in returns the return code specified in the returnCodeproperty. However, if the output does not match the pattern,the plug-in returns the return code specified in thedefaultReturnCode property. Therefore, the meaning of thereturn code depends on the service template that is using theplug-in.



65 The connection with the Automation Director server failed. Forexample, the Automation Director server might have stoppedwhile the plugin was being executed.




69 An environment variable of the task-processing engine couldnot be acquired.




82 The request message from the task-processing engine couldnot be correctly parsed.

83 The environment of the Automation Director server iscorrupted.



87 Standard output and standard error output have timed out.

88 The total standard output and standard error output hasexceeded 100 KB.


Property list

The properties available for the Terminal Command Plug-in.



I/O typeRequired

token Token Specify the value of the tokenproperty of the terminalconnect plug-in.

-- Input R

commandLine Command Line Specify the absolute path of thecommand or script to beexecuted on the operationtarget device, using amaximum of 1024 characters.In the command line, specifycharacters that can be enteredin command lines in theoperating systems of the

-- Input O




I/O typeRequired

Automation Director server andthe operation target device.Special characters thatrepresent environmentvariables in the command lineare not escaped. To handle aspecial character as a characterstring, escape the characterwith a percent sign (%) inWindows, and a backslash (\)in UNIX.

If you need to enter thesuperuser password in thecommand line to give the useradministrator privileges, specifythereserved.terminal.suPasswordreserved property. Thereserved.terminal.account,reserved.terminal.password,andreserved.terminal.suPasswordreserved properties referencetoken related authenticationinformation set for the terminalconnect plug-in. The specificauthentication information theproperties reference dependson the setting of thecredentialType property of theterminal connect plug-in.• If destination is specified for

the credentialType property,the reserved propertiesreference the authenticationinformation defined in theconnection destination.

• If property is specified forthe credentialType property,the reserved propertiesreference the authenticationinformation specified in thecredentialType property ofthe terminal connect plug-in.

charset Character Set Specify the character set to usewhen writing to the standardinput of the operation targetdevice and reading fromstandard output and standarderror output. Specify the samecharacter set as that of the

-- Input O




I/O typeRequired

user who logs in to theoperation target. The names ofcharacter sets are not casesensitive. You can specify thefollowing character sets:• EUC-JP• eucjp• ibm-943C• ISO-8859-1• MS932• PCK• Shift_JIS• UTF-8• windows-31j

lineEnd NewlineCharacter

When Telnet is specified in theprotocol property of theterminal connect plug-in,specify the newline character toappend to the values specifiedin the account and passwordproperties. You can specify thefollowing:• CR• LF• CRLF

To use 0x0D as the newlinecharacter, specify CR. To use0x0A, specify LF, and to use0x0D0A, specify CRLF.

CR Input O

promptPattern Prompt Pattern Specify the regular expressionpattern to use to detectprompts in standard output andstandard error output, using nomore than 1,024 characters.This property is used to detectwhen the operation targetdevice is ready to executecommands after the connectionis established. Specify thepattern in a PCRE-compliantformat. When the outputmatches the specified regularexpression pattern, the plug-inends immediately. If the outputdoes not match the pattern,the plug-in ends in an errorwhen the time set in thereadWaitTime property haselapsed since the last output to

-- Input R




I/O typeRequired

standard output or standarderror output.

readWaitTime StandardOutput WaitTime

When logging in to anoperation target device, specifyhow long to wait after output tostandard output or standarderror output until the nextoutput. Specify the timeouttime in a range from 1 to86,400,000 (in milliseconds).

60000 Input O


Specifies a condition to beoutput to the standard outputproperty 1-3. You can specifythe following values:• - always -- Outputs a null

character even if it does notmatch the specified pattern.

• - patternMatch -- Outputsonly when matching thestandard output pattern1-3.

If there is no output in outputproperties, mapped serviceproperties are also notupdated.

Always Input O


The character string extractedby the stdoutPattern1 propertyis output to this property.

-- Output O

stdoutPattern1 StandardOutput Pattern1

Specify the regular expressionpattern of the standard outputto output to thestdoutProperty1 property, usinga maximum of 1,024characters. Specify the regularexpression pattern in a PCRE-compliant format. If you specifythe key of a service property inthe stdoutProperty1 propertybut do not specify thestdoutPattern1 property, theentire standard output andstandard error output of thecommand or script specified inthe commandLine property isassigned to the serviceproperty.

Input




I/O typeRequired



-- Output O



Input O



-- Output O



-- Input O

defaultReturnCode

Default ReturnCode

Specify the value to return asthe return code when standardoutput and standard erroroutput do not match theregular expression pattern

0 Input O




I/O typeRequired

specified in thereturnCodePattern property.Specify a value in the rangefrom 0 to 63.

returnCodePattern

Return CodePattern

Specify the regular expressionpattern for standard output andstandard error output, using amaximum of 1,024 characters.Specify the pattern in aPCREcompliant format. Ifstandard output and standarderror output match thespecified pattern, the plug-inreturns the value specified inthe returnCode property.

-- Input O

returnCode Return Code Specify the return code to bereturned by the plug-in whenstandard output and standarderror output match the patternset in the returnCodePatternproperty. You can specify avalue in the range from 0 to63. If you omit this property,the plug-in returns the valuespecified in thedefaultReturnCode property.

-- Input O

Usage examples of terminal command plug-in

Example of terminating a terminal command plug-in with an error when anerror is output to standard output

The table below describes an example of a terminal command plug-in thatterminates with an error when it acquires error-related information fromstandard output. Set the plug-in property as follows:

Property keyExample of specifiedvalue

Meaning of specified value

commandLine configServer arg0arg1 arg2

Executes the specified command or script.

promptPattern ^\[prompt\] If the contents of standard output matches [prompt], theplug-in terminates and determines the return value.

stdoutPattern1

^Message:(.*) The character string following Message: in standardoutput is stored in the stdoutProperty1 property.


Property keyExample of specifiedvalue

Meaning of specified value

stdoutPattern2

Êrror:(.*) The character string following Error: in standard output isstored in the stdoutProperty2 property.

stdoutPattern3

^ReturnCode:(.*) The character string following Returncode: in standardoutput is stored in the stdoutProperty3 property.

defaultReturnCode

0 If the contents of standard output do not match the valuespecified in the returnCodePattern property, return code 0is returned.

returnCodePattern

Êrror: If the contents of standard output match Error:, the plug-in returns the return code specified in the returnCodeproperty.

returnCode 1 If the contents of standard output matches the valuespecified in the returnCodePattern property, the plug-inreturns code 1.

The following describes the operation of a plug-in with the above propertieswhen it encounters the following standard output.

The contents of standard output match the value specified in thepromptPattern property, so the terminal command plug-in determines whichreturn code to return. Because standard output matches the value specifiedin the returnCodePattern property, the plug-in returns code (1), the valuespecified in the returnCode property.

The character strings extracted by the properties stdoutPattern1 tostdoutPattern3 are stored as follows in the properties stdoutPrpoerty1 tostdoutProperty3:• stdoutProperty1: command failed• stdoutProperty2: Permission Denied• stdoutProperty3: 128

Example of sending a GET request to an HTTP server

The following describes how to configure a plug-in that issues a request likethe one below to an HTTP server and verifies the response:


To issue a GET request to an HTTP server, specify each line of the requestmethod and request header in the commandLine property of a terminalcommand plug-in.

Because the last line of the request needs to be blank, you need to executethe terminal command plug-in five times. The following table describesexamples of the values to set in the properties of each instance of the plug-in.

Order of executionValue specified in thecommandLine

Value specified in thelineEnd

Value specified inpromptPattern

First GET /index.htmlHTTP/1.1

CRLF .*

Second Host: ServerA CRLF .*

Third User-Agent:Automation Director

CRLF .*

Fourth Accept-Charset: UTF-8 CRLF .*

Fifth -- (adds a blank line.Do not specify a value)

CRLF .*

Because HTTP server requests use [CR]+[LF] as delimit characters, specifyCRLF for the value specified in the lineEnd.

In the promptPattern property of the first to fourth terminal command plug-ins, you can specify regular expression patterns that also match blankcharacters.

Because standard output continues after you execute the terminal commandplug-ins, specify a regular expression that detects the end of standard outputby the terminal command plug-ins in the promptPattern property.

The following describes the operation of a plug-in with the above propertieswhen it encounters the following standard output:

Because the contents of standard output match the value specified in thepromptPattern property, the terminal command plug-in determines the returncode.


If standard output matches the value specified in the returnCodePatternproperty, the return code specified in the returnCode property is returned asthe return code of the plug-in.

If standard output does not match the value specified in thereturnCodePattern property, the plug-in returns the return code specified inthe defaultReturnCode property.

Terminal Disconnect Plug-inDisconnects the terminal from the destination host connected to by theTerminal Connect Plug-in.

The Terminal Disconnect Plug-in terminates a connection established with anoperation target device by a terminal connect plug-in.

Prerequisite for execution• Terminal disconnect plug-in uses the protocol specified in the protocol

property of the terminal connect plug-in to communicate with theAutomation Director server.

Cautionary notes• If execution of a task is stopped during plug-in execution, the status of the

task becomes Failed or Completed when the processing of the terminaldisconnect plug-in has finished. The status of steps and tasks after plug-inexecution has finished depends on the return code of the step and thecondition for executing subsequent steps. You can set Subsequent-stepExecution Condition in the Create Step dialog box or the Edit Step dialogbox.

• If you forcibly terminate a task during plug-in execution, reading fromstandard output and prompt detection are canceled and the task entersFailed status. The session and token are then discarded. In this case, thereturn code of the step in the Task Details dialog box is -1. The return codeoutput to the task log depends on the timing with which the task wasforcibly terminated.

Return codes

The following return codes are generated by the Terminal Disconnect Plug-in:


0 The plug-in ended normally. The plug-in ends normally even if

the connection has already been closed.










not be acquired.






corrupted.




Property list

The following properties are available for the Terminal Disconnect Plug-in:

Propertykey

Property name DescriptionDefaultvalue

I/O typeRequired

token Token Specify the value of the tokenproperty of the terminal connectplug-in.

-- Input R

Flow Plug-inHierarchizes the flow.

The Flow Plug-in allows you to create hierarchical flows by defining flowswithin other flows. You can define a maximum of 25 hierarchical levels, withthe top-level flow being level 1.

The following figure shows how the flow is established:


Cautionary notes• If execution of a task is stopped during plug-in execution, the status of the

task becomes Failed or Completed when the step being executed in theflow plug-in ends.

• The return code of a flow plug-in is always 0. If a step within a hierarchyflow terminates abnormally, the plug-in returns code 0. The return code ofthe flow plug-in does not reflect the return codes of the constituent stepsof the hierarchy flow.

Return codes

The following return codes are generated by the Flow Plug-in:


0 The plug-in ended normally.

1 A step in a lower execution flow ended with a warning.



2 A step in a lower execution flow ended abnormally.

Note: If the step execution of a lower flow fails, the task will not end at thatpoint. Determination of the tasks continuation/stop is made by setting theNext Step Condition of the flow plug-in step.

Property list

The following properties are available for the Flow Plug-in:



I/O typeRequired

errorStep Error step The step ID that failed in onelower flow is output in half-width comma-separated.

-- Output O

returnValueOfErrorStep

Returnvalue oferror step

The return value of the stepthat failed in one lower flow isoutput in half-width commaseparated values.

-- Output O

Interval Plug-inControls the interval between steps.

The Interval Plug-in controls the execution interval between steps. Theoperator specifies the wait time for a process as the execution interval, andAutomation Director waits for the execution interval to elapse beforeexecuting succeeding steps. By using an interval plug-in, you can executesteps at fixed intervals.

The following figure shows how the Interval Plug-in is used:


Cautionary notes• The communication status and other factors might cause a discrepancy

between the actual wait time and the time specified by the plug-in.• You cannot change the property values when you execute the service. Set

the values when you create the flow.• You can only specify literal characters in the input property. You cannot

map the value of a service property or reserved property.• If execution of a task is stopped during plug-in execution, the task enters

Failed or Completed status after the interval plug-in has finishedprocessing.

Return codes

The following return codes are generated by the Interval Plug-in:


0 The plug-in ended normally. The plug-in ends normally even if

the connection has already been closed.

18 A task was forcibly terminated during plug-in execution.

1 to 17, 19 or higher The plug-in terminated abnormally. Use the hcmds64getlogscommand to acquire log information and identify the problem.

Property list

The following properties are available for the Interval Plug-in:


Description Default value I/O type Required

interval Interval This propertyspecifies howlong to waitbeforeexecuting thenext step, inthe range from1 to 1,440(seconds).

10 Input R

Branch by ReturnCode Plug-inBranches the flow of processing based on the return value of the previousstep.

This plug-in allows you to select which step to execute next based on thereturn code of the preceding step.


A Branch by ReturnCode Plug-in connects to two branch destination steps: Asucceeding step, and a step that is only executed when certain conditions aremet. If the return code matches the specified condition, Automation Directorexecutes the branch destination step and the succeeding step, in that order.If the return code does not match the specified conditions, AutomationDirector executes the succeeding step only.

By using this plug-in together with a test value plug-in, you can select thesteps in a flow based on a character string.

The following figure shows how the Branch by ReturnCode Plug-in is used:

Cautionary notes• When a task is stopped or forcibly terminated during plug-in execution, the

task enters Completed status after the Branch by ReturnCode Plug-infinishes processing.

• You cannot change the property values when you execute the service. Setthe values when you create the flow.

• You can only specify literal characters in input properties. You cannot mapthe value of a service property or reserved property.

• If the Branch by ReturnCode Plug-in stops processing, use thehcmds64getlogs command to acquire log information and identify theproblem.

Return codes

The following return codes are generated by the Branch by ReturnCode Plug-in:



0 or higher The plug-in ended normally. The return code of the preceding

step of the Branch by ReturnCode Plug-in is set as the return

code.

Property list

The following properties are available for the Branch by ReturnCode Plug-in:

Propertykey

Propertyname


I/O type Required

condition Condition Specify the judgmentcondition for the return codeof the preceding step. You canchoose from the followingconditions:• ReturnCode=value1

The return code is equal toValue1.

• ReturnCode!=value1The return code is notequal to Value1.

• ReturnCode<value1The return code is lessthan Value1.

• ReturnCode>value1The return code is greaterthan Value1.

• ReturnCode<=value1The return code is lessthan or equal to Value1.

• ReturnCode>=value1The return code is greaterthan or equal to Value1.

• ReturnCode>value1 ANDReturnCode<value2The return code is greaterthan Value1 and less thanValue2.

• ReturnCode>=value1 ANDReturnCode<value2The return code is greaterthan or equal to Value1,and less than Value2.

• ReturnCode>value1 ANDReturnCode<=value2The return code is greaterthan Value1, and less thanor equal to Value2.

• ReturnCode>=value1 ANDReturnCode<=value2

ReturnCode=value1

Input R


Propertykey

Propertyname


I/O type Required

The return code is greaterthan or equal to Value1,and less than or equal toValue2.

• ReturnCode<value1 ORReturnCode>value2The return code is lessthan Value1, or greaterthan Value2.

• ReturnCode<=value1 ORReturnCode>value2The return code is lessthan or equal to Value1, orgreater than Value2.

• ReturnCode<value1 ORReturnCode>=value2The return code is lessthan Value1, or greaterthan or equal to Value2.

• ReturnCode<=value1 ORReturnCode>=value2The return code is lessthan or equal to Value1, orgreater than or equal toValue2.

value1 Value1 Specify a numerical valueagainst which to judge thereturn code, within the rangefrom 0 to 999. The value ismapped to value1 in thecondition property.

0 Input R

value2 Value2 Specify a numerical valueagainst which to judge thereturn code, within the rangefrom 0 to 999. The value ismapped to value2 in thecondition property. This valuetakes effect when value2 isincluded in a conditionproperty.

0 Input O

Example of a property specification

A Branch by ReturnCode Plug-in determines whether the return code is withina specified range of values.

The following describes the range of valid judgment values, using thefollowing values of the condition, value1, and value2 properties as examples.

A. The return code is 25 or greater and less than 75

condition (Condition): ReturnCode>=value1 AND ReturnCode<value2


value1 (Value1): 25

value2 (Value2): 75

B. The return code is less than 25, or 75 or higher

condition (Condition): ReturnCode<value1 OR ReturnCode>=value2

value1 (Value1): 25

value2 (Value2): 75

The following figure shows the range of return codes that match eachjudgment condition.

Test Value Plug-inCompares service property values and returns 0 if the values match thejudgment conditions.

The Test Value Plug-in compares the value of a service property, the value ofa reserved property, a literal string, or any combination thereof against aspecified value. If the judgment condition is met, the plug-in returns 0.

By using this plug-in together with a Branch by ReturnCode Plug-in, you canselect the steps in a flow based on a character string.

The following figure shows how the Test Value Plug-in is used:


Cautionary notes• If execution of a task is stopped during plug-in execution, the task enters

Completed status after the Test Value Plug-in finishes processing.

Return codes

The following return codes are generated by the Test Value Plug-in:


0 The value matched the judgment condition. Alternatively, 0 is

specified in the defaultReturnCode property.

1 The value did not match the judgment condition. Alternatively,

1 is specified in the defaultReturnCode property.

63 Judgment failed. 63 is specified in the defaultReturnCode

property.








not be acquired.








corrupted.




Property list

The following properties are available for the Test Value Plug-in:



I/Otype

Required

condition Condition Specify the judgment conditionfor the valueX property. You canselect from the followingconditions:• valueX=value1

ValueX and Value1 are equal(numerical comparison).

• valueX!=value1ValueX and Value1 are notequal (numericalcomparison).

• valueX<value1ValueX is less than Value1(numerical comparison).

• valueX>value1ValueX is greater than Value1(numerical comparison).

• valueX<=value1ValueX is less than or equalto Value1 (numericalcomparison).

• valueX>=value1ValueX is greater than orequal to Value1 (numericalcomparison).

• valueX>value1 ANDvalueX<value2ValueX is greater than Value1and less than Value2(numerical comparison)

valueX=value1

Input R




I/Otype

Required

• valueX>=value1 ANDvalueX<value2ValueX is greater than orequal to Value1, and lessthan Value2 (numericalcomparison).

• valueX>value1 ANDvalueX<=value2ValueX is greater thanValue1, and less than orequal to Value2 (numericalcomparison).

• valueX>=value1 ANDvalueX<=value2ValueX is greater than orequal to Value1, and lessthan or equal to Value2(numerical comparison).

• valueX<value1 ORvalueX>value2ValueX is less than Value1, orgreater thanValue2(numericalcomparison).

• valueX<=value1 ORvalueX>value2ValueX is less than or equalto Value1, or greater thanValue2 (numericalcomparison).

• valueX<value1 ORvalueX>=value2ValueX is less than Value1, orgreater than or equal toValue2 (numericalcomparison).

• valueX<=value1 ORvalueX>=value2ValueX is less than or equalto Value1, or greater than orequal to Value2 (numericalcomparison).

• valueX equals value1ValueX and Value1 are equal.Values are case sensitive(character stringcomparison).

• valueX not equals value1ValueX and Value1 are notequal. Values are casesensitive (character stringcomparison).

• valueX contains value1ValueX contains Value1.Values are case sensitive




I/Otype

Required

(character stringcomparison).

• valueX not contains value1ValueX does not containValue1. Values are casesensitive (character stringcomparison).

valueX ValueX Specify a value as the basis forcomparison, using no more than1,024 characters. You can usethe following formats individuallyor combined.• ?dna_service-property-key?

(when referencing the valueof a service property)

• ?dna_reserved-property-key?(when referencing the valueof a reserved property)

• literal-string

-- Input R

value1 Value1 Specify the value against whichto compare the valueX property,using no more than 1,024characters. You can use thefollowing formats individually ortogether.• ?dna_service-property-key?



• literal-string

The value is mapped to value1 inthe condition property.

-- Input O




• literal-string

The value is mapped to value2 inthe condition property.

-- Input O




I/Otype

Required

The value in this property takeseffect when value2 is specified inthe condition property.

defaultReturnCode

DefaultReturn CodeOn Error

This property specifies the valuereturned by the plug-in when anumerical comparison isspecified in the conditionproperty, and a value thatcannot be compared on anumerical basis is specified inany of the valueX, value1, andvalue2 properties.• 0

Specify 0 when using "Thevalue matched the judgmentcondition." as the judgmentresult.

• 1Specify 1 when using "Thevalue did not match thejudgment condition." as thejudgment result.

• 63Specify 63 when using"Judgment failed" as thejudgment result to make thestep terminate abnormally.

63 Input R

Example of property specification

A test value plug-in determines whether an input value is within a specifiedrange of values.

The following describes the range of valid judgment values, using thefollowing values of the condition, value1, and value2 properties as examples.

A. The input value is greater than or equal to 25 and less than 75

condition (Condition): ReturnCode>=value1 AND ReturnCode<value2

value1 (Value1): 25

value2 (Value2): 75

B. The input value is less than 25, or 75 or greater

condition (Condition): ReturnCode<value1 OR ReturnCode>=value2

value1 (Value1): 25

value2 (Value2): 75


The following figure shows the range of return codes that match eachjudgment condition.

Abnormal-End Plug-inHandles the abnormal termination of an executing flow, task, hierarchicalflow, or repeatedly executed flow.

The Abnormal-End Plug-in allows you to abnormally terminate an executingtask.

By using this plug-in together with a Branch by ReturnCode Plug-in, you canalso abnormally terminate a flow when a judgment condition is met.

The following figure shows how the Abnormal-End Plug-in is used:

Cautionary notes• If execution of a task is stopped during plug-in execution, the task enters

Abnormal termination status after the abnormal-end plug-in has finishedprocessing.

• If you use an abnormal-end plug-in within a flow plug-in, the hierarchicalflow and any higher-level flows that feature flow plug-ins also terminate


abnormally. Executing tasks also terminate abnormally, and the flow plug-in returns 0.

• When you use an abnormal-end plug-in in the context of a repeatedexecution plug-in, the repeated execution plug-in returns 1 if the repeatedprocessing abnormally terminates even once. If every instance of therepeated processing terminates abnormally, the repeated execution plug-inreturns 2.

Return codes

The following return code is generated by the Abnormal-End Plug-in:


0 The plug-in ended normally (the step was abnormally

terminated).


Branch by Property Value Plug-inBranches the flow of processing based on service property values.

The Branch by Property Value Plug-in compares the value of a serviceproperty, the value of a reserved property, a literal string, or any combinationthereof against a specified value. The result of the comparison determineswhich step Automation Director executes next.

This Branch by Property Value Plug-in allows you to select which step toexecute next based on the return code of the preceding step.

This plug-in connects to two branch destination steps: A succeeding step, anda step that is only executed when the judgment condition is met. If the inputvalue matches the judgment condition, Automation Director executes thebranch destination step and the succeeding step, in that order. If the inputvalue does not match the judgment conditions, Automation Director executesthe succeeding step only.

This plug-in combines the functionality of a test value plug-in and a Branchby Returncode plug-in.

The following figure shows how the Branch by Property Value Plug-in is used:


Cautionary notes• When you execute this plug-in, the information output to the task log

reflects the execution of the test value plugin. The Branch by PropertyValue Plug-in does not contribute to the task log.

• If execution of a task is stopped during plug-in execution, the task entersCompleted status after the Branch by Property Value Plug-in finishesprocessing.

Return codes

The following return codes are generated by the Branch by Property ValuePlug-in:


0 The plug-in returns 0 when:• The judgment result is true.• A numerical comparison is specified in the condition

property, a value that cannot be compared on a numericalbasis is specified in any of the valueX, value1, and value2properties, and 0 is specified in the defaultReturnCodeproperty.

1 The plug-in returns 1 when:• The judgment result is false.• A numerical comparison is specified in the condition

property, a value that cannot be compared on a numericalbasis is specified in any of the valueX, value1, and value2properties, and 1 is specified in the defaultReturnCodeproperty.



Property list

The following properties are available for the Branch by Property Value Plug-in:

Propertykey

Propertyname


I/O type Required

condition Condition Specify the branch condition forthe valueX property. You canselect from the followingconditions:• valueX>=value1

ValueX is greater than orequal to Value1 (numericalcomparison).

• valueX>value1 ANDvalueX<value2ValueX is greater thanValue1 and less than Value2(numerical comparison).

• valueX>=value1 ANDvalueX<value2ValueX is greater than orequal to Value1, and lessthan Value2 (numericalcomparison).

• valueX>value1 ANDvalueX<=value2ValueX is greater thanValue1, and less than orequal to Value2 (numericalcomparison).

• valueX>=value1 ANDvalueX<=value2ValueX is greater than orequal to Value1, and lessthan or equal to Value2(numerical comparison).

• valueX<value1 ORvalueX>value2ValueX is less than Value1,or greater than Value2(numerical comparison).

• valueX<=value1 ORvalueX>value2ValueX is less than or equalto Value1, or greater thanValue2 (numericalcomparison).

• valueX<value1 ORvalueX>=value2ValueX is less than Value1,or greater than or equal toValue2 (numericalcomparison).

• valueX<=value1 ORvalueX>=value2

valueX=value1

Input R


Propertykey

Propertyname


I/O type Required

ValueX is less than or equalto Value1, or greater than orequal to Value2 (numericalcomparison).

• valueX equals value1ValueX and Value1 are equal.This judgment is casesensitive (character stringcomparison).

• valueX not equals value1ValueX and Value1 are notequal. This judgment is casesensitive (character stringcomparison).

• valueX contains value1ValueX contains Value1. Thisjudgment is case sensitive(character stringcomparison).

• valueX not contains value1ValueX does not containValue1. This judgment iscase sensitive (characterstring comparison).

valueX ValueX Specify a value as the basis forcomparison, using no more than1,024 characters. You can usethe following formatsindividually or combined.• ?dna_service-property-key?


• ?dna_reserved-property-key? (when referencing thevalue of a reserved property)

• literal-string

-- Input R




• literal-string

The value is mapped to value1in the condition property. Thevalue in this property takes

-- Input O


Propertykey

Propertyname


I/O type Required

effect when value2 is specifiedin the condition property.




• literal-string

The value is mapped to value2in the condition property.

The value in this property takeseffect when value2 is specifiedin the condition property.

-- Input O

defaultReturnCode

DefaultReturnCode OnError

This property specifies the valuereturned by the plug-in when anumerical comparison isspecified in the conditionproperty, and a value thatcannot be compared on anumerical basis is specified inany of the valueX, value1, andvalue2 properties.• 0

Specify 0 when using "Thevalue matched the judgmentcondition." as the judgmentresult.

• 1Specify 1 when using "Thevalue did not match thejudgment condition." as thejudgment result.

• 63Specify 63 if you want thestep to terminate abnormallywhen the judgment gives afailed result.The plug-in terminatesabnormally withoutexecuting the branchdestination step or thesucceeding step.

63 Input R


File Export Plug-inExports the input content to the specified file.

The File Export Plug-in can output input values of any format to any file. Youcan use the Apache Velocity Engine VTL (Velocity Template Language) http://velocity.apache.org/ to specify the output format. If no format is specified,then input values are output as-is with no formatting.

The File export plug-in specifies the full-path to the output file and exportsthe data and generates error messages if necessary

Prerequisites for execution• Name and location of the file to be exported.• If necessary, prepared template for output format.

Cautionary notes• If a file has the same name as an existing output file, the former will be

overwritten.• If a directory has the same name as an existing output file, a write error

occurs.• Line feed codes in the export content and output template are included in

the output file.

Return codes

The following return codes are generated by the File Export Plug-in:


0 Ended normally.

1 The length of the output file path is longer than 256

characters.

2 A grammatical error has been detected in the VTL description.

3 This value is returned when an undefined attribute or method

is detected in the VTL description. Usually, this value is not

returned unless Velocity is executed in strict mode. By default,

strict mode is set to false.

4 The resource file used for Velocity cannot be located. In most

cases, this value is not returned since the File Export Plug-in

does not use the resource file but is included to accommodate

the exception that is generated by the Velocity API.

5 An error occurred while writing the output file.


http://velocity.apache.org/

http://velocity.apache.org/


63 An error occurred during the processing of the plug-in.


Property list

The following properties are available for the File Export Plug-in:



I/O typeRequired

content ContentTo Export

Specifies the content to beexported to the file.

-- Input R

fileName OutputFile Name

Specifies the name of the filewhere the content is to beexported. Empty strings areinvalid. The length of the fullpath consisting of the outputdirectory path and the output filename cannot exceed 256characters.

-- Input R

directoryPath OutputDirectoryPath

Directory path where the outputfile is to be created; an absoluteor relative path can be specified.If you specify a relative path, thetask working directory(Automation/data/task/[tasked])is assumed as the starting pointfor the path. If you do notspecify a directory path, the taskworking directory (Automation/data/task/[tasked]) is used. Thelength of the full path consistingof the output directory path andthe output file name cannotexceed 256 characters.

-- Input O

template TemplateFor TheOutput

Specifies a template with theVTL description that defines theformat for the output content.

-- Input O

charset CharacterSet

Specifies the character set forthe output file.

-- Input O

exportFilePath OutputFile Path

Specifies the full path for theoutput file to be exported.

-- Output O

message Message Specifies the log for messagesgenerated during the processingof the plug-in.

-- Output O


Input values with the output template

Any character can be specified in the input values. If the input values areJSON, the values are JSON decoded as objects via the variable $root in theVTL description of the output template, and the objects can be viewed. If theinput values are not JSON, $root keeps the input values as character strings.The description method of the output template complies with the VTL syntax.Note that the variable $root described above is a reserved variable to whichFile Export Plug-in specifies values in advance. In addition, File Export Plug-inprovides a utility for CSV output as a reserved variable $csv. The followingtable shows the reserved variables that can be used in the VTL description forFile Export Plug-in.

Variable name Description

$root If an input value is JSON, the value is JSON decoded and stored as anobject. If the input value is not JSON, the value is stored as a characterstring.

$csvProvides the followingutility methods forCSV output. Thesecan be used for theVTL description usingVelocity'sToolManager.

$csv.value(String) -- Takes a single string as an argument; if a character(such as a double quotation mark, comma, or line feed) that requires anescape in CSV is included, enclose the value with double quotation marks.If a double quotation mark is included in a string value, the string in whichthe double quotation mark is escaped (" --> "") is output. (Output processas a single cell of the CSV format)

$csv.values(String…) -- Takes multiple strings as arguments (variable-length arguments) and outputs the strings into a single line with the CSVformat; the output format of a single cell is same as the value(String)function described above.

$csv.values(Collection<String>) -- Takes an array and outputs the arrayinto a single line with the CSV format; the output format of a single cell isthe same as the value(String) function described above.

JavaScript Plug-inExecutes an appointed JavaScript code.

The JavaScript Plug-in can execute any specified JavaScript code as follows:• To view any service property and plug-in property value.• To pass the maximum of 10 arguments via plug-in properties to the

JavaScript code.• To keep the maximum of 10 values in plug-in output properties.• To return a value and keep the return value in the output properties.



Cautionary notes

Return codes

The following return codes are generated by the JavaScript Plug-in:


0 Ended normally.

1 Script has terminated due to an error.

60 A JavaScript library read error has occurred.

61 A JavaScript compile error has occurred.

62 The JavaScript code is not properly formatted.



Property list

The following properties are available for the JavaScript Plug-in:


I/Otype

Required

scriptBody JavaScript Body Specifies the JavaScript codestrings.

-- Input R

arg0 Argument(0) Specifies an argument to bepassed to the script.

-- Input O


-- Input O


-- Input O


-- Input O


-- Input O


-- Input O


-- Input O


-- Input O



I/Otype

Required


-- Input O


-- Input O

notify Notification Flag Specifies a non-empty string ifthe script detects something tonotify; the plugin wouldterminate with a return valueof 1 if a non-empty string wasspecified here.

-- Output O

returnValue Return Value The content of the objectreturned from the function ofthe specified script is output asa character string.

-- Output O

out0 Argument(0) A value set to the out0 key inthe map of the secondargument in the user-specifiedscript is output.

-- Output O


-- Output O


-- Output O

out3 Argument(3) A value set to the out3key inthe map of the secondargument in the user-specifiedscript is output.

-- Output O


-- Output O


-- Output O


-- Output O

out7 Argument(7) A value set to the out7 key inthe map of the second

-- Output O



I/Otype

Required

argument in the user-specifiedscript is output.


-- Output O


-- Output O

You specify the plug-in input/output properties in the property list.Combinations of service property values, reserved property values, and literalcharacters can be used for the input properties.

JavaScript code specifiable for the JavaScript body

The following table provides the JavaScript codes that are allowable in thebody of the script:

Table 42 JavaScript codes

Character encoding UTF-8

Available JS Library underscore.js 1.8.3

auto_util-1.0.0.js (Bundled library of HAD)

Format Must be an unnamed function (See the samplecode.)

Function callinterface

Argument serviceProperties Object type Service properties are mapped.The values of the serviceproperties can be viewed fromthe script. Note that even if thescript updates, deletes, or addsany of the values, the modifiedvalues will not be reflected inthe service properties after thescript is called.

pluginProperties Object type Plug-in properties are mapped.The values of the plug-inproperties can be viewed fromthe script.

arg0 to arg9 Stringsspecified in theplug-inproperties aredirectly


mapped. Eventhe stringsconform toJSON, if thescript refers tohere, andarguments canbe obtained asstrings, notobjects. Whenyou do notexpect that thevalidation fromJSON stringsto objectsdescribedbelow, checkhere.

notify If you specify avalue otherthan a non-empty string toa memberspecified fornotify in thescript, theplug-in finisheswith a returnvalue of 1 aftercalling.

out0 to out9 If you specifyvalues tomembersspecified forout0 to out9 inthe script, thevalues arereflected in theplug-in outputproperties ofArgument(0)toArgument(9)after calling.The values arereflected in theprocessingresults of thescript, and theresults will beused for the


next step. (Seethe samplecode.)

arg0 to arg9 Plug-in properties Argument(0) to Argument(9)are mapped. (Optional)If you specify JSON strings to the plug-inproperties, the strings can be obtained asobjects in the functions of the script.• Strings that are enclosed with double

quotation marks are mapped as is.• If strings are not enclosed, strings that fail

JSON validation are mapped as is.

Return code Any objects can be returned from the script. After calling the script,the return codes are extracted as JSON strings that are thenreflected in the plug-in output property Return value. The valuesare reflected in the processing results of the script and then usedfor the next step. (See the sample code.)

print ()function

By using the print() function in the script, you can output any strings to the tasklog. In this case, choose a log level by adding a specific prefix to the beginning ofthe string. Note that alphabetical prefixes are case-sensitive. (See the samplecode.)

Prefix [Severe] Outputs as log level 0

[Informational] Outputs as log level 10

[Fine] Outputs as log level 20

[Finer] Outputs as log level 30

[Debug] Outputs as log level 40

(No prefix) Same as the prefix [Information]

Otherfunctionalities

If an exception is thrown in the script or an unexpected exception occurs in thescript, the plug-in terminates abnormally and shows the exception in the task log.

When the script finishes properly, and when the values returned from the script orthe values specified in the plug-in output properties (out0 to out9) of the scriptcontain null or undefined, those values are stored as null or undefined.

auto util Library

The JavaScript plug-in supports the auto util library with the followingfeatures:• Sends a http(s) request to any destination.• It is possible to refer to the setting values of Web Service Connection as

the connection information.

The following table provides the auto util methods that are available:


Table 43 auto util Methods

Method Name Argument Return Value Description

sleep Specify the time tosleep in a numerictype (inmilliseconds)

None Sleep for thespecified time.

parseJson Specify a stringrepresentation ofJSON by stringtype.

JSON object Convert a string toa JSON object.

stringifyJson Specify any JSONobject.

Stringrepresentation ofJSON

Convert a JSONobject to a string.

base64.encode Specify a string tobe converted toBASE64.

String encoded toBASE64

Encode intoBASE64.

base64.decode Specify a BASE64string.

String decoded fromBASE64

Decode fromBASE64.

http.call JSON object of therequest

JSON object of theresponse

Perform http(s)request and returna response.

http.toRawHeader JSON object of theheader

Header string Return the headerin the form ofstring. To theargument, specifythe JSON objectwhere the key andits value is set.

http.defaultErrorHandler Error None Throw HttpErrorinstance.JSON object of the

request

JSON object of theresponse

http.handleCall httpCall method None Call the httpCallmethod of the firstargument byspecifying therequest of thesecond argument. Ifthe response of theresult is 200 ormore and less than400, call the thirdargument, and inthe case of otherresponse codes, call

JSON object of therequest

Method to call whenthe http call issuccessful.

Method to call whenthe result statuscode is 200 or moreand less than 400.


Method Name Argument Return Value Description

Method to call whenan error occursbefore the http call.

the fourthargument.

The following members are available for the auto util

Table 44 auto util Members

Member Type Description

requestUrl String [If not using Web ServiceConnection] Specify the requestURL starting with http(s). [Ifusing Web Service Connection]Specify the part from the "/"after the host name of therequest URL to the en.Example: In the case ofhttp://host:port/folder,specify "/Folder".

requestMethod String HTTP request method. Specifythe following value as thestring. - GET - POST - PUT -DELETE

requestHeaders String Request header. Assume thatthe return value of thehttp.toRawHeader method isset. [When using Web ServiceConnection] The followingvalues can be used as padcharacters for user ID andpassword. - ${connection.username} - ${connection.password}

requestBody String Request body

authScheme String If authentication is required,specify one of the followingvalues. - basic - digest -negotiate

productName String Specify Web Service Connectioncategory. Be sure to specify ifusing Web Service Connection.

connectionName String Specify Web Service Connectionname. Be sure to specify ifusing Web Service Connection.



userName String Specify the user name if youwant to authenticate to thedestination. Do not specify ifusing Web Service Connection.

password String Specify the password if youwant to authenticate to thedestination.

useProxy boolean Specify whether to use a proxy(true/false).

proxyHost String Specify the hostname or IPaddress of the proxy server.

proxyPort int Specify the port number of theproxy server.

proxyAuthScheme String If the authentication is requiredat the proxy server, specify oneof the following values. - basic -digest

proxyUserName String Specify the user name if theauthentication is required at theproxy server.

proxyPassword String Specify the password if theauthentication is required at theproxy server.

The following table provides the allowable response members:

Table 45 Response Members


responseHeaders String Response header

responseStatusCode int Response code

responseStatusMessage String Response message

responseBody String Response body

Sample code

A JavaScript sample code that can be specified in the plug-in propertyJavaScript body is shown below:(function(serviceProperties, pluginProperties, arg0, arg1, arg2) { var obj = new Object(); print("[Debug] Function begin.");

obj.mem1 = arg0; obj.mem2 = arg1;


if (arg2 == "") { pluginProperties["notify"] = 999; pluginProperties["out1"] = "NOTE!: The arg2 is EMPTY."; } else { obj.mem3 = arg2; obj.status = "success"; pluginProperties["out1"] = "Finished succesfully."; }

print("[Debug] Function end.");

return obj;})As described in the above table, there are two ways of obtaining arg0,arg1,... where each can provide a different value. For pluginProperties, thearguments are obtained as a string but when obtained from the argumentarg0, arg1,..., the evaluated value can be obtained from JavaScript. Theexample that shows the difference between the case of obtaining the inputproperty of the plug-in from pluginProperties and the case of obtaining itfrom arg0, arg1,... is shown below.

Suppose that the following sample code is run by specifying 3 to arg0 and 5to arg1.(function(serviceProperties, pluginProperties, arg0, arg1) { pluginProperties["out0"] = pluginProperties["arg0"] + pluginProperties["arg1"]; pluginProperties["out1"] = arg0 + arg1;})When this sample code is run, "35" is set to out0, and "8.0" is set to out1.From pluginProperties, the arguments are handled as strings of "3" and "5"respectively, while the "+" symbol is handled as the string concatenation. Inaddition, for arg0 and arg1, they become 3.0 and 5.0 respectively, while the"+" symbol is handled as the addition operation.

This sample gets the service template list from Automation Director byreferring to the connection information provided by Web Service Connection,and sets to the output property to out1. As a prerequisite, the Web ServiceConnection whose category is "Automation" and whose name is "view" mustalready be registered.

(function(serviceProperties, pluginProperties) { pluginProperties.out0 = getServiceTemplates('Automation', 'view');

function getServiceTemplates(productname, connectionname) { var respBody = null; var request = { requestMethod: 'GET', requestUrl: '/Automation/v1/objects/ServiceTemplates/', requestHeaders:auto.util.http.toRawHeader({ 'Accept': 'application/json', 'Accept-Language': 'en',


'Content-Type': 'application/json', }), authScheme: 'basic', connectionName: connectionname, productName: productname, };

auto.util.http.handleCall(auto.util.http.call, request, function(resp, req) { respBody = resp.responseBody; }, function(resp, req) { auto.util.http.defaultErrorHandler(null, req, resp); }, function(err, req) { auto.util.http.defaultErrorHandler(err, req); }); return respBody; }})This sample shows how to get the service template list from AutomationDirector without referring to the connection information of Web ServiceConnection, and sets to the output property out1. As a prerequisite, the hostname must be "host", the login user name is "user", and the password is"password".

function(serviceProperties, pluginProperties) { pluginProperties.out0 = getServiceTemplates();

function getServiceTemplates() { var respBody = null; var request = { requestMethod: 'GET', requestUrl: 'http://host:22015/Automation/v1/objects/ServiceTemplates/', requestHeaders:auto.util.http.toRawHeader({ 'Accept': 'application/json', 'Accept-Language': 'en', 'Content-Type': 'application/json', }), authScheme: 'basic', userName: 'user', password: 'password', useProxy: 'false', };

auto.util.http.handleCall(auto.util.http.call, request, function(resp, req) { respBody = resp.responseBody; }, function(resp, req) { auto.util.http.defaultErrorHandler(null, req, resp); }, function(err, req) { auto.util.http.defaultErrorHandler(err, req); }); return respBody; }})


JavaScript Plug-in for Configuration Manager REST APIRuns any script written in JavaScript and includes methods for accessingConfiguration Manager REST API.

The relationship between the specification of Configuration Manager REST APIand the specification of methods & data models which are available in thescript of this plug-in, is as follows:• The path name of each API, the method with the name where the

"/"(slash) separator is replaced with a "."(dot) separator, is providedthrough the plug-in.

• The HTTP Method can be specified such as "~.get(…", "~.post(…" at theend of the method name.

• The variables and the query parameters in the API path can be specified asthe arguments of the method.

• The Request Body can be given to the arguments as the relevant datamodel.

Return codes

The following return codes are generated by the JavaScript Plug-in forConfiguration Manager REST API:


0 Ended normally.

1 Script has terminated due to an error.

60 A JavaScript library read error has occurred.

61 A JavaScript compile error has occurred.

62 The JavaScript code is not properly formatted.



Property list

The following properties are available for the JavaScript Plug-in forConfiguration Manager REST API:


I/Otype

Required

webServiceConnectionCategory

Web ServiceConnectionCategory

Specify the Web ServiceConnection category. By thecombination of this property

- Input O



I/Otype

Required

and Web Service ConnectionName, Web Service Connectioncan be identified uniquely.

webServiceConnectionName

Web ServiceConnectionName

Specify the Web ServiceConnection name. If thisproperty and Web ServiceConnection Category arespecified, Web ServiceConnections registered intoAutomation Director aresearched and if there ismatching one, its URL andProxy are used at the time ofAPI call.

- Input O

baseUrl Base URL Specify the base URL at thetime of API call. - The inputformat is "<protocol>://<host>:<port>/". - Thesubsequent resource path andthe query parameters cannotbe specified. See details onWebServiceConnection below.

- Input O

requestHeaders

RequestHeaders

Specify the HTTP requestheaders appended at each APIcall. Main usage is the variousauthentications. Specify as thefollowing format (The leadingand trailing white spaces of theheader name and the value areignored.): < Header-name-of-Header1 > : < Value-of-Header1 > \n < Header-name-of-Header2 > : < Value-of-Header2 > \n You can specifyany additional headers.However, since the headerrequired to connect withConfiguration Manager RESTAPI (such as credential, etc.) isautomatically appended,basically it is not necessary tospecify the header here.

- Input O

webUsername ServerAuthenticationBasic UserName

Specify the user name used forserver authentication.

- Input O



I/Otype

Required

webPassword ServerAuthenticationBasic Password

Specify the password used forserver authentication.

- Input O

useProxy Use ProxyServer

Set this to true when a proxyconnection is required.

- Input O

ApiKey ServerAuthenticationAPI Key

Specify the API key forauthentication (used togetherwith API Key Prefix)

- Input O

ApiKeyPrefix ServerAuthenticationAPI Key Prefix

Specify the API Key Prefix forauthentication (used togetherwith API Key). The followingpart of HTTP header.Authorization: [API Key Prefix][API Key].

- Input O

proxyHostname

Proxy Hostname Specify the proxy host name orIP address.

- Input O

proxyPort Proxy PortNumber

Specify the proxy port number. - Input O

proxyAuth Proxy ServerAuthenticationScheme

Specifies the proxyauthentication type. Thefollowing authenticationfunctions are supported: •Basic authentication • Digestauthentication

- Input O

proxyUsername

Proxy Username

Specify the user name used forproxy authentication.

- Input O

proxyPassword

Proxy Password Specify the password used forproxy authentication.

- Input O

scriptBody Script body Specifies the JavaScript codestrings.

-- Input R


-- Input O


-- Input O


-- Input O


-- Input O


-- Input O


-- Input O



I/Otype

Required


-- Input O


-- Input O


-- Input O


-- Input O

notify Notification Flag Specifies a non-empty string ifthe script detects something tonotify; the plugin wouldterminate with a return valueof 1 if a non-empty string wasspecified here.

-- Output O

returnValue Return Value The content of the objectreturned from the function ofthe specified script is output asa character string.

-- Output O


-- Output O


-- Output O


-- Output O

out3 Argument(3) A value set to the out3key inthe map of the secondargument in the user-specifiedscript is output.

-- Output O


-- Output O


-- Output O

out6 Argument(6) A value set to the out6 key inthe map of the second

-- Output O



I/Otype

Required

argument in the user-specifiedscript is output.


-- Output O


-- Output O


-- Output O

The setting value of Web Service Connection can be referred to as a value ofthe input property of the Plug-in. In this case, the corresponding inputproperty is overwritten by the setting value of the Web Service Connection.Whether or not to refer to the setting value of Web Service Connection isdetermined by the input value of webServiceConnectionCategory andwebServiceConnectionName. When referring to the setting value ofWebServiceConnection, the URL (property name: baseUrl) is ignored.

You specify the plug-in input/output properties in the property list.Combinations of service property values, reserved property values, and literalcharacters can be used for the input properties.

Input Value ofwebServiceConnectionCategory

Input Value ofwebServiceConnectionName

Behavior of the plug-in

Exist Exist Refer to the value of WebService Connection. If nomatching Web ServiceConnection is found, it becomesa run-time error.

Exist Not exist Error (tried to refer to WebService Connection, butcouldn't find the matching one.)

Not exist Exist Same as above.

Not exist Not exist Do not refer to the value ofWeb Service Connection.


JavaScript code specifiable for the JavaScript body

The following table provides the JavaScript codes that are allowable in thebody of the script:

Character encoding UTF-8

Available JS Library underscore.js 1.8.3

auto_util-1.0.0.js (Bundled library of HAD)

Format Must be an unnamed function (See the samplecode.)

Function callinterface

Argument serviceProperties Object type Service properties are mapped.The values of the serviceproperties can be viewed fromthe script. Note that even if thescript updates, deletes, or addsany of the values, the modifiedvalues will not be reflected inthe service properties after thescript is called.

pluginProperties Object type Plug-in properties are mapped.The values of the plug-inproperties can be viewed fromthe script.

arg0 to arg9 Stringsspecified in theplug-inproperties aredirectlymapped. Eventhe stringsconform toJSON, if thescript refers tohere, andarguments canbe obtained asstrings, notobjects. Whenyou do notexpect that thevalidation fromJSON stringsto objectsdescribedbelow, checkhere.

notify If you specify avalue otherthan a non-empty string to


a memberspecified fornotify in thescript, theplug-in finisheswith a returnvalue of 1 aftercalling.

out0 to out9 If you specifyvalues tomembersspecified forout0 to out9 inthe script, thevalues arereflected in theplug-in outputproperties ofArgument(0)toArgument(9)after calling.The values arereflected in theprocessingresults of thescript, and theresults will beused for thenext step. (Seethe samplecode.)

arg0 to arg9 Plug-in properties Argument(0) to Argument(9)are mapped. (Optional)If you specify JSON strings to the plug-inproperties, the strings can be obtained asobjects in the functions of the script.• Strings that are enclosed with double

quotation marks are mapped as is.• If strings are not enclosed, strings that fail

JSON validation are mapped as is.

Return code Any objects can be returned from the script. After calling the script,the return codes are extracted as JSON strings that are thenreflected in the plug-in output property Return value. The valuesare reflected in the processing results of the script and then usedfor the next step. (See the sample code.)

print ()function

By using the print() function in the script, you can output any strings to the tasklog. In this case, choose a log level by adding a specific prefix to the beginning ofthe string. Note that alphabetical prefixes are case-sensitive. (See the samplecode.)

Prefix [Severe] Outputs as log level 0


[Informational] Outputs as log level 10

[Fine] Outputs as log level 20

[Finer] Outputs as log level 30

[Debug] Outputs as log level 40

(No prefix) Same as the prefix [Information]

Otherfunctionalities

If an exception is thrown in the script or an unexpected exception occurs in thescript, the plug-in terminates abnormally and shows the exception in the task log.

When the script finishes properly, and when the values returned from the script orthe values specified in the plug-in output properties (out0 to out9) of the scriptcontain null or undefined, those values are stored as null or undefined.

Sample code

The following examples show the sample code of Configuration ManagerREST API (HTTP) and the JavaScript that can be specified in the plug-inproperty JavaScript body:

Obtain Pool Information[In the case of Configuration Manager REST API (HTTP)]HTTP Method: GETRequest URL: ../ConfigurationManager/v1/objects/storages/<storageDeviceID>/pools?poolType=<poolType>Request Body: None

[In the case of JavaScript Plug-in for Configuration Manager REST API]var client = new api.ObjectsApi();client.v1.objects.storages.storageDeviceID.pools.get(<storageDeviceID>, <poolType>, <responseMaxWait>, <responseJobStatus>);Register the Pool information[In the case of Configuration Manager REST API (HTTP)]HTTP Method: POSTRequest URL: ../ConfigurationManager/v1/objects/storages/<storageDeviceID>/poolsRequest Body: { "poolId": 76, "poolName": "pool1", "ldevIds": [405], "poolType": "HDP" }

[In the case of JavaScript Plug-in for Configuration Manager REST API]var reqBody = model.RequestBody27();reqBody.setPoolId(76);reqBody.setPoolName("pool1");reqBody.setLdevIds([405]);reqBody.setPoolType("HDP");

var client = new api.ObjectsApi();client.v1.objects.storages.storageDeviceID.pools.post(<storageDeviceID>, reqBody,<responseMaxWait>, <responseJobStatus>);


LDEV ID Search Plug-inOutputs a list of LDEV IDs to match the conditions specified in input property.

Return codes

The following return codes are generated by the LDEV ID Search Plug-in:


0 Ended normally.

1 Ended abnormally.


Property list

The following properties are available for the LDEV ID Search Plug-in:



I/O typeRequired

deviceManagerName

DeviceManagerName

Specifies the HDvM namedefined throughDeviceManagerName in DeviceManager Connections on HAD.

-- Input R

storageModel StorageModel

Specifies the storage modelname. Only physical storagesystems are supported. (e.g.,HUS150 VSP G1000)

-- Input R

storageSerialNumber

StorageSerialNumber

Specifies the storage serialnumber. Only physical storagesystems are supported. Specifythe serial number of the storagesystem displayed on HDvM.

-- Input R

resourceGroupName

ResourceGroupName

Resource group name. Onlyphysical storage systems aresupported. If All Resources isspecified, it doesn’t have arelationship to the resource, soread it to Default resourcegroup instead. If nothing isspecified, acquire with beingindependent on the resourcegroup.

-- Input O

LdevIds LDEV IDs LDEV ID. Specify in decimalnumber. Specify LDEV ID to

-- Input O




I/O typeRequired

search in comma separatedvalue. If nothing is specified,acquire with being independenton LDEV ID.

startLdevId LDEV IDStartsFrom

Specifies the starting LDEV IDfrom of the range to search indecimal number. If nothing isspecified, acquire with beingindependent on LDEV ID.

-- Input O

endLdevId End WithLDEV ID

End with LDEV ID. Specify endwith LDEV ID of the range tosearch in decimal number. Ifnothing is specified, acquirewith being independent on LDEVID.

-- Input O

isAssigned Assigned LDEV ID is already assigned ornot. If you want to search onlyunassigned LDEVs, specify false.true/false format. If nothing isspecified, search both assignedand unassigned LDEVs.

-- Input O

limit Limit Upper limit of search resultcount. If nothing is specified,the default value is used.

100 Input O

offset Offset Offset value of search result. Ifnothing is specified, the defaultvalue is used.

0 Input O

resultData ResultData

Search result data. Json format.LDEV ID (decimal)/ LDEV ID(hexadecimal)/ Assigned (trueor false)/ are outputted.Example of Json file outputformat:

[{"ldevId":328,"displayLdevId":"00:01:48","assigned":false},"ldevId":329,"displayLdevId":"00:01:49","assigned":false}]

[ ] Output O

resultCount ResultCount

Search result count. 0 Output O

errorMessage SummaryMessage

Output the error message to theproperty for Summary.

-- Output O


Path Search Plug-inSearches for path details based on a given search criteria.

Path Search Plug-in is the plug-in which perform a search of path informationwhose input value of search conditions is at least one of host name / hostport / storage port /LDEV ID, and output the search result.

Return codes

The following return codes are generated by the Path Search Plug-in:


0 Ended normally.

1 Ended abnormally.


Property list

The following properties are available for the Path Search Plug-in:



I/O typeRequired

deviceManagerName

DeviceManagerName

Specifies the HDvM namedefined throughDeviceManagerName in DeviceManager Connections onAutomation Director.

-- Input R

storageModel StorageModel

Specifies the storage modelname. Only physical storagesystems are supported. (e.g.,HUS150 VSP G1000)

-- Input O

storageSerialNumber

StorageSerialNumber

Specifies the storage serialnumber. Only physical storagesystems are supported. Specifythe serial number of thestorage system displayed onDevice Manager.

-- Input O

host Host Host name. Specify the host ofthe path information to search.At least one of Host Name /Host Port / Storage Port / LDEVID is required.

-- Input O

hostPort Host Port Host Port. Multiplespecifications are not allowed.

-- Input O




I/O typeRequired

Specify WWN or iSCSI Name ofthe path information to search.Specification by port name isnot supported. At least one ofHost Name / Host Port /Storage Port / LDEV ID isrequired.

storagePort StoragePort

Storage Port. Specify StoragePort of the path information tosearch. Multiple specificationsare not allowed. Specificationby WWN is possible. At leastone of Host Name / Host Port /Storage Port / LDEV ID isrequired.

-- Input O

ldevId LDEV ID LDEV ID. Specify LDEV ID indecimal number. Multiplespecifications are not allowed.At least one of Host Name /Host Port / Storage Port / LDEVID is required.

-- Input O

lun LUN LUN. Specify LUN of the pathinformation to search. Multiplespecifications are not allowed.NNNN format. If nothing isspecified, acquire with beingindependent on LUN.

-- Input O

limit Limit Upper limit of search resultcount. If nothing is specified,the default value is used.

100 Input O

offset Offset Offset value of search result. Ifnothing is specified, the defaultvalue is used.

0 Input O

resultData ResultData

Search result data. Json format.Storage System Name/ StorageModel/ Storage Serial Number/Storage Port/ LDEV ID(decimal)/ LDEV ID(hexadecimal)/ Volume Label/Volume Capacity/ Host Name/Host Port/LUN are out putted.Example of Json file outputformat:

[{"storageSystemName":"R700#1","arrayFamily":"VSP","serialNumber":"53001","storagePort":"50.06.0E.80.06.CF.

[] Output O




I/O typeRequired

2E.00","ldevId":"251","displayLdevId":"00:00:FB","volumeLabel":"","capacity":"50.00MB","hostName":"host1","hostPort":"00.00.00.00.00.00.00.12","lun":"0005"}]

resultCount ResultCount

Search result count. 0 Output O

errorMessage SummaryMessage

Output the error message tothe property for Summary.

-- Output O

Web Client Plug-inThe Web Client Plug-in sends and receives HTTP request and responsemessages. When requested, it accesses the server via a proxy and performsserver and proxy authentication.

Function

This plug-in sends and receives HTTP request and response messages andconsists of the following functions:• Supports HTTP/HTTPS 1.1.• Generates an HTTP request message based on the input properties and

receives HTTP response messages as output properties.

The following table shows the relationships between HTTP request messagesand their corresponding input properties.

Element Input Property

Request line Method requestMethod

URI requestURl

HTTP/version -

Header requestHeaders

Body requestBody

The following table shows the relationships between HTTP response messagesand their corresponding output properties.

Element Output Property

Status line HTTP/version -


Element Output Property

Status code responseStatusCode

Status message responseStatusMessage

Header responseHeaders

Body responseBody

Prerequisites for execution• To use HTTPS communication, import the destination server certificate or a

root certificate that authenticates the server certificate in JRE Trust Storeon the client (Automation Director installation server).

Return codes

The following return codes are generated by the Web Client Plug-in:


0 Ended normally.

1 A status code other than Success is returned for an HTTPresponse message.

70 Failed to connect to the remote host.

77 Failed to resolve the host name for the remote host.


86 An incorrect property value has been specified.

90 A data transmission failure occurred after the connection wasestablished.

91 The size of the HTTP response message exceeds the upperlimit value of the system.

127 Another unspecified type of error has occurred.

Property list

The properties available for the Web Client Plug-in.



I/O typeRequired

webServiceConnectionCategory

Web ServiceConnectionCategory

When referring to theinformation of Web ServiceConnection and using it as aninput value of Web Client Plug-in, specify the category of WebService Connection.

-- Input O




I/O typeRequired

webServiceConnectionName

Web ServiceConnectionName

When referring to theinformation of Web ServiceConnection and using it as aninput value of Web Client Plug-in, specify the name of WebService Connection.

-- Input O

requestMethod Method Specify the HTTP method asfollows:• GET• POST• PUT• DELETE

GET Input R

requestUrl Request URL Specify the resource URL towhich the HTTP request is sent,and a query parameter. TheURL-encoded value specified asthe input property value is usedas is. See details onWebServiceConnection below.

-- Input R

requestHeaders RequestHeaders

Specify the HTTP requestheader in raw format. It isrecommended that you use theContent-Type header and thecharset parameter to specifythe request body format andcharacter set.

-- Input O

requestBody Request Body Specify the HTTP request bodyin the raw format. Use theformat specified in the Content-Type header.

-- Input O

webAuth ServerAuthenticationScheme

Specify the serverauthentication type:• none -- No authentication• basic -- Basic authentication• digest -- Digest

authentication• negotiate -- Negotiate

authentication

It is recommended that youspecify "none" for theauthentication header inrequestHeaders.

-- Input R

webUsername ServerAuthenticationUsername

Specify the user name used forserver authentication. Invalidwhen the webAuth property key

-- Input O




I/O typeRequired

is set to none. See details onWebServiceConnection below.

webPassword ServerAuthenticationPassword

Specify the password used forserver authentication. Seedetails onWebServiceConnection below.

-- Input O

useProxy Use ProxyServer

Set this to true when a proxyconnection is required. Seedetails onWebServiceConnection below.

false Input R

proxyHostname ProxyHostname

Specify the proxy host name orIP address. See details onWebServiceConnection below.

-- Input O

proxyPort Proxy PortNumber

Specify the proxy port number.See details onWebServiceConnection below.

8080 Input O

proxyAuth Proxy ServerAuthenticationScheme

Specifies the proxyauthentication type. Thefollowing authenticationfunctions are supported:• Basic authentication• Digest authentication

It is recommended that youspecify "none" for theauthentication header inrequestHeaders.See details onWebServiceConnection below.

none Input R

proxyUsername ProxyUsername

Specify the user name used forproxy authentication. Seedetails onWebServiceConnection below.

-- Input O

proxyPassword ProxyPassword

Specify the password used forproxy authentication. Seedetails onWebServiceConnection below.

-- Input O

responseStatusCode

Status Code Outputs the status code of theHTTP response message. When"3xx Redirect" is returned,automatic tracking is activated

-- Output O

responseStatusMessage

StatusMessage

Outputs the status message ofthe HTTP response message.

-- Output -

responseHeaders

ResponseHeaders

Outputs the header informationof the HTTP response message.

-- Output --




I/O typeRequired

responseBody ResponseBody

Outputs the body information ofthe HTTP response message.

-- Output --

Note: When using Basic authentication, a request without authenticationreturns the 401 response code and a "WWW-Authenticate:Basic" headerindicating that authentication is required. If "WWW-Authenticate:Basic" is notreturned, the authentication token with Base64-converted"Username:Password" is added to the request header. Authentication by thepreemptive method is not supported because Digest authentication requiresvalues such as a nonce value to be returned from the server.

The setting value of Web Service Connection can be referred to as a value ofthe input property of the Web Client Plug-in. In this case, the correspondinginput property is overwritten by the setting value of the Web ServiceConnection.

Whether or not to refer to the setting value of Web Service Connection isdetermined by the input value of webServiceConnectionCategory andwebServiceConnectionName.

Input Value ofwebServiceConnectionCategory

Input Value ofwebServiceConnectionName

Behavior of Web Client Plug-in

Exist Exist Refer to the value of WebService Connection. If nomatching Web ServiceConnection is found, it becomesa run-time error.

Exist Not exist Error (tried to refer to WebService Connection, butcouldn't find the matching one.)

Not exist Exist Same as above.

Not exist Not exist Do not refer to the value ofWeb Service Connection.

When referring to the setting value of WebServiceConnection, the URL(property name: requestUrl) is assembled dynamically at the run time. Asthe input value of the property, you must specify the part after "/" after thehost name. The part before "/" is assembled from the setting value of WebService Connection. In the case of the string, where the value specified inrequestUrl does not begin with "/", it generates a run-time error.


Example: In the case of "http://host:port/Folder/", specify "/Folder/" as theinput value. The following table shows the relationship between the value ofthe Web Server Connection and the input value of the Web Client Plug-in:

Item of the Web ServiceConnection

Input Property of Web ClientPlug-in

Remark

IP Address/Host Name Part of requestUrl host part of "http://host:port/

Folder/"

Protocol Part of requestUrl http part of "http://host:port/

Folder/"

Port Part of requestUrl port part of "http://host:port/

Folder/"

User ID webUsername Output the message to the task

logs that overwriting the input

value if it was set.

Password webPassword Output the message to the task

log that overwriting the input


Use Proxy Server useProxy -

IP Address/Host Name in Use

Proxy Server

proxyHostname Output the message to the task



Port in Use Proxy Server proxyPort Output the message to the task



Authentication Type in Use

Proxy Server

proxyAuth -

User ID in Use Proxy Server proxyUsername Output the message to the task



Password in Use Proxy Server proxyPassword Output the message to the task



Supported Headers

Headers are transmitted and received in their raw format. The followingdefault headers are supported:

Header Value

Accept application/json


Header Value

Accept-Language en

Content-Type (Only when POST or PUT isspecified as the method.)

application/json

Cache-Control no-cache

Pragma no-cache

User-Agent client-software-name, version

Host destination-host-name, port-number

Connection keep-alive

The following headers have a special behavior:

Header Behavior

Charset parameter in the Content-Type header Request: The body character set is converted byusing the value specified in the Charsetparameter of the Content-Type header. When novalue is specified, it is converted to UTF-8.

Response: The body character set is interpretedaccording to the value specified in the Charsetparameter of the Content-Type header. When acharset parameter is not returned, it isinterpreted as UTF-8.

Content-Encoding When the Content-Encoding header is returned,the body is extended. The following encodingformats are supported:• gzip• deflate

Connection timeout value settings

To deal with any HTTP/HTTPS communication problems that might occurwhen connecting to the destination, you should configure the connectiontimeout key value (plugin.http.connect.timeout) so it is obvious when aproblem occurs with the connection. The connection timeout value isspecified through the key name (config_user.properties) in the propertyfile under Automation-director-install-path\Automation\conf.

Linkage with the JavaScript Plug-in

Because the Web Client Plug-in does not rewrite input and output propertyvalues, linkage with the JavaScript Plug-in is effective when values need tobe rewritten. Following is an example of linkage with the JavaScript Plug-in toextract the URL encoding and the SSO authentication token from the serverresponse.


The following table shows the flow linkage with the JavaScript Plug-in:

Plug-in Flow Description

JavaScript Plug-in 1 Input URL entered by the user.Script that executes URLencoding.

Execute Executes URL encoding.

Output URL-encoded URL.

Web Client Plug-in 1 Input URL-encoded URL.Other information entered bythe user (such as the header).

Execute Generates and sends the HTTPrequestReceives and analyzes the HTTPresponse .

Output Outputs the HTTP responseelements (such as the header).

JavaScript Plug-in 2 Input URL-encoded URL.Reconfigured header.

Other information entered bythe user.

Execute Generates and sends the HTTPrequestReceives and analyzes the HTTPresponse.

Output Outputs the HTTP responseelements.


Prerequisites for using Negotiate authentication

Negotiate authentication uses Kerberos v5 authentication, which requires thefollowing configuration files:

File Name Description Edited by user

Kerberos configuration file

(krb5.conf)

Kerberos configuration in theuser environment.

Required

Login configuration file

(login.conf)

Specifies the authenticationtechnology to be used.

Not required

As shown below, the Kerberos configuration file is located in Automation-director-install-path\Automation\conf\plugin. Edit the italicizedcharacters, etc., as needed for the user environment.[libdefaults] // Default value for Kerberos authentication default_realm = EXAMPLE.COM // Default realm for Kerberos authentication udp_preference_limit = 1

[realms] // KDC setting for each Kerberos realm (you can define settings for multiple realms) EXAMPLE.COM = { kdc = kdc.example.com // KDC host name }

[domain_realm] // Maps the Active Directory domain to the Kerberos realm .example.com = EXAMPLE.COM example.com = EXAMPLE.COM

Note: Realms are case-sensitive. Because uppercase letters areconventionally used, use uppercase to specify realms (lowercase letterscannot be used).

Note: Although Kerberos authentication uses UDP by default, it uses TCP forlager messages. Because TGT requests that use UDP will fail to link withActive Directory, use udp_preference_limit=1 so that TCP is used.

Login Configuration File

The following login configuration file is located in Automation-director-install-path\Automation\conf\plugin.com.sun.security.jgss.krb5.initiate { com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true doNotPrompt=false refreshKrb5Config=true; // Specifies the authentication technology and options to be used};


Enter the following in Hbase-install-path\Base64\uCPSB\CC\web\containers\AutomationWebService\usrconf\usrconf.cfg so that theKerberos configuration file and the login configuration file are referenced.add.jvm.arg=-Djava.security.krb5.conf=Automation/conf/plugin/krb5.confadd.jvm.arg=-Djava.security.auth.login.config=Automation/conf/plugin/login.conf add.jvm.arg=-Djavax.security.auth.useSubjectCredsOnly=false


IndexB

Build operation 126Built-in Plug-in Parameters 189

CCharacter Set Auto Judgment 93conditional branch

Plug-ins 105, 107, 111conditional branch in flow 57Configuration type

debug 126release 145

creating a service templateedit service template attributes, dialog box148

Creating newplug-ins 93

creating the flow 47

Ddata map

component version management, dialog box154create property group, dialog box 150create step attributes, dialog box 49edit domain type definition dialog box 78edit property group, dialog box 152import service template package, dialog box33

DebuggerChecking property mapping 140Controlling the display of tasks 139Controlling the processing flow of debug task137edit step property, dialog box 141editing service and request entries 132Examining debug details 136Exporting property values 143Handling interruptions of debug tasks 138Importing property files 141Perform Debugging, dialog box 130running 128

Working with the debugger 133Debugging and releasing

workflow 125

EEnvironment variables 104Example

creating a service template 86, 112

Ggenerating an email

Plug-ins 105, 107, 111Getting started tips 26GUI

create variable, dialog box 85GUI settings

create input property for service, dialog box 65create output property for service, dialog box83select reference property, dialog box 64select service share property, dialog box 63

IInput properties

in plug-ins 93, 99Intended audience 8

JJudgment level 48

MManaging tasks during debugging 137

OOutput filters

Plug-ins 105, 107, 111

Index 307Hitachi Automation Director Service Builder User Guide

Output propertiesin plug-ins 93, 102

Pplug-in

create plug-in, dialog box 94plug-in mapping

specify component input properties formapping parameters, dialog box 53

plug-inscreate environment variable, dialog box 105create input property for custom plug-in,dialog box 99create output property for plug-in, dialog box102edit output filter, dialog box 107specify execution condition, dialog box 59

Plug-ins 105, 107, 111creating new 93creation workflow 93input properties 99managing 37output properties 102properties 98remote commands 103

RRelease operation 145

SService Builder

GUI 26service template

create service template, dialog box 47Service template

managing 28overview 28

Service templatesadding input properties 65adding output properties 83adding variables 84build result, dialog box 127Creating a flow hierarchy 56creating a new service template 46creating the steps 48creation workflow 44Establishing the flow of execution 54releasing 145selecting the service share properties 62step properties 51testing 126

308 IndexHitachi Automation Director Service Builder User Guide

Hitachi Automation Director Service Builder User Guide

Hitachi Data Systems

Corporate Headquarters2845 Lafayette StreetSanta Clara, California 95050-2639U.S.A.www.hds.com

Regional Contact Information

Americas+1 408 970 [email protected]

Europe, Middle East, and Africa+44 (0) 1753 [email protected]

Asia Pacific+852 3189 [email protected]

Contact Uswww.hds.com/en-us/contact.html

MK-92HC222-08

http://www.hds.com

MAILTO:[email protected]

