InstallerAutomationService

Installer automation webservice. Provides a SOAP API to perform most InstallerManager functions.

Endpoint Metadata

  • Namespace: http://videoscape.cisco.com/oci/webservices/installerautomation
  • Endpoint Name: InstallerAutomationWebService
  • Endpoint Address: http(s)://{VMS URL}/InstallerManager/webservices/installerautomation-service

The following methods are available on this endpoint:

applyCommandToJBossNodeWithIpAddress

Apply the specified command [START/STOP/RESTART] to JBoss, on the JBossNode whose IP Address is provided.

Input Parameters

name type description
ipAddress string the ipAddress of the node on which the command needs to be applied.
jbossCommand string the command to be applied to JBoss [START/STOP/RESTART].

Faults

name description
InstallerAutomationWebServiceFault if specified values are invalid; or if the operation encounters an error;

applyCommandToJBossNodeWithNodeId

Apply the specified command [START/STOP/RESTART] to JBoss, on the JBossNode whose ID is provided.

Input Parameters

name type description
nodeId string the Id of the node on which the command needs to be applied.
jbossCommand string the command to be applied to JBoss [START/STOP/RESTART].

Faults

name description
InstallerAutomationWebServiceFault if specified values are invalid, or if the operation encounters an error.

createCustomFile

Create a custom file. The custom file object must be populated to include a name, file name, valid target module, and optionally a targetpath. The active flag can be set as needed (can activate/deactivate custom files via the InstallerManager UI)

Input Parameters

name type description
customFile CustomFile Custom file to create.
fileBytes byte[] Custom file content.

Return Value

type description
CustomFile Newly created custom file

Faults

name description
InstallerAutomationWebServiceFault If the specified custom file already has a primary key; if a name or file name are missing; ifa target module is missing, invalid, or refers to the Agent or the Installer itself; if a custom file with the same name alreadyexists; if the custom file is configured to be placed inside the target module's deployment home, but the target module does nothave a deployment home; if another custom file that resolves to the same target path (file or directory) already exists in thesystem; if the save operation encountered an error;

createCustomLog4JAppender

Creates a custom log4j appender file. The custom file object must be populated to include a name, file name. A custom log4j appendertarget path can be either null(then default value "lib" will be used for it) OR equal to 'lib', because all appenders must be placedinside 'lib' directory on JBoss. The custom file must be marked as log4j appender (log4jAppender flag is false). The active flag can beset as needed (can activate/deactivate custom files via the InstallerManager UI).

Input Parameters

name type description
log4jAppender CustomFile the custom log4j appender to create
fileBytes byte[] the custom log4j appender content

Return Value

type description
CustomFile Newly created custom file

Faults

name description
InstallerAutomationWebServiceFault If the specified custom file already has a primary key; if a name or file name are missing; ifa custom file with the same name already exists; if the save operation encountered an error; if custom file is not marked as log4jappender (log4jAppender flag is false); if target path is not null OR is not equal to 'lib';

deleteCustomFile

Delete custom file reference from InstallerManager. This is akin to deleting custom file from InstallerManager UI. This will not deletethe custom file from node if the cusotm file has already been deployed.

Input Parameters

name type description
customFilePk integer Primary key of custom file to delete

Faults

name description
InstallerAutomationWebServiceFault If the primary key is invalid or the delete operation encountered an error.

disableUpgradeMode

Disable the upgrade mode. If running nodes (of the same version) have already loaded the upgrade mode flag, their installer config will becached until restart, so this change will not have effect on them.

Faults

name description
InstallerAutomationWebServiceFault In case of error.

enableUpgradeMode

Enable upgrade mode. In order to enable, all nodes in the system must be partitioned with sufficient redundancy. Once the flag is set, allrunning nodes (of the same version) will stop reloading installer configuration, effectively caching it in memory until shutdown.

Faults

name description
InstallerAutomationWebServiceFault If node partitioning is incorrect, or in case of error.

findJBossNodeIdByIpAddress

Get the ID of a JBossNode given its IP address.

Input Parameters

name type description
ipAddress string the ipAddress of the node whose ID we want to find.

Return Value

type description
string the nodeId of the JBossNode to which the IP Address belongs.

Faults

name description
InstallerAutomationWebServiceFault if the operation encounters any error;

generateFullTargetPath

Generate proper target path for the specified custom file. Removes backslashes, duplicate forward slashes, and leading slashes. Builds thepath starting from 'deploy' and includes parent directories.

Input Parameters

name type description
customFile CustomFile unpersisted custom file

Return Value

type description
string If the specified target path is null, returns a blank string. If the specified target path is one character short and is a forwardslash, returns a blank string.

Faults

name description
InstallerAutomationWebServiceFault if the specified custom file has a pk

getDefaultAdminLanguage

Get the default admin language

Return Value

type description
string The default language for VMS administrators

Faults

name description
InstallerAutomationWebServiceFault In case of error

getDefaultSystemLanguage

Get the default system language

Return Value

type description
string The default language for VMS services

Faults

name description
InstallerAutomationWebServiceFault In case of error

getJBossLogLevel

Get the JBoss log level for VMS and related packages.

Return Value

type description
string The JBoss log level for VMS and related packages.

Faults

name description
InstallerAutomationWebServiceFault In case of error.

getModClusterProxy

Get the mod_cluster proxy host:port

Return Value

type description
string The mod_cluster proxy host:port

Faults

name description
InstallerAutomationWebServiceFault In case of error

getPackagesAvailableForSelection

List names and versions all packages available for selection. All nodes must be inactive for this call to proceed.

Return Value

type description
list<packageMetadata> List names and versions all packages available for selection

Faults

name description
InstallerAutomationWebServiceFault If any of the nodes are active; if the lookup operation encountered an error

getSelectedLanguages

Get the language set selected for VMS.

Return Value

type description
set The language set selected for VMS.

Faults

name description
InstallerAutomationWebServiceFault In case of error

getSSODomain

Get the SSO cookie domain

Return Value

type description
string The SSO cookie domain

Faults

name description
InstallerAutomationWebServiceFault In case of error

getSSOLogLevel

Get the log level for SSO debug logs.

Return Value

type description
string The current debug log level for OpenAM.

Faults

name description
InstallerAutomationWebServiceFault in case of error.

getSSOLogRotationInterval

Get the log rotation interval in days for SSO debug logs.

Return Value

type description
string The current OpenAM debug log rotation interval (in days).

Faults

name description
InstallerAutomationWebServiceFault in case of error.

isDatabaseUpdateComplete

Is the global database updater state complete?

Return Value

type description
boolean True if the global database updater state is complete

Faults

name description
InstallerAutomationWebServiceFault If the lookup operation failed

isDatabaseUpdateInError

Is the global database updater state in error?

Return Value

type description
boolean True if the global database updater state is in error

Faults

name description
InstallerAutomationWebServiceFault If the lookup operation failed

isDatabaseUpdateInProgress

Is the global database updater state in progress?

Return Value

type description
boolean True if the global database updater state is in progress

Faults

name description
InstallerAutomationWebServiceFault If the lookup operation failed

isDatabaseUpdateReady

Is the global database updater state ready for update?

Return Value

type description
boolean True if the global database updater state is ready for update

Faults

name description
InstallerAutomationWebServiceFault If the lookup operation failed

isUpgradeModeEnabled

Is upgrade mode enabled?

Return Value

type description
boolean true is the upgrade mode flag is set

Faults

name description
InstallerAutomationWebServiceFault In case of error

listCustomFiles

List all custom files registered in the system

Return Value

type description
list<CustomFile> A list of all custom files registered in the system

Faults

name description
InstallerAutomationWebServiceFault In case of error

listCustomLog4JAppenders

Fetches list of all custom Log4j Appender registered in the system

Return Value

type description
list<CustomFile> A list of all custom Log4J Appender registered in the system

Faults

name description
InstallerAutomationWebServiceFault In case of error

listDatabases

List all databases in the system

Return Value

type description
list<Database> all databases in the system

Faults

name description
InstallerAutomationWebServiceFault in case of error

listEndpoints

List all endpoints for all modules in the system.

Return Value

type description
list<Endpoint> List of endpoints in the system

Faults

name description
InstallerAutomationWebServiceFault In case of error

listInstalledModules

List all modules selected and known to the system.

Return Value

type description
list<Module> A list of modules contained in the packages selected by the user, whether they are installed on node(s) or not.

Faults

name description
InstallerAutomationWebServiceFault In case of error

listInstalledPackages

List all packages selected and known to the system.

Return Value

type description
list<Package> A list of all packages selected by the user, whether they are installed on node(s) or not.

Faults

name description
InstallerAutomationWebServiceFault In case of error

listJBossNodes

List all registered nodes.

Return Value

type description
list<JBossNode> A list of all nodes in the system.

Faults

name description
InstallerAutomationWebServiceFault In case of error.

listSupportedLanguages

List all languages supported by VMS.

Return Value

type description
set A list of all languages supported by VMS. Entries in this list are of the format 'aa_BB-cc', where 'aa' is the language code, 'BB'is the country code, and 'cc' is the language group code. For example, 'ko_KR-as' represents the Korean/Korea/Asia.

Faults

name description
InstallerAutomationWebServiceFault In case of error

partitionNodesForUpgrade

Partition nodes for an A-side/B-side upgrade. To enable upgrade mode, all nodes in the deployment must partitioned into 2 groups --upgrade FIRST and upgrade LAST. The nodes in the FIRST partition are upgraded first while the nodes in the LAST partition remain running,and once the FIRST partition upgrade is complete, the nodes in the LAST partition are upgraded. There must be sufficient redundancy toenable upgrade mode - each module must have nodes in both partitions.

Input Parameters

name type description
firstPartition list<JBossNode> Nodes in the FIRST partition
lastPartition list<JBossNode> Nodes in the LAST partition

Faults

name description
InstallerAutomationWebServiceFault If a node is present in both partitions, or in case of error

performDatabaseUpdate

Start the database update process. All nodes must be inactive and the global database updater state must be ready. This call performsvalidation on items required for database updater operations and then starts the update process asynchronously. Callers need to poll thestate using the provided 'isDatabaseUpdate...()' methods.

Faults

name description
InstallerAutomationWebServiceFault If any nodes are active; if the global database update state is not ready; if some datasourcesare not mapped to databases; if any of the individual database updaters are not in the ready or complete states; ifEntitlementManager is included and a random entry from OEM_LOGIN has a password that cannot be decrypted; if this is a 4.x -> 5.xupgrade and the 4.x version is below the minimum required for a direct upgrade (4.1.2.2 at the time of this writing); if any ofthe system passwords have not been set (SSO directory manager, admin, wsuser, JMX admin, client truststore, if used); if any ofthe endpoints use HTTPS and no client truststore has been provided; if this is an upgrade and any of the included modules havedata referencing locales outside of the selected locale set;

removeJBossNode

Remove the specified node from the system. In order to be removed, the node must be inactive, meaning the Agent must be out ofcommunication for more than the standard node TTL (90 seconds by default). If the node being removed is the SSO primary, the system willselect an alternate SSO primary from any of the other active running SSO nodes. If no alternate SSO primary can be selected, the systemwill switch the SSO state to "Packages Installed", and VMS will become inoperable until an SSO primary can be brought online.

Input Parameters

name type description
node JBossNode Node to remove

Faults

name description
InstallerAutomationWebServiceFault If the node cannot be found by ID; if the node is still active; if the removal operationencountered an error

removeSSLKeystoreForHostname

Remove the SSL Keystore, uploaded for deployment to the specified hostname.

Input Parameters

name type description
hostname string the hostname of the node to which the Ssl Keystore was deployed

Faults

name description
InstallerAutomationWebServiceFault if the delete operation encountered an error

restoreSolrMasterStandbyNode

Restore a Solr Master Standby node that has been switched-over or is in the process of being switched-over to an active Master, back tobeing a standby node. At the time of this operation, there must be an active running Solr Master node. Or, there must be an existingswitched-over Solr Master Standby node.

Input Parameters

name type description
jbossNode JBossNode Solr Master Standby node to be restored. The Solr Master Standby package must be installed and the switch-over operation must have been performed/in-progress.

Faults

name description
InstallerAutomationWebServiceFault If the restore operation fails.

selectLanguages

Select the language set used by VMS and specify the default administrative and system languages. All language parameters passed to thiscall must belong to the supported language set, returned by 'listSupportedLanguages()'. WARNING: If this is an upgrade and there is datain the system that references locales outside the selected set, it will be deleted during database update (a warning is generated whenstarting database update and the user is given the option to expand the locale selection). NOTICE: Select only the locales needed for yourservice; selecting extra locales will degrade performance.

Input Parameters

name type description
selectedLanguages set (no documentation provided)
defaultAdminLang string Default locale for VMS administrators.
defaultSystemLang string Default locale for VMS services.

Faults

name description
InstallerAutomationWebServiceFault If any of the specified locales are outside the supported set; if the save operationencountered an error;

selectPackagesByName

Perform package selection - select packages with names in the specified set

Input Parameters

name type description
packageNames set (no documentation provided)

Faults

name description
InstallerAutomationWebServiceFault If there are active nodes; if any of the specified packages are not available for selection; incase of dependency failures; if the selection process encountered an error.

setAdminPassword

Set the VMS admin password. This password is applied to SSO at configuration/administration time. Changing it here without propagating toSSO (via the InstallerManager UI or the SSO management console) will have no effect on the running system.

Input Parameters

name type description
password string VMS admin password; 8 characters minimum.

Faults

name description
InstallerAutomationWebServiceFault If the password does not meet minimum length; if the save operation encountered an error;

setAdminUsername

Set the administrator user account username. Only applicable for clean installed environments prior to running the database updater.

Input Parameters

name type description
username string (no documentation provided)

Faults

name description
InstallerAutomationWebServiceFault if the username requirements are not met; if the save operation encounters an error;

setJBossLogLevel

Set the JBoss log level for VMS and related packages. This value is applied to JBoss at Agent runtime. Changing it here withoutreinstalling the RPMs has no effect on the running system. Changing log levels at runtime (for troubleshooting purposes) can be done viathe InstallerManager UI.

Input Parameters

name type description
logLevel string The desired log level for VMS and related packages. Supported values are TRACE, DEBUG, WARN, ERROR.

Faults

name description
InstallerAutomationWebServiceFault If the specified value is invalid; if the save operation encountered an error;

setJMXPassword

Set the JBoss JMX console and connector password. This password is applied to JBoss at Agent runtime. Changing this password via this callwithout later reinstalling the RPMs will have no effect on the running system, but will break the InstallerManager features that use theJMX connector (JGroups membership check and instantaneous log level change)

Input Parameters

name type description
password string JBoss JMX console and connector; 8 characters minimum.

Faults

name description
InstallerAutomationWebServiceFault If the password does not meet minimum length; if the save operation encountered an error;

setModClusterProxy

Set the mod_cluster proxy host:port; if mod_cluster is not installed, this operation has no effect.

Input Parameters

name type description
proxy string Mod cluster proxy host:port.

Faults

name description
InstallerAutomationWebServiceFault In case of error

setNfsMountPoint

Set the absolute path to the NFS mountpoint. If the last character is a "/" it will be removed. The directory "/" is also an invalidargument. The NFS mountpoint can be used to store any state data that needs to persist on cloud environments, where the virtual machinemay be torn down. Currently, it is used to store Solr index data.

Input Parameters

name type description
nfsMountPoint string absolute path to NFS mountpoint, eg /mnt/vms

Faults

name description
InstallerAutomationWebServiceFault If the specified path is empty; if the operation encountered an error

setSolrIndexNfsDirectory

Set the name of the directory where Solr indices will be saved on the NFS. This value is used together with the NFS mountpoint value, todetermine the full path. Any "/" characters if specified, will be removed.

Input Parameters

name type description
solrIndexDir string (no documentation provided)

Faults

name description
InstallerAutomationWebServiceFault If the specified name is empty; if the operation encountered an error

setSolrStopwordsFile

Upload the stopwords file used by the Solr Master.

Input Parameters

name type description
stopwordsFileData byte[] the stopwords file data.

Faults

name description
InstallerAutomationWebServiceFault in case of error.

setSSLClientTruststoreAndPassword

Upload a client truststore and set its password. A client truststore is required if any VMS endpoints are configured to use HTTPs. Thetruststore and its password are applied to JBoss at Agent runtime. Changing them via this call without later reinstalling the RPMs willhave no effect on the running system.

Input Parameters

name type description
clientTruststore byte[] Client truststore file containing all necessary certificates to enable SSL communication over applicable endpoints.
password string The password of the client truststore.

Faults

name description
InstallerAutomationWebServiceFault If none of the endpoints use HTTPs; if the save operation encountered an error;

setSSLKeystoreAndPasswordForHostname

Upload a Ssl Keystore and set its password. Also specify the hostname of the node to which this Keystore should be applied. Ssl Keystoresshould be provided for ALL nodes in the deployment, if FULL-HTTPS mode is enabled on the endpoints. Ssl Keystores are not needed for SSLOffloading. Changing them via this call without later reinstalling the RPMs will have no effect on the running system.

Input Parameters

name type description
hostname string the hostname of the node to which the Ssl Keystore shoule be deployed
sslKeystore byte[] (no documentation provided)
password string the password of the keystore

Faults

name description
InstallerAutomationWebServiceFault If full-HTTPS mode is not enabled; if the save operation encountered an error;

setSSODirectoryManagerPassword

Set the SSO directory manager password. This password is applied to SSO at configuration/administration time. WARNING: Changing thispassword via this call without propagating to SSO (via the InstallerManager UI or the SSO management console) will cause VMS to becomeinoperable.

Input Parameters

name type description
password string SSO directory manager password; 8 characters minimum.

Faults

name description
InstallerAutomationWebServiceFault If the password does not meet minimum length; if the save operation encountered an error;

setSSOLogLevel

Set the log level for SSO debug logs.

Input Parameters

name type description
logLevel string The debug log level to set OpenAM to.

Faults

name description
InstallerAutomationWebServiceFault If the specified value is invalid; if the save operation encountered an error;

setSSOLogRotationInterval

Set the log rotation interval in days for SSO debug logs.

Input Parameters

name type description
logRotationIntervalDays string The log rotation inteval to set for OpenAM debug logs.

Faults

name description
InstallerAutomationWebServiceFault If the specified value is invalid; if the save operation encountered an error;

setWsuserPassword

Set the VMS wsuser password. This password is applied to SSO at configuration/administration time, and to various VMS webservices atdatabase update time. WARNING: Changing this password via this call without propagating to SSO (via the InstallerManager UI or the SSOmanagement console) and to VMS webservices (via the InstallerManager UI) will cause VMS to become inoperable.

Input Parameters

name type description
password string VMS wsuser password; 8 characters minimum.

Faults

name description
InstallerAutomationWebServiceFault If the password does not meet minimum length; if the save operation encountered an error;

setWsuserUsername

Set the webservices user account username. Only applicable for clean installed environments prior to running the database updater.

Input Parameters

name type description
username string (no documentation provided)

Faults

name description
InstallerAutomationWebServiceFault if the username requirements are not met; if the save operation encounters an error;

shutdownJBossNode

Enable shutdown mode on the specified node. Shutdown mode blocks the execution of scheduled tasks; it is strongly recommended to removethe node from the load-balancer pool immediately prior to making this call.

Input Parameters

name type description
node JBossNode Node to prepare

Faults

name description
InstallerAutomationWebServiceFault If the node cannot be found by ID; if the update operation encountered an error

switchStandbyMasterToActive

Switch the SOLR Master Standby Node into an Active Mode.

Input Parameters

name type description
jbossNode JBossNode SOLR Master Standby Node to switch to active SOLR Master Node. This node must have a SOLR Master Standby package installed.

Faults

name description
InstallerAutomationWebServiceFault If Main SOLR Master is running or if failed to switch or other failures.

switchStandbyMasterToPassive

Switch the SOLR Master Standby Node into a Passive Mode. Used to switch back to SOLR Master.

Input Parameters

name type description
jbossNode JBossNode SOLR Master Standby Node to switch to passive mode. This node must have a SOLR Master Standby package installed.

Faults

name description
InstallerAutomationWebServiceFault If failed to switch or other failures.

updateCustomFile

Update custom file content. Agents running on nodes hosting this custom file's target module will redeploy the custom file.

Input Parameters

name type description
customFilePk integer Primary key of custom file to update
fileBytes byte[] New custom file content

Faults

name description
InstallerAutomationWebServiceFault If the primary key is invalid or the save operation encountered an error.

updateEndpoints

Update endpoint configuration, setting protocols, hosts, and the SSO cookie domain. Only protocol and hostname values are user-settable;ports, context paths, and traffic types are fixed. All web UI endpoints must reside under the specified SSO cookies domain. The specifiedendpoints collection must include all endpoints in the system; updating a subset at a time is not allowed.

Input Parameters

name type description
endpoints list<Endpoint> The collection of all endpoints in the system, with user-specified protocols and hosts
ssoDomain string The new SSO cookie domain.

Faults

name description
InstallerAutomationWebServiceFault If not all endpoints are included in the specified collection; if an invalid endpoint isspecified (no pk, etc.); in case of validation failures - SSO cookie domain must start with a dot, all web UI endpoints mustreside under the specified SSO cookies domain; hostnames must pass basic validation; results of strict hostname validation thatshow warning messages on the UI are ignored here.

updateEndpointsAndEnableFullHttps

Performs the same function as the updateEndpoints method. Additionally, enables full-https mode so that communication between the loadbalancer and JBoss also takes place over HTTPS. This method can ONLY be invoked if all endpoint protocols are set to HTTPS. All therequirements of the updateEndpoints method apply to this method as well.

Input Parameters

name type description
endpoints list<Endpoint> The collection of all endpoints in the system, with HTTPS protocols and hosts
ssoDomain string The new SSO cookie domain.

Faults

name description
InstallerAutomationWebServiceFault If not all endpoints are included in the specified collection; if any endpoint does not haveHTTPS as its protocol; if an invalid endpoint is specified (no pk, etc.); in case of validation failures - SSO cookie domain muststart with a dot, all web UI endpoints must reside under the specified SSO cookies domain; hostnames must pass basic validation;results of strict hostname validation that show warning messages on the UI are ignored here.