server management job api tandem 1 -...

User Guide - English

FUJITSU Software ServerView Suite

Server Management

Job API Tandem 1.5

Edition February 2018

Comments… Suggestions… Corrections…The User Documentation Department would like toknow your opinion of this manual. Your feedback helpsus optimize our documentation to suit your individual needs.

Feel free to send us your comments by e-mail to [email protected].

Certified documentation according to DIN EN ISO 9001:2000To ensure a consistently high quality standard anduser-friendliness, this documentation was created tomeet the regulations of a quality management system which complies with the requirements of the standardDIN EN ISO 9001:2000.

cognitas. Gesellschaft für Technik-Dokumentation mbHwww.cognitas.de

Copyright and Trademarks

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.vo

r

Copyright 2010 FUJITSU LIMITED

All rights reserved.Delivery subject to availability; right of technical modifications reserved.

All hardware and software names used are trademarks of their respective manufacturers.

http://www.cognitas.de

mailto:[email protected]

Job API Tandem

Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.1 Document scope . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2 Notational conventions . . . . . . . . . . . . . . . . . . . . . 8

2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 API client /server function flow . . . . . . . . . . . . . . . . 13

4.1 Installation, image creation use case . . . . . . . . . . . . . 13

5 API function classes . . . . . . . . . . . . . . . . . . . . . . 17

5.1 Function overview . . . . . . . . . . . . . . . . . . . . . . . 17

5.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.3 API Management . . . . . . . . . . . . . . . . . . . . . . . . 245.3.1 GetAPIVersion . . . . . . . . . . . . . . . . . . . . . . . . . . 245.3.2 GetAPIinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.3.3 CreateUserKey . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.4 Server/Nodelist Management . . . . . . . . . . . . . . . . . 295.4.1 AddServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295.4.2 ChangeServerConfiguration . . . . . . . . . . . . . . . . . . . 365.4.3 StartSystemInfoRetrieval . . . . . . . . . . . . . . . . . . . . 415.4.4 GetSystemInfoResult . . . . . . . . . . . . . . . . . . . . . . 445.4.5 RdDeplServerList . . . . . . . . . . . . . . . . . . . . . . . . 455.4.6 ImportDeploymentConfiguration . . . . . . . . . . . . . . . . . 515.4.7 ExportDeploymentConfiguration . . . . . . . . . . . . . . . . . 535.4.8 SetUserKey . . . . . . . . . . . . . . . . . . . . . . . . . . . 555.4.9 RemoveUserKey . . . . . . . . . . . . . . . . . . . . . . . . . 56

Job API Tandem

Contents

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obAP

I_Ta

ndem

\Han

dbuc

h\us

\job_

AP

I-en.

ivz

5.5 Power Management . . . . . . . . . . . . . . . . . . . . . . . 575.5.1 SetPower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575.5.2 SetPXEBootImage . . . . . . . . . . . . . . . . . . . . . . . . 615.5.3 GetPower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.5.4 GetBootMode . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

5.6 Repository Management . . . . . . . . . . . . . . . . . . . . 685.6.1 AddRepository . . . . . . . . . . . . . . . . . . . . . . . . . . 705.6.2 RemoveRepository . . . . . . . . . . . . . . . . . . . . . . . . 725.6.3 GetRepositoryList . . . . . . . . . . . . . . . . . . . . . . . . . 735.6.4 CreateImage . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.6.5 DeleteImage . . . . . . . . . . . . . . . . . . . . . . . . . . . 835.6.6 GetRepositoryContents . . . . . . . . . . . . . . . . . . . . . . 845.6.7 ReadImagefilenameList . . . . . . . . . . . . . . . . . . . . . . 865.6.8 ReadImageInfoText . . . . . . . . . . . . . . . . . . . . . . . . 875.6.9 GetImageProperties . . . . . . . . . . . . . . . . . . . . . . . 88

5.7 Directory Management . . . . . . . . . . . . . . . . . . . . . 895.7.1 CreateDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . 895.7.2 DeleteDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . 915.7.3 GetDirectoryContents . . . . . . . . . . . . . . . . . . . . . . . 93

5.8 Group Management . . . . . . . . . . . . . . . . . . . . . . . 955.8.1 CreateGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 965.8.2 DeleteGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 985.8.3 GetGroupList . . . . . . . . . . . . . . . . . . . . . . . . . . . 995.8.4 SetGroupProperties . . . . . . . . . . . . . . . . . . . . . . . 1015.8.5 GetGroupProperties . . . . . . . . . . . . . . . . . . . . . . 1035.8.6 AddGroupMember . . . . . . . . . . . . . . . . . . . . . . . 1055.8.7 RemoveGroupMember . . . . . . . . . . . . . . . . . . . . . 1075.8.8 GetGroupMemberList . . . . . . . . . . . . . . . . . . . . . . 1085.8.9 SetGroupMemberProperties . . . . . . . . . . . . . . . . . . 1105.8.10 GetGroupMemberProperties . . . . . . . . . . . . . . . . . . 112

5.9 Deployment Management . . . . . . . . . . . . . . . . . . . 1145.9.1 Deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

5.10 Job Management . . . . . . . . . . . . . . . . . . . . . . . 1265.10.1 GetJobStatusDetails . . . . . . . . . . . . . . . . . . . . . . 1275.10.2 GetServerJobStatus . . . . . . . . . . . . . . . . . . . . . . 1305.10.3 CancelJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335.10.4 GetScheduledJobProperties . . . . . . . . . . . . . . . . . . 1355.10.5 GetScheduledJobLogList . . . . . . . . . . . . . . . . . . . . 1375.10.6 DeleteScheduledJob . . . . . . . . . . . . . . . . . . . . . . 139

Job API Tandem

Contents

6 Job scheduling . . . . . . . . . . . . . . . . . . . . . . . . . 141

7 API error codes . . . . . . . . . . . . . . . . . . . . . . . . . 145

8 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

8.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 147

8.2 Installation process . . . . . . . . . . . . . . . . . . . . . . 148

8.3 JobAPI with Internet Information Server (IIS) . . . . . . . . 1548.3.1 JobAPI with Internet Information Server (IIS) on

Windows Server 2003 . . . . . . . . . . . . . . . . . . . . . . 1548.3.2 JobAPI with Internet Information Server (IIS) on

Windows Server 2008 . . . . . . . . . . . . . . . . . . . . . . 154

8.4 Installation test . . . . . . . . . . . . . . . . . . . . . . . . . 155

9 Further information . . . . . . . . . . . . . . . . . . . . . . 157

9.1 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

9.2 HTTP authentication . . . . . . . . . . . . . . . . . . . . . . 158

9.3 HTTPS / SSL . . . . . . . . . . . . . . . . . . . . . . . . . . 160

9.4 SOAP timeouts . . . . . . . . . . . . . . . . . . . . . . . . . 162

9.5 CGI timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639.5.1 Apache configuration . . . . . . . . . . . . . . . . . . . . . . 1639.5.2 IIS configuration . . . . . . . . . . . . . . . . . . . . . . . . . 165

9.6 SOAP error handling . . . . . . . . . . . . . . . . . . . . . . 167

9.7 SOAP debugging . . . . . . . . . . . . . . . . . . . . . . . . 1689.7.1 Job API client . . . . . . . . . . . . . . . . . . . . . . . . . . 1689.7.2 Job API server . . . . . . . . . . . . . . . . . . . . . . . . . . 168

10 Job API client development . . . . . . . . . . . . . . . . . . 169

10.1 Generating C/C++ stubs . . . . . . . . . . . . . . . . . . . . 170

10.2 Using generated C/C++ stubs . . . . . . . . . . . . . . . . . 173

Job API Tandem

Contents

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obAP

I_Ta

ndem

\Han

dbuc

h\us

\job_

AP

I-en.

ivz

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Job API Tandem 7

1 IntroductionTandem is a powerful remote interface of the PRIMERGY ServerView Suite. It contains of two major API packages:

– central NodeList API (not released yet)

– central Job API

Job API as well as NodeList API will be implemented as Web services based on SOAP. The Simple Object Access Protocol (SOAP) is an XML-based messaging protocol and defines a set of rules for structuring messages that can be used to perform RPC-style request-response dialogues. SOAP messages are independent of any operation system, programming language or transport protocol. Therefore the clients and servers in request-response dialogues can be running on any platform and written in any language as long as they can prepare and handle SOAP messages.

The Job API Tandem is designed to offer for the most of function set as offered by the Deployment Manager front-end. The Job API allows to prepare, install and clone single server or servers arranged in server groups. The Job API provides the ability to submit jobs to ServerView Deployment Manager service.

The function class Server/Nodelist Management of Job API contains functions which manipulate the central ServerView server list containing the physical view of all administrated servers managed by PRIMERGY ServerView Suite software. So it is possible to add a new bare server which are not be managed by ServerView up to now. Until the NodeList API will be released the Server/Nodelist Management offers functions which can be used instead.

The Job API is an independent installation package provided on the Deployment Manager CD.

1.1 Document scope

This document describes the parameters and expected behaviors of the different functions of the Job API Tandem. The primary audience for this documentation are programmers who want to access the PRIMERGY server management function set remote over LAN by 3rd party software.

8 Job API Tandem

Notational conventions Introduction

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

1

1.2 Notational conventions

The following notational conventions are used in this specification document.

For the indication of IP addresses the standard format "XXX.XXX.XXX.XXX" is used, i.e. the 32bit long integer is specified in four decimal numbers between 0 and 255 separated by points (RFC 791).

The valid format for a GUID is "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" where X is a hex digit (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F).

The MAC addresses in the functions are returned in the format "AA-BB-CC-DD-EE-FF". Whenever a MAC address is required as input parameter, it can be provided in addition in the format "AA:BB:CC:DD:EE:FF". It does not matter, whether the characters are uppercase or lowercase.

Job API Tandem 9

2 ArchitectureThe following figure illustrates the overview of the server management of the PRIMERGY ServerView Suite combined with the Job API and NodeList API packages of Tandem:

Figure 1: Architecture

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

2

Job API Tandem 11

3 SecurityThe current Job API service is realized as CGI-based web service application. In principle the way CGI works from the Web server's point of view is that certain web services are defined to be served by a CGI application. Whenever a request to the Web server is received, the CGI application is called with any data that the client sent as input. Finally the output from the CGI application is collected by the Web server and sent back to the client.

Due to this fact, the information contained in the SOAP messages can only be intercepted between client and Web server. At the lowest level, SOAP messages can be passed over HTTPS. Since HTTPS uses SSL for its transport, this ensures that the contents of the message are encoded to prevent snooping, and that the client and server can verify each other's identity. Therefore, HTTPS / SSL support must be configured for the Web server and for the JobAPI client (not CGI-based Web service application itself).

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

3

Job API Tandem 13

4 API client /server function flowGenerally a protocol is described in the computer science as a set of rules, which specify the format, the contents, the meaning and the sequence of a communication between two end points. Therefore it is true that the exchange of information between a Job API client and a Job API server can be interpreted in sense of a protocol, but the client / server communication is defined inside the Job API specification as a function flow. Additional the function flow has no defined calling order of the functions. However, it is necessary for a Job API client to create a valid user key at the beginning. It is possible to create user keys multiple times, but it is not necessary to create always a new one. A Job API client should create a user key only once.

In the following sub chapters function flows of different use cases are contained which explain the use and the correct sequence of the Job API function by means of the shown figures.

4.1 Installation, image creation use case

The first use case covers the execution of an installation of a target system as well as the creation of an image for the later deployment of further servers.

As introductorily mentioned to use the total functionality of Job API the creation of a valid user key is necessary. Please be aware that the parameter UserKey is mandatory for the use of all functions and needs the specification of a valid user key. In general all servers in the server list can be managed on the Job API independent on their server type like PRIMERGY, Blade etc. However, to get a list of all discovered server by ServerView and/or new added bare server by AddServer use the function RdDeplServerList.

14 Job API Tandem

Installation, image creation use case API client /server function flow

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

4

In order to install the new bare server, for example as target system, the path of the configuration file can be specified directly as a parameter or an installation group can be created. If an installation group is created, the group member specific property is the path of the configuration file which is defined previously by Installation Manager.

Dependent on the deploy call either all servers contained in the specified group or a subgroup of servers (see parameter ServerIdList) are installed by Installation Manager. After the installation job has finished (poll the job status with GetJobStatusDetails), an image of the installed target system can be created in order to deploy further servers. Job API as well as Deployment Manager administrate all available images in repositories. That means, to make the new cloning image visible add a new repository of type REPOSITORYTYPE_CLONING via AddRepository into the repository management.

Job API Tandem 15

API client /server function flow Installation, image creation use case

Basically each server can be managed by different Job API clients or Deployment Manager front-ends. Therefore it makes sense to reserve the server especially for the own user key with SetUserKey. After successfully finishing of the installation and image creation job, do not forget to remove the reservation of the target system. This can be executed by the use of the function RemoveUserKey.

16 Job API Tandem

Installation, image creation use case API client /server function flow

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

4

Job API Tandem 17

5 API function classesThe following chapter contains an informal description of the parameters and expected behaviors of the different functions of the Job API. All parameters will be encoded in SOAP/XML.

5.1 Function overview

The table below gives an overview of the implemented functions.

API Management

Server/Nodelist Management

GetAPIVersion Returns information about the version of Job API, see page 24.

GetAPIInfo Returns details information about Job API and available deployment engines, see page 25.

CreateUserKey Creates a unique user key, see page 28.

AddServer Adds a new server with specified deployment configuration, see page 29.

ChangeServerConfiguration

Changes any settings of the deployment configuration of a specified server, see page 36.

StartSystemInfoRetrieval

Starts the job to get detailed system information from a specified server, see page 41.

GetSystemInfoResult Returns detailed system information from a specified server, see page 44.

RdDeplServerList Returns a list of all available servers in the deployment table, see page 45.

ImportDeploymentConfiguration

Imports the deployment table in form of an XML document, see page 51.

ExportDeploymentConfiguration

Exports the deployment table in form of an XML document, see page 53.

18 Job API Tandem

Function overview API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Power Management

SetUserKey Reserves one or more server for the given user key, see page 55.

RemoveUserKey Removes the user reservation of the specified servers, see page 56.

SetPower Power on or power off a server, see page 57.SetPXEBootImage Sets the given boot image on the TFTP server to

enable a PXE boot for the given server, see page 61.GetPower Determines the current setting of the power switch of

a server, see page 64.GetBootMode Gets the current boot mode of a server, see page 66.

Job API Tandem 19

API function classes Function overview

Repository Management

Directory Management

AddRepository Adds a new repository, see page 70.RemoveRepository Removes a specified repository, see page 72.GetRepositoryList Returns a list of detailed information about all

repositories or repositories of a certain type, see page 73.

CreateImage Creates an image that can be used for the deployment of multiple target systems, see page 75.

DeleteImage Deletes an existing image file, see page 83.GetRepositoryContents Returns a list of image file names that have been

found in a specified repository or in all repositories of a specified type, see page 84.

ReadImagefilenameList Returns a list of image file names that have been found in all known repositories, see page 86.

ReadImageInfoText Returns the info text for a specified image, see page 87.

GetImageProperties Returns all properties of a given image in form of a XML document, see page 88.

CreateDirectory Creates a new directory, see page 89.DeleteDirectory Deletes a directory, see page 91.GetDirectoryContents Returns a list of all known files contained in a specified

directory, see page 93.

20 Job API Tandem

Function overview API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Group Management

Deployment Management

CreateGroup Create a new group of specified type, see page 96.DeleteGroup Deletes a specified group, see page 98.GetGroupList Returns a list of all known groups, see page 99.SetGroupProperties Sets the specified group properties to the specified

value for the given group, see page 101.GetGroupProperties Returns the information about all available group

properties and their values, see page 103.AddGroupMember Adds a new server to the given group, see

page 105. RemoveGroupMember Removes a specified server form the given group,

see page 107.GetGroupMemberList Returns a list of all known members in the specified

group, see page 108.SetGroupMemberProperties

Sets properties of the specified group member to the specified values, see page 110.

GetGroupMemberProperties

Returns the information about all available server properties and their values, see page 112.

Deploy Deploys specified target servers and starts alternatively a boot of these, see page 115.

Job API Tandem 21

API function classes Function overview

Job Management

GetJobStatusDetails Returns the current job status and more job details by given JobID, see page 127.

GetServerJobStatus Returns the current job status by given list of server identifier, see page 130.

CancelJob Cancels a running job, see page 133.DeleteScheduledJob Deletes an existing scheduled job by given

ScheduledJobID, see page 139. GetScheduledJobProperties

Returns all scheduled job properties of a given scheduled job, see page 135.

GetScheduledJobIDList Returns a list of all available running and/or already finished jobs of the given scheduled job, see page 137.

22 Job API Tandem

Data Types API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.2 Data Types

The following general data types are used in this document:

Layout of the ArrayOf_PropertyData structure

The structure of properties will have the following layout:

NameSpecifies a known name of a property.

ValueSpecifies the value of the specified property.

Layout of the ServerIdentifier structure

In order to identify a server you can specify MAC address, IP address or the host name of the server. The following structure allows the server identification by several types.

Identifier=<string> Type=<int>

IdentifierString, containing a distinctive identifier of a known server.

TypeType of the identifier:0 (IDENTIFIERTYPE_MAC): physical address of network interface1 (IDENTIFIERTYPE_IP): IP address of the server. This must be the SV_IPAddress field returned by RdDeplServerList.2 (IDENTIFIERTYPE_NAME): host name of the server. This must be the ServerName field returned by RdDeplServerList.

Type Descriptionstring String which may contain any alpha-numeric characters. int An integerlong A long integer.

Table 1: Data types

Job API Tandem 23

API function classes Data Types

Layout of the ArrayOf_ParameterData structure

The following structure contains the specification of parameter.

Name=<string> Value=<string>

NameName of the parameter.

ValueValue of the corresponding parameter name.

24 Job API Tandem

API Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.3 API Management

The Job API function class API Management can be used to manage the use of the Job API, i.e.to get information about the Job API Web service as also about the used deployment engines.

5.3.1 GetAPIVersion

The GetAPIVersion function is used to inform the caller of the API about the current API version that is provided by the Job API service.

Syntax

GetAPIVersion UserKey=<string>

Parameter

UserKeySpecifies the unique user key which is exclusively associated with one user account.

Return Value

ErrorCodeDiagnostic number of the last execution. If successful execution, ErrorCode is set to 0.

ErrorStringTextual description of the error code. If successful execution, ErrorString is empty.

APIVersionCurrent Version of Job API (e.g. 1.5).

Job API Tandem 25

API function classes API Management

5.3.2 GetAPIinfo

Beside the version information which GetAPIVersion returns, GetAPIInfo retrieves further detailed information of JobAPI and the deployment environment, e.g. build number as well as availability deployment engines.

I In order to use this function Deployment Manager is necessary.

Syntax

GetAPIInfo DeploymentEngines= <ArrayOf_DeploymentEngineIdentifier> RDServer=<string> UserKey=<string> APIProperties=<ArrayOf_PropertyData> DeploymentEngineProperties=<ArrayOf_DeploymentEngineData>

Parameter

Deployment EnginesSpecifies the deployment engines which will be checked in order to return the current engine properties. For details about the structure refer to "Layout of the DeploymentEngineIdentifier structure" on page 26.

RDServerSpecifies the host name or the IP address of the server where the ServerView Deployment Manager service is running. If this parameter is not specified, the local machine is used.Default value: ""

UserKeySpecifies the unique user key which is exclusively associated with one user account.

APIProperties Returns an array of all Job API properties, e.g. BuildNumber. For details about the structure refer to "Layout of the ArrayOf_PropertyData structure" on page 22.

DeploymentEngineProperties Returns the status of the specified deployment engines, e.g. Installation Manager. For details about the structure refer to the "Layout of the returned DeploymentEngineData structure" on page 27.

26 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Layout of the DeploymentEngineIdentifier structure

The structure of the deployment engine identifier contains detailed connection information of the deployment engine. This structure will have the following layout:

ServerId=<ServerIdentifier> Type=<int> Username=<string> Password=<string>

ServerIdServer name on which the engine is installed. For more details about the structure see "Layout of the ServerIdentifier structure" on page 22.

TypeType of the deployment engine:1: (DEPLOYMENTENGINE_SCW)2: (DEPLOYMENTENGINE_INSTALLATIONMANAGER)3: (DEPLOYMENTENGINE_DEPLOYMENTMANAGER)

UsernameName of a user account for the specified engine. This parameter is mandatory.

PasswordCorresponding password for the specified user account. This parameter is mandatory.

Job API Tandem 27

API function classes API Management

Layout of the returned DeploymentEngineData structure

The structure of the deployment engine data contains the returned information about one or more specified engines. This structure has the following layout:

ServerId=<ServerIdentifier> Type=<int> Properties=<ArrayOfPropertyData>

ServerIdDisplays the server on which the engine is installed. For more details about the structure see "Layout of the ServerIdentifier structure" on page 22.

TypeDisplays the type of the deployment engine:1: (DEPLOYMENTENGINE_SCW)2: (DEPLOYMENTENGINE_INSTALLATIONMANAGER)3: (DEPLOYMENTENGINE_DEPLOYMENTMANAGER)

PropertiesDisplays the properties of the specified deployment engine.

Return Value



28 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.3.3 CreateUserKey

The function CreateUserKey creates a unique user key which is exclusively associated with the specified user account. This valid user key is necessary to work with Job API.

Syntax

CreateUserKey Username=<string> Password=<string>

Parameter

UsernameSpecifies the name of a user account contained in the group Deployment Admins.

PasswordSpecifies the corresponding password for the specified user account.

I The lengths as well as the format of the parameters username and password are operating system dependently.

Return Value



UserKeyUnique user key which is exclusively associated with the specified user account.

Job API Tandem 29

API function classes Server/Nodelist Management

5.4 Server/Nodelist Management

The Server/Nodelist Management hosts the configurations, status and additional information of all discovered server by ServerView and/or all added server by Deployment Manager or Job API. These all servers can be managed by Job API independent on their server type.

5.4.1 AddServer

Job API offers the function AddServer to enter manual configuration settings (with the specified deployment configuration) for a new bare server.

Syntax

AddServer Hostname=<string> GUID=<string> NetworkInterface=<ArrayOf_NetworkInterfaceData> PXEBootInterface=<int> Params=<ArrayOf_ParameterData> RDServer=<string> UserKey=<string>

Parameter

HostnameSpecifies the name of the new server. This new name will be used as the host name of the new server when this server is installed or deployed with an image. This parameter is mandatory.

GUIDSpecifies the globally unique identifier. Default value: 00000000-0000-0000-000000000000

NetworkInterfaceSpecifies an array of structures of the type NetworkInterfaceData containing the detailed network interface information of the new server. For more details about the network structure see "Layout of the NetworkInterfaceData structure" on page 31.

30 Job API Tandem

Server/Nodelist Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

PXEBootInterfaceSpecifies the interface index (beginning with 1) of a specified network interface which will be used for PXE boot (for cloning and installation). It is mandatory to specify one network interface that is used for PXE boot.

ParamsSpecifies an array of structure of type ParameterData. For more details about available parameters see "Table of available parameters" on page 33 and about the parameter structure see "Layout of the ArrayOf_ParameterData structure" on page 23.


UserKeySpecifies the unique user key which is exclusively associated with the calling user account.

I The lengths as well as the permitted characters for the parameters Hostname, DNSSuffix, AdminUsername and AdminPassword are operating system dependently.

Job API Tandem 31


Layout of the NetworkInterfaceData structure

The structure of the network interface data contains detailed information of the network interface configuration of the new server. This structure will have the following layout:

Type=<int> Properties=<ArrayOf_PropertyData>

TypeSpecifies the type of the network interface.1: (NETWORKINTERFACETYPE_PHYSICAL)

PropertiesSpecifies the properties of the network interface of the new server, see "Layout of the ArrayOf_PropertyData structure" on page 22.

Table of available physical network interface properties

The table contains the available properties which can be specified in the array of network interface data.

MACAddressSpecifies the physical address of network interface of the new server. This parameter is mandatory.

IPAddressSpecifies the IP address of the network interface. If DHCP is used, IP address has to be 0.0.0.0.Default value: 0.0.0.0

NetMaskSpecifies the net mask of the network interface. If DHCP is used, the net mask has to be 255.255.255.255.Default value: 255.255.255.255

GatewaySpecifies the default gateway of the LAN. If DHCP is used, the IP address of a default gateway has to be 0.0.0.0.Default value: 0.0.0.0

DNSServerListSpecifies a comma separated list of DNS server names or IP addresses of domain servers.Default value: ""

32 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

RegisterInDNSEnables or disables the dynamically registration of the IP addresses in DNS. This parameter is evaluated only for Windows systems.0: (OFF)1: (ON)Default value: 1 (ON)

UseSuffixInDNSEnables or disable a DNS dynamic update to register the IP addresses and the connection-specific domain name of this connection. If RegisterInDNS is enabled, this registration enabled here is in addition to the DNS registration of the full computer name. This parameter is evaluated only for Windows systems.0: (OFF)1: (ON)Default value: 0 (OFF)

ConnectionDNSSuffixSpecifies the domain suffix string for this interface.This parameter is evaluated only for Windows systems.Default value: ""

Job API Tandem 33


Table of available parameters

The table contains the available parameters which can be specified in the array of parameters.

SystemTypeSpecifies the system type of PRIMERGY server, e.g. PRIMERGY TX300.Default value: "Any Server"

ServerModelSpecifies the standardized description of the Fujitsu server model, e.g. D1710 is taken from the full description S26361-D1710-A1.Default value: ""

DNSSuffixSpecifies the domain suffix string, e.g. <hostname>.<dnssuffix>.Default value: ""

DNSAppendListSpecifies a list of configured DNS suffixes to resolve an unqualified name by appending the suffixes from the list instead of the primary and connection specific DNS suffixes. Default value: ""

CommunitySpecifies the SNMP community defined for the SNMP service. This is only used to specify the SNMP community string in the server list and will be used by ServerView Suite applications for SNMP access of this server. It does not define the SNMP community of the SNMP service after cloning or installation.Default value: ""

AdminUsernameSpecifies the user account of the administrator.Default value: "" (administrator is used for Windows and root for Linux)

AdminPasswordSpecifies the corresponding password for the specified administration user account.Default value: "" (do not change the password during deployment)

34 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

RemoteAccessSpecifies the remote access:0 (REMOTEACCESSTYPE-NONE)1 (REMOTEACCESSTYPE-BMC): BMC support2 (REMOTEACCESSTYPE-WOL): Wake on LANDefault value: 0

IpmiMgmtIPAddressSpecifies the IP address of the baseboard management controller (BMC) as configured in the BIOS setup.Default value: "".This parameter is mandatory when parameter RemoteAccess is 1 (BMC).

IpmiUsernameSpecifies the name of the user for the BMC authentication (Ipmi 1.5).Default value: "".This parameter is mandatory when parameter RemoteAccess is 1 (BMC).

IpmiPasswordSpecifies the corresponding password for the specified user account for the BMC authentication (Ipmi 1.5).Default value: "".This parameter is mandatory when parameter RemoteAccess is 1 (BMC).

IpmiTimeoutSpecifies the timeout in seconds for every BMC access. Default value: 3

IpmiRetriesSpecifies the number of retries for every BMC access.Default value: 1

WOLBroadcastIPAddressSpecifies the IP address of the target where the magic packet should be sent to. If the parameter is empty and RemoteAccess=WOL, the target must be in the same LAN segment. The limited broadcast IP address 255.255.255.255 is used and the magic packet is directly sent as ethernet broadcast to UDP port 9.Default value: ""

Job API Tandem 35


WOLBootstrapProtocolIPAddressSpecifies the IP address of the bootstrap protocol server.This parameter is mandatory, if the broadcast should be sent to the UDP port 67 and if the WOL BroadcastIPAddress contains a unicast IP address. Default value: ""

I If the specified server type does not support IPMI over LAN, Wake on LAN will be used by default.

Return Value



36 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.4.2 ChangeServerConfiguration

This function is used to change the current settings (including the deployment configuration) of the specified server. Only defined parameters cause a change of the server configuration.

Syntax

ChangeServerConfiguration ServerId=<ServerIdentifier> NetworkInterface=<ArrayOf_NetworkinterfaceData> Params=<ArrayOf_ParameterData> RDServer=<string> UserKey=<string>

Parameter

ServerIdSpecifies the server identification of the server which deployment configuration is changed. For more details about the structure see "Layout of the ServerIdentifier structure" on page 22. This parameter is mandatory.

NetworkInterfaceSpecifies an array of structures of type NetworkInterfaceData contained the detailed network interface information of the server. For details about the network interface structure see "Layout of the NetworkInterfaceData structure" on page 31. For physical network interfaces see "Table of available physical network interface properties" on page 37.

I If there is no NetworkInterfaceData specified, the current network interface configuration of the server is left unchanged. But if a NetworkInterfaceData is specified, it must contain the complete Network configuration (all interfaces).


Job API Tandem 37




I In the current version the host name can only be changed for a specified blade. For future versions the modification of the host name will be possible for all server types.

Table of available physical network interface properties

The table contains the available properties which can be specified in the array of network interface data.

MACAddressSpecifies the physical address of network interface of the server to be changed.

IPAddressSpecifies the IP address of the network interface. If DHCP is used, IP address has to be 0.0.0.0.Default value: 0.0.0.0

NetMaskSpecifies the net mask of the network interface. If DHCP is used, the net mask has to be 255.255.255.255.Default value: 255.255.255.255

GatewaySpecifies the default gateway of the LAN. If DHCP is used, the IP address of a default gateway has to be 0.0.0.0.Default value: 0.0.0.0

DNSServerListSpecifies a comma separated list of DNS server names or IP addresses of domain servers.Default value: ""

38 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

RegisterInDNSEnables or disables the dynamically registration of the IP addresses in DNS. This parameter is evaluated only for Windows systems.0: (OFF)1: (ON)Default value: 1 (ON)

UseSuffixInDNSEnables or disable a DNS dynamic update to register the IP addresses and the connection-specific domain name of this connection. If RegisterInDNS is enabled, this registration enabled here is in addition to the DNS registration of the full computer name. This parameter is evaluated only for Windows systems.0: (OFF)1: (ON)Default value: 0 (OFF)

ConnectionDNSSuffixSpecifies the domain suffix string for this interface.This parameter is evaluated only for Windows systems.Default value: ""

Job API Tandem 39




I The parameters can be specified or not specified. Therefore only defined parameters cause a change of the server configuration.

HostnameSpecifies the new name of the specified server. This new name will be used as the host name of the new server if this server is installed or deployed with an image.

GUIDSpecifies the globally unique identifier.

SystemTypeSpecifies the system type of PRIMERGY server, e.g. PRIMERGY TX300.

ServerModelSpecifies the standardized description of the Fujitsu server model, e.g. D1710 is taken from the full description S26361-D1710-A1.

DNSSuffixSpecifies the domain suffix string, e.g. <hostname>.<dnssuffix>.

CommunitySpecifies the SNMP community defined for the SNMP service. This is only used to specify the SNMP community string in the server list and will be used by ServerView Suite applications for SNMP access of this server. It does not define the SNMP community of the SNMP service after cloning or installation.

AdminUsernameSpecifies the user account of the administrator.

AdminPasswordSpecifies the corresponding password for the specified administration user account.

PXEBootInterface Specifies the interface index (beginning with 1) of a specified network interface which will be used for PXE boot (for cloning and installation). It is mandatory to specified one network interface that is used for PXE boot.

40 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

RemoteAccessSpecifies the remote access:0 (REMOTEACCESSTYPE-NONE)1 (REMOTEACCESSTYPE-BMC): BMC support2 (REMOTEACCESSTYPE-WOL): Wake on LAN

IpmiMgmtIPAddressSpecifies the IP address of the baseboard management controller (BMC).

IpmiUsernameSpecifies the name of the user for the BMC authentication (Ipmi 1.5).

IpmiPasswordSpecifies the corresponding password for the specified user account for the BMC authentication (Ipmi 1.5).

IpmiTimeoutSpecifies the timeout in seconds for every BMC access.

IpmiRetriesSpecifies the number of retries for every BMC access.

WOLBroadcastIPAddressSpecifies the IP address of the target where the magic packet should be sent to. If the parameter is empty, the target must be in the same LAN segment. The limited broadcast IP address 255.255.255.255 is used and the magic packet is directly sent as ethernet broadcast to UDP port 9.

WOLBootstrapProtocolIPAddressSpecifies the IP address of the bootstrap protocol server.This parameter is mandatory, if the broadcast should be sent to the UDP port 67 and if the WOLBroadcastIPAddress contains a unicast IP address.

Return Value



Job API Tandem 41


5.4.3 StartSystemInfoRetrieval

The StartSystemInfoRetrieval function is useful to get current system information about the specified server. Dependent on different factors this started job can take a few minutes in order to get the current system information. Via the returned job ID the current status of the job can be retrieved by the function GetJobStatusDetails.

Syntax

StartSystemInfoRetrieval ServerId=<ServerIdentifier> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> ShutdownType=<int> ShutdownCommunity=<string> ShutdownUsername=<string> ShutdownPassword=<string> FinalSeStAgentStatus=<int> RDServer=<string> UserKey=<string>

Parameter

ServerIdSpecifies the server identification of the server. For more details about the structure see "Layout of the ServerIdentifier structure" on page 22.

DeploymentServerSpecifies the host name or the IP address of the first LAN port of a deployment server.

DeploymentUsernameSpecifies the name of a user account for the specified deployment server. This parameter is mandatory.

DeploymentPasswordSpecifies the corresponding password for the specified user account on the deployment server. This parameter is mandatory.

42 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

ShutdownTypeSpecifies the reaction if the server is running:0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off1 (SHUTDOWNTYPE_ACPI)2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agents3 (SHUTDOWNTYPE_FORCE): for servers of type Blade force a power off by the management blade; for other server types do an ACPI power off.Default value: 0 (SHUTDOWNTYPE_NO)

ShutdownCommunitySpecifies the SNMP community for shutdown request towards ServerView SNMP agents running on the target server.

ShutdownUsernameSpecifies the user name for ServerView SNMP agents shutdown.Default value: ""

ShutdownPasswordSpecifies the corresponding password for the user indicated before.Default value = " "

FinalSeStAgentStatusSpecifies the status of the ServerStart agent Installation Manager agent and the power status of the server after the installation:1 (AGENTSTOP_OFF): ServerStart Installation Manager agent agent is not running and the server is power off2 (AGENTSTOP_REBOOT): ServerStart agent Installation Manager agent is not running and the server is rebooted3 (AGENTSTOP_KEEPRUNNING): ServerStart Installation Manager agent agent is kept runningDefault value: 1 (AGENTSTOP_OFF)


Job API Tandem 43



I If ShutdownType=2 specified, the parameters ShutdownType, ShutdownUsername, ShutdownPassword must be specified.

Return Value



JobIDA unique ID that can be used for GetJobStatusDetails to get more job details.

44 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.4.4 GetSystemInfoResult

The GetSystemInfoResult function supplies the system information in form of a XML document which are received by StartSystemInfoRetrieval. To receive the current system information, it is necessary to perform StartSystemInfoRetrieval before.

Syntax

GetSystemInfoResult ServerId=<ServerIdentifier> RDServer=<string> UserKey=<string>

Parameter




Return Value



ModificationDateDate of the last modification of the system information of the specified server (seconds since 1970).

SystemInfoDetailed system information of the specified server in XML format.

Job API Tandem 45


5.4.5 RdDeplServerList

In order to get a list of all available servers in the deployment table, Job API supports the function RdDeplServerList. This function is supported as long as the NodeList API is not released.

Syntax

RdDeplServerList RDServer=<string> UserKey=<string>

Parameter



Return Value



DeplServerListArray of structures of type DeplServer.

I The ServerView database is not accessed on every call to RdDeplServerList. There might be a delay of up to 2 minutes until changes in the ServerView database are updated in the Deployment Manager database and returned by RdDeplServerList.

46 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Layout of the returned list

The returned list of deployment server and their details will have the following layout. Depending on the type of the server only some of the fields will be meaningful.

ServerName=<string> ServerType=<int> SV_SystemName=<string>SV_IPAddress=<string> SV_IPAddress=<string>SV_Status=<string> SystemType=<string> Administrator=<string> Location=<string> MgmtServerName=<string> MgmtIPAddress=<string> MgmtSlot=<int> ServerModel=<string> CurrentImage=<string> NewImage=<string> DeploymentStatus=<string> MacAddress1=<string> IPAddress1=<string> NetMask1=<string> Gateway1=<string> MacAddress2=<string> IPAddress2=<string> NetMask2=<string> Gateway2=<string> MacAddress3=<string> IPAddress3=<string> NetMask3=<string> Gateway3=<string> MacAddress4=<string> IPAddress4=<string> NetMask4=<string> Gateway4=<string> UserKeyInfo=<string>

Job API Tandem 47


ServerNameDisplays the name of the server as specified in the deployment configuration. This need not be the same name than SV_SystemName below (OS hostname).

ServerTypeDisplays the type of the server:Server (ServerView)BladeServer (ServerView)Blade (ServerView)BareServer (Deployment Manager)If a server blade was entered as a server into the ServerView database, an entry with the same host name appears twice.

SV_SystemNameDisplays the system name from the ServerView database. This is probably the OS hostname if there already a running operating system installed on the server.

SV_IPAddressDisplays the IP address of the server which is specified in the associated ServerView database entry.

SV_StatusDisplays the status of the server inside of ServerView database:OKDegradedFaultsnmpOKRSB_ModeNot ManageableUnknownPing

SystemTypeDisplays the full description of the server type.

AdministratorDisplays the person who administrates the server.

LocationDisplays a detailed description of the location of the server.

MgmtServerNameDisplay the host name of the management blade from the blade server to which the specified server belongs to.

48 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

MgmtIPAddressDisplays SV_IPAddress of the management blade from the blade server to which the specified server belongs to (if the ServerType is Blade). Displays the IP address of the BMC if the ServerType is Server or BareServer and the server is manageable by Ipmi.

MgmtSlotDisplays the slot id of this blade inside the blade server (between 1 and 20).

ServerModelDisplays the standardized description of the Fujitsu server model (e.g. D1710, taken from full description S26361-D1710-A1)

CurrentImageDisplays the image name which is currently loaded.When the deployment status is cloned, the MasterImageReference in the deployment table is CurrentImage (and NewImage is ""), otherwise the MasterImageReference is NewImage (and CurrentImage contains the image name of the last cloned image).

NewImageDisplays the image name of the group, where the server is member (a server becomes a member of a group as soon as a cloning job is started).

DeploymentStatusDisplays the status of deployment:"" (blank)unknownnot clonedcloningclonedinstallinginstalled

MacAddress1Displays the physical address of the LAN port (interface) 1.

IPAddress1Displays the current IP address of LAN port (interface) 1. IPAddress1 is empty if DHCP is used.

NetMask1Displays the current net mask of LAN port (interface) 1. NetMask1 is empty if DHCP is used.

Job API Tandem 49


Gateway1Displays the current gateway of LAN port (interface) 1. Gateway1 is empty if DHCP is used.



NetMask2Displays the current net mask of LAN port (interface) 2. If DHCP is used NetMask2 is empty.

Gateway2Displays the current gateway of LAN port (interface) 2. If DHCP is used Gateway2 is empty.


IPAddress3Displays the current IP address of LAN port (interface) 3. IPAddress3 is empty if DHCP is used (future).

NetMask3Displays the current net mask of LAN port (interface) 3. If DHCP is used NetMask3 is empty (future).

Gateway3Displays the current gateway of LAN port (interface) 3. If DHCP is used Gateway3.



NetMask4Displays the current net mask of LAN port (interface) 4. If DHCP is used NetMask4 is empty.

Gateway4Displays the current gateway of LAN port (interface) 4. If DHCP is used Gateway4 is empty.

50 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

UserKeyInfoDisplays the info whether the server is either not reserved, reserved by itself or reserved by a foreign user. Possible values are:"" (blank)userkey_noneuserkey_ownuserkey_foreign

I This Job API function is supported as long as the NodeList API is not released. With the release of the NodeList API this function will become obsolete and will not be supported in future versions of Job API.

The number of interfaces is restricted to 4 now. As alternative ExportDeploymentConfiguration (see section "ExportDeploymentConfiguration" on page 53) can be used to export the information of all available interfaces.

Job API Tandem 51


5.4.6 ImportDeploymentConfiguration

Job API offers the function ImportDeploymentConfiguration to import one or more deployment configurations in form of a XML document which was created by a previous ExportDeploymentConfiguration run.

Syntax

ImportDeploymentConfiguration DeploymentConfiguration=<XML> Params=<ArrayOf_ParameterData> RDServer=<string> UserKey=<string>

Parameter

DeploymentConfigurationSpecifies the deployment table in form of an XML document.

ParamsSpecifies an array of structure of type ParameterData. For more details about available parameters see "Table of available parameter" on page 51 and about the parameter structure see "Layout of the ArrayOf_ParameterData structure" on page 23.



Table of available parameter


AddNonExistingBareServersEnables or disables the import of the deployment configuration of bare servers which do not exist in the server list.0 (OFF): means that the non existing bare servers in the server list will not be imported

52 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

1 (ON): means that the non existing bare servers in the server list will be importedDefault value: 0 (OFF)

MatchServerIdEnables or disables the import of the deployment configuration of servers whose server ID stored in the given deployment configuration also matches the server ID found in the server list.0 (OFF): means that the deployment configuration of servers whose server Id is identical with an existing server ID in the server list will not be imported.1 (ON): means that the deployment configuration of servers whose server id is identical with an existing server ID in the server list will be imported.Default value: 0 (OFF)

MatchSlotIdEnables or disables the import of the deployment configuration of server blades whose slot number stored in the deployment configuration also matches the slot number found in the server list.0 (OFF): means that the deployment configuration of server blades whose slot number is identical with an existing slot number in the server list will not be imported.1 (ON): means that the deployment configuration of server blades whose slot number is identical with an existing slot number in the server list will be imported.Default value: 0 (OFF)

Return Value



Job API Tandem 53


5.4.7 ExportDeploymentConfiguration

The ExportDeploymentConfiguration function exports the deployment configurations of the given servers in form of a XML document. If the indicated server is a management blade, all deployment configurations of existing blades are also returned.

Syntax

ExportDeploymentConfiguration ServerIdList=<Array of ServerIdentifier> Params=<ArrayOf_ParameterData> RDServer=<string> UserKey=<string>

Parameter

ServerIdListSpecifies an array of structures of type ServerIdentifier which contain MAC addresses, IP addresses or host names from a server in the server list. For the definition of this structure ServerIdentifier see "Layout of the ServerIdentifier structure" on page 22.

ParamsSpecifies an array of structure of type ParameterData. For more details about available parameters see "Table of available parameter" on page 54 and about the parameter structure see "Layout of the ArrayOf_ParameterData structure" on page 23.



54 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Table of available parameter

PasswordDecodedEnables or disables the decoding of passwords which are contained in the exported deployment configuration.0 (OFF): Passwords in encoded form1 (ON): Passwords in decoded formDefault value: 0 (OFF)

Return Value



DeploymentConfigurationDeployment configuration which exported in XML format.

Job API Tandem 55


5.4.8 SetUserKey

When a user has decided to reserve a server, the Job API function SetUserKey will mark the specified server or a list of server as reserved.

Please note, the reservation of the servers are applied exclusively with the indicated UserKey, i.e. loosing the UserKey means no possibility to unreserve the servers which are reserved by this lost UserKey.

Syntax

SetUserKey ServerList=<string> RDServer=<string> UserKey=<string>

Parameter

ServerListSpecifies a list of MAC addresses of different servers to be reserved, e.g. 00-C0-12-34-5F-67, 00-C0-A4-12-34-23.



Return Value



56 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.4.9 RemoveUserKey

This function removes available user reservation from the calling user of the specified servers.

Syntax

SetUserKey ServerList=<string> RDServer=<string> UserKey=<string>

Parameter

ServerListSpecifies a list of MAC addresses of servers, e.g. 00-C0-12-343-5F-67, 00-C0-A4-12-34-23.



Return Value



Job API Tandem 57

API function classes Power Management

5.5 Power Management

Over Job API the power status of the servers can be controlled. The following functions of the power management offer the possibility to power off or to power on server blades by the corresponding management blade and standalone servers directly by IPMI.

5.5.1 SetPower

SetPower does not require specific parameters like BMC IP address or BMC user name. The specific knowledge about how to power on or to power off a server must be configured and is known by the ServerView Deployment Manager service.

Syntax

SetPower ServerId=<ServerIdentifer> PowerStatus=<int> Params=<ArrayOf_ParameterData> RDServer=<string> UserKey=<string>

Parameter


PowerStatusSpecifies the status of the power switch:0 (POWERSTATUS_OFF)1 (POWERSTATUS_ON)

ParamsSpecifies an array of structure of type ParameterData. For more details about available parameters see "Table of available parameters to power off a server" on page 58 and "Table of available parameters to power on a server" on page 59 and about the parameter structure see "Layout of the ArrayOf_ParameterData structure" on page 23.

58 Job API Tandem

Power Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5



Table of available parameters to power off a server

The table contains the available parameters which can be specified in the array of parameters to set the power status of a server to power off.

ShutdownTypeSpecifies the type of shutdown:0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off1 (SHUTDOWNTYPE_ACPI)2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agents3 (SHUTDOWNTYPE_FORCE): for servers of type Blade force a power off by the management blade; for other server types do an ACPI power off.Default value: 0 (SHUTDOWNTYPE_NO)

ShutdownIpSpecifies the host name or IP address for the ServerView agents shutdown.This parameter is mandatory, if ShutdownType=2.

ShutdownCommunitySpecifies the community for SNMP access to the ServerView agents shutdown on the target system for shutdown access.This parameter is mandatory, if ShutdownType=2.

ShutdownUsernameSpecifies the name of a user account for ServerView agents shutdown.This parameter is mandatory, if ShutdownType=2.

ShutdownPasswordSpecifies the corresponding password for the specified user for ServerView agents shutdownThis parameter is mandatory, if ShutdownType=2.

Job API Tandem 59


TimeoutSpecifies the timeout in seconds for a request which is issued to the ServerView agent, to the management blade or to the BMC.Suggested value for Blades: 6Suggested value for BMC: 3

RetriesSpecifies the number of shutdown retries.Suggested value for Blades: 2Suggested value for BMC: 1

Table of available parameters to power on a server

The table contains the available parameters which can be specified in the array of parameters to power on a specified server.

BootModeSpecifies the boot mode:0 (BOOTMODE_NORMAL)1 (BOOTMODE_PXE)Default value: 0 (BOOTMODE_NORMAL)

ShutdownTypeSpecifies the type of shutdown:0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off1 (SHUTDOWNTYPE_ACPI)2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agents3 (SHUTDOWNTYPE_FORCE): for servers of type Blade force a power off by the management blade; for other server types do an ACPI power off.Default value: 0 (SHUTDOWNTYPE_NO)

ShutdownIpSpecifies the host name or IP address for the ServerView agents shutdown.This parameter is mandatory, if ShutdownType=2.

ShutdownCommunitySpecifies the community for SNMP access to the ServerView agents shutdown on the target system for shutdown access.This parameter is mandatory, if ShutdownType=2.

60 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

ShutdownPasswordSpecifies the corresponding password for the specified user for ServerView agents shutdownThis parameter is mandatory, if ShutdownType=2.

TimeoutSpecifies the timeout in seconds for a request which is issued to the ServerView agent, to the management blade or to the BMC.Suggested value for Blades: 6Suggested value for BMC: 3

RetriesSpecifies the number of shutdown retries.Suggested value for Blades: 2Suggested value for BMC: 1

Return Value



Job API Tandem 61


5.5.2 SetPXEBootImage

The SetPXEBootImage function can be used in order to register or unregister a boot image for a PXE client at the PXE service.

Syntax

SetPXEBootImage ServerId=<ServerIdentifer> BootImagePath=<string> BootImageType=<int> Params=<ArrayOf_ParameterData> DeploymentServer DeploymentUsername DeploymentPassword RDServer=<string> UserKey=<string>

Parameter

ServerIdSpecifies the server with a structure of type ServerIdentifier. If the server is specified by a MAC address, the PXE client will be exactly registered by the given MAC address. If it specifies by an IP address or host name, the PXE client will be registered by the MAC address which was registered in the deployment configuration as PXEBootInterface. For more details about the ServerIdentifer structure see "Layout of the ServerIdentifier structure" on page 22.

BootImagePathSpecifies s path including the name of the boot image relative to the root directory of the tftp server. For a DOS image this can be either a path relative to the root directory of the server or any absolute path in the file system. In case of an absolute path, the file is copied automatically to a temporary directory on the tftp server.

BootImageTypeSpecifies the type of the boot image:0 (BOOTIMAGETYPE_BOOTSTRAPIMAGE)1 (BOOTIMAGETYPE_DOSIMAGE)Default value: 0 (BOOTIMAGETYPE_BOOTSTRAPIMAGE)

62 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

ParamsSpecifies an array of structure of type ParameterData. For more details about available parameters see "Table of available parameters to register a boot image for a PXE client" on page 63 and "Table of available parameters to deregister a boot image for a PXE client" on page 63 and about the parameter structure see "Layout of the ArrayOf_ParameterData structure" on page 23.

DeploymentServerSpecifies the host name or the IP address of the first LAN port of a deployment server where the PXE service is running (must be the same than RDServer in this release).

DeploymentUsernameSpecifies a user account for the specified deployment server. This parameter is mandatory.




I Without specification of any parameters in the structure Params, the non-persistent registration will be done by default.

Job API Tandem 63


Table of available parameters to register a boot image for a PXE client


RegisterModeSpecifies a persistent or non-persistent registration of the specified PXE boot image.0 (REGISTER_NONPERSISTENT): to register the server at the PXE service for the next boot via PXE. After the execution of this one PXE boot, the server will be automatically deregistered at the PXE service (the boot image still keeps registered).1 (REGISTER_PERSISTENT): to register server persistent at the PXE serviceDefault value: 0 (REGISTER_NONPERSISTENT)

Table of available parameters to deregister a boot image for a PXE client


UnregisterModeSpecifies the mode of the unregistration. 1 (UNREGISTER_BOOTIMAGE_AND_CLIENT): to deregister the server from the given boot image and to deregister the boot image itself. (if no more other PXE clients are registered to this boot image). If the server is not registered (might occur when the server was registered in mode REGISTER_NONPERSISTENT and a PXE boot was already done), no error is returned and the boot image is deregistered (if no more other clients are registered to this boot image).

Return Value



64 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.5.3 GetPower

The GetPower function can be used to determine the current power status of a server.

Syntax

GetPower ServerId=<ServerIdentifer> Params=<ArrayOf_ParameterData> RDServer=<string> UserKey=<string>

Parameter

ServerIdSpecifies the MAC address of a server with a structure of type ServerIdentifier. For more details see "Layout of the ServerIdentifier structure" on page 22.




Job API Tandem 65




TimeoutSpecifies the timeout in seconds for a request which is issued to the management blade.Suggested value: 6

RetriesSpecifies the number of SNMP retries.Suggested value: 2

Return Value



PowerStatusReturns the current power status:0 (POWERSTATUS_OFF)1 (POWERSTATUS_ON)

66 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.5.4 GetBootMode

The GetBootMode function is useful to retrieve the current boot mode of a specified server via MAC address. Based on the system type information Job API can directly check if the function is managed by management blade or by BMC via IPMI.

Syntax

GetBootMode ServerId=<ServerIdentifer> RDServer=<string> UserKey=<string>

Parameter

ServerIdSpecifies the MAC address of a server with a structure of type ServerIdentifier. For more details see "Layout of the ServerIdentifier structure" on page 22.



Job API Tandem 67


Return Value



BootModeReturns the boot mode:0 (BOOTMODE_NORMAL)1 (BOOTMODE_PXE)

68 Job API Tandem

Repository Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.6 Repository Management

A repository is kind of container (share directory on a Window server) that can be accessed by the services Deployment Service and ServerView Deployment Manager. A repository can be subdivided in multiple directories as well as sub-directories. But in principle a repository and its directories are used in Deployment Manager to store images.

Images are the focal point of interest within Deployment Manager also as in Job API. Basically an image is in the IT a kind of copy of a hard disk, a partition or a CD. Inside of Job API image creation means to create an image from a fully installed and configured system, i.e. the image contains the configuration information on the reference system, e.g. on the hard disk, on an attached storage area, the configuration of the partitions, and all data of the operating system. Therefore an image can be used as a reference image to deploy multiple target systems.

Please note the new version of Job API offers a new generic function CreateImage. This function allows the image creation of all supported image types, i.e. CreateImage also offers the creation of snapshot images.

In principle there are different types of images which are stored therefore also into repositories of different types. In following all repository types are listed which are supported by Job API in the current version:

– Cloning ImagesThese are repositories which contain all disk image files which can be created via Job API or Deployment Manager and are used for the cloning execution.

– Boot ImagesA repository of boot images is a directory containing PXE boot images which were created in order to make a generic system preparation.

– Installation ConfigurationA repository of installation configuration files is a directory with sub-directories where installation configuration files stored. These installation configuration files must be created by Installation Manager.

– Deployment TableThe deployment table repository contains XML files which are exported with the Deployment Manager front-end function Export Deployment Configuration.

Job API Tandem 69

API function classes Repository Management

Example

Each image object in the repository refers to a set of files with identical but different extensions:

– Binary cloning image file (.img)

This file contains a copy of a hard disk (URL on a storage place somewhere in the net).

– Image documentation (.txt)

This file could be used for describing an image, e.g. reference on a text document which is created during the image creation.

– Hardware / operation system parameter file (.cfg)

This information is used for later modification of an existing image and for a compatibility check to the assigned target HW.

– Remote Mass Installation File (.xml)

This configuration file is created by the Installation Manager Wizards (e.g. in Preparation Mode).

The next subsections contain all repository functions which are used to add new repositories, remove needless repositories and get a list of all known repositories. Additionally JobAPI still offers functions, in order to handle in a repository contained images and/or to create new images.

70 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.6.1 AddRepository

In order to add a repository it is mandatory to specify a symbolic name that will be used in Job API to identify the repository and a path name. In general the path name should be the network path to a shared directory (UNC notation). It is also possible that this is the absolute path to a local directory and not a network path, but this requires that the services ServerView Deployment Manager and Deployment Service are installed on the same machine. If this is not the case it must be the network path to a share in UNC notation: \\server_name\share_name

Syntax

AddRepository RepositoryName=<string> RepositoryType=<int> NetworkPath=<string> RDServer=<string> UserKey=<string>

Parameter

RepositoryNameSpecifies the name of the new repository.

RepositoryTypeSpecifies the type of the new repository:1 (REPOSITORYTYPE_CLONING_IMAGE)2 (REPOSITORYTYPE_BOOT_IMAGE)3 (REPOSITORYTYPE_CONFIG_FILE)4 (REPOSITORYTYPE_DEPLOYMENT_TABLE)Default value: 1 (REPOSITORYTYPE_CLONING_IMAGE)

NetworkPathSpecifies a full-qualified network path in UNC format, which contains later the corresponding image files.



Job API Tandem 71


Return Value



72 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.6.2 RemoveRepository

The RemoveRepository function can be used to remove needless repositories. Therefore it is mandatory to specify a symbolic name of an existing repository, the deployment server and a unique user key which identifies a user account.

Syntax

RemoveRepository RepositoryName=<string> RDServer=<string> UserKey=<string>

Parameter

RepositoryNameSpecifies the name of the repository to remove.



Return Value



I With this function image objects are not removed, but the entry in the repository list.

Job API Tandem 73


5.6.3 GetRepositoryList

The GetRepositoryList function returns information about all known repositories. In order to view the existing repositories for each type select the corresponding repository type or 0 (ALL) for all types.

Syntax

GetRepositoryList RepositoryType=<ServerIdentifer> RDServer=<string> UserKey=<string>

Parameter

RepositoryTypeSpecifies the type of the repositories to get the information:0 (ALL)1 (REPOSITORYTYPE_CLONING_IMAGE)2 (REPOSITORYTYPE_BOOT_IMAGE)3 (REPOSITORYTYPE_CONFIG_FILE)4 (REPOSITORYTYPE_DEPLOYMENT_TABLE)Default value: 0 (ALL)



74 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



RepositoryListReturns an array of structures of type RepositoryData.


The returned list of repository and their details will have the following layout.

RepositoryName=<string> RepositoryType=<int> NetworkPath=<string>

RepositoryNameDisplays the name of the repository.

RepositoryTypeDisplays the type of the repository:1 (REPOSITORYTYPE_CLONING_IMAGE)2 (REPOSITORYTYPE_BOOT_IMAGE)3 (REPOSITORYTYPE_CONFIG_FILE)4 (REPOSITORYTYPE_DEPLOYMENT_TABLE)

NetworkPathDisplays the network path in UNC format.

Job API Tandem 75


5.6.4 CreateImage

The CreateImage function allows the creation of cloning images and snapshot images. These images can be used to deploy to multiple servers (with individualization based on the deployment table). The parameter ImageType selects the type of the generated image. The parameter Params contains a list of image creation parameter and is interpreted depending on the ImageType. CreateImage starts the image creation and returns a job ID. This job ID can be used as input to subsequent calls of GetJobStatusDetails.

Syntax

CreateImage ServerId=<int> ImagePath=<string> ImageType=<int> InfoText=<string> Params=<ArrayOf_ParameterData> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> RDServer=<string> UserKey=<string>

Parameter

ServerIdSpecifies the MAC address of the target server blade with a structure of type ServerIdentifier. For more details see "Layout of the ServerIdentifier structure" on page 22.

ImagePathSpecifies a full-qualified path including the name of the image

ImageTypeSpecifies the type of the image:1 (IMAGETYPE_CLONING)2 (IMAGETYPE_SNAPSHOT)

InfoTextSpecifies any information to be saved with the image. It will be stored in the file with the suffix .txt.

76 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

ParamsSpecifies an array of structure of type ParameterData. For more details about the parameter structure see "Layout of the ArrayOf_ParameterData structure" on page 23 and for available parameters see "Table of all available parameters to create a cloning image" on page 77 and "Table of all available parameters to create a snapshot image" on page 80.


DeploymentUsernameSpecifies the name of a user account for the specified deployment server.

DeploymentPasswordSpecifies the corresponding password for the specified user account on the deployment server.



I In case of ShutdownType=3 and a server without IPMI is specified, this function returns a successful execution because the user must accomplish a shutdown manually.

Job API Tandem 77


Table of all available parameters to create a cloning image

The following table of parameters contains specific names and values which can specified in the array of Params to create an image of type IMAGETYPE_CLONING.

SaveModeSpecifies the save mode during the image creation of hard disks:0 (SAVEMODE_FILESYSTEM_DEPENDENT): save only used sectors in the partitions1 (SAVEMODE_FILESYSTEM_INDEPENDENT): save all sectors in the partitions2 (SAVEMODE_RAW): save the full diskDefault value: 0 (SAVEMODE_FILESYSTEM_DEPENDENT)

ShutdownTypeSpecifies the reaction if the server is running0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off1 (SHUTDOWNTYPE_ACPI): 2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agentsDefault value: 0 (SHUTDOWNTYPE_NO)

ShutdownUsernameSpecifies the name of a user account for a ServerView agents shutdown.This parameter is mandatory, if ShutdownType=2.Default value: ""

ShutdownPasswordSpecifies the corresponding password for the user indicated before.This parameter is mandatory, if ShutdownType=2.Default value: ""

FinalPowerStatusSpecifies the power status of the server after image generation.0 (FINALPOWERSTATUS_OFF): the server is powered off 1 (FINALPOWERSTATUS_ON): the installed operating system is bootedThis parameter allows to choose whether the server operating system should be booted or whether the server should be powered off after image generation. Default value: 0 (FINALPOWERSTATUS_OFF)

78 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

OSSpecifies one of the supported operating systems:Windows: to create a cloning image from a Windows 2000 or 2003 systemWindows2008: to create a cloning image from a Windows 2008 systemLinux: to create a cloning image from a Linux systemThis parameter is mandatory.

LinuxConfigLocationSpecifies the location of the /etc directory of the system from which the image is created. This parameter applies only and is mandatory when selected Linux as operating system.

WindowsAdminNameSpecifies the name of the login with administrator rights for the operating system WINDOWS (Windows-dependent).This parameter applies only when selected Windows or Windows2008 as operating system.Default value: ""This must be a local administrator account on the reference system. If the deployment server or the reference system are member of a domain, please specify this parameter in the form <hostname>\administrator or <IP address>\administrator.

WindowsAdminPasswordSpecifies the corresponding password for the admin user indicated before.This parameter applies only when selected Windows or Windows2008 as operating system.Default value: ""

WindowsProductIDSpecifies the ProductID of the reference system.This parameter applies only when selected Windows (mandatory) or Windows2008 (optional) as operating system.Default value: ""

LogicalDiskSpecifies the logical disk.Default value: 0

VerifyVerify file-system before backup0: (OFF)1: (ON)Default value: 1 (ON)

Job API Tandem 79


CompressPerform compression:0: (OFF)1: (ON)Default value: 1 (ON)

UnknownFailSpecifies the reaction in conjunction with SaveMode=SAVEMODE_FILESYSTEM_DEPENDENT, if an unknown file system is recognized.0 (OFF): function process is continued1 (ON): function process is failed with errorDefault value: 0 (OFF)

FastModeUsed only for the creation of a Linux cloning image. Specifies the optimization of the image creation of ext2/ext3 file systems.0 (OFF): disable fast image creation1 (ON): enable fast image creationPlease be aware optimized produced images can not be cloned with enabled ExpandLastPartition (see Deploy).Default value: 0 (OFF)

ServerAccessDataThis parameter applies only when selected Windows or Windows2008 as operating system. This parameter might contain an IP address or a host name (full-qualified names are allowed), that is used to access the windows system during system preparation. If this parameter is empty, the server name from deployment configuration is used.Default value: ""

80 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

InstallationLocaleAvailable only for Windows 2008.This parameter must be supplied when the reference system was installed from a "Fujitsu OEM" DVD (a "Multi Language" DVD). Do not supply this parameter for a "Microsoft" DVD ("Single Language").Default value: ""Possible values:English (United States)German (Germany)Japanese (Japan)French (France)Spanish (Spain)Italian (Italy)Dutch (Netherlands)Portuguese (Portugal)Portuguese (Brazil)Czech (Czech Republic)Polish (Poland)Russian (Russia)Swedish (Sweden)Hungarian (Hungary)Turkish (Turkey)Korean (Korea)Chinese (PRC)

Table of all available parameters to create a snapshot image

The following table of parameters contains specific names and values which can specified in the array of Params to create an image of type IMAGETYPE_SNAPSHOT.

SaveModeSpecifies the save mode during the image creation of hard disks:0 (SAVEMODE_FILESYSTEM_DEPENDENT): save only used sectors in the partitions1 (SAVEMODE_FILESYSTEM_INDEPENDENT): save all sectors in the partitions2 (SAVEMODE_RAW): save the full diskDefault value: 0 (SAVEMODE_FILESYSTEM_DEPENDENT)

Job API Tandem 81


ShutdownTypeSpecifies the reaction if the server is running0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off1 (SHUTDOWNTYPE_ACPI): 2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agents Default value: 0 (SHUTDOWNTYPE_NO)

ShutdownUsernameSpecifies the name of a user account for a ServerView agents shutdown.This parameter is mandatory, if ShutdownType=2 (SHUTDOWNTYPE_GRACEFUL).Default value: ""

ShutdownPasswordSpecifies the corresponding password for the user indicated before.This parameter is mandatory, if ShutdownType=2.Default value: ""

FinalPowerStatusSpecifies the power status of the server after image generation.0 (FINALPOWERSTATUS_OFF): the server is powered off 1 (FINALPOWERSTATUS_ON): the installed operating system is bootedThis parameter allows to choose whether the server operating system should be booted or whether the server should be powered off after image generation. Default value: 0 (FINALPOWERSTATUS_OFF)

LogicalDiskSpecifies the logical disk.Default value: 0

VerifyVerify file-system before backup0: (OFF)1: (ON)Default value: 1 (ON)

CompressPerform compression0: (OFF)1: (ON)Default value: 1 (ON)

82 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



JobIDReturns a unique ID that can be used for GetJobStatusDetails to get more details.

Job API Tandem 83


5.6.5 DeleteImage

The DeleteImage function deletes a specified image file.

Syntax

DeleteImage Imagefilename=<string> RepositoryName=<string> SubPath=<string> RDServer=<string> UserKey=<string>

Parameter

ImagefilenameSpecifies the name of the image to delete.

RepositoryNameSpecifies the name of the repository which contains the image.

SubPathSpecifies a full-qualified subpath relative to the specified repository which contains the image to delete.Default value: ""



Return Value



84 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.6.6 GetRepositoryContents

The GetRepositoryContents function can be used to get a list of image file names that have been found in a specified repository or in all repositories of a specified type.

Syntax

GetRepositoryContents RepositoryName=<string> RepositoryType=<int> RDServer=<string> UserKey=<string>

Parameter

RepositoryNameSpecifies the name of the repository. If no RepositoryName is specified, the content of all available repositories of the specified type are delivered. Default value: ""

RepositoryTypeSpecifies the type of the repository:0 (ALL)1 (REPOSITORYTYPE_CLONING_IMAGE)2 (REPOSITORYTYPE_BOOT_IMAGE)3 (REPOSITORYTYPE_CONFIG_FILE)4 (REPOSITORYTYPE_DEPLOYMENT_TABLE)Default value: 0 (ALL)



Job API Tandem 85


Return Value



FilenameListReturns an array of image file names.

86 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.6.7 ReadImagefilenameList

The ReadImagefilenameList function returns an array of image file names that have been found in all known Deployment Manager repositories.

Syntax

ReadImagefilenameList RDServer=<string> UserKey=<string>

Parameter



Return Value



FilenameListReturns an array of image file names.

Job API Tandem 87


5.6.8 ReadImageInfoText

The ReadImageInfoText function retrieves the image documentation that was given during the call to the function CreateImage.

Syntax

ReadImageInfoText ImagePath=<string> RDServer=<string> UserKey=<string>

Parameter

ImagePathSpecifies a full-qualified path including the name of the image.



Return Value



InfoTextReturns the image documentation.

88 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.6.9 GetImageProperties

The GetImageProperties function returns the properties of a specified image which was generated during the call to the function CreateImage or defined by the function SetImageProperties.

Syntax

GetImageProperties ImagePath=<string> RDServer=<string> UserKey=<string>

Parameter

ImagePathSpecifies a full-qualified path including the name of the image.



Return Value



ImageProperties Returns the configuration of the image in form of a XML document.

Job API Tandem 89

API function classes Directory Management

5.7 Directory Management

As mentioned above existing repositories can have multiple directories as well as sub-directories. This section describes all Job API functions to manage directories inside of repositories.

5.7.1 CreateDirectory

The CreateDirectory function creates a new directory in the specified repository.

Syntax

CreateDirectory DirectoryName=<string> RepositoryName=<string> SubPath=<string> RDServer=<string> UserKey=<string>

Parameter

DirectoryNameSpecifies the name of the new directory.

RepositoryNameSpecifies the name of the repository which contains the new directory.

SubPathSpecifies a partially-qualified path to the new directory relative to the specified repository.Default value: ""



90 Job API Tandem

Directory Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



Job API Tandem 91


5.7.2 DeleteDirectory

The DeleteDirectory function completely removes the specified directory in the given repository. If the directory is not empty all files (image files) and sub-directories are removed first.

Syntax

DeleteDirectory DirectoryName=<string> RepositoryName=<string> SubPath=<string> RDServer=<string> UserKey=<string>

Parameter

DirectoryNameSpecifies the name of the directory to delete.

RepositoryNameSpecifies the name of the repository which contains the specified directory.

SubPathSpecifies the partially-qualified path to the specified directory relative to the repository.Default value: ""



92 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



Job API Tandem 93


5.7.3 GetDirectoryContents

The GetDirectoryContents function retrieves the list of all known files and sub-directories in the specified directory.

Syntax

GetDirectoryContents DirectoryName=<string> RepositoryName=<string> SubPath=<string> RDServer=<string> UserKey=<string>

Parameter

DirectoryNameSpecifies the name of the directory.

RepositoryNameSpecifies the name of the repository.

SubPathSpecifies the partially-qualified path to the specified directory relative to the specified repository.Default value: ""



94 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



FileListReturns an array of FileData names.


Name=<string> Type=<int> Size=<int> ModificationDate=<long>

NameDisplays the name of the file.

TypeDisplays the type of the file0 (FILETYPE_DIRECTORY)1 (FILETYPE_INSTALLATION_CONFIG)2 (FILETYPE_CLONING_IMAGE)3 (FILETYPE_OTHER)

SizeDisplays the size of the file.

ModificationDateDisplays the date of the last modification.

Job API Tandem 95

API function classes Group Management

5.8 Group Management

In the sense of mass deployment many server will be deployed parallel with nearly identical configuration. To minimize the effort it is helpful to organize servers with the same or similar configuration to one group, i.e. a group means generally a named collection of group members with same as well as individual properties.

Job API supports two different types of group assignments, 1:N and N:N group properties assignment. In the case of 1:N properties assignment the specified group properties are assigned to each server in the group. However, in the case of N:N assignment each server in the group are directly assigned the properties via the function SetGroupMemberProperties and specified group properties are not considered.

Additional it is also possible to create groups inside of groups. Thus created sub-groups make a further refinement for a grouping possible.

96 Job API Tandem

Group Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.8.1 CreateGroup

The CreateGroup function produces a group of the accordingly specified type of group (GroupType). Independent of the group type the newly created group is empty and has no specific group properties. After a successful group creation a unique group identifier (GroupID) is returned. This GroupID is used in other group functions to identify existing groups.

Syntax

CreateGroup GroupName=<string> GroupType=<int> ParentGroupID=<int> RDServer=<string> UserKey=<string>

Parameter

GroupNameSpecifies the name of a new group.

GroupTypeSpecifies the type of the group:2 (GROUPTYPE_CLONING)3 (GROUPTYPE_INSTALLATION)This parameter is always mandatory.

ParentGroupIDSpecifies the identifier of an existing group in order to create a new sub-group.Default value: 0

I In the current version of Job API the ParentGroupID can not be specified, i.e. this parameter is not evaluated. Therefore the creation of sub-groups is not possible in the current version.


Job API Tandem 97



Return Value



GroupIDReturns a unique group identifier for the new group entry.

98 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.8.2 DeleteGroup

In order to delete an existing group use the function DeleteGroup. If the specified group is not empty all group members are removed first. Removing of the group members results in appropriate calls of the function RemoveGroupMember of the Job API.

Syntax

DeleteGroup GroupID=<int> RDServer=<string> UserKey=<string>

Parameter

GroupIDSpecifies a group entry to delete.



Return Value



Job API Tandem 99


5.8.3 GetGroupList

The GetGroupList function lists all known groups. The range of the returned list can be limited by the selection of one specific GroupType.

Syntax

GetGroupList GroupType=<int> RDServer=<string> UserKey=<string>

Parameter

GroupTypeSpecifies the type of the groups to get the information.0 (ALL)2 (GROUPTYPE_CLONING)3 (GROUPTYPE_INSTALLATION)Default value: 0 (ALL)



Return Value



GroupListAn array of structures of type GroupData.

100 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5


GroupID=<int> GroupName=<string> GroupType=<int>

GroupIDDisplays the group identifier of the group.

GroupNameDisplays the name of the group.

GroupTypeDisplays the type of the group:2 (GROUPTYPE_CLONING)3 (GROUPTYPE_INSTALLATION)

Job API Tandem 101


5.8.4 SetGroupProperties

The SetGroupProperties function enables the setting and the modifying of group properties of an existing group. Therefore it is necessary to identify a valid group identifier which is returned by the function GetGroupList.

Syntax

SetGroupProperties GroupID=<int> GroupProperties=<ArrayOf_PropertyData> RDServer=<string> UserKey=<string>

Parameter

GroupIDSpecifies the group identifier of an existing group.

GroupPropertiesSpecifies an array of structure of type PropertyData which contains the available properties of a group, see "Layout of the ArrayOf_PropertyData structure" on page 22.



Return Value



102 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Layout of group properties


NameSpecifies a known name of a group property.

ValueSpecifies the value of the specified property.

Table of Cloning group properties

ImagePathSpecifies the full-qualified path including the name of the image.

Job API Tandem 103


5.8.5 GetGroupProperties

The GetGroupMemberProperties function just returns the list of properties for the specified member and the specified GroupID.

Syntax

GetGroupProperties GroupID=<int> RDServer=<string> UserKey=<string>

Parameter

GroupIDSpecifies the identifier of an existing group.



Return Value



GroupNameReturns the name of the group.

GroupTypeReturns the type of the group:2 (GROUPTYPE_CLONING)3 (GROUPTYPE_INSTALLATION)

104 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

GroupPropertiesReturns an array of structure of type PropertyData. For more details see "Layout of group properties" on page 102 and "Table of Cloning group properties" on page 102.

Job API Tandem 105


5.8.6 AddGroupMember

The AddGroupMember function adds new group member to the specified group. In the current Job API version a group member can be a server which is identified by its MAC, IP address or host name (MemberId).

Syntax

AddGroupMember MemberIdList=<ArrayOf_MemberIdentifier> GroupID=<int> RDServer=<string> UserKey=<string>

Parameter

MemberIdListSpecifies one or a list of new group members. For more details about the structure of MemberIdentifier see "Layout of the MemberIdentifier structure" on page 106.

GroupIDSpecifies the group in which the new member is added.



I If one specified member in the MemberIdList can not added into the specified group, the function failed and none of the specified members were added.

106 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



Layout of the MemberIdentifier structure

In order to identify a member the user can select between several types of identifier, e.g. MAC address, IP address, host name or other. The following structure allows the member identification by the specified types.


IdentifierSpecifies a string contained a distinctive identifier of a member.

TypeSpecifies the type of the specified member identifier0 (IDENTIFIERTYPE_MAC): physical address of network interface1 (IDENTIFIERTPE_IP): IP address of the serverThis must be the SV_IPAddress field returned by RdDeplServerList.2 (IDENTIFIERTYPE_NAME): host name of the serverThis must be the ServerName field returned by RdDeplServerList.

Job API Tandem 107


5.8.7 RemoveGroupMember

The RemoveGroupMember function removes the specified group member from the given group. The group itself is not deleted.

Syntax

RemoveGroupMember MemberId=<MemberIdentifier> GroupID=<int> RDServer=<string> UserKey=<string>

Parameter

MemberIdSpecifies the group member which will be removed.For more details about the structure of MemberIdentifier see "Layout of the MemberIdentifier structure" on page 106.

GroupIDSpecifies the GroupID from a previous CreateGroup call.



Return Value



108 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.8.8 GetGroupMemberList

The GetGroupMemberProperties function just returns the list of properties for the specified member and the given group via GroupID.

Syntax

GetGroupMemberList GroupID=<int> MemberIdType=<int> RDServer=<string> UserKey=<string>

Parameter

GroupIDSpecifies the known group whose members are returned.

MemberIdTypeSpecifies which member identifier type of the returned members is used.0 (IDENTIFIERTYPE_MAC): physical address of first network interface1 (IDENTIFIERTYPE_IP): IP address of the server2 (IDENTIFIERTYPE_NAME): host name of the server. If the specified identifier is empty, another type of identifier will be returned.Default value: 0 (IDENTIFIERTYPE_MAC)



Job API Tandem 109


Return Value



MemberListReturns an array of structure of MemberIdentifier.


The returned list of repository and their details will have the following layout:


IdentifierDisplays a string contained a distinctive identifier of a member.

TypeDisplays dependent on the setting of parameter MemberIdType the identifier type of the member0 (IDENTIFIERTYPE_MAC): physical address of network interface1 (IDENTIFIERTYPE_IP): IP address of the server2 (IDENTIFIERTYPE_NAME): host name of the server3 (IDENTIFIERTYPE_GROUPID): group ID

110 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.8.9 SetGroupMemberProperties

With the SetGroupMemberProperties function each property of the group members can be set. The definition of the arbitrary list of properties is done by specifying an array of type PropertyData (name / value pair). The specified properties are only specific for the group member (server) in this group.

Syntax

SetGroupMemberProperties MemberId=<MemberIdentifier> GroupID=<int> GroupMemberProperties=<ArrayOf_PropertyData> RDServer=<string> UserKey=<string>

Parameter

MemberIdSpecifies the identifier of the group member. For more details about the structure of MemberIdentifier see "Layout of the MemberIdentifier structure" on page 106.

GroupIDSpecifies the identifier of an existing group.

GroupMemberPropertiesSpecifies an array of the structure of type PropertyData. For more details about the structure see "Layout of group member properties" on page 111.



Job API Tandem 111


Return Value



Layout of group member properties


NameSpecifies a known name of a group member property.

ValueSpecifies the value of the specified group member.

Table of the installation group members properties

ConfigPathSpecifies the full-qualified path including the name of the configuration name which is defined by Installation Manager.

112 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.8.10 GetGroupMemberProperties

In order to get the properties of a given group member the function GetGroupMember can be used to list the properties of the group member.

Syntax

GetGroupMemberProperties MemberId=<MemberIdentifier> GroupID=<int> RDServer=<string> UserKey=<string>

Parameter

MemberIdSpecifies the identifier of the group member. For more details about the structure of MemberIdentifier see "Layout of the MemberIdentifier structure" on page 106

GroupIDSpecifies the identifier of the group.



Job API Tandem 113


Return Value



GroupMemberPropertiesReturns an array of the structure of type PropertyData. For more details see "Layout of group member properties" on page 111 and "Table of the installation group members properties" on page 111.

114 Job API Tandem

Deployment Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.9 Deployment Management

In principle JobAPI provides several procedures for deployment:

– Cloning

Cloning means to install a reference system, create an image file of that reference installation (see image creation), and clone this image file to a group of servers to be installed with the same configuration parameters.

– Mass remote installation

Mass remote installation means to use configuration files created with Installation Manager, assign them to servers or server groups, and then start the installation for all servers.

Job API Tandem 115

API function classes Deployment Management

5.9.1 Deploy

The function Deploy allows to manage the deployment of all server in a group, one specified server or a list of servers in a group. The generally accepted parameters, e.g. DeplomentServer, must be supplied in the usual manner. Additionally further parameters can be specified over the array of the parameter structure (ParameterData). The list of all known parameters is dependent of the type of the group and is described in the following sub sections.

The function Deploy will start a new job and returns a job ID. This job ID can be used as input to subsequent calls of GetJobStatusDetails.

To simplify the deployment of one single server, Job API distinguishes between two deploy modes:

– Single server modeThis mode can be activated by the specification of GroupID=0 and only one server in ServerIdList. Therefore only this given single server will be deployed and no group management is necessary.

– Group modeThe group mode will be useful to deploy more than one server with only one accomplishing Deploy function. Therefore an appropriate group with contained servers must be configured by the group management before the execution of the deployment. Additionally, a given group can be reduced on given servers specified via ServerIdList.

I For this function Installation Manager is required, if cloning with Deployment Platform WinPE MDP or an installation should be done.

116 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Syntax

Deploy GroupID=<int> ServerIdList=<ArrayOf_ServerIdentifier> Params=<ArrayOf_ParameterData> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> RDServer=<string> UserKey=<string>

Parameter

GroupIDSpecifies an identifier of an existing group or 0 for single server selection mode.

ServerIdListSpecifies a list of servers to define a temporary subgroup out of the selected group. If no servers are specified, this function will apply to all servers of the group. To specify the servers use an array of structures of type ServerIdentifier. For the definition of this structure see "Layout of the ServerIdentifier structure" on page 22.

ParamsSpecifies an array of structures of type ParameterData. For more details about the structure see "Layout of the ArrayOf_ParameterData structure" on page 23 and the available parameters see "Table of available parameters for cloning" on page 117 and "Table of available parameters for installing" on page 123.


DeploymentUsernameSpecifies the name of a user account for the specified deployment server.

DeploymentPasswordSpecifies the corresponding password for the specified user account on the deployment server.

Job API Tandem 117




I In case of ShutdownType=3 and a server without IPMI is specified, this function returns a successful execution because the user must accomplish a shutdown manually.

Table of available parameters for cloning

The table contains the available parameters which can be specified in the array of parameter to perform the deployment method cloning.

ImagePathSpecifies a full-qualified path including the image name.This parameter is mandatory in the single server selection mode.

PreparationModeSpecifies the preparation mode:1 (PREPARATIONMODE_BLADEOPTIMIZED): 2 (PREPARATIONMODE_ALLPRIMERGY): 3 (PREPARATIONMODE_GENERICBOOTIMAGE): 4 (PREPARATIONMODE_MANUAL): This parameter is mandatory.1 (PREPARATIONMODE_BLADEOPTIMIZED) is obsolete and should only be used for legacy blade BX300. In this case Deployment Platform Caldera DOS will be used. For all other blades please use 2 (PREPARATIONMODE_ALLPRIMERGY). In this case Deployment Platform WinPE MDP will be used (if not specified different in deployment configuration).

BootImageSpecifies the full-qualified path where the selected boot image is stored.This parameter can only be used and is mandatory when PreparationMode is 3 (PREPARATIONMODE_GENERICBOOTIMAGE).

118 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

BootImageTypeSpecifies the boot image type:0 (BOOTIMAGETYPE_BOOTSTRAPIMAGE): boot image consists of multiple parts, whereby the first part is PXE booted and requests the rest by tftp download1 (BOOTIMAGETYPE_DOSIMAGE): boot image is a "virtual" floppy image (1 file of size 1.4 MB)This parameter can only be used when PreparationMode is 3 (PREPARATIONMODE_GENERICBOOTIMAGE).Default value: BOOTSTRAPIMAGE

ControllerVendorSpecifies the controller vendor.·LSI/Mylex Raid ControllerAdaptec Raid ControllerPromise Raid ControllerAny Raid Controller (only for deployment platform WinPE MDP)Fujitsu Raid Controller (only for deployment platform WinPE MDP)The possible values for ControllerVendor/ControllerFamily/ControllerName/RaidType are defined by Installation Manager (see file RaidDef.xml).It is sufficient to only specify the ControllerVendor and omit ControllerFamily and ControllerName. You can specify one or both of these two parameters when there are multiple controllers of the same vendor, but with different family or name, in your machine, and you want to specify which one exactly to use.This parameter can only be used and is mandatory when PreparationMode is 2 (PREPARATIONMODE_ALLPRIMERGY).

ControllerFamilySpecifies the controller family.This parameter can only be used when PreparationMode is 2 (PREPARATIONMODE_ALLPRIMERGY).Default value: ""

ControllerNameSpecifies the name of the controller.This parameter can only be used when PreparationMode is 2 (PREPARATIONMODE_ALLPRIMERGY).Default value: ""

Job API Tandem 119


ControllerNumberSpecifies the logical controller number as defined in the system (based on the selection by vendor/family/name given).This parameter can only be used when PreparationMode is 2 (REPARATIONMODE_ALLPRIMERGY).Default value: 0

RaidTypeSpecifies the Raid configuration. This parameter is optional.If PreparationMode is 1 (PREPARATIONMODE_BLADEOPTIMIZED):-1 (RaidType unchanged): no raid configuration is done0 (RaidType_0)1 (RaidType_1)2000 (RaidType_2_Raid0_Arrays)Default value: 0 (RaidType_0)

If PreparationMode is 2 (PREPARATIONMODE_ALLPRIMERGY):The possible values are defined by Installation Manager (see file RaidDef.xml).If the parameter is not given, Automatic Mode is assumed. If the parameter is given, Manual Mode is assumed and the optional parameters DiskNumber and HotSpare can be given in addition.

RaidInitSpecifies the initialization of the specified raid configuration:0 (RAIDINIT_OFF)1 (RAIDINIT_ON)Default value: 0 (RAIDINIT_OFF)This parameter can only be used when PreparationMode is 1 (PREPARATIONMODE_BLADEOPTIMIZED).

DiskNumberSpecifies the number of disks (0 means all disks).Default value: 0This parameter can only be used, if PreparationMode is 2 (PREPARATIONMODE_ALLPRIMERGY) and parameter RaidType has been given.

HotSpareSpecifies a standby hard disk which can be used to replace a defective hard disk.Default value: 0

120 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

This parameter can only be used, if PreparationMode is 2 (PREPARATIONMODE_ALLPRIMERGY) and parameter RaidType has been given.

ShutdownTypeSpecifies the reaction if the server is running:0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off1 (SHUTDOWNTYPE_ACPI): 2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agents 3 (SHUTDOWNTYPE_FORCE): for servers of type Blade force a power off by the management blade; for other server types do an ACPI power off.Default value: 0 (SHUTDOWNTYPE_NO)

ShutdownCommunitySpecifies the SNMP community for shutdown request towards ServerView SNMP agents running on the target server. Default value: ""

ShutdownUsernameSpecifies the user name for ServerView SNMP agents shutdown.This parameter is mandatory, if ShutdownType=2 (graceful) is specified.Default value: ""

ShutdownPasswordSpecifies the corresponding password for the user indicated before.This parameter is mandatory, if ShutdownType=2 (graceful) is specified.Default value: ""

FinalPowerStatusSpecifies the power status after cloning:0 (FINALPOWERSTATUS_OFF)1 (FINALPOWERSTATUS_ON)Default value: 0 (FINALPOWERSTATUS_OFF)

CustomScriptCmdlineSpecifies a script produced by the customer that should be executed after cloning.For Windows target systems the path name should be the network path name of the script in UNC notification. This means, it should be used a network share where the script was stored. For this script it can be also specified optional parameters.For Linux target systems the path name has the format

Job API Tandem 121


\\<server>\<path>\script_name [parameters] or //<server>/<path>/script_name [parameters]Default value: ""

CustomScriptUsernameSpecifies account information which is used to access the customer script of the target systems. In the case of a Windows target system, the user account must have read and execute permission for the share and the specified subdirectory. In the case of a Linux target system, this account is used to access the FTP server. This parameter is mandatory, if customer script is specified.Default value: ""

CustomScriptPasswordSpecifies the corresponding password for the specified custom script user account.This parameter is mandatory, if customer script is specified.Default value: ""

WindowsDomainSpecifies the windows domain to join after cloning.Default value: ""

WindowsDomainJoinUsernameSpecifies the user name to be used when joining the domain. This user account must have administrative rights.Default value: ""

WindowsDomainJoinPasswordSpecifies the corresponding password for the specified WindowsDomainJoinUsername account.Default value: ""

LogicalDiskSpecifies the logical disk number on which the image should be deployed.Default value: 0

ExpandLastPartitionEnables or disables the expansion of the last partition of the image to use the rest of disk. 0 (EXPANDLASTPARTITION_OFF): means that the last partition will not be expand to the available disk size. Any unused disk space will remain available for additional partitions.

122 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

1 (EXPANDLASTPARTITION_ON): means that the last partition will be expanded to the available disk size on the cloned systemDefault value: 0 (EXPANDLASTPARTITION_OFF)

UnicastSpecifies a multicast or unicast cloning execution:0 (MULTICAST) 1 (UNICAST)Default value: 0 (MULTICAST)

GUIDCheckEnables and disables respectively the global user identification check.0 (GUIDCHECK_OFF)1 (GUIDCHECK_ON)Default value: 0 (GUIDCHECK_OFF)

IgnoreModelCompatibilityEnable or disable the compatibility check if the cloning image is compatible to a given PRIMERGY server or not. 0 (IGNORE_OFF) check compatibility 1 (IGNORE_ON) ignore compatibility checkDefault value: 0 (IGNORE_OFF)

ForceSnapshotCloningEnables or disables the option to clone a non snapshot image to a disk without performing the post-preparation of the cloned system (setting of host name, IP address, ...), which is normally done for non snapshot images.0 (FORCESNAPSHOT_OFF)1 (FORCESNAPSHOT_ON)Default value: 0 (FORCESNAPSHOT_OFF)

SetEtcHostnameUsed only when cloning Linux RedHat. Some RedHat versions add the host name to the localhost line in /etc/hosts. With this parameter you can force a change of the localhost line after cloning. 0 (or parameter not specified): default handling, that should work in most cases1: the host name of the cloned system is added to the localhost line2: the host name is removed from the localhost lineDefault value: 0

Job API Tandem 123


MakKeyAvailable only for Windows 2008.This parameter can contain a Multiple Activation Key to automatically activate the Windows 2008 target after cloning.Default value: ""

KmsServerAvailable only for Windows 2008.This parameter can contain the IP address or host name of a "Key Management Service" server to automatically activate the Windows 2008 target after cloning.Default value: ""

KmsPortAvailable only for Windows 2008.The port number of the "Key Management Service". This parameter must be supplied when parameter KmsServer is set.Default value: ""

ProxyServerAvailable only for Windows 2008.This parameter can optionally be set when either parameter MakKey or KmsServer are set. It can contain the IP address or host name of a Proxy Server.Default value: ""

ProxyPortAvailable only for Windows 2008.The port number of the Proxy Server. This parameter must be supplied when parameter ProxyServer is set.Default value: ""

Table of available parameters for installing

The table contains the available parameters which can be specified in the array of parameter to perform the deployment method install.

ConfigPathSpecifies a full-qualified path including the name of the configuration file.This parameter is mandatory in the single server selection mode.

ShutdownTypeSpecifies the reaction if the server is running:0 (SHUTDOWNTYPE_NO): do not try to shutdown, but return an error if the server is not powered off

124 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

1 (SHUTDOWNTYPE_ACPI): 2 (SHUTDOWNTYPE_GRACEFUL): shutdown with ServerView agents 3 (SHUTDOWNTYPE_FORCE): for servers of type Blade force a power off by the management blade; for other server types do an ACPI power off.Default value: 0 (SHUTDOWNTYPE_NO)

ShutdownCommunitySpecifies the SNMP community for shutdown request towards ServerView SNMP agents running on the target server. Default value: ""

ShutdownUsernameSpecifies the user name for ServerView SNMP agents shutdown.This parameter is mandatory, if ShutdownType=2 (graceful) is specified.Default value: ""

ShutdownPasswordSpecifies the corresponding password for the user indicated before.This parameter is mandatory, if ShutdownType=2 (graceful) is specified.Default value: ""

FinalPowerStatusSpecifies the power status of the server after installation.0 (FINALPOWERSTATUS_OFF): the server is powered off 1 (FINALPOWERSTATUS_ON): the installed operating system is bootedThis parameter allows to choose whether the server operating system should be booted or whether the server should be powered off after installation. Default value: 0 (FINALPOWERSTATUS_OFF)

SeStContentsPathSpecifies the full-qualified path of the Installation Manager contents tree in UNC format.If this parameter is not specified, the default value of the Installation Manager contents tree is used.

SeStContentsUsernameSpecifies the name of a user to access the Installation Manager data. If this parameter is not specified, the default value of the user for remote access is used.

Job API Tandem 125


SeStContentsPasswordSpecifies the corresponding password for the specified user (or for the default user if no SeSetContentsUsername has been specified).This parameter is mandatory.

Return Value



JobIDReturns a unique ID that can be used for GetJobStatusDetails to get more job details.

126 Job API Tandem

Job Management API function classes

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.10 Job Management

Job API considers jobs as requests which were sent to the deployment engines and are executed in the background. Each job is associated with a unique job ID that is created for each:

– Image creation (CreateImage)

– Image assignment (Deploy)

– System installation (Deploy)

– System info retrieval (StartSystemInfoRetrieval)

Job API additionally supports the possibility of job scheduling. Jobs defined by the generic Job API functions Deploy and CreateImage can be scheduled for immediate, daily, weekly or monthly execution, or for any valid scheduling combinations which can be configured with scheduled job control properties. For more details about the scheduling control properties, please see the chapter "Job scheduling" on page 141.

Job API distinguishes between two job types:

– Scheduled jobsScheduled jobs are defined in the current Job API version by the functions Deploy or CreateImage together with the additional indication of the scheduled job control properties. (These jobs are sent to a deployment engine according the specified scheduling control properties.)

– Nonscheduled jobsNonscheduled jobs are directly started jobs requested to a deployment engine in the background.

Job API Tandem 127

API function classes Job Management

5.10.1 GetJobStatusDetails

To retrieve details about a job performed by Job API since it was launched, use this function. GetJobStatusDetails returns the current job status and further job details of a job identified by job ID or a list of job IDs. It returns when either one of the jobs is no longer running or when the timeout expires. The API functions are asynchronous. If you prefer to work synchronously, issue a GetJobStatusDetails with Timeout set to INFINITE (but be aware, that most SoapClients and SoapServers set a timeout by themselves). Multiple calls to GetJobStatusDetails can be issued in parallel.

Syntax

GetJobStatusDetails JobIDList=<string> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> Timeout=<int> RDServer=<string> UserKey=<string>

Parameter

JobIDListSpecifies a comma separated list of job IDs from previous calls, e.g. Deploy or CreateImage.




TimeoutSpecifies number of seconds to wait if the job is not finished yet.0: return immediately 1 (INFINITE): wait until the job is finishedDefault value: 0

128 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5



I On a job with several servers, the GetJobStatusDetails returns a summary record for all involved servers. This can be Success or Error. If the status is Error the deployment of at least one server failed.

Return Value



JobStatusDetailsListReturns an array of structures of type JobStatusDetailsData.

Job API Tandem 129



The returned list contains all available job information of specified job IDs, which will have the following layout.

JobID=<int> JobType=<int> StatusDetails=<ArrayOf_DetailData>

JobIDDisplays the job ID.

JobTypeDisplays the type of the job:0 (JOBTYPE_STARTSYSTEMINFORETRIEVAL)8 (JOBTYPE_CREATEIMAGE)9 (JOBTYPE_DEPLOY)

StatusDetailsDisplays all available status details of the specified job ID in an array with elements of type DetailData. For more details see "Layout of the DetailData structure" on page 129.

Layout of the DetailData structure


NameDisplays the name of the status detail.

ValueDisplays the value of the status detail.

130 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

5.10.2 GetServerJobStatus

The function GetServerJobStatus returns the current job status (latest job on the server) by given MAC address of a list of servers. The API functions are asynchronous. If you prefer to work synchronously, issue a GetServerJobStatus with Timeout set to INFINITE (but be aware, that most SoapClients and SoapServers set a timeout by themselves). Multiple calls to GetServerJobStatus can be issued in parallel.

Syntax

GetServerJobStatus ServerIdList=<ArrayOf_ServerIdentifier> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> Timeout=<int> RDServer=<string> UserKey=<string>

Parameter

ServerIdListSpecifies an array of ServerIdentifier structures to identify one or more servers, on which job calls were started before, e.g. Deploy or CreateImage. For more details about the structure see "Layout of the ServerIdentifier structure" on page 22.

DeploymentServerSpecifies the host name or an IP address of LAN port 1 of a deployment server.



TimeoutSpecifies number of seconds to wait if the job is not finished yet. 0: return immediately -1 (INFINITE): wait until the job is finishedDefault value: 0

Job API Tandem 131




Return Value



ServerJobStatusListReturns an array with elements of type ServerIdentifier.

132 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5


The returned list contains detailed job status information of specified Server IDs, which will have the following layout.

JobIDDisplays the job ID of the latest job on the specified server.

StatusDisplays the current job status:"Initializing""Waiting""Running""'Cancelling""Success""Error""Cancelled"

TypeDisplays the type of the job:0 (JOBTYPE_STARTSYSTEMINFORETRIEVAL)8 (JOBTYPE_CREATEIMAGE)9 (JOBTYPE_DEPLOY)

DetailedStatusCodeDisplays a more detailed status code number (currently always 0).

DetailedStatusDisplays a more detailed status (detailed error message when job already finished or description of job progress).

I If no job for the specified server was started until now, the JobID=0 will be returned.

Job API Tandem 133


5.10.3 CancelJob

Some jobs may be cancelable under some circumstances. In order to cancel such a job, the Job API function CancelJob may by used by the user to cancel a running job.

Syntax

CancelJob JobID=<int> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> RDServer=<string> UserKey=<string>

Parameter

JobIDSpecifies a job ID from a previous call, e.g Deploy or CreateImage.




RDServerSpecifies the host name or the IP address of the server where the ServerView Deployment Manager service is running. If this parameter is not specified, the local machine is used. Default value: ""


134 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



Job API Tandem 135


5.10.4 GetScheduledJobProperties

The GetScheduledJobProperties function retrieves the scheduled job control properties of an already defined scheduled job identified by ScheduledJobID.

Syntax

GetScheduledJobProperties ScheduledJobID=<int> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> RDServer=<string> UserKey=<string>

Parameter

ScheduledJobIDSpecifies a scheduled job ID from a previous function call, e.g. Deploy, CreateImage which defined a scheduled job.






136 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



PropertiesReturns a list of all scheduled job control properties.

Job API Tandem 137


5.10.5 GetScheduledJobLogList

The GetScheduledJobLogList function is useful to return detailed job information about jobs which were initiated by the given scheduled job.

Syntax

GetScheduledJobLogList ScheduledJobID=<int> DeploymentServer=<string> DeploymentUsername=<string> DeploymentPassword=<string> RDServer=<string> UserKey=<string>

Parameter

ScheduledJobIDSpecifies a ScheduledJobID from a previous function call, e.g. Deploy, CreateImage which defined a scheduled job.






138 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Return Value



LogListReturns an array of all available logs of the specified scheduled job. A log contains details about a job which was initiated by this defined scheduled job.

Layout of the returned log list

The returned list of logs contains detailed information of initiated jobs.

JobID=<int> Details=<ArrayOf_DetailData>

JobIDDisplays the job ID of a job initiated by the scheduled job.

DetailsDisplays job details of the job indicated by the JobID. For more details about the structure see "Layout of the DetailData structure" on page 129.

Job API Tandem 139


5.10.6 DeleteScheduledJob

In order to delete defined scheduled jobs use the function DeleteScheduledJob.

Syntax

DeleteScheduledJob ScheduledJobID=<int> RDServer=<string> UserKey=<string>

Parameter

ScheduledJobIDSpecifies a ScheduledJobID from a previous function call, e.g. Deploy, CreateImage which defined a scheduled job.



Return Value



140 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

5

Job API Tandem 141

6 Job schedulingJob API supports the possibility of job scheduling. Jobs of the generic Job API functions Deploy and CreateImage can be scheduled for immediate, daily, weekly or monthly execution, or for any valid scheduling combinations which can be configured with the scheduled job control properties.

The following table contains all available scheduling job control properties which can be used as parameters (Name/Value pair) in the Job API functions to set up the date and times when one-time or recurring scheduled jobs should be performed.

The modification of properties of already defined scheduled jobs can be done via a repeated execution of the appropriate Job API function (Deploy or CreateImage) and the additional indication of the ScheduledJobID as well as the complete selection of the scheduled job properties. The next time this scheduled job runs, it will be started with the modified scheduled job control properties. A further way to correct a scheduled job is to delete the already defined scheduled job with the function DeleteScheduledJob and the execution of the appropriate function as well as the specification of the valid combination of the scheduled job control properties.

Please note, in principle scheduled jobs are exclusively reserved for the UserKey which was specified in the defining Job API function, i.e. any modification and any deletion of an already defined scheduled job presuppose the specification of this appropriate UserKey.

Name of parameter Description and value of parameterScheduled Enables or disables the option to create a

scheduled job. To define the scheduling specify the additional scheduled job control properties or the default values of the control properties will be used."0": execute job immediately"1": create scheduled jobDefault value: "0"

ScheduledJobName Specifies the name of the new scheduled job.ScheduledJobID Specifies the JobID of an already defined

scheduled job. This parameter can be used to modify an already defined scheduled job.

142 Job API Tandem

Job scheduling

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

6

Retries Specifies the number of retries if the scheduled job fails.Default value: 2

RetriesInterval Specifies the time (in minutes) before the next attempt if previous attempts at a scheduled job failed and the retries does not exceed the specified scheduled job retries. Value range: 1 - 360 minutesDefault value: 15

ScheduledStartTimeWindow Specifies the range (in minutes) of a time window. If the scheduled job could not be started successfully within the time window beginning with the start time of the scheduled job and ending xx minutes later (xx is the specified value for StartTimeWindow), the scheduled job will be cancelled. Also retries of the scheduled job will be made only during this time window. Therefore the scheduled job will not be started after the job start time window has elapsed. It can happen that a job is handed over to the deployment server, but is only queued because too many other jobs are already running. If the job start time window elapses while a job stays in this state, the task will also be canceled. A running job will not be cancelled when the job start time window elapses.Value range: 10 - 600 minutesDefault value: 60

ScheduledInterval Specifies the interval of the scheduled job:"Once": the job will be performed once only."Daily": the job will be performed daily."Weekly": the job will be performed weekly."Monthly": the job will be performed monthly.

ScheduledTime Specifies the start time (in hours and minutes) of the scheduled job. The format of ScheduledTime is: hh:mm. Default value:

Name of parameter Description and value of parameter

Job API Tandem 143

Job scheduling

ScheduledDate Specifies the date of the scheduled job start. The format of the ScheduledDate is: mm/dd/yyyyDefault value: current date

ScheduledDays Specifies one day of a week or a comma separated list of days in which a scheduled job is to perform. The days can be specified for weekly scheduled jobs (ScheduledInterval=Weekly) as:"SUN" | "1": Sunday"MON" | "2": Monday"TUE" | "3": Tuesday"WED" | "4":Wednesday"THU" | "5":Thursday"FRI" | "6": Friday"SAT" | "7":SaturdayFor daily scheduled jobs the days can be specified as:"WEEKDAYS": all days from Monday to FridayIf ScheduleDailyInterval > 1 the specification of ScheduledDays is not allowed.Default value: current date

ScheduledMonths Specifies one month or a comma separated list of months in which the scheduled job is to perform. The month can be specified as:"JAN" | "1": January"FEB" | "2": February.."NOV" | "11": November"DEC" | "12": DecemberThis parameter can be specified for monthly scheduled jobs (ScheduledInterval=Monthly). If ScheduledMonthlyInterval > 1 is selected the ScheduledMonths can not be additionally specified.Default value: ""


144 Job API Tandem

Job scheduling

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

6

ScheduledDayOfMonth Specifies one day of a month in which the scheduled job is to occur. This parameter can be specified for monthly scheduled jobs, but only one of the parameters ScheduledDayOfMonth and ScheduledWeekdayOfMonth are allowed.Default value: ""

ScheduledWeekdayOfMonth Specifies a week and a weekday of a month in which the scheduled job is to perform (First Mon, second Wed, etc.). This parameter can be specified for monthly scheduled (ScheduledInterval=Monthly), but only one of the parameters ScheduledDayOfMonth and ScheduledWeekdayOfMonth are allowed.Default value: ""

ScheduledWeeklyInterval Specifies the interval between the weeks of the scheduled job. An interval of 1 produces a weekly scheduled job. An interval of 2 produces an every other week scheduled job.Value range: 1 - 52Default value: 0

ScheduledMonthlyInterval Specifies the interval between the months of the scheduled job. An interval of 1 produces a monthly scheduled job. An interval of 2 produces an every other month scheduled job.Value Range: 1 - 12Default value: 0


Job API Tandem 145

7 API error codesAPI error codes may be returned in the ErrorCode and ErrorString parameters within a response to the Job API calls. The specific information defined in the individual API function call descriptions are useful for determining the reason for failures or other reasons.

I Due to the large description extent of the error codes as well as the different error causes, the error codes cannot be described here. Please contact the Deployment Manager development team to get detail information about errors and/or measures to reduce or to eliminate them.

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

7

Job API Tandem 147

8 InstallationJob API is distributed as an add-on package on the Deployment Manager CD-ROM. The installation starts automatically after insertion of the CD-ROM.

Job API consists of two installation packages:

– Job API for IIS package

– Job API for Apache package

You can install both packages at the same time or separately from each other. The Job API packages can be installed on a different system as Deployment Manager, because Job API allows remote access to the deployment server. If the Job API package is installed in different locations, both computers must be within the same Windows network domain. In addition, the user account specified during the installation process must be a member of this network domain.

For the installation of Job API for Apache package, the Apache Web server integration of Job API is only available if the Apache Web server has been installed along with the ServerView Operations Manager setup. Job API and ServerView Operations Manager must be installed on one system.

8.1 Requirements

Job API can be installed on:

– Windows 2003

– Windows 2008

Additional requirements:

– Web Server (IIS or ServerView Apache)

148 Job API Tandem

Installation process Installation

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

8

8.2 Installation process

This section describes an example installation of the Job API for IIS package.

To install the package please follow the instructions below.

1. Activate the control button of the package. The following window appears:

Click Next to continue the installation. If you want to quit the setup program, click Cancel.

Job API Tandem 149

Installation Installation process

2. Approve the licence agreement by marking the appropriate radio button and click Next.

150 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

8

3. Approve the destination folder of the install package and click Next.

Job API Tandem 151


4. Fill in your name and organization. Specify whether the Job API settings should only apply to the current user or to anyone who uses the target computer. Mark the appropriate radio button and click Next.

152 Job API Tandem


© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

8

5. To start the installation process, click the Next button of the Ready to install the Application window. If you want to stop the installation process, click Cancel.

Job API Tandem 153


6. If the JobAPI was successfully installed, click Finish to exit the installation.

154 Job API Tandem

JobAPI with Internet Information Server (IIS) Installation

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

8

8.3 JobAPI with Internet Information Server (IIS)

8.3.1 JobAPI with Internet Information Server (IIS) on Windows Server 2003

When JobAPI is installed on Windows Server 2003 and Internet Information Server (IIS) is used as Web server, the default configuration of the IIS must be changed in order to allow the execution of CGI scripts. This can be done in the following way:

Ê Start the Internet Information Services (IIS) Manager from the Administrative Tools.

Ê Select the local system's WebService Extensions.

Ê Select All Unknown CGI Extensions.

Ê Press the Allow button.

8.3.2 JobAPI with Internet Information Server (IIS) on Windows Server 2008

When JobAPI is installed on Windows Server 2008 and Internet Information Server (IIS) is used as Web server, JobAPI.exe must be added to the list of CGI scripts that can be executed. This can be done in the following way:

Ê Select Start – Administrative Tools – Internet Information Services (IIS) Manager.

Ê Click your server in the left pane.

Ê Double-click ISAPI and CGI Restrictions in the middle pane.

Ê Click Add ... in the right pane.

Ê In the Add ISAPI or CGI Restriction window enter the following values:

– ISAPI or CGI path: C:\Inetpub\scripts\JobAPI\JobAPI.exe– Description: JobAPI– Check Allow extension path to execute.

Ê Click OK.

Job API Tandem 155

Installation Installation test

8.4 Installation test

Now after the installation it is possible to test out the Job API service via Web browser.

1. In your browser's location bar type:

http://<server>:<port>/scripts/JobAPI/JobAPI.exe?Installation

or

http://<server>:<port>/scripts/JobAPI/JobAPI.exe?Test

Where <server> is the IP address or hostname of the server where you installed the JobAPI service and where <port> is the used port of your Web server. Please see section "URL" on page 157 for more details about the URL of Job API.

2. If the Job API service is correctly installed, the Job API CGI is invoked and generates a Web page or a string as shown in the following figures.

This web page contains information about the version of Job API and additional information about the installation of Deployment Manager on the same server.

156 Job API Tandem

Installation test Installation

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

8

The provided string contains the same information as the generated Web pages, but only stored in following variables:

If an HTTP error occurs (e.g. 404 Not found, 400 Bad request), either Job API is not installed, or the CGI call was not correct.

JobAPIVersion Shows the version of the installed Job API service.

Deployment Manager Shows whether Deployment Manager is installed on the same server as the installed Job API.

Deploment Manager Version

Shows the version of the installed Deployment Manager.

Deployment Manager Service Status

Shows the status of the ServerView Deployment Manager service (unknown = can not be checked, because access was denied).

Job API Tandem 157

9 Further informationThe following chapter describes some information which are important for the Job API client application and the settings of the used Web server.

9.1 URL

The Job API server can be installed for the Internet Information Server (IIS) and Apache Web server. The table below contains a description which URL you must use with which Deployment Manager, Job API version and configurations:

The development tool information concerns the used tool for the generation of Job API server. This is not necessary for the Job API client generation. We suggest to use a gSOAP version in the range of V2.6 - V2.7.13.

DeploymentManager

JobAPI

Development tool

Web server

URL

V5.30 V1.5 gSOAP V2.7.13

IIS http://<server>/scripts/JobAPI/JobAPI.exe

gSOAP V2.7.13

Apache(SV)

http://<server>:3169/scripts/JobAPI/JobAPI.exe

158 Job API Tandem

HTTP authentication Further information

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

9

9.2 HTTP authentication

The HTTP authentication can be enabled at the Job API client side by setting the soap.userid and the soap.passwd strings to a user name and password, respectively. The Web server may request user authentication and denies access (HTTP 401 error) when the Job API client tries to connect without HTTP authentication or with the wrong authentication information.

Here is the example of Job API client code fragment to set the user and password of the installed Apache server by ServerView:

⎜ struct soap soap; ⎟⎜ soap init(&soap); ⎟⎜ soap.userid = "svuser"; ⎟⎜ soap.passwd = "password"; ⎟

A client SOAP request will have the following HTTP header:

⎜ POST /scripts/JobAPI/JobAPI.exe HTTP/1.1 ⎟⎜ Host: YYY:3169 ⎟⎜ User-Agent: gSOAP/2.7 ⎟⎜ Content-Type: text/xml; charset=utf-8 ⎟⎜ Content-Length: nnn ⎟⎜ Authorization: Basic Z3Vlc3Q6Z3Vlc3Q= ⎟

I A Job API client application MUST set the soap.userid and soap.passwd strings for each call that requires client authentication, because the strings are reset after each successful or unsuccessful call.

If ServerView is configured by default installation to use Apache server, the SSL support is enabled. Additional the HTTP authentication for the Job API service is activated too.

Job API Tandem 159

Further information HTTP authentication

In order to avoid the HTTP authentication, you can modify the configuration file (ssl.config) of the Apache server as described in the following.

1. Open the SSL configuration file (C:\Program Files\Fujitsu\ServerView Suite\ServerView\ServerView Services\WebServer\conf\ssl.config) and add the IP address of your server on which the JobAPI client is installed to the settings of the scripts authentication. You can enter an IP address or an IP address range, for example 122.138 is the IP address range of your called server 122.138.200.151.

ssl.config file - example

⎜ # scripts ˜⎜ Directory "C:/PROGRA~1/FUJITS~1/SERVER~1/SERVER~1/scripts"> ⎟⎜ Options FollowSymLinks ⎟⎜ AllowOverride None ⎟⎜ ⎟⎜ Order deny,allow ⎟⎜ Deny from all ⎟⎜ Allow from 127.0.0.1 ⎟⎜ AuthType Basic ⎟⎜ AuthUserFile "C:/PROGRA~1/FUJITS~1/SERVER~1/SERVER~1/WebServer/bin/passwd" ⎟⎜ AuthName "C:/PROGRA~1/FUJITS~1/SERVER~1/SERVER~1/WebServer/cgi-bin" ⎟⎜ Require valid-user ⎟⎜ Satisfy any ⎟⎜ </Directory> ⎟

I The current SSL settings allow only a Job API client request from the local server. In order to allow access from server 122.138.200.151 extend the Allow statement by this IP address:

Allow from 127.0.0.1 122.138.200.151

In order to allow a complete IP address change extend it by

Allow from 127.0.0.1 122.138.200

2. Restart the Apache Web server.

160 Job API Tandem

HTTPS / SSL Further information

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

9

9.3 HTTPS / SSL

As described in chapter "Security" on page 11, Job API is implemented as CGI application. It uses the standard I/O that is encrypted/decrypted by the Web server that runs the Job API service CGI. Therefore, HTTPS / SSL support must be configured for the Web server and the Job API client application.

To enable secure Job API clients to utilize HTTPS / SSL the OpenSSL library (http://www.openssl.org) must installed on your platform. After installation, compile all the sources of the Job API client application with option -DWITH_OPENSSL or you can add the following line to soapdefs.h and compile with -DWITH_SOAPDEFS_H.

#define WITH_OPENSSL;

The Job API client application simply uses the prefix https: instead of http: in the endpoint URL of a function call to the Job API service to use encrypted transfers (if the Web server supports HTTPS). Furthermore the Web servers use another port for the HTTPS protocol as HTTP. By default, IIS 7.0 listens on port 443 for HTTPS protocol and Apache 2.0 (ServerView) on port 3170.

In addition you need to specify the client-side key file and password of the key file. Instructions on how to do this can be found in the OpenSSL documentation http://www.openssl.org.

⎜ if (soap_ssl_client_context(&soap, ⎟⎜ SOAP_SSL_DEFAULT, ⎟⎜ "client.pem", // key file: required only when client must authenticate ⎟⎜ to server ⎟⎜ // (see SSL docs on how to obtain this file) ⎟⎜ "password", // password to read the key file ⎟⎜ NULL, // optional cacert file to store trusted certificates ⎟⎜ NULL, // optional capath to direcoty with trusted certificates ⎟⎜ NULL // if randfile!=NULL: use a file with random data to seed ⎟⎜ randomness ⎟⎜ )) ⎟⎜ { ⎟⎜ soap_print_fault(&soap, stderr); ⎟⎜ exit(1); ⎟⎜ } ⎟⎜ soap_call_ns_jobapifunction(&soap, ⎟⎜ "https://server:3169/scripts/JobAPI/JobAPI.exe", "", ...); ⎟

Job API Tandem 161

Further information HTTPS / SSL

By default, the server authentication is enabled. To disable server authentication for testing purposes, use the following:

⎜ if (soap_ssl_client_context(&soap, ⎟⎜ SOAP_SSL_NO_AUTHENTICATION, ⎟⎜ NULL, ⎟⎜ NULL, ⎟⎜ NULL, ⎟⎜ NULL, ⎟⎜ NULL, ⎟⎜ )) ⎟⎜ { ⎟⎜ soap_print_fault(&soap, stderr); ⎟⎜ exit(1); ⎟⎜ } ⎟

This also assumes that the server does not require clients to authenticate (the key file is absent). Make sure you have signal handlers set in your application to catch broken connections (SIGPIPE):

⎜ signal(SIGPIPE, sigpipe_handle); ⎟

where, for example:

⎜ void sigpipe_handle(int x) {…} ⎟

I It is important that the WITH_OPENSSL macro must be consistently defined to compile the sources, such as stdsoap2.cpp, soapC.cpp, soapClient.cpp, and all application sources that include stdsoap2.h or soapH.h. If the macros are not consistently used, the application will crash due to mismatches in the declaration and access of the gSOAP environment.

162 Job API Tandem

SOAP timeouts Further information

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

9

9.4 SOAP timeouts

Socket connect, accept, send, and receive timeout values can be set to manage the communication timeouts. The soap.connect_timeout, soap.accept_timeout, soap.send_timeout, and soap.recv_timeout attributes of the current gSOAP runtime environment soap can be set to the appropriate user defined socket send, receive, and accept timeout values. A positive value measures the timeout in seconds. A negative timeout value measures the timeout in microseconds (10-6 sec.).

– The soap.connect_timeout specifies the timeout value for soap call ns method calls.

– The soap.accept_timeout specifies the timeout value for soap accept(&soap) calls.

– The soap.send_timeout and soap.recv_timeout specify the timeout values for non-blocking socket I/O operations.

Example

⎜ struct soap soap; ˜⎜ soap init(&soap); ⎟⎜ soap.send timeout = 10; ⎟⎜ soap.recv timeout = 10; ⎟

This will result in a timeout if no data can be send in 10 seconds and no data is received within 10 seconds after initiating a send or receive operation over the socket. In addition a value of zero disables timeout, for example:

⎜ soap.send timeout = 0; ⎟⎜ soap.recv timeout = 0; ⎟

When a timeout occurs in send/receive operations, a SOAP_EOF exception will be raised ("end of file or no input").

Job API Tandem 163

Further information CGI timeout

9.5 CGI timeout

The CGI timeout specifies the maximum number of seconds that a synchronous Job API client request waits for a response from the Job API server. If the CGI does not respond within the timeout period, the request process will be deleted by the Web server. The timeout property has no effect on asynchronous requests made with the functions CreateImage, Deploy or StartSystemInfoRetrieval.

Furthermore one must assure that the CGI timeout is always greater than a timeout period which is indicated in a synchronous request. If this is not the case, the request will be possibly deleted by the Web server before expiration of the function timeout.

Follow the server-specific default timeout values and the instructions to increase the timeout interval.

9.5.1 Apache configuration

The modification of the time interval inside the Apache Web server is specified with the timeout directive in httpd.conf. This directive defines the amount of time the Apache Web server will wait for three things:

1. The total amount of time it takes to receive a GET request.

2. The amount of time between receipt of TCP packets on a POST or PUT request.

3. The amount of time between ACKs on transmissions of TCP packets in responses.

The timer used to default to 1200 before Apache 1.2, but has been lowered to 300 which is still far more than necessary in most situations.

164 Job API Tandem

CGI timeout Further information

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

9

Follow the server-specific instructions below to increase the timeout interval:

1. Open the httpd.conf file.

2. Modify timeout value, shown in figure bellow.

3. Save the httpd.conf file.

⎜ # ⎟⎜ # Timeout: The number of seconds before receives and sends time out. ⎟⎜ # ⎟⎜ Timeout 300 ⎟⎜ ⎟⎜ # ⎟⎜ # KeepAlive: Whether or not to allow persistent connections (more than ⎟⎜ # one request per connection). Set to "Off" to deactivate. ⎟⎜ # ⎟⎜ KeepAlive On ⎟⎜ ⎟⎜ # ⎟⎜ # MaxKeepAliveRequests: The maximum number of requests to allow ⎟⎜ # during a persistent connection. Set to 0 to allow an unlimited amount. ⎟⎜ # We recommend you leave this number high, for maximum performance. ⎟⎜ # ⎟⎜ MaxKeepAliveRequests 100 ⎟⎜ ⎟⎜ # ⎟⎜ # KeepAliveTimeout: Number of seconds to wait for the next request from the ⎟⎜ # same client on the same connection. ⎟⎜ # ⎟⎜ KeepAliveTimeout 15 ⎟

I In order to activate the modification of the timeout period the Web server must restarted.

Job API Tandem 165

Further information CGI timeout

9.5.2 IIS configuration

Inside the Microsoft Internet information service (IIS) configuration the default value of timeout is specified to 900 seconds.

Follow the server-specific instructions below to increase the timeout interval:

Ê Open up the Internet Service Manager.

The IIS window appears, as shown in the figure.

Ê Right click on the Web Sites folder, and click Properties.

Ê In the Connections box go to the Process Options tab, and modify the timeout value.

166 Job API Tandem

CGI timeout Further information

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

9

Job API Tandem 167

Further information SOAP error handling

9.6 SOAP error handling

The first line of error reporting is governed by the SOAP specification. SOAP fault reporting and fault codes will be returned for most invalid requests or any request where the intent of the caller cannot be determined. An error message from a SOAP message is carried generally inside a Fault element. If a Fault element is present, it must appear as a child element of the Body element. A Fault element can only appear once in a SOAP message. The SOAP Fault element has the following sub elements:

The faultcode values defined below are used in the faultcode element to describe faults:

Sub element Description<faultcode> Displays a code for identifying the fault.<faultstring> Shows a human readable explanation of the

fault.<faultactor> Displays information about who caused the fault

to happen.<detail> Holds application specific error information

related to the Body element.

error DescriptionVersionMismatch Found an invalid namespace for the SOAP

Envelope element.MustUnderstand An immediate child element of the Header

element, with the MustUnderstand attribute set to "1", was not understood.

Client The message was incorrectly formed or contained incorrect information.

Server There was a problem with the server so the message could not proceed.

168 Job API Tandem

SOAP debugging Further information

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k0

9

9.7 SOAP debugging

9.7.1 Job API client

To activate message logging for debugging the Job API client side, un-comment the #define DEBUG directive in stdsoap2.h and compile the client applications (or simply use g++ -DDEBUG ... to compile with debugging activated). When the client applications run, they will log their activity in three separate files:

– SENT.logThe SOAP content transmitted by the application.

– RECV.logThe SOAP content received by the application.

– RECV.logA log containing various activities performed by the application.

I The Job API client applications may run slow due to the logging activity.

9.7.2 Job API server

To get additional debugging information the message logging can also be activated on the Job API server side. For more details, please read the ReadMe.txt file.

I The Job API service may run slow due to the logging activity.

Job API Tandem 169

10 Job API client developmentThe purpose of this chapter is to explain the steps how to develop a Job API client application with the gSOAP Web services development environment that can interoperate with the Job API service.

In principle, there are different SOAP development tools, which generate interfaces for a client application on basis of a given WSDL. The selection of an according SOAP tool is affected by the used platform and/or the used programming language, e.g. C, C++, Java etc. gSOAP is a platform-independent development environment for deploying efficient SOAP/XML Web services and Web service client applications in C and C++, whereby in principle no detailed understanding of the SOAP protocol is necessary.

First download and install the gSOAP toolkit, which is available at

http://www.cs.fsu.edu/~engelen/soap.html

(inside the development of the Job API Web services was used the gSOAP release V2.7.13).

To start the building of client applications with gSOAP, the following is necessary:

– a C or C++ compiler

– the gSOAP soapcpp2 (e.g. soapcpp2.exe for windows) stub and skeleton compiler

– the gSOAP wsdl2h (e.g. wsdl2h.exe for windows) WSDL parser, which converts WSDL into a gSOAP specification header file for the soapcpp2 stub and skeleton compiler

– the stdsoap2.c or stdsoap2.cpp and stdsoap2.h files containing the runtime library to be linked with the Web services applications

– optionally, you may want to install OpenSSL and the Zlib libraries to enable SSL (HTTPS) and compression

170 Job API Tandem

Generating C/C++ stubs Job API client development

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k1

0

10.1 Generating C/C++ stubs

In general, the implementation of a SOAP client application requires a stub routine for each remote method that the client application needs to invoke. The primary responsibility of a stub is to marshal the parameter data, send the request with the parameters to the designated SOAP service, to wait for the response, and to unmarshal the parameter data of the response when it arrives. The client application invokes the stub routine for a remote method as if it would invoke a local method. The gSOAP wsdl2h WSDL parser and soapcpp2 stub and skeleton compiler automate the development of Web service client. The gSOAP stub and skeleton compiler is a preprocessor that generates the necessary sources to build SOAP clients. The input to soapcpp2 consists of a standard C/C++ header file, which must be generated from a WSDL documentation of a service with the gSOAP WSDL parser before.

Now, to develop a Job API client application, import in the first step the WSDL of Job API with the gSOAP WSDL parser to create a header file with the C/C++ declarations of all Job API function prototypes of SOAP remote methods.

wsdl2h -o JobAPI.h JobAPI.wsdl

This generates the file JobAPI.h in C++ format from the Job API WSDL. To generate a header file to develop a pure C client application, issue the command:

wsdl2h -c -o JobAPI.h JobAPI.wsdl

In the next development step the gSOAP compiler translates this generated JobAPI.h header file into stub routines for the client application. The resulting stub routines allow C and C++ client applications to seamless interact with the existing Job API Web service. The gSOAP compiler is invoked from the command line by:

soapcpp2 JobAPI.h

The input and output parameters of a Job API SOAP service method may be simple data types or compound data types, which are generated by the WSDL parser according to the data type definitions contained in the WSDL. Furthermore the gSOAP stub and skeleton compiler automatically generates serializers and deserializers for the data types to enable the generated stub routines to encode and decode the contents of the parameters of the remote methods in XML.

Job API Tandem 171

Job API client development Generating C/C++ stubs

The details of the files generated by the WSDL parser or the stub/skeleton compiler are:

soapStub.h A modified and annotated header file produced from input header file.

soapH.h Main header file to be included by all client and service sources.

soapC.cpp Serializers and deserializers for the specified data structures.

soapClient.cpp Client stub routines for remote operations.

soapServer.cpp Service skeleton routines.soapClientLib.cpp Client stubs combined with local static

(de)serializers.soapServerLib.cpp Service skeletons combined with local

static (de)serializers.JobAPI.h A header file with the C/C++

declarations of all Job API function prototypes of SOAP remote methods.

JobAPISoapBinding.nsmp Namespace mapping table to be included by server and clients.

soapJobAPISoapBindingProxy.h A C++ proxy object (can be used instead of soapClient.cpp).

soapJobAPISoapBindingProxy.cpp Implementation of C++ proxy object.soapJobAPISoapBindingObject.h A C++ server object (can be used

instead of soapServer.cpp).soapJobAPISoapBindingObject.cpp Implementation of C++ server object..xsd An ns.xsd file is generated with an XML

schema for each namespace prefix ns used by a data structure in the header file input to the compiler.

172 Job API Tandem

Generating C/C++ stubs Job API client development

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k1

0

All steps of the development process of a Job API client application are illustrated in the figure below as:

Job API Tandem 173

Job API client development Using generated C/C++ stubs

10.2 Using generated C/C++ stubs

To use the generated C/C++ stub routines, implement a C/C++ client application code like illustrated below:

After compilation with an C++ compiler, for example g++

g++ soapC.cpp soapClient.cpp stdsoap2.cpp client.cc -o client

and running the application, it returns the version of the installed Job API service on the accessed host ( ex. local host) by calling the Job API method GetAPIVersion.

I In this explanation of client development some details were skipped. Please see the gSOAP user guide for more details.

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obA

PI_

Tand

em\H

andb

uch\

us\jo

b_A

PI-e

n.k1

0

Job API Tandem 175

IndexAAddGroupMember 105AddRepository 70AddServer 29API error codes 145API Management 24

CCancelJob 133ChangeServerConfiguration 36CreateDirectory 89CreateGroup 96CreateImage 75CreateUserKey 28

Ddata types 22DeleteDirectory 91DeleteGroup 98DeleteImage 83DeleteScheduledJob 139Deploy 115Deployment Management 114Directory Management 89

EErrorCode 145ErrorString 145ExportDeploymentConfiguration 53

Ffunction

AddGroupMember 105AddRepository 70AddServer 29CancelJob 133ChangeServerConfiguration 36CreateDirectory 89CreateGroup 96CreateImage 75CreateUserKey 28

DeleteDirectory 91DeleteGroup 98DeleteImage 83DeleteScheduledJob 139Deploy 115ExportDeploymentConfiguration

53GetAPIinfo 25GetAPIVersion 24GetBootMode 66GetDirectoryContents 93GetGroupList 99GetGroupMemberList 108GetGroupMemberProperties 112GetGroupProperties 103GetImageProperties 88GetJobStatusDetails 127GetPower 64GetRepositoryContents 84GetRepositoryList 73GetScheduledJobLogList 137GetScheduledJobProperties 135GetServerJobStatus 130GetSystemInfoResult 44ImportDeploymentConfiguration

51RdDeplServerList 45ReadImagefilenameList 86ReadImageInfoText 87RemoveGroupMember 107RemoveRepository 72RemoveUserKey 56SetGroupMemberProperties 110SetGroupProperties 101SetPower 57SetPXEBootImage 61SetUserKey 55StartSystemInfoRetrieval 41

Function overview 17

176 Job API Tandem

Index

© c

ogni

tas.

Ges

ells

chft

für T

echn

ik-D

okum

enta

tion

mbH

200

9 P

fad:

Q:\J

obAP

I_Ta

ndem

\Han

dbuc

h\us

\job_

AP

I-en.

six

GGetAPIinfo 25GetAPIVersion 24GetBootMode 66GetDirectoryContents 93GetGroupList 99GetGroupMemberList 108GetGroupMemberProperties 112GetGroupProperties 103GetImageProperties 88GetJobStatusDetails 127GetPower 64GetRepositoryContents 84GetRepositoryList 73GetScheduledJobLogList 137GetScheduledJobProperties 135GetServerJobStatus 130GetSystemInfoResult 44Group Management 95

IImportDeploymentConfiguration 51Installation 147Installation process 148

JJob Management 126Job scheduling 141

PPower Management 57

RRdDeplServerList 45ReadImagefilenameList 86ReadImageInfoText 87RemoveGroupMember 107RemoveRepository 72RemoveUserKey 56Repository Management 68Requirements 147

SServer/Nodelist Management 29SetGroupMemberProperties 110SetGroupProperties 101SetPower 57SetPXEBootImage 61SetUserKey 55StartSystemInfoRetrieval 41

server management job api tandem 1 -...

Documents