hitachi automation director service builder - hitachi … · · 2015-11-09this manual describes...

Hitachi Command Suite

Automation Director Service BuilderUser Guide

MK-92HC222-03

© 2015 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 photocopying and recording, or stored in a database or retrieval system forany purpose without the express written permission of Hitachi, Ltd.

Hitachi, Ltd., reserves the right to make changes to this document at any time without notice andassumes no responsibility for its use. This document contains the most current information availableat the time of publication. When new or revised information becomes available, this entire documentwill be updated and distributed to all registered users.

Some of the features described in this document 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, Ltd., products and services can be ordered only under the terms and conditions ofthe applicable Hitachi Data Systems Corporation agreements. The use of Hitachi, Ltd., products isgoverned by the terms of your agreements 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

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.

Hitachi is a registered trademark of Hitachi, Ltd., in the United States and other countries. HitachiData Systems is a registered trademark and service mark of Hitachi, Ltd., in the United States andother countries.

Archivas, Essential NAS Platform, HiCommand, Hi-Track, ShadowImage, Tagmaserve, Tagmasoft,Tagmasolve, Tagmastore, TrueCopy, Universal Star Network, and Universal Storage Platform areregistered trademarks of Hitachi Data Systems.

AIX, AS/400, DB2, Domino, DS6000, DS8000, Enterprise Storage Server, ESCON, FICON, FlashCopy,IBM, Lotus, MVS, OS/390, RS/6000, S/390, System z9, System z10, Tivoli, VM/ESA, z/OS, z9, z10,zSeries, z/VM, and z/VSE are registered trademarks or trademarks of International Business MachinesCorporation.

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

Microsoft product screen shots are reprinted with permission from Microsoft Corporation.

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.

2Hitachi Automation Director Service Builder

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

Contents

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

1 Overview of Service Builder.................................................................. 13Using Service Builder..............................................................................................15Terminology...........................................................................................................17Accessing Service Builder........................................................................................21Navigating the interface..........................................................................................21

2 Working with service templates.............................................................25Service template overview...................................................................................... 26Service Template List dialog box..............................................................................26Managing service templates....................................................................................27

Viewing a service template................................................................................27Copying a service template................................................................................28Copy Service Template dialog box...................................................................... 28Deleting a service template............................................................................... 29Importing a service template.............................................................................30Import Service Template Package dialog box...................................................... 30Exporting a service template............................................................................. 31

3 Working with plug-ins.......................................................................... 33Plug-ins overview...................................................................................................34Custom Plug-in List dialog box................................................................................ 35


Managing plug-ins..................................................................................................36Copying a plug-in............................................................................................. 36Copy Custom Plug-in dialog box.........................................................................37Deleting a plug-in............................................................................................. 37

4 Creating and editing service templates.................................................. 39Service template creation workflow......................................................................... 40Creating a service template.....................................................................................42Create Service Template dialog box......................................................................... 42Editing a service template.......................................................................................43Specifying the step flow..........................................................................................44

Creating the steps in a data flow........................................................................44Create/Edit Step dialog box............................................................................... 45Specifying step properties................................................................................. 46Specify Component Input/Output Property for Mapping Parameters dialog box......49Establishing the flow of execution...................................................................... 50Creating a flow hierarchy...................................................................................52

Specifying the GUI settings..................................................................................... 53Selecting the service share properties................................................................ 54Select Service Share Property dialog box............................................................ 54Adding input properties.....................................................................................55Create/Edit Input Property for Service dialog box................................................ 56Adding output properties...................................................................................58Create/Edit Output Property for Service dialog box..............................................58Adding variables............................................................................................... 59Create/Edit Variable dialog box.......................................................................... 60

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

5 Creating and editing plug-ins................................................................ 65Plug-in creation workflow........................................................................................67Creating a new plug-in........................................................................................... 67Editing a plug-in.....................................................................................................69Create/Edit Custom Plug-in dialog box..................................................................... 69About plug-in properties......................................................................................... 71Adding plug-in input properties............................................................................... 72Specify/Edit Input Property for Custom Plug-in dialog box......................................... 72Adding plug-in output properties............................................................................. 73Specify/Edit Output Property for Custom Plug-in dialog box.......................................73Setting remote commands in plug-ins......................................................................74Edit Remote Command dialog box........................................................................... 74Setting environment variables................................................................................. 75Create/Edit Environment Variable dialog box............................................................ 76Adding output filters...............................................................................................76Edit Output Filter dialog box....................................................................................77Creating a conditional branch..................................................................................77Generating an email............................................................................................... 81Example of creating a new plug-in ..........................................................................82


6 Building, debugging and releasing.........................................................93Debug and release workflow...................................................................................95Building a service template..................................................................................... 96Build/Release Result dialog box...............................................................................97Running the debugger............................................................................................98Perform Debugging dialog box.............................................................................. 100Editing service and request entries while debugging............................................... 102Working with the debugger...................................................................................103Examining debug details....................................................................................... 105Managing tasks during debugging......................................................................... 106

Controlling the processing flow of debug tasks..................................................106Handling interruptions of debug tasks.............................................................. 107Controlling the display of tasks in the Task List..................................................108

Checking the property mapping of a plug-in........................................................... 110Edit Step Property dialog box................................................................................ 111Importing property values.....................................................................................111Exporting property values..................................................................................... 112Releasing a service template................................................................................. 115

7 Advanced options...............................................................................117Editing the service template attributes................................................................... 118Edit Service Template Attributes dialog box............................................................ 118Specifying property groups....................................................................................119

Create Property Group dialog box.....................................................................120Edit Property Group dialog box........................................................................ 122

Using preset property definition files......................................................................123Formatting preset property definition files.........................................................124Implementing preset property definition files.................................................... 124

Managing versions................................................................................................125Component Version Management dialog box.....................................................126

8 Reference information........................................................................ 127List of built-in service templates............................................................................ 128List of built-in plug-ins.......................................................................................... 133List of reserved properties.....................................................................................137Locale settings for plug-ins....................................................................................140

9 Description of built-in plug-ins.............................................................143General Command Plug-in.....................................................................................145File-Forwarding Plug-in......................................................................................... 154Repeated Execution Plug-in...................................................................................165Email Notification Plug-in...................................................................................... 168User-Response Wait Plug-in.................................................................................. 170Terminal Connect Plug-in...................................................................................... 176Terminal Command Plug-in................................................................................... 189Terminal Disconnect Plug-in.................................................................................. 199Flow Plug-in.........................................................................................................200Interval Plug-in.................................................................................................... 202Judge ReturnCode Plug-in.....................................................................................203


Test Value Plug-in.................................................................................................206Abnormal End Plug-in........................................................................................... 212Judge Value Plug-in.............................................................................................. 213File Export Plug-in................................................................................................ 217JavaScript Plug-in.................................................................................................220LDEV ID Search Plug-in........................................................................................ 225Path Search Plug-in.............................................................................................. 227Web Client Plug-in................................................................................................229

Index................................................................................................ 237


PrefaceThis manual describes how to use Hitachi Automation Director ServiceBuilder.

□ Intended audience

□ Product version

□ Release notes

□ Document conventions

□ Conventions for storage capacity values

□ Referenced documents

□ Accessing product documentation

□ Getting help

□ Comments

Preface 7Hitachi Automation Director Service Builder

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 version

This document revision applies to Hitachi Automation Director v8.2.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.

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

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

8 PrefaceHitachi Automation Director Service Builder

Convention Description

{ } 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 or consequences (for example,disruptive operations).

WARNING Warns the user of severe conditions or consequences (for example,destructive operations).

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 storage capacity values (for example, logical device capacity) arecalculated based on the following values:

Logical capacity unit Value

1 block 512 bytes


Logical capacity unit Value

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

Referenced documentsThe following documents are referenced or contain more information aboutthe features described in this manual.

• Hitachi Automation Director User Guide, MK-92HC205

• Hitachi Automation Director Installation and Configuration Guide,MK-92HC204

• Hitachi Automation Director API Use Case Reference, MK- 92HC232

• Hitachi Automation Director Release Notes, RN-92HC206

• Hitachi Command Suite System Requirements, MK-92HC209

Accessing product documentationProduct user documentation is available on Hitachi Data Systems SupportConnect: https://support.hds.com/en_us/documents.html. Check this site forthe most 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 make


https://support.hds.com/en_us/documents.html



https://community.hds.com/welcome

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

Thank you!


https://community.hds.com/welcome

mailto:[email protected]

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 HAD, there is no need to install HAD ona separate test environment, and files and folders remain in a centrallocation. A feature allows you to test services, plug-ins, configuration filesand mapping parameters before they are released so that quality andfunctionality 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

□ Terminology

□ Accessing Service Builder

□ Navigating the interface

14 Overview of Service BuilderHitachi Automation Director Service Builder

Using Service BuilderService Builder allows 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 HAD Develop or Admin role is required in order to use Service Builder.For more information on permissions and user roles, see the HitachiCommand Suite Automation Director User Guide.


Related concepts

• Accessing Service Builder on page 21• Terminology on page 17• Navigating the interface on page 21

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


Following are definitions for each of the terms:

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). HAD provides pre-packaged servicetemplates that are created, modified and managed through ServiceBuilder. When creating or modifying service templates, you specify thesteps and flow and supply the relevant parameters while in thedevelopment environment until the template has been fully debuggedand tested. Once a service template is functioning properly andperforms 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 HAD installation where it can then besubmitted 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 view.

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 HAD and other areas of the GUI, seethe Hitachi Command Suite Automation Director User Guide.

Related concepts

• Using Service Builder on page 15• Terminology 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.

The Service Builder Home screen provides the options that allow you tocreate and manage the service templates and plug-ins.


The following functions are available to manage service templates:

• Create to create a new service template.• Edit to modify an existing service template in the Developing state. Opens

the Service Builder view.• Copy to copy a service template that is either released or in the

Developing state.• View to review service templates that are released and in the Developing

state. Opens the Service Builder - View Mode screen.• Delete to remove a service template that is in the Developing state.• Import to import a service template from a given source.• Export to export a service template.

The following functions are available to manage plug-ins:

• Create to create a new plug-in.• Edit to modify an existing plug-in that is in the Developing state.• Copy to copy an existing plug-in that is released or in the Developing

state.• Delete to remove a plug-in that is released or in the Developing state.


You create and edit service templates from the Service Builder view whereyou can select the appropriate plug-ins (and sometimes, other servicetemplates) and place them in an execution flow where the logic and valuesrequired to complete a given task are supplied through various input andoutput properties.

The Service Builder interface consists of the following views:• Component view -- Shows the components that are available to be

included in the service template.• Flow view -- Shows the component steps currently included in the service

template.• Flow Tree view -- Shows a structured view of the component steps that are

currently added to the service template.• Step Information view -- Shows the input and output properties available

for the selected component step as well as general details for the step.• Flow Steps view -- Shows the flow of steps in the current service template

and provides the ability to edit the flow if necessary.

The workflow tabs at the top of the screen guide you through the variousprocesses involved in creating or editing a service template as follows:• Create Flow -- Used to select the plug-ins (and services) that are to be

included in the flow for the service template and to specify the input/output properties and attributes.


• GUI Settings -- Specifies the settings for displaying instructions andrequesting values from the user when submitting a service.

• Debug -- Builds the service template and provides access to the debuggerinterface 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 HAD userinterface.

Related concepts

• Using Service Builder on page 15• Accessing Service Builder on page 21• Terminology on page 17


2Working with service templates

You create and manage service templates by choosing the appropriate optionfrom the Service Builder Home View screen.

Note: For information on creating a new template or editing an existingtemplate, please see:Creating and edting service templates on page 39.

This module covers:

□ Service template overview

□ Service Template List dialog box

□ Managing service templates

Working with service templates 25Hitachi Automation Director Service Builder

Service template overviewA custom service template consists of one or multiple components withcommand or script information, and input or output definitions. One or morecomponents are added as steps and arranged in a sequence to form theoperational flow. The service template also requires mapping of input andoutput properties to define the data flow. Using property groups and sharedservice properties can assist in defining in the input and output properties.

There are two versions of service templates:

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

• Debug. A newly created service template begins with a debug version.Testing a service template includes the creation of services and tasksbased 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 debug version of a service template isreleased, the debug version of the service template and all the relatedservices 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.

When managing existing service templates by selecting one of the options (toedit, copy, view, delete, import, or export a service template), the ServiceTemplate List dialog box provides the interface for selecting the servicetemplate to work with.

Service Template List dialog boxThe Service Template List dialog box shows the service templates that can beaccessed from the Service Builder view for a given menu option. It is fromthis list that you select the service template to work with when editing,viewing, copying, deleting, importing, or exporting a service template.

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.

26 Working with service templatesHitachi Automation Director Service Builder

Table 1 Service Template List dialog box

Field Subfield Description

Display Name - Name for the service template.

Description - Description of the service template.

Version - Version of the service template.

Tags - Tag category associated with the service template.

Vendor Name - Vendor name, if applicable, for the service template

A selection of options are provided at the top of the list to find and arrangethe service templates based on the criteria you specify.

Managing service templatesYou manage service templates from the Service Builder Home view.

The various service template management options available from the ServiceTemplate Actions menu are covered in the following topics:

• Viewing a service template on page 27• Copying a service template on page 28• Deleting a service template on page 29• Importing a service template on page 30• Exporting a service template on page 31

For details on creating and editing a service template, please see: Creating aservice template on page 42 and Editing a service template on page 43

Viewing a service templateYou view service templates that are in the released or development statefrom the Service Builder Home screen.

To view an existing service template, follow these steps:

Procedure

1. From the Service Builder Home screen, under Service TemplateActions, click View.The Service Template List dialog appears.

2. From the Service Template List dialog box, select the target servicetemplate and click View.

Result

When viewing a service template, details for the flow and associatedcomponent steps are shown from the Service Builder - View Mode screen.


Related references

• Service Template List dialog box on page 26

Copying a service templateYou copy a service template to create a new version of an existing servicetemplate that you can then modify for your particular operating environment.

You can make a copy of any service template in Released or Developingstatus. Each copied service template must be assigned a new Key Name,Version, or Vendor ID. A service template with the reserved vendor IDstarting with com.hitachi.software.dna requires assigning both a new keyname and vendor ID.

Procedure

1. From the Service Builder Home screen under the Service TemplateActions menu, click Copy.The Service Template List dialog box appears.

2. In the Service Template List dialog box, select the service templatethat you want to copy, and click Copy.The Copy Service Template dialog box appears.

3. In the Copy Service Template dialog box, enter the basic informationfor the service template, then click Save.The service template is created and the Service Builder view opens.

Result

A new copy of the service template is created and is in the Developing state.

Next steps

• After you have created a copy of an existing service template, you canchoose the Edit option to make whatever modifications are necessary foryour environment.

Related references

• Copy Service Template dialog box on page 28

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 2 Copy Service Template dialog box


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.

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 HAD, see the Hitachi Command Suite Automation Director UserGuide.

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 screen, under the Service TemplateActions menu, click Delete.The Service Template List appears.

2. From the Service Template List dialog box, select the target servicetemplate and click Delete.

3. Click OK to confirm deletion.


Result

The specified service template is deleted.

Related references


Importing a service templateYou import a service template to make use of its service on a given system.

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 services onpage 128.

To import a service template, follow these steps:

Procedure

1. From the Service Builder Home screen, under the Service TemplateActions menu, click Import.The Import Service Template Package dialog box appears.

2. From the Import Service Template Package dialog box, click Browseand specify the name and location of the template to import.

3. After specifying the template name and location, click Import.

Result

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

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 3 Import Service Template Package dialog box


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

Exporting a service templateYou 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 Service Builder Home screen, under the Service TemplateActions menu, click Export.The Service Template List appears.

2. From the Service Template List dialog box, select the target servicetemplate and click Export.

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

Result

The service template is exported.

Related references



3Working with plug-ins

Plug-ins are a fundamental part of a service template. Each plug-in isdesigned with a specific purpose and their use and sequence within a servicetemplate is an important part of the service template operation.

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

This module covers:

□ Plug-ins overview

□ Custom Plug-in List dialog box

□ Managing plug-ins

Working with plug-ins 33Hitachi Automation Director Service Builder

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.

Types of plug-ins

The types of plug-in that accessible from the Component view are describedbelow:• 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-insand basic plug-ins can be found under the Released tab of the Componentview.

• Developing. Newly created plug-ins and plug-ins that have not completedtesting and the build process are plug-ins in the Developing state.Components in the Developing state can be copied and modified to use inother service templates. While in the creation or testing phase,components in the developing state can be found under the Developing tabof the Component view.

• Service. A service component is a released service template that has beenimported into HAD. When a service is used as a component and placedinto the flow of another service template, the new service template canincorporate the flow of the service component. HAD provides a set of built-in service components along with its built-in services. Service componentscan be found under the Service tab of the Component view.

The following screen shows how the various types of plug-ins (and services)are accessed from the Component view:

34 Working with plug-insHitachi Automation Director Service Builder

Related references

• Custom Plug-in List dialog box on page 35

Custom Plug-in List dialog boxThe Custom Plug-in List dialog box shows the plug-ins that can be accessedfrom the Service Builder Home view for a given menu option.


Table 4 Custom Plug-in List dialog box


Display Name - Name for the plug-in.

Description - Description of the plug-in.

Version - Version of the plug-in.

Tags - Tag category associated with the plug-in.

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


A selection of options are provided at the top of the list to find and arrangethe plug-ins based on the criteria you specify.

Managing plug-insYou can create and manage plug-ins by choosing the appropriate option fromthe Custom Plug-in Actions menu.

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

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

For details on creating and editing a plug-in, please see: Creating a newplug-in on page 67 and Editing a plug-in on page 69.

Copying a plug-inYou make a copy of a plug-in to create a duplicate version that can bemodified to suit your operating environment.

Any plug-in that is in the Developing or Released state can be copied. Thenew copy requires assigning a new vendor ID, plug-in key name, or versionnumber.

Procedure

1. From the Service Builder Home screen, under the Custom Plug-inActions menu, click Copy.The Custom Plug-in List dialog box appears.

2. In the Custom Plug-in List dialog box, select the plug-in that you wantto copy, then click Copy.The Copy Custom Plug-in dialog box appears.

3. In the Copy Custom Plug-in dialog box, enter the plug-in information,then click Save.

4. Click OK.The plug-in is created and the Edit Custom Plug-in dialog box opens.

Result

A new plug-in is created and is in the Developing state.

Next steps

• Continue to edit the plug-in.

Related references

• Copy Custom Plug-in dialog box on page 37


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.


Table 5 Copy Custom Plug-in dialog box


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.

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

Fields marked with an asterisk (*) are required.

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

Procedure

1. Delete a plug-in using one of the following methods:• From the Service Builder Home screen, under the Custom Plug-in

Actions menu, click Delete.• From the Actions drop-down list on the Service Builder screen,

choose Custom Plug-in, then Delete.2. From the Custom Plug-in List dialog box, choose the plug-in to be

deleted and click Delete.

Result

The plug-in is deleted.

Related tasks

• Copying a plug-in on page 36


4Creating and editing service templates

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, resource files, preset propertydefinition files, an icon file, custom files, a flow and service definitions.

This module covers:

□ Service template creation workflow

□ Creating a service template

□ Create Service Template dialog box

□ Editing a service template

□ Specifying the step flow

□ Specifying the GUI settings

□ Example of creating a new service template

Creating and editing service templates 39Hitachi Automation Director Service Builder

Service template creation workflowCreating a service template involves the following processes:

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

steps involved to automate the process and determine if the steps requirecreating 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.

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 illustration shows the typical steps you follow when creating orediting a service template:

40 Creating and editing service templatesHitachi Automation Director Service Builder

Note: This chapter covers the steps of creating a service template. Fordetails on testing and releasing a service template, please see Testing andReleasing on page 93.

Related references

• Custom Plug-in List dialog box on page 35


Creating a service templateYou 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. From the Service Template Actions menu, select the Create option.The Create Service Template dialog opens.

2. Enter the information for the new service template, and click Save.The Service Builder view is shown where you can begin creating the newservice template.

Result

A new service template is created with the specified name.

Next steps

• Continue to edit the service template by selecting the components fromthe list, providing the input and output step properties, and establishingthe flow.

Related references

• Create Service Template dialog box on page 42

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



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

Version ID * - An ID assigned to the template

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 a tag that specifies a category to which thetemplate is associated.

Fields with an asterisk (*) are required.

Editing a service templateYou can edit an existing service template to modify or add details.

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


template.

Procedure

1. From the Service Template Actions menu on the Service BuilderHome screen, select the Edit option.The Service Template List dialog opens.

2. Select the template to edit, and click Edit.The Service Builder view is shown where you can begin editing the newservice template.

Next steps

• Continue to edit the service template by selecting the components fromthe list, providing the input and output step properties, and establishingthe flow.

Related references

• Create Service Template dialog box on page 42


Specifying the step flowYou specify the component steps and flow for a service template from theCreate 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 Create Flow viewand then draw connectors to establish the order in which they are to beexecuted. You then need to specify the mapping for the input and outputproperties.

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

• Creating the steps in a data flow on page 44• Specifying the Step Properties on page 46• Setting the flow on page 50• Creating flow hierarchies on page 52

Creating the steps in a data flowYou create the steps in a service template from the Service Builder byspecifying the appropriate components for a given service.

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

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


template.


Procedure

1. From the Component view of Service Builder, click on a componentand drag it to the Flow view and release.The Create Step dialog box opens.

2. Enter the information of the step, and click OK.The component icon appears in the Flow view as a step.

3. Continue to add steps as needed.• To delete a step, click on the step icon and press the Delete key.• To select multiple steps, drag the mouse to create a rectangle

encompassing the targeted steps, or click each step icon whilepressing the Control key to add to the selection.

• To copy a step, right click on the step icon and select the copy menu,and right click in the same Flow view or in another service templateand select the paste menu.

• 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 window, click Close located in the upperright corner.

4. Click Save.

Result

Steps 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 dialog box on page 45

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

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



Table 7 Create/Edit Step dialog box


Step ID* The ID of the step.

Display Name* The name of the step.

Description A short description of the step.

Component Display Name Name assigned to the component

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

Vendor Name The vendor Name associated with the component.

Description The description of the component.

Key Name The key name associated with the component.

Vendor ID The vendor name of the plug-in.

Next StepConditions

Condition: Set instructions on when to execute next step. Thechoices are:• Determine by Threshold

Execute 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 RunAlways execute the next step.

• Always TerminateAlways 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.

Specifying step propertiesYou can specify the input and output properties for a given component stepfrom the Step Properties view.

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 a


service 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 in the StepProperties view of the Service Builder view. The input and output propertiesand variables for the service template are set in the Edit Service TemplateAttributes dialog box.

The following illustration shows a typical mapping between the servicetemplate properties 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 Service Builder view, select a step:• Click on a step in the Flow Step view.• Click on a step in the Flow view.

A table of the input and output properties appear in the Step Propertiesview.

2. Under the Input tab, enter the Input properties of the step:• Enter the details directly in the Value column of the table.• Click ... to enter the details using the Specify Component Input

Property Mapping Parameters dialog box.3. Under the Output tab, click ... to enter the details of the output

properties using the Specify Component Output Property MappingParameters dialog box.

4. Under the Attributes tab, review a summary of the input and outputproperties.

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

whether or not the selected input property is visible for config/submitusers. For output properties, this affects the View Details. You can alsoset the visibility that determines whether the property is visible for boththe Edit and Submit windows or just for the Edit Window Only whenadding or editing an input property from the GUI Settings view.

Next steps

• Set the service definitions of the service template.

Related references

• Specify Component Input/Output Property for Mapping Parameters dialogbox on page 49

Specify Component Input/Output Property for 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 8 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.

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 or you canchose the Show All Steps option to see all component steps associated withthe service template. When specifying component output properties, you canview a listing of current output properties defined for the service template.

From the Actions pull-down menu, you can chose Select Service ShareProperty (only available when specifying input properties) to add a serviceshare property, Add Input/Output Property to add and input or outputproperty (depending on whether you are viewing input or output properties),or Add Variable to add a variable to a specified property group.

Establishing the flow of executionMapping the process flow of a service template is performed in the ServiceBuilder view. Use the Flow view to connect the steps icons and establish aflow. The Flow Tree view displays the hierarchy of the 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 followingillustration:


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 Service Builder view, drag and add the necessary plug-ins (orservices) into the Flow view according to the relative order in which thesteps 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 key.

Next steps

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

Related tasks

• Specifying step properties on page 46


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 repeat a unitof processing that consists of several steps by deploying repeated-executionplug-ins as shown in the following illustration:

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.


Dragged & dropped plug-in Type of step Role

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 plugin. 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 Service Builder view, drag the appropriate plug-ins to beexecuted into the Flow

2. Select the Flow plug-in and drag it into position to establish the hierarchyof execution for the other plug-ins in the flow.

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

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

the Delete key.

Next steps

Specifying the GUI settingsYou specify the input and output properties, service share properties, andvariables for a service template from the GUI tab. These settings affect howthe various parameters associated with a given template are presented to theuser.

You can also add and edit the property groups which allows you to group theproperties from different components into a given category for presentationto the user. To add a property group, click on the plus sign (+) in theProperty Group List or click the wrench icon to edit an existing propertygroup. By clicking the radio button associated with a property group or anindividual property, you can specify Display or Hide to specify whether or notthese items are visible to the user.


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. To information onhow to customize the service template, please see the advanced topic: EditService Template Attributes dialog box on page 118.

For more information on the options available from the GUI Settings view,see the following topics:

• Selecting the service share properties on page 54• Adding input properties on page 55• Adding output properties on page 58• Adding variables on page 59

Selecting the service share propertiesYou can add service share properties to a service template by choosing SelectService Share Property from the GUI Settings view.

A list of share properties that can be assigned to a given property group areprovided for the current service template.


Procedure

1. From the GUI Settings tab, choose Select Service Share Property.2. Select the service share property to add to the service template. You can

add a service share property to a particular property group from theProperty Group pull down menu.• 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.

Related references

• Select Service Share Property dialog box on page 54

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 9 Select Service Share Property dialog box


Property - Service share property available for inclusion in a servicetemplate.

Description - Description of the service share property and its purpose.

Value - A value associated with the service share property.

Key - A key associated with the service share property.

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

The key associated with the service share property is shown along with a pulldown menu for selecting the Property Group. You can set the values forservice share properties from the Add Input Property dialog box.

Adding input propertiesYou can specify the input properties for a given property group associatedwith a service template from the Create Input Property for Service dialogbox.

A list of input properties is shown.


Procedure

1. From the Property List area of the screen, under the GUI Settings tab,choose Add Input Property. You can also add input properties from theSpecify Component Input Property Mapping Parameters dialog boxunder the Create Flow tab, by clicking ... in the Value field of the StepProperties area of the screen.

2. Enter the relevant details for the input properties in the Create InputProperty for Service dialog box.

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 56


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 10 Create/Edit Input Property for Service dialog box


Key: * - The input property key.

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, oruse reserved.defaultGroup.

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: - Enable if the property is required.

Data Type: - Select a data type of the property: string, boolean, integer,double date, password, list, composite. Various option arepresented depending on which of the options are chosen.For instance, if you chose the date option, a calenderinterface is provided.

Default Value: - Enter the default value of the property. If the data type iscomposite, then click the Select button to specify the filename and location.

Specify ListItems*

- If the data type is a list, specify the list items.

Minimum Value/Length:

- Specifies the minimum value for an integer. If the data typeis string or password, then enter the minimum length of theproperty.

Maximum Value/Length:

- Specifies the maximum value for an integer. If the data typeis string or password, then enter the maximum length ofthe property.

RestrictedCharacter:

- If the data type is string or password, then enter thecharacters that are not allowed.

Validation: - Enter the name of the file with the javascript code thatvalidates the properties.



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

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.


Adding output propertiesYou can specify output properties for a service template from the CreateOutput Property for Service dialog box.

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 List area of the screen, under the GUI Settings tab,click Add Output Property. You can also add input properties from theSpecify Component Output Property Mapping Parameters dialogbox under the Create Flow tab, by clicking ... in the Value field of theStep Properties area of the screen.

2. Enter the relevant details for the output properties in the Add OutputProperties dialog box.

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 58

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 11 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, andcomposite. Various option are presented depending onwhich of the options are chosen.

Default Value: - Enter the default value of the property. If the data type iscomposite, then click the Select button to specify the filename and location.

Restricted Character: - If the data type is string or password, then enter thecharacters that are not allowed.

Fields with an asterisk are required.

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

A list of current properties for a given Property Group is shown in theProperty List.

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

Procedure

1. From the Property List view, under the GUI Settings tab, choose AddVariable.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 60


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 Add/Edit Variable dialog box. A field group is a collection of fields thatare related to a specific action or configuration.


Table 12 Create/Edit Variable dialog box


Key:* - Specifies the variable key.

Display Name:* - The variable name.

Description: - The variable description.

Data Type: - Select a data type of the variable.

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


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 Service Builder Home screen under the Service Template

Actions menu, click Copy. The Service Template List dialog box appears.2. From the Service Template List dialog box, select the service template

that you want to copy, and click Copy. For the purpose of this example,please select the "Allocate Volumes and Add to Oracle Database" servicetemplate. The Copy Service Template dialog box appears for the selectedtemplate.

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

Table 13 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 Save and the new service template is created with the modifieddetails. The Service Edit screen appears with details for the copiedservice template.

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. Locate the Email Notification Plug-in in the Component area of the

screen and drag it into the Flow area of the screen. If necessary, youcan use the search button to locate the email notification plug-in. TheCreate Step dialog box appears.

2. In the Create Step dialog box, enter the appropriate details for theplug-in step, as shown in the following table:

Table 14 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-n 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.

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

2. At this point, you are going to want to make sure that the servicetemplate is functioning correctly. In order to accomplish this, you need to


return to the main Hitachi Automation Director GUI where you can createa request and submit the service request for the service template.

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. Click Submit.6. In the Submit Service confirmation dialog box, click OK.7. On the Tasks tab, in the Debug view, select the NewTemplate example

task and click Show Details to view the task summary, details, result,log, and notes.

8. 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 tabto make the template available for users to submit.

Related concepts

• Service template creation workflow on page 40

Related tasks

• Creating a service template on page 42• Creating the steps in a data flow on page 44• Adding input properties on page 55• Adding output properties on page 58


5Creating and editing plug-ins

Plug-ins are a fundamental part of a service template based on a commandor script that performs a given step during the execution of a servicetemplate.

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 new plug-in

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

□ Edit Remote Command dialog box

□ Setting environment variables

Creating and editing plug-ins 65Hitachi Automation Director Service Builder

□ Create/Edit Environment Variable dialog box

□ Adding output filters

□ Edit Output Filter dialog box

□ Creating a conditional branch

□ Generating an email

□ Example of creating a new plug-in

66 Creating and editing plug-insHitachi Automation Director Service Builder

Plug-in creation workflowCreating a plug-in involves the following processes:

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 view. 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 new plug-in on page 67

Creating a new plug-inYou can create a new plug-in that will execute the commands or scripts for agiven 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 125.


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. Open the Create Custom Plug-in dialog box using one of the followingmethods:• From the Service Builder Home screen, under the Custom Plug-in

Actions menu, click Create.• From the Actions >> Custom Plug-in pull down menu, available

from the GUI Settings tab, click Create.

The Create Custom Plug-in dialog box opens.2. In the Custom Plug-in section, enter the basic information of the plug-

in.3. In the Input Properties section, click Add and enter the details of the

input properties. Click OK to add the input property and return to thePlug-in dialog box. You can add multiple input properties and drag anddrop within the section to change the order of the input properties.

4. Expand the Output Properties section, and click Add to enter thedetails of the output properties. Click OK to add the output property andreturn to the Plug-in dialog box. You can add multiple output propertiesand drag and drop within the section to change the order of the outputproperties.

5. In the Remote Command section, click Edit to select an OperatingSystem.The Edit Remote Command dialog box appears. For more informationon setting remote commands, see Setting remote commands onpage 74.

6. If environment variables are required to execute the remote command orscript, click Details in the Edit Remote Command dialog box. ClickAdd to enter the name (required) and value of the environment variable.

7. Click OK to return to the Create Custom Plug-in dialog box.8. When you are finished, click Save.

Result

A new plug-in is created and is in the Developing state. The plug-in can belocated in the Developing tab of the Component view.

Related references

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


Editing a plug-inYou use the Edit Custom Plug-in dialog box to edit the input and outputproperties, variables, and remote commands associated with a plug-in.

Procedure

1. Access the Edit Custom Plug-in dialog box using one of the followingmethods:• From the Actions >> Custom Plug-in pull down menu in the

Service Builder view, click Edit.• From the Custom Plug-in Actions list in the Service Builder Home

View screen, click Edit.

2. From the Custom Plug-in List dialog box, select the custom plug-in toedit and click Edit.The Edit Custom Plug-in dialog box appears for the selected plug-in.

3. Edit the selected plug-in.

Related references

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

Create/Edit Custom Plug-in dialog boxWhen creating a new plug-in, you supply the relevant details from the CreateCustom Plug-in dialog box. After a plug-in exists, you can use the EditCustom Plug-in dialog box to make any modifications.

The following table describes the Create/Edit Custom Plug-in dialog boxfields, subfields, and field groups. A field group is a collection of fields thatare related to a specific action or configuration.


Table 15 Create/Edit Custom Plug-in dialog box


Custom Plug-in 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 125.



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

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

AdvancedOptions

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

A default image is provided.

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

Select Shared agentless setting, if you want to usethe credential information in the agentless remoteconnections view under the HAD Administration tabwhen the service is executed. Shared agentlesssetting is the default Credential Type.

The following reserved plug-in property isautomatically set for the shared agentless settingcredential type:

plugin.destinationHost Enter the target of anoperation by IPv4 address, IPv6 address, or hostname (up to 256 characters).

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

The following reserved plug-in properties areautomatically set for the Service input propertycredential type:

• plugin.destinationHost

Enter the target of an operation by IPv4address, IPv6 address, or host name (up to 256characters). If the destination host is HADServer (localhost), the user ID and thepassword are not necessary.

• plugin.account

Enter the user ID for logging in to the targethost (up to 256 characters).

• plugin.password

Enter the password for logging in to the targethost (up to 256 characters).

• plugin.suPassword

Enter the password of the root account used forlogging in to a target host in a Linux



environment (up to 245 characters). If thetarget is host is running the Windows, thisproperty is ignored.

Character Set AutoJudgement (SSH)

Character Set Auto Judgment (SSH) applies toUNIX operating systems. If enabled, executes thescript using the default locale ofthe user. Ifdisabled, scripts are executed with the LC_ALL=Clocale. Default is enabled. For more details onCharacter Set Auto Judgement, see:Locale settingsfor plug-ins on page 140.

Executive with rootprivileges (SSH)

Executes with root privileges.

Input Properties - Shows the input properties currently associatedwith the plug-in and provides the controls foradding, editing, or removing input properties.

OutputProperties

- Shows the output properties currently associatedwith the plug-in and provides the controls foradding, editing, or removing output properties.

RemoteCommand

- Specifies the remote command for a given OS thatis to be executed by the plug-in. By selecting theEdit button, you can specify the Execution Methodthat determines whether the plug-in treated as ascript, a command, or not to be submitted.

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 in the StepProperties view of the Service Builder view. The input and output properties


and variables for the service template are set in the Property List from theGUI Settings.

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 46 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 in the InputProperties section of the Create Custom Plug-in or Edit Custom Plug-in dialogboxes.

Click Add in the Input Properties section to access the Specify Input Propertyfor Custom Plug-in dialog box.

Click OK to enter the input properties. You can add multiple input propertiesand drag and drop from within the section to change the order of the inputproperties.

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

Related references

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

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 16 Specify/Edit Input Property for Custom Plug-in dialog box


Key: * - The input property key (up to 128 characters).

Display Name: * - The name of the input property (up to 128 characters).

Description: - The description of the input property (up to 256characters).

Required: - Enable the check box if a value is required for the plug-in.

Default Value: - Enter the default value of the input property (up to 1,024characters).


Adding plug-in output propertiesThe output properties store standard output and standard error outputpassed to the output filter. The output properties are created and defined inthe Output Properties section of the Create Custom Plug-in or Edit CustomPlug-in dialog boxes.

Click Add in the Output Properties section to access the Specify OutputProperty for Custom Plug-in dialog box.

Click OK to enter the output properties. You can add multiple outputproperties and drag and drop from within the section to change the order ofthe output properties.

Continue to enter the remote commands for the plug-in.

Related references

• Specify/Edit Output Property for Custom Plug-in dialog box on page 73

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 17 Specify/Edit Output Property for Custom Plug-in dialog box


Key:* - The output property key (up to 128 characters).

Display Name:* - The name of the output property (up to 128 characters).

Description: - The description of the output property (up to 256characters).


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.

The remote commands are created and defined in the Remote Commandsection of the Create Custom Plug-in or Edit Custom Plug-in dialog boxes.

To set a remote command:

Click Edit for the Operating System you want. Enter the following informationin the Edit Remote Command dialog box.

Continue to add output filters or environment variables to the outputproperties.

Related references

• Edit Remote Command dialog box on page 74

Edit Remote Command dialog boxYou can control the output for tasks generated by a service template throughthe use of remote commands that you specify by clicking Edit from theRemote Command area of the Create Custom Plug-in dialog box. Standardoutput and error output are stored in the output property and you use anoutput filter to only store specific data.

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



Table 18 Edit Remote Command dialog box


Operating System:* - Displays the operating system for the system where theplug-in is being executed. By choosing the Import Settingsof Other Operating Systems button, you can specify that thesettings should be derived from another operating 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 By 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 Name* - 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.

EvironmentVariables

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


Setting environment variablesEnvironment variables can be set when a remote command of a plug-in isexecuted.

To set an environment variable:

In the Environment Variable section of the Edit Remote Command dialogbox , click Add. Enter the following information in the Create EnvironmentVariable dialog box.

Related references

• Create/Edit Environment Variable dialog box on page 76

Create/Edit Environment Variable dialog boxWhen entering information for a remote command from the Edit RemoteCommand dialog box, you can click the Add or Edit button to access theCreate/Edit Environment Variable dialog box where you can enter or modifyenvironment variables for the remote command.

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 19 Create/Edit Environment Variable dialog box


Name: * - Name of the environment variable.

Value: - Value of the variable.

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


The Mapping Definition of Output Properties section of the Edit RemoteCommand dialog box displays the output properties entered for the plug-in.

To set an output filter:

Highlight the line of the output property and click Edit. Enter the followinginformation 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.

Related references

• Edit Output Filter dialog box on page 77

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 20 Edit Output Filter dialog box


Key: - Shows the key associated with output property.

Display Name: - Shows the name for the output property for which the filteris being applied.

Description: - Shows a description for the output property.

Output Filter: - Enter a regular expression to filter the data stored by theoutput property.

Verification of theOutput Filter

- Click on Verification of the Output Filter to verify that thefilter is processing the data in the manner you intended.

Creating a conditional branchYou 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:• Judge Value Plug-in -- compares a particular service property with a

specified value (or if necessary, can also be compared with a variable orstep property) and then acts accordingly.

• Judge Return Code Plug-in -- compares the Return Code generated by aprevious 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 Judge Value Plug-in to setup a conditional branch when a step property generated by a previous stepequals 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 Judge Return Code Plug-in to set up a conditional branch when a return code generated by a previousstep 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 JudgeRetrun Code plug-ins so that one step is executed when a particular conditionis 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 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 tospecify 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 82.

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 Homescreen by choosing Service Builder from the Tools pull-down menu. TheService Builder Home screen provides all of the options for creating andmanaging service 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 Service Builder Home screen under the Service Template

Actions menu, click Copy. The Service Template List dialog boxappears.

2. From the Service Template List dialog box, select the service templatethat you want to copy ("Allocate Volumes for Oracle Database" for thisexample), and click Copy. The Copy Service Template dialog boxappears for the selected template.

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

Table 21 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 Save and the new service template is created with the modifieddetails. The Service Builder view appears with details for the copiedservice template.

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 view to create yournew 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`echo "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 Create from the Actions >> Custom Plug-in pull down menu.

The Create Custom Plug-in dialog box appears.2. In the Create Custom Plug-in dialog box, enter the appropriate details

for the plug-in, as shown in the following table:

Table 22 Create/Edit Custom Plug-in Parameters


Custom Plug-in 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 125.

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

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.

AdvancedOptions

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.

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

Select Shared agentless setting, if you wantto use the credential information in theagentless remote connections view under theHAD Administration tab when the service isexecuted. Shared agentless setting is thedefault Credential Type.

The following reserved plug-in property isautomatically set for the Shared agentlesssetting credential type:

plugin.destinationHost Enter the target of anoperation by IPv4 address, IPv6 address, or hostname (up to 256 characters).

Select Service input property to use thecredential information as an input property.



The following reserved plug-in properties areautomatically set for the Service inputproperty credential type:

• plugin.destinationHost

Enter the target of an operation by IPv4address, IPv6 address, or host name (up to256 characters).

• plugin.account

Enter the user ID for logging in to the targethost (up to 256 characters).

• plugin.password

Enter the password for logging in to thetarget host (up to 256 characters).

• plugin.suPassword

Enter the password of the root account usedfor logging in to a target host in a Linuxenvironment (up to 245 characters). If thetarget is host is running the Windows, thisproperty is ignored.

Character Set AutoJudgement (SSH)

Character Set Auto Judgment (SSH) applies toUNIX operating systems. If enabled, executesthe script using the default locale ofthe user. Ifdisabled, scripts are executed with theLC_ALL=C locale. Default is enabled. Make surethis option is enabled for this example.

For more details on Character Set AutoJudgement, see:Locale settings for plug-ins onpage 140.

Execute with rootprivileges (SSH)

Executes with root privileges.

For this example, do not select this option.

Input Properties - Shows the input properties currently associatedwith the plug-in and provides the controls foradding, editing, or removing input properties.

OutputProperties

- Shows the output properties currently associatedwith the plug-in and provides the controls foradding, editing, or removing output properties.

RemoteCommand

- Specifies the remote command for a given OSthat is to be executed by the plug-in. Byselecting the Edit button, you can specify theExecution Method that determines whether theplug-in treated as a script, a command, or not tobe submitted .

Don't bother with this now as you will supply thisinformation in a following step.

3. Click on Input Properties to access the listing of input properties forthe plug-in. The Create Input Property for Plug-in dialog boxappears. To extract the serial number and volume ID information fromthe adapter, you need to specify two input properties for the plug-in asshown in the following table:


Table 23 Specify Input Property for Custom Plug-in Parameters


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.

4. Click Add to provide the relevant details for each of the required inputproperties shown in the table and then click OK. When done, you arereturned to the Create Custom Plug-in dialog box where you can seethat the input properties you created are now included in the InputProperties list.

5. From the Remote Command area of the Create Custom Plug-indialog box, specify the remote commands that are executed for the plug-in by clicking Edit for your particular OS environment (AIX for thisexample). The Edit Remote Command dialog box appears where youcan enter the relevant details as instructed in the following table:

Table 24 Edit Remote Command Parameters


Operating System: 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 areto be 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 ofthe input properties that have been created for the plug-in into theCLI Command 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.

Script specificationmethod

Choose the Attachment button.



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

6. After entering the relevant details, click OK to exit the Edit RemoteCommand dialog box and return to the Create Custom Plug-in dialogbox

7. To specify the proper credentials required to execute the remotecommand script for the new plug-in, click Advanced Options. You candetermine the credentials that are needed by consulting AgentlessRemote Connections option from the Administration tab in the mainHitachi Automation Director user interface. If the credentials are alreadydefined, you can choose the Shared agentless setting option for theCredential Type. If the credentials are not defined, you can choose theService Input property option and the specified credential inputproperties are used to query the user at the time the service is run forthe 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 theFlow area of the screen. The Create Step dialog box appears where youcan enter some relevant step details. Click OK to accept the defaultvalues.

2. Click on the Developing tab, locate the newly created plug-in(PluginExample), and drag it after the other two plug-ins in the Flowarea of the screen. Once again, the Create Step dialog appears whereyou can enter some details for the plug-in step. Click OK to accept thedefault 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 25 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 ... in thevalue field and accessing the Specify Component Input PropertyMapping Parameters dialog box that lists properties for all steps in theflow. 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 26 Step Input properties for PluginExample


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 tab in the Step Properties view, choose the TaskResults Raw Data LDEVs output property, then click the ... in theValue field to access the associated Specify Component OutputProperty Mapping Parameters dialog box.

Note: For this example to work, you must change the Setting Method tothe None option in order to build the service template with your new plug-in.In addition, 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 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.

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

3. On the Services tab, select the PluginExample service in Developingstatus and click 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 PluginExample

Description A brief description of the task A task to perform LDEV

mapping.

Schedule Type The time when the task executes Immediate

5. Click Submit.6. In the Submit Service confirmation dialog box, click OK.7. On the Tasks tab, in the Debug view, select the "PluginExample" task

and click Show Details to view the task summary, details, result, log,and notes.

8. 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 tabto make the template and plug-in available for users to submit.

Related concepts

• Adding plug-in input properties on page 72• Adding plug-in output properties on page 73

Related tasks

• Creating a new plug-in on page 67• Setting remote commands in plug-ins on page 74• Setting environment variables on page 75• Adding output filters on page 76


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.

This module covers the steps to debug and release service templates andplug-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 93Hitachi Automation Director Service Builder

□ Exporting property values

□ Releasing a service template

94 Building, debugging and releasingHitachi Automation Director Service Builder

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 by clicking on the Run Debugger button at thebottom of the Build/Release dialog.

• Correct any errors and continue re-building the service template until allerrors are resolved.

• After all issues have been resolved, conduct an operation test by addingand 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 illustration 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 screen, click the Debug tab.The service template undergoes the build process and its configurationtype changes to Debug. If any errors are generated, error icons anderror link buttons are displayed in the upper part of Service Builderscreen. Warning icons appear when you have failed to enter a requiredproperty.

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, you can access thedebugger by clicking Run Debugger to check the flow of execution and makeany adjustments 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 115.

Related references

• Build/Release Result dialog box on page 97

Build/Release Result dialog boxYou check the results when building and releasing a service template fromthe Build/Release Result dialog box. You can also start the debugger byclicking Run Debugger to check the execution flow of the service templateand identify and fix any problems with the property mapping.


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

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

Message Provides the content of the status message.

After the service template builds successfully, you can click Run Debugger toaccess the debugging interface.

Running the debuggerOnce you have successfully built a service template, you can run the built-indebugger by clicking Run Debugger from the Build/Release 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 for

user 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, HAD creates a debug service and debugtask.

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, HAD deletes the existing debug service and creates a new one. Notethat debug services appear in the Service Name column in the Debug-Tasksview, 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, HAD deletes the existing debug task and creates anew one. Debug tasks appear in the service template Debugging view andDebug-Tasks view. Only users assigned the Admin or Develop role can viewand work with debug tasks. Note that debug tasks do not appear in the tasksummary.

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 lastoperation 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. Click Run Debugger from the Build/Release dialog box. You can alsorestart the debugger from within the debugger user interface by clickingRun Debugger.The Perform Debugging dialog box opens.

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 otherservice and task related fields

4. For the Task Log Level, specify the level of details that are to be storedin the task log file.

5. If necessary, you can supply the values that would normally be specifiedby 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.

Result

The debug interface is accessed where you can begin the debugging process.

Related references

• Perform Debugging dialog box on page 100

Perform Debugging dialog boxAfter successfully building a service template, you can run the debugger andspecify the relevant details for the debugging session through the PerformDebugging 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 28 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 config andsubmit user's perspective.• From Create Service Window• From Create Request Window

See: Editing service and request entries whiledebugging on page 102for 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.


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 config 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 Debugger window 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.

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 theconfig 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 105 for complete details.

Related references

• Examining debug details on page 105

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 Log File and then specify the location for the log file. Youspecify the level 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:

• Establishing the flow of debug tasks on page 106• Handling interruptions of debug tasks on page 107• Archiving debug tasks on page 108

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 thenetwork 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 HAD server stops

If the HAD server stops during debugging, the debug task that is running isforcibly stopped. Therefore, before stopping the HAD server, wait for alldebug tasks that are still running (not yet completed) to finish or stop thedebug tasks. This is the same as the handling of tasks generated whennormal 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 (input/output parameters and status of AJS in the units of jobs) is deleted, andtherefore 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 archiving

1 90 7



Default

of tasks takes place oncea day according to thetime specified throughthetasklist.autoarchive.executeTime property.

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

100 5000 5000



Default

specify 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 Propertydialog 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 111


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

Importing property valuesWhile debugging a service template, you can import property values to aspecified property file.

While debugging, you can import multiple property values from a propertyfile.

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

Property

Group

Attribute

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 112

Exporting property valuesWhile debugging a service template, you can import and export property files

While debugging, you can export property values to a property file. Thisallows you 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 p roperty-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 111

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 HAD as an availableservice 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

1. From the Service Builder screen, click Release.The service template undergoes the release process and its configurationtype changes to Released status.

Result

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

deleted.• Any tasks executed from the template while in Developing status are

archived.• The service template appears in the Service Template list when creating a

new service.• The related plug-ins appear under the Released tab of the Component

view.• If specified in the service definitions, a service component is created and

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


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

□ Specifying property groups

□ Using preset property definition files

□ Managing versions

Advanced options 117Hitachi Automation Director Service Builder

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 Actions pull down menu, select the Edit Service TemplateAttributes option.The Edit Service Template Attributes dialog opens.

2. Enter the information for the new service template, and click OK.The Edit Service Template attribute dialog is closed.

Result

Any changes you specify are reflected in the edited service template.

Next steps

• Continue to edit the service template by selecting the plug-ins from thelist, providing the input and output step properties, and establishing theflow.

Related references

• Edit Service Template Attributes dialog box on page 118

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 30 Edit Service Template Attributes dialog box


Key Name - The key name for the service template.

118 Advanced optionsHitachi Automation Director Service Builder


Version - The version of the service template.

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.

Fields with a asterisk (*) are required.

Specifying property groupsYou use property groups to categorize the properties that are shown onsubmit dialog.

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 Properties Group List view, click + to create and enter thedetails of a property group. Continue to add property groups as needed.


2. Click on and highlight the property group in the Properties Group Listfor which you want to add input and output properties or variables.

3. From the Property List view, click Add Input Property to add an inputproperty. Continue to add input properties as needed.

4. From the Property List view, click Add Output Property to create anoutput property. Continue to add output properties as needed.

5. From the Property List view, click Add Variable to create a variable.Continue to create variables as needed.

Next steps

• Address any warning icons that may appear in the step, flow or servicedefinitions.

• Provided the steps, flow and service definitions contain no warning icons,continue to build the service template. For more information on the buildprocess, see Testing a service template on page 96.

Related references

• Create Property Group dialog box on page 120• Edit Property Group dialog box on page 122

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 31 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 the property group is displayed or hidden.

Validation: - Specifies a validation file for the property group.

Custom File package: - Specifies a custom 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

}

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.

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

Validation: - Specifies a validation file for the property group.

Custom Filespackage:

- Specifies a custom files for the property group.

Custom File Namefor Edit Service(Navigation):

- Specifies a custom file for the edit service from theNavigation menu.

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.


Using preset property definition filesThe property values of a service template can be set up using preset propertydefinition files. A preset property definition file can set the values of theproperties that appear in the Edit Service Template Attributes dialog boxwithout manual entry through the GUI.

You can set multiple preset properties to a preset property definition file upto 1MB. If multiple preset property definition files are required, assign uniquefile names using the following format:

preset_preset-name.propertiesUse preset property values based on the user environment and mode ofoperation for multiple properties to define property values of a servicetemplate. For example, to set different values for the same property fordifferent hosts (e.g., hostA, hostB, hostC), create the filespreset_hostA.properties, preset_hostB.properties, andpreset_hostC.properties. These values contained in these files would appearin the Edit Service Template Attributes dialog box.

Related concepts

• Formatting preset property definition files on page 124

Related tasks

• Implementing preset property definition files on page 124


Formatting preset property definition filesUse the following formats and guidelines to create the preset propertydefinition files:

For property values:

property-key = property-value

Where:• property-key is the property key that is defined in the Edit Service

Template Attributes dialog box.• property-value is the value that meets the criteria for the Data Type,

Minimum Length, Maximum Length, and Restricted Character of thatproperty.

• If you do not want to specify a property value, use the format property-key=linefeed.

• Specify only one property key and value on each line.• Use UTF-8 character coding.• A line starting with a hash mark (#) is a comment line.• Characters are case sensitive.• Blank lines are ignored.

For file names:

preset_preset-name.properties

Where:• preset-name is 1 to 30 characters using half-width alphanumeric

characters, hyphens, underscores, and periods.

Implementing preset property definition filesUsing preset property definition files in a service template requires placingthe preset property definition files in the proper folder.

Note: To implement a preset property definition file, administrative access tothe operating system is required.

Procedure

1. Identify the Vendor ID, Service Template ID and Service TemplateVersion for the preset property definition files.

2. Save the preset property definition files in the following folder:shared-folder-name\Automation\extra_presets\vendor-ID-of-service-template\service-template-ID\service-template-version


3. Open the Edit Service Template Attributes dialog box of the servicetemplate and the values from the preset property definition files aredisplayed in the Properties section.

4. Select a preset name and click Apply.

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. To display a listof all versions, remove the check mark from the Display Latest Version optionat the top of the dialog box.

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 Actions pull-down menu, choose the Component Version

Management option. The Component Version Management dialog boxappears.

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 126

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


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 127Hitachi Automation Director Service Builder

List of built-in service templatesA collection of pre-configured service templates are provided with HAD.

The following service templates are provided by default and are availableimmediately to begin creating 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 Like Volumes and Create Datastore on

VMware vSphere service allocates and create an

identical datastore for the selected ESX server and

datastore within the associated infrastructure group.

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.


Database for Windows

Creates a volume on a storage system, and adds the

volume to the disk group for Oracle ASM for

Windows.

128 Reference informationHitachi Automation Director Service Builder

Name Description

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




consumed by server(s) running XenDesktop on

VMware vSphere.


Name Description

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.

Allocate Volumes with Snapshot for Microsoft

SQL Server





Name Description


Microsoft SQL.

Allocate Volumes with Snapshot for Oracle

Database




group to be consumed by server(s) running Oracle

ASM.

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 Datastore on VMware vSphere Creates an LU and a data store in an environment

consisting of VMware vSphere and HDvM.

Execute Remote Command Executes a command on the remote execution

target server.

Pre-check for Datastore Creation on VMware

vSphere

Checks the environment prerequisites for adding a

virtual server (creation of LU and data store).

In addition to the service templates that are provided by default with HitachiAutomation Director, there is a collection of other service templates that areavailable for import. These templates are in the released state and can beused immediately without having to go through the build process.

The following table lists the reserved service templates that can be imported:

Template file name (*.st) Template name Description

changeVMSpec_vSphere Modify Virtual Machine

Configuration

Modifies the virtual server

configuration in the VMware

vSphere environment.

createCloneVMvSphere Clone Virtual Machine Creates a clone of a virtual

server in the VMware vSphere

environment.

deleteCloneVMvSphere Delete Cloned Virtual Machine Deletes a clone of a virtual

server in the VMware vSphere

environment.

deleteDatastoreAndLU Delete Datastore on VMware

vSphere

Deletes a data store and a

logical unit in an environment

that includes VMware vSphere

and Device Manager.


migrateVM_vSphere Migrate Virtual Machine Migrates multiple virtual servers

in a VMware vSphere

environment.

osShowUsers Get List of Users from Server Obtains a list of Windows or

Linux OS users from a specific

host.

osShowUsersAll Get Lists of Users from Multiple

Servers

Obtains a list of Windows or

Linux OS users from multiple

hosts.

powerOffVM_vSphere Stop Virtual Machine Stops multiple virtual servers in

a VMware vSphere

environment.

powerOnVM_vSphere Start Virtual Machine Starts multiple virtual servers

in a VMware vSphere

environment.

rebootVM_vSphere Restart Virtual Machine Restarts multiple virtual servers

in a VMware vSphere

environment.

snapshotVMvSphere Create Snapshot of Virtual

Machine

Creates a snapshot of the

virtual machine for updating

the status of a virtual server.

storageGetInfo Get List of Storage Systems

from Device Manager

Acquires a list of storage

devices registered in Device

Manager.

vsphereAddDisk Add Virtual Disk to Virtual

Machine

Adds a disk to a virtual server

in a VMware vSphere

environment.

vsphereDeleteVDisk Remove Virtual Disk from

Virtual Machine

Deletes a virtual server in a

VMware vSphere environment.

vsphereDeleteVM Delete Virtual Machine Deletes a virtual server in a


vsphereDeployVM Deploy and Setup OS on Virtual

Machine

Creates a virtual server in a


vsphereDeployVMCheck Pre-check for OS Deployment

on Virtual Machine

Checks the environment

prerequisites for adding a

virtual server (deployment and

OS initialization)

vsphereGetInfo Get List of Virtual Machines

from VMware vSphere

Acquires a list of VMware

vSphere virtual servers.


Imported by default, and

available in the Service

Templates tab and Service

Builder.

Pre-check for Datastore

Creation on VMware vSphere

Checks the environment

prerequisites for adding a

virtual server (creation of LU

and data store)




Builder.

Execute Remote Command Executes a command on the

remote execution target server.




Builder.

Create Datastore on VMware

vSphere

Creates a logical unit and a

data store in an environment

that includes VMware vSphere

and Device Manager.

The reserved service templates have an extension of (.st) and are stored inthe following location:

HAD installation folder>/public/contents

For instructions on how to import a service template, please see: Importing aservice template on page 30

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 HAD that you can use to createcustomized service templates.

The following plug-ins are included by default:

Plug-in Name Description

Abnormal-End Plug-in Handles the abnormal termination of an executing flow, task,

hierarchical flow, or repeatedly executed flow.

Allocate Like Volumes Plug-in Allocates identical newly added volumes and existing volumes

for the selected server and volume.

Allocate Volumes Plug-in Executes the intelligent allocation of newly added volumes and

existing volumes.



Check HDvM connectivity Determines whether or not a connection to the HDvM server

can be established.

Check LU creation Determines whether or not the DP volume (LU) can be created.

Check VMware vCenter Server

connectivity

Determines whether or not a connection to the vCenter server

can be established.

Check data store creation Determines whether or not a data store can be added.

Create DP volume Creates the specified DP volume in the storage system

managed by the Device Manager.

Create Datastore Plug-in Creates a datastore instance on VMware vSphere server.

Create data store Adds a data store in VMware vSphere ESXi (or VMware ESX

Server).

Email Notification Plug-in Sends emails to the specified destination.

File Export Plug-in Exports the input content to the specified file.

File-Forwarding Plug-in Transfers a file or folder to or from a remote host.

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.

Flow Plug-in Hierarchize the flow.

General Command Plug-in Executes a command line on the destination host.

Get canonical name of SCSI LUN Acquires the canonical name of the SCSI LUN recognized by

VMware vSphere ESXi (or VMware ESX Server)

Interval Plug-in Controls the interval between steps.

JavaScript Plug-in Executes an appointed JavaScript code.

Judge ReturnCode Plug-in Judges the return value of the previous step to divide the flow

of processing.

Judge Value Plug-in Judges service property values to divide the flow of processing.

Recognize LUN Recognizes an added or deleted LUN in VMware vSphere ESXi

(or VMware ESX Server).

LDEV ID Search Plug-in Searches for and outputs a listing of LDEV ID's.

Path Search Plug-in Searches for path details based on a given search criteria.

Register LU in host group Registers the specified LU in the host group in the storage

system managed by the Device Manager.

Repeated Execution Plug-in Executes a specific flow repeatedly.



Replication Plug-in Executes allocation of newly added secondary volumes with in-

system replication.

Set FC path priority Sets the FC path to "preferred" for the specified data store in

VMware vSphere ESXi (or VMware ESX Server)

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.

Task Submit Time Plug-in Acquires the submit time of the task.

Terminal Command Plug-in Executes commands on the destination host connected to by

the Terminal Connect Plug-in.

Terminal Connect Plug-in Allows terminals to establish connections.

Terminal Disconnect Plug-in Disconnects the terminal from the destination host connected

to by the Terminal Connect Plug-in.

Test Value Plug-in Compares service property values and returns 0 if the values

match the judgment conditions.

Thin Image Pool Selection Plug-in Selects a Thin Image pool.

User-Response Wait Plug-in Waits for user responses.

V-Vol Provisioning Plug-in Performs the allocation of newly added secondary virtual

volumes.

VolumeReport Plug-in Reports volume information to Replication Manager.

Web Client Plug-in Sends and receives HTTP request and response messages.

When requested, it accesses the server via a proxy and

performs server and proxy authentication.

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.

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

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



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.

VolumeReport Plug-in Reports volume information to Replication Manager.

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.

List of reserved propertiesA reserved property is a special service property whose property key has aspecific definition or purpose in HAD.


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.loop.index References a numerical value from 1 to 99 that indicates how

many times a repeated execution plugin has repeated.

reserved.loop.input References the value of the inputProperties input property of a

repeated execution plug-in. 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.category References the category assigned to the service from which a

task was generated. To reference this reserved property,

specify the property key in the format ?



dna_reserved.service.category?. You can use this property in

any plug-in to which service properties can be mapped.

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

me

References the resource 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.resourceGroupName?. You can use this

property in any plug-into 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 HAD 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 HAD, 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 HAD. The locale andcharacter set are determined by the settings in the Region and Languagearea of the Windows Control Panel that govern date and time formats, user-level display languages, system-level display languages, and system localesettings.

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

□ Judge ReturnCode Plug-in

□ Test Value Plug-in

□ Abnormal End Plug-in

□ Judge Value Plug-in

□ File Export Plug-in

Description of built-in plug-ins 143Hitachi Automation Director Service Builder

□ JavaScript Plug-in

□ LDEV ID Search Plug-in

□ Path Search Plug-in

□ Web Client Plug-in

144 Description of built-in plug-insHitachi Automation Director Service Builder

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 HAD Server (localhost), the user ID and the passwordare unnecessary.

For the command to be executed on the operation target device, specifycharacters that can be used in commands in the operating systems of theHAD server and the operation target device. For example, if the HAD serverand the operation target device both run the Japanese version of Windows,characters in the MS932 character set can be specified.• 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 HAD 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, the

status 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 WMI in Windows, and SSH in UNIX.Therefore, the SSH server must be set up on UNIX-based operation targetdevices.

• The port number used by SSH can be set in connection-destinationproperty file (connection-destinationname. properties) or the property 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-forwarding 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-forwarding plug-in when a non-ASCII characteris included 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 HAD server failed. For example, the

HAD server might have stopped while the plugin was being

executed.

66 The following user is mapped to the HAD 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 HAD 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 DescriptionDefault value

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 HAD server andthe operation target device mustbe connected by a network. Notethat multiple IP addresses or hostnames cannot be specified.

-- 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 destinationapplies the authenticationinformation set for WMI or SSH inthe connection destinationdefinition according to the IPaddress of the HAD 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:• account• password• suPassword

-- Input R



I/Otype

Required

• publicKeyAuthentication• keyboardInteractiveAuthentica

tion

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 to login to the operation target device,using a maximum of 256characters. You can omit thisproperty when the operationtarget device is running UNIX andtrue is specified for thepublicKeyAuthentication property.

-- Input O

suPassword Root Password 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 can alsoomit this property when theoperation target device is runningWindows, or when false isspecified for the elevatePrivilegesproperty.

-- Input O

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

false Input O



I/Otype

Required

Specify this option to usepassword or keyboard interactiveauthentication.

keyboardInteractiveAuthentication

SSH KeyboardInteractiveAuthentication

Controls whether or not to useSSH keyboard interactiveauthentication for the Linux/UNIXenvironment. If the operatingsystem of the destination is Linux/UNIX, the system toggles betweenusing and not using keyboardinteractive authentication. If theproperty is set to true, keyboardinteractive authentication is used.If the property is set to false,keyboard interactiveauthentication is not used. Thisproperty is not case-sensitive.This property is valid only 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 for theproperty.

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 isassumed. You can omit thisproperty when the operationtarget device 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.

false Input O

commandLine Command Line Specify the absolute path of thecommand or script to be executedon the operation target device,

-- Input R



I/Otype

Required

using a maximum of 256characters. In the command line,specify characters that can beentered in command lines in theoperating systems of the HADserver and the operation targetdevice. Special characters thatrepresent environment variablesin the command line are notescaped. 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,the command is executed withthe privileges of the user set inthe Agentless RemoteConnections view.

• 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• If destination is specified for

the credentialType property,the command is executed withthe privileges of the root useror the user set in theAgentless Remote Connectionsview, depending on the valueof the elevatePrivilegesproperty.

• If property is specified for thecredentialType property, thecommand is executed with theprivileges of the root user orthe user specified in theaccount property, dependingon the value of theelevatePrivileges property.

commandLineParameter

Command LineParameter

Specify the arguments of thecommand or script using amaximum of 1,024 characters.

-- Input O



I/Otype

Required

As the command line parameters,specify characters that can beentered in command lines in theOSs of the HAD server and theoperation target device. Specialcharacters that representenvironment variables in thecommand line are not scaped. Tohandle 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

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 standarderror output of the command orscript specified in thecommandLine property is assignedto the service property.

Input



-- Output O


Specify the regular expressionpattern of the standard output to

Input O



I/Otype

Required

output to the stdoutProperty2property, using a maximum of1,024 characters. Specify theregular expression pattern in aPCRE-compliant format. If youspecify the key of a serviceproperty in the stdoutProperty2property but do not specify thestdoutPattern2 property, the entirestandard output and standarderror output of the command orscript specified in thecommandLine property is assignedto the service property.



-- Output O


Specify the regular expressionpattern of the standard output tooutput to the stdoutProperty3property, using a maximum of1,024 characters. Specify theregular expression pattern in aPCRE-compliant format. If youspecify the key of a serviceproperty in the stdoutProperty3property but do not specify thestdoutPattern3 property, the entirestandard output and standarderror output of the command orscript specified in thecommandLine property is assignedto the service property.

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 inHAD. However, processing for which the total standard output and standarderror output of the command or script exceeds 100 KB is outside the scope ofproduct support. Execute the command or script in advance to make surethat the total standard output and standard error output does not exceed 100KB.

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-Forwarding Plug-inThe File-Forwarding 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-forwarding plug-in by specifyingthe following information:• Operation target device (remoteHost property)• Transfer mode (transferMode property)• Path of a file or folder on the HAD 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 theHAD server and the operation target device. For example, if the HAD serverand the operation target device are both running the Japanese version ofWindows, characters in the MS932 character set can be specified.

If destination host is a HAD Server (localhost), the user ID and the passwordare 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.


Depending on the OS of the operation target device, configure theenvironment as follows:

For Windows• Make sure that the HAD 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 the propertiesfile (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-forwarding plug-in.

Cautionary notes• IPv6 is not supported when HAD is running on Linux and the destination

host is Windows.


• The execution method differs depending on the OS of the operation targetdevice. File transfer is implemented by WMI and CIFS (SMB) in Windows,and SSH and SCP in UNIX. When selecting a protocol in the definition of anagentless connection destination, select WMI in Windows and SSH in UNIX.

• 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 HAD is installed and the connection-destinationhost, in addition to the free space needed for the files and foldersthemselves, an amount of free space equivalent to twice the size of thetransferred files is required as a temporary work area. The temporary workarea is as follows:○ For the machine where HAD is installed (non-cluster environment): The

drive where HAD is installed.○ For the machine where HAD 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 the HADsystem. Examples of these limitations include the maximum size of a file,the number of files per folder, the length of file and folder names, and theresources available to the user. File forwarding that exceeds the limitationsof the operating system is outside the scope of product support. Theoperating systems whose limitations affect HAD operation are those on theHAD server and on operation target devices. The OS limitations thatgovern which resources are available to users are those set for theconnection user and for users with root privileges. Limitations for userswith root privileges only apply in UNIX.

• When you specify a folder on a host running UNIX as the file-forwardingdestination, 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. HAD archives files beforesending them, which means that the limits of the destination host mightbe exceeded despite the individual files in the archive being smaller thanthe maximum size. In this scenario, either reduce the total size of the filesin the folder you are sending, or increase the limits at the destination.


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

Return codes

The following return codes are generated by the File-Forwarding Plug-in:


0 Ended normally.


HAD server might have stopped 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.











Property list

The following properties are available for the File-Forwarding 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 HAD server andthe operation target device mustbe connected by a network. Notethat multiple IP addresses orhost names cannot 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 forWMI or SSH in the connectiondestination definition accordingto the IP address of the HADlogin user. You can omit thespecification of propertiesrelating to authenticationinformation (account, password,suPassword,publicKeyAuthentication), and

destination Input R




I/Otype

Required

keyboardInteractiveAuthentication.

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 publickey authentication. The valuesare not case sensitive. If you donot specify a value, false is

false Input O




I/Otype

Required

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

false Input O




I/Otype

Required

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 HAD server to the operationtarget device. When you specifya file path in the localFilePathproperty, the same path must bespecified in the remoteFilePathproperty. When transferring asingle file, if you specify differentfile names in the localFilePathand remoteFilePath properties,the file name specified in theremoteFilePath property applies.

receive

Specify this option whentransferring a file or folder fromthe operation target device to theHAD server. When you specify afile path in the remoteFilePathproperty, the same path must bespecified in the localFilePathproperty. When transferring asingle file, if you specify differentfile names in the remoteFilePathand localFilePath properties, thefile name specified in thelocalFilePath property applies.

send Input R

localFilePath Local FilePath

Specify the absolute path of thefile or folder on the HAD serverusing no more than 256characters. In the localFilePathproperty, specify characters thatcan be used in commands in theoperating systems of the HADserver and the operation targetdevice. If there is a file or folderwith the same name in thedestination folder, the file orfolder is overwritten. For thisreason, we recommend that you

-- Input R




I/Otype

Required

specify 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 the HADserver and the operation targetdevice. If the OS of the operationtarget device is UNIX, make surethat the names of the files andfolders you are transferring areencoded in the same characterset used by the connection user.If there is a file or folder with thesame name in the destinationfolder, the file or folder isoverwritten. For this reason, werecommend that you specify aunique name. If the destinationfolder does not exist, the folderwill be created in the specifiedconfiguration.

-- Input R

When specifying file paths, use characters that can be used in commands inthe operating systems of the HAD server and the operation target device.When specifying a file name in the localFilePath property, also specify a filename in the remoteFilePath property. When specifying a folder name in thelocalFilePath property, also specify a folder name in the remoteFilePathproperty.

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

send receiveUnix

send receive

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 ofconnectionuser

Access permissions required for parentfolder of destination file

Writeprivilege ofthe user setin the

Systemaccountwriteprivilege

Writeprivilege ofconnectionuser



ItemWindows

send receiveUnix

send receive

authenticationinformation

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.

Cautionary notes• If parallel is specified in the foreachMode property, the values of service

properties referenced or updated in the context of a repeated task is onlyvalid for the same repeated task (the nth flow). The value of the serviceproperty cannot be shared with concurrently processed repeated tasks(except for the nth flow).

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.

65 The connection with the HAD server failed. For example, theHAD server might have stopped while the plugin was beingexecuted.




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.





Property list

Following are the properties for the Repeated Execution Plug-in:



I/O typeRequired

inputProperties InputProperties

Specify an input property valuefor each repetition of the flow,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 commaseparated values.

-- Input R

outputProperties

OutputProperties

Outputs the value of the outputproperty for the number of

-- Output O




I/O typeRequired

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

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

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). Evenif an error occurs, all theunexecuted flows will beexecuted.

serial

Repeated flows are executedsequentially. If an error occurs,unexecuted repeated flows arenot executed.

parallel Input R


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 shared built-in service properties.Therefore, set the values for these items in advance in the Service ShareProperties view.• 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-in

server share property. Therefore, make sure that you specify at least oneof 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, thestatus 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.



executed.





not be acquired.

70 The connection with the SMTP server failed.

78 Authentication failed.

79 Email transmission failed.









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 than

-- Input O




I/O typeRequired

1,024 characters. Whenspecifying multiple addresses,separate them with commas.

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

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 shared built-in 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 Service ShareProperties view.• 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 shared built-in 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

server share property. Therefore, make sure that you specify at least oneof 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.



executed.





not be acquired.








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




I/O typeRequired

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

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 using 1,024 characters orless. 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 button

0 Input R




I/O typeRequired

associated with thelabelButton0 property will beexecuted. Specify a returncode in the range from 0 to 63.

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

-- Input O


-- Input O


-- Input O

labelButton4 Label Button 4 Specify the button label for theresponse that generates returncode 4, using a maximum of256 characters. You can displaybuttons that meets the user'soperational needs in the

-- Input O




I/O typeRequired

Respond dialog box. If youomit this property, thecorresponding button is notdisplayed.


-- Input O


-- Input O


-- Input O


-- Input O

labelButton9 Label Button 9 Specify the button label for theresponse that generates returncode 9, using a maximum of

-- Input O


I/O typeRequired

256 characters. You can displaybuttons that meets the user'soperational needs in theRespond dialog box. If youomit this property, thecorresponding button is notdisplayed.

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

Specifiable tag Specifiable attributes

Anchor tag (<a>) href

target

Bold tag () --

Break tag ( ) --

Font tag () color

face

size

Italic tag () --

Underline 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 HAD 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, HAD uses the values setin 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 in

the 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 port number,the plug-in finishes executing without waiting for standard outputorstandard 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 HAD step. The size of thestandard output and standard error output is the total number of bytesreceived by HAD. If the Telnet server or SSH server is configured toreplace the linefeed character LF with CR+LF, allow two bytes for eachlinefeed character. The results of processing whose total standard outputand standard error output exceeds 100 KB is outside the scope of productsupport. Make sure that the total standard output and standard erroroutput 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.

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.



executed.





not be acquired.






resolved.

78 When connecting by SSH, authentication on the operation

target device failed.








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



I/O typeRequired

destinationHost DestinationHost

Specify the IPv4 address, IPv6address, or host name of theoperation target device usingno more than 1,024 characters.Multiple IP addresses or hostnames cannot 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




I/O typeRequired

credentialType CredentialsType

As the authentication type touse during command or scriptexecution, specify either of thefollowing:DestinationSpecify this option to use theauthentication information setin the Agentless RemoteConnections view. Specifyingdestination applies theauthentication information setfor WMI or SSH in theconnection destinationdefinition according to the IPaddress of the HAD login user.You can omit the specificationof properties relating toauthentication information(account, password,suPassword,publicKeyAuthentication, andkeyboardInteractiveAuthentication).

PropertySpecify this option to use thevalues specified in the followingproperties as authenticationinformation:• account• password• suPassword• publicKeyAuthentication• keyboardInteractiveAuthent

ication

-- Input R

account User ID Specify the user ID to use tolog in to the operation targetdevice, using a maximum of256 characters.This property is required if bothof 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 use tolog in to the operation targetdevice, using a maximum of256 characters. This property is

-- Input O




I/O typeRequired

required if all of the followingconditions are met:• SSH is specified in the

protocol property.• property is specified in the

credentialType property.• false is specified in the

publicKeyAuthenticationproperty.

If the OS of the operationtarget device is UNIX and trueis specified for thepublicKeyAuthenticationproperty, any value you specifyis ignored. You can, however,set a value for thereserved.terminal.passwordreserved property to reference.

suPassword AdministratorPassword

Specify the password requiredto elevate the user toadministrator privilege, using amaximum of 256 characters.The value of the suPasswordproperty is assigned to thereserved.terminal.suPasswordproperty when you specify thelatter in the command line or aterminal 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




I/O typeRequired


SSHKeyboardInteractiveAuthentication

Controls whether or not to useSSH 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. Thisproperty is not case-sensitive.This property is valid 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 to usewhen connecting to theoperating target device.

-- Input O

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

-- Input O




I/O typeRequired

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 PromptPattern

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 tostandard output or standarderror output.

-- Input R

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

token Token String The token string that identifiesthe session is output to thisproperty. You can specify the

-- Output O




I/O typeRequired

character string output to thisproperty in the token propertyof terminal command plug-insand terminal disconnect plug-ins.

stdoutPattern1 StandardOutputPattern 1

Specify the regular expressionpattern of the standard outputand standard error output tooutput the stdoutPropertyproperty, using a maximum of1,024 characters. 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 stdoutPattern1 propertyis output to this property.

-- Output O



Input O



-- Output O



-- Input O




I/O typeRequired



-- Output

defaultReturnCode

DefaultReturn Code

Specify the value to return asthe return code when standardoutput and standard erroroutput 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 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 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)

tenet.port.number 3 23

SSH port number Plug-in property port 1 --

Connectiondestinationproperties file(connection-destination-name.properties)

ssh.port 2 --

Property file(config_user.properties)

ssh.port.number 3 22

Character setname

Plug-in property charset 1 --

Connectiondestinationproperties file

terminal.charset 2 --


Setting Location Property key Priority Default value

(connection-destination-name.properties)

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 and

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


Property key Example of specified value Meaning of specified value

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


properties 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 HAD 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 HAD step. The size of thestandard output and standard error output is the total number of bytesreceived by HAD. If the Telnet server or SSH server is configured toreplace the linefeed character LF with CR+LF, allow two bytes for eachlinefeed character. The results of processing whose total standard outputand standard error output exceeds 100 KB is outside the scope of productsupport. Make sure that the total standard output and standard erroroutput does not exceed 100 KB.

• If you intend to specify non-ASCII characters in the commandLineproperty, see General Command Plug-in on page 145.

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 HAD server failed. For example, theHAD server might have stopped while the plugin was beingexecuted.




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.




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




I/O typeRequired

commandLine Command Line Specify the absolute path of thecommand or script to beexecuted on the operationtarget device, using amaximum of 256 characters. Inthe command line, specifycharacters that can be enteredin command lines in theoperating systems of the HADserver and the operation targetdevice. 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.

-- Input O




I/O typeRequired

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

-- Input O

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 regular

-- Input R




I/O typeRequired

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



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



-- Output O


Specify the regular expressionpattern of the standard outputto output to thestdoutProperty2 property, usinga maximum of 1,024characters. Specify the regular

Input O




I/O typeRequired

expression pattern in a PCRE-compliant format. If you specifythe key of a service property inthe stdoutProperty2 propertybut do not specify thestdoutPattern2 property, theentire standard output andstandard error output of thecommand or script specified inthe commandLine property isassigned to the serviceproperty.



-- Output O


Specify the regular expressionpattern of the standard outputto output to thestdoutProperty3 property, usinga maximum of 1,024characters. Specify the regularexpression pattern in a PCRE-compliant format. If you specifythe key of a service property inthe stdoutProperty3 propertybut do not specify thestdoutPattern3 property, theentire standard output andstandard error output of thecommand or script specified inthe commandLine property isassigned to the serviceproperty.

-- Input O

defaultReturnCode

Default ReturnCode

Specify the value to return asthe return code when standardoutput and standard erroroutput 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 output andstandard error output, using amaximum of 1,024 characters.Specify the pattern in a

-- Input O




I/O typeRequired

PCREcompliant format. Ifstandard output and standarderror output match thespecified pattern, the plug-inreturns the value specified inthe returnCode property.

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.

stdoutPattern2

^Error:(.*) 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.


Property keyExample of specifiedvalue

Meaning of specified value

returnCodePattern

^Error: 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 describes


examples 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: HAD 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 the HADserver.

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.



executed.







not be acquired.








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





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, andHAD waits for the execution interval to elapse before executing succeedingsteps. By using an interval plug-in, you can execute steps at fixed intervals.

The following illustration 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:




18 A task was forcibly terminated during plug-in execution.

1 to 17, 19 or higher The plug-in terminated abnormally. Use the hcmdsgetlogs

command 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

Judge ReturnCode Plug-inJudges the return value of the previous step to divide the flow of processing.

This plug-in allows you to select which step to execute next based on thereturn code of the preceding step.

A judge returncode plug-in connects to two branch destination steps: Asucceeding step, and a step that is only executed when the judgmentconditions is met. If the return code matches the judgment condition, HADexecutes the branch destination step and the succeeding step, in that order.If the return code does not match the judgment conditions, HAD executes thesucceeding 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 illustration shows how the Judge 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 judge returncode plug-in finishesprocessing.

• 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 judge returncode plug-in stops processing, use the hcmdsgetlogscommand to acquire log information and identify the problem.

Return codes

The following return codes are generated by the Judge ReturnCode Plug-in:


0 or higher The plug-in ended normally. The return code of the preceding

step of the judge returncode plug-in is set as the return code.

Property list

The following properties are available for the Judge 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

Input R

Propertykey

Propertyname


I/O type Required

• 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<=value2The 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 the

0 Input O

Propertykey

Propertyname


I/O type Required

condition property. This valuetakes effect when value2 isincluded in a conditionproperty.

Example of a property specification

A judge returncode plug-in determines whether the return code is within aspecified 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 judge returncode plug-in, you can selectthe steps in a flow based on a character string.

The following illustration 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.



executed.





not be acquired.









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

valueX=value1

Input R

I/Otype

Required

ValueX is greater than Value1and 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, 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).



I/Otype

Required

• valueX contains value1ValueX contains Value1.Values are case sensitive(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

-- Input O


I/Otype

Required

The value is mapped to value2 inthe condition property.

The value in this property takeseffect when value2 is specified inthecondition 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 judge returncode plug-in, you can alsoabnormally terminate a flow when a judgment condition is met.

The following illustration 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 terminateabnormally. 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 plugin 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).

Judge Value Plug-inJudges service property values to divide the flow of processing.

The Judge Value Plug-in compares the value of a service property, the valueof a reserved property, a literal string, or any combination thereof against aspecified value. The result of the comparison determines which step HADexecutes next.This plug-in allows you to select which step to execute next based on thereturn code of the preceding step.

A judge value plug-in connects to two branch destination steps: A succeedingstep, and a step that is only executed when the judgment condition is met. Ifthe input value matches the judgment condition, HAD executes the branchdestination step and the succeeding step, in that order. If the input valuedoes not match the judgment conditions, HAD executes the succeeding steponly.

A judge value plug-in combines the functionality of a test value plug-in and ajudge returncode plug-in.

The following illustration shows how the Judge 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 Judge Value Plug-indoes not contribute to the task log.

• If execution of a task is stopped during plug-in execution, the task entersCompleted status after the Judge Value Plug-in finishes processing.

Return codes

The following return codes are generated by the Judge Value Plug-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 Judge Value Plug-in:


Propertykey

Propertyname


I/O type Required

condition Condition Specify the judgment conditionfor the 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>=value2ValueX is less than or equalto Value1, or greater than orequal to Value2 (numericalcomparison).

valueX=value1

Input R

Propertykey

Propertyname


I/O type Required

• 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



• ?dna_reserved-property-key? (when referencing thevalue of a reserved property)

• literal-string

The value is mapped to value2in the condition property. Thevalue in this property takeseffect when value2 is specifiedin the condition property.

-- Input O


Propertykey

Propertyname


I/O type Required

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.


http://velocity.apache.org/

http://velocity.apache.org/

• If a directory has the same name as an existing output file, a write erroroccurs.

• Line feed codes in the export content and output template are included inthe 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.

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.

-- Input O




I/O typeRequired

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.

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

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


Variable name Description

can be used for theVTL description usingVelocity'sToolManager.

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

63 An error occurred during the processing of the plug-in.

Property list

The following properties are available for the JavaScript Plug-in:

Property key Property name DescriptionDefaultvalue

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


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

out2 Argument(2) A value set to the out2 key inthe map of the second

-- Output O


Property key Property name DescriptionDefaultvalue

I/Otype

Required

argument in the user-specifiedscript is output.

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


-- Output O


-- Output O


-- Output O

You specify the plug-in input/output properties in the property list.Combinations of service property values, reserved property values, literalcharacters, and HAD/AJS3 macro variables can be used for the inputproperties.

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


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

JavaScript 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;})

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 tosearch in comma separatedvalue. If nothing is specified,acquire with being independenton LDEV ID.

-- Input O

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 is

-- Input O




I/O typeRequired

specified, search both assignedand unassigned LDEVs.

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

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

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

-- Input O

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 is

-- Input O




I/O typeRequired

specified, acquire with beingindependent on LUN.

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

[] Output O

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

Status line HTTP/version -

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

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.

-- Input R

requestHeaders Requestheader

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 User name forserver

Specify the user name used forserver authentication. Invalid

-- Input O




I/O typeRequired

when the webAuth property keyis set to none.

webPassword Password forserverauthentication

Specify the password used forserver authentication.

-- Input O

useProxy Use Proxy Set this to true when a proxyconnection is required.

false Input R

proxyHostname Proxy hostnumber

Specify the proxy host name orIP address.

-- Input O

proxyPort Proxy portnumber

Specify the proxy port number. 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.

none Input R

proxyUsername Proxyusername

Specify the user name used forproxy authentication.

-- Input O

proxyPassword Proxypassword

Specify the password used forproxy authentication

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

Responseheader

Outputs the header informationof the HTTP response message.

-- Output --

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.


Supported Headers

Headers are transmitted and received in their raw format. The followingdefault headers are supported:

Header Value

Accept application/json

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 property fileunder <HAD Installation 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.


Plug-in Flow Description

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 HAD-installation-path\Automation\conf\plugin. Edit the italicized characters, etc., as neededfor the user environment.[libdefaults] // Default value for Kerberos authentication default_realm = EXAMPLE.COM#1 // Default realm for Kerberos authentication udp_preference_limit = 1#2

[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 HAD-installation-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-installation-path\Base64\uCPSB\CC\web\containers\AutomationWebService\usrconf\usrconf.cfg so that theconfiguration files described in (i) and (ii) are referencedadd.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 96Built-in Plug-in Parameters 143

CCharacter Set Auto Judgment 67Character Set Auto Judgment (SSH) 140conditional branch

Plug-ins 76, 77, 81Configuration type

debug 96release 115

Copyingplug-ins 36service templates 28

creating a service templateedit service template attributes, dialog box118

Creating newplug-ins 67

creating the flow 44Custom files 119

Ddata map

component version management, dialog box126create property group, dialog box 120create step, dialog box 45edit property group, dialog box 122import service template package, dialog box30

DebuggerChecking property mapping 110Controlling the display of tasks 108Controlling the processing flow of debug task106edit step property, dialog box 111editing service and request entries 102Examining debug details 105Exporting property values 112Handling interruptions of debug tasks 107

Importing property files 111Perform Debugging, dialog box 100running 98Working with the debugger 103

Debugging and releasingworkflow 95

Deletingplug-ins 37service templates 29

EEnvironment variables 75Example

creating a service template 60, 82Exporting

service templates 31

Ggenerating an email

Plug-ins 76, 77, 81gui

create variable, dialog box 60gui settings

create output property for service, dialog box58

GUI settingscreate input property for service, dialog box 56select service share property, dialog box 54

IImporting

service templates 30Input properties

in plug-ins 67, 72in service templates 119

Intended audience 8

JJudgment level 44

Index 237Hitachi Automation Director Service Builder

MManaging tasks during debugging 106

OOutput filters

Plug-ins 76, 77, 81Output properties

in plug-ins 67, 73in service templates 119

Pplug-in

create plug-in, dialog box 69plug-in mapping

specify component input properties formapping parameters, dialog box 49

plug-inscreate environment variable, dialog box 76create input property for custom plug-in,dialog box 72create output property for plug-in, dialog box73edit output filter, dialog box 77edit remote command, dialog box 74

Plug-ins 76, 77, 81Abnormal End Plug-in 212basic 34, 133built-in 133, 145, 154, 165, 168, 170, 176,189, 199, 200, 202, 203, 206, 212, 213, 217,220, 225, 227, 229copying 36creating a new 65creating new 67creation workflow 67definition 17deleting 37editing 69Email Notification Plug-in 168File Export Plug-in 217File-Forwarding Plug-in 154Flow Plug-in 200General Command Plug-in 145input properties 72Interval Plug-in 202JavaScript Plug-in 220Judge ReturnCode Plug-in 203Judge Value Plug-in 213LDEV ID Search Plug-in 225managing 36output properties 73overview 34Path Search Plug-in 227properties 71remote commands 74Repeated Execution Plug-in 165reserved 137serivce 34

Terminal Command Plug-in 189Terminal Connect Plug-in 176Terminal Disconnect Plug-in 199Test Value Plug-in 206User-response wait plug-in 170Web Client Plug-in 229

Preset property definition files 123, 124implementing 124

Property groups 119

RRelease operation 115

SService

definition 17Service Builder

accessing 21GUI 21

Service Builder view 21Service Definitions

editing 119Service plug-ins

creating 119definition 34

service templatecreate service template, dialog box 42

Service templatemanaging 27overview 26

Service Template Editor view 21Service templates

adding input properties 55adding output properties 58adding variables 59build result, dialog box 97built-in 128copying 28Creating a flow hierarchy 52creating a new service template 42, 43creating the steps 44creation workflow 40definition 17deleting 29editing 27editing the service definition 118Establishing the flow of execution 50exporting 31importing 30preset property definition files 123, 124releasing 115selecting the service share properties 54service definitions 119step properties 46testing 96

Stepdefinition 17

238 IndexHitachi Automation Director Service Builder

TTask

definition 17

VVersioning 125

Index 239Hitachi Automation Director Service Builder

240 IndexHitachi Automation Director Service Builder

Hitachi Automation Director Service Builder

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]

MK-92HC222-03

http://www.hds.com

MAILTO:[email protected]



hitachi automation director service builder - hitachi … · · 2015-11-09this manual describes...

Documents