REST API

The Solution Manager provides a REST API to perform programmatically certain tasks. This is useful to automate the creating and deployment of revisions, automate the management of the licenses, etc. The operations to register and deregister servers from the Solution Manager can be used in combination with the auto scaling capabilities of your cloud provider, to start and stop Denodo servers when necessary. The article Configuring Auto Scaling of Denodo in AWS of the Knowledge Base explains how to do this.

Considerations to use this API:

  • The base URL for all the operations (except externalShutdown and pingLicenseManager) is this:

    https://<host of the Solution Manager server>:10090

    10090 is the default port of the Solution Manager.

  • This API supports the following authentication methods:

    • HTTP Basic

    • SPNEGO (Kerberos over HTTP)

    This API is stateless. That is, each request from the client has to contain all of the information necessary to understand the request, including the credentials. This is the usual pattern followed by REST APIs, in which each request is independent from the previous ones.

List of operations:

Some operations are available since an update version. You can see the update version in the operation description.

Get the List of Environments

You can get the list of environments defined in the Solution Manager executing the following request:

  • URL: /environments

  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the list of environments in JSON format. Each environment can contain the following information:

{
    "id": <number>,
    "name": <text>,
    "uuid": <uuid>,
    "description": <text>,
    "minimumUpdateValue":<number>  /* format yyyymmdd */,
    "minimumUpdateMandatory": <boolean> /* the minimum update is mandatory in the Virtual DataPort Administration Tool */,
    "minimumUpdateDownloadUrl": <URL>,
    "licenseAlias": <text>,
    "environmentType": <environment type> /* environment type */
}

<environment type>::= "STANDARD" | "AUTOMATED_AWS"

The following example represents a list of 2 environments.

[
    {
        "id": 1,
        "name": "Environment 1",
        "uuid" : "46984e8e-be0a-4f28-9802-aab0aa03e451",
        "description": "First environment",
        "minimumUpdateMandatory": false,
        "licenseAlias": "PRODUCTION",
        "environmentType": "STANDARD"
    },
    {
        "id": 2,
        "name": "Environment 2",
        "uuid" : "979475f0-51b5-4f2e-af26-09aa76fa72a0",
        "description": "Second environment",
        "minimumUpdateMandatory": false,
        "licenseAlias": "DEVELOPMENT",
        "environmentType": "STANDARD"
    },
    {
        "id": 3,
        "name": "Environment AWS",
        "uuid": "4b6bc266-61f6-4394-9b43-aee507beddbb",
        "description": "",
        "minimumUpdateValue": "",
        "minimumUpdateMandatory": false,
        "minimumUpdateDownloadUrl": "",
        "licenseAlias": "PRODUCTION",
        "environmentType": "AUTOMATED_AWS"
    }
]

Create an Environment

Endpoint to create an environment:

  • URL: /environments

  • Method: POST

  • Syntax of the body of the request:

{
    "name": <text>,
    "description": <text>,  /* optional */
    "minimumUpdateValue":<number>  /* /* optional, format yyyymmdd */,
    "minimumUpdateMandatory": <boolean> /* optional, the minimum update is mandatory in the Virtual DataPort Administration Tool */,
    "minimumUpdateDownloadUrl": <URL> /* optional */,
    "licenseAlias": <text>,    /* optional, assign a license to this environment */
    "environmentType": <environment type>  /* only "STANDARD" <environment type> is supported */
}

<environment type>::= "STANDARD" | "AUTOMATED_AWS"

Note

To assign a license to the environment, indicate the license alias. To obtain it, use the operation licenseAlias.

Note

This operation only allows to create standard environments.

If the request succeeds, the service returns the HTTP code 201 and a response that contains the id of the new environment.

Example

In this example, we create a file “new_environment.json” with the body of the request and then, use cURL to send a request with the content of this file.

Content of the file “new_environment.json”
{
    "name": "finance-development",
    "description": "Environment for the development servers allocated to the finance department",
    "minimumUpdateValue": "20190312",
    "minimumUpdateDownloadUrl": "https://denodo-repository.acme.com/denodo-v70-update-20190903.zip",
    "minimumUpdateMandatory": true,
    "licenseAlias": "DEVELOPMENT",
    "environmentType": "STANDARD"
}
Example of a request to the operation “create environment” using “cURL”
curl --data @new_environment.json --header "Content-Type: application/json" --user "jsmith" "https://solution-manager.acme.com:10090/environments"
Example of a response of the operation “create environment”
{
    "id": 1,
    "name": "finance-development",
    "uuid": "d7bea1bb-8aa6-4161-bdbe-f976fdfb6d1f",
    "description": "Environment for the development servers allocated to the finance department",
    "minimumUpdateValue": "20190312",
    "minimumUpdateDownloadUrl": "https://denodo-repository.acme.com/denodo-v70-update-20190903.zip",
    "minimumUpdateMandatory": true,
    "licenseAlias": "DEVELOPMENT",
    "environmentType": "STANDARD"
}

Get the List of Licenses Available

Get the list of licenses available license loaded in the Solution Manager.

  • URL: /licenseAlias

  • Method: GET

If the request succeeds, the service returns the HTTP code 200 and the body of the response contains the list of licenses in JSON format. Each license can contain the following information:

{
    "alias": <text>,  /* license alias name */
    "licenseType": <license type>,  /* license type */
    "version": <text>,  /* licence version number, i.e: 8.0 */
    "uniqueLicenseType": boolean /* indicates if there is more than one license with the same type */
}

<license type>::=
      "PRODUCTION"
    | "STAGING"
    | "HOT_BACKUP"
    | "COLD_BACKUP"
    | "DEVELOPMENT"
    | "PERSONAL_DEVELOPER"
    | "TRAINING"
    | "EVALUATION"
    | "EXPRESS"
    | "TESTING"

Example of response

[{
        "alias": "DEVELOPMENT",
        "licenseType": "DEVELOPMENT",
        "version": "8.0",
        "uniqueLicenseType": true
    }, {
        "alias": "PERSONAL_DEVELOPER",
        "licenseType": "PERSONAL_DEVELOPER",
        "version": "8.0",
        "uniqueLicenseType": true
    }, {
        "alias": "PRODUCTION",
        "licenseType": "PRODUCTION",
        "version": "8.0",
        "uniqueLicenseType": true
    }
]

Update an Environment

Operation to modify the configuration of an environment.

  • URL: /environments/{number:environmentId}

  • Method: PUT

  • Syntax of the body of the request:

    {
    "name": <text>,
    "description": <text>,  /* optional */
    "minimumUpdateValue": <number>,  /* optional, format yyyymmdd */
    "minimumUpdateMandatory": <boolean>, /* optional, the minimum update is mandatory in the Virtual DataPort Administration Tool */
    "minimumUpdateDownloadUrl": <URL>, /* optional */
    "licenseAlias": <text>,    /* optional, associate the environemnt with a license */
    "environmentType": <environment type>  /* only "STANDARD" <environment type> is supported */
}

<environment type>::= "STANDARD" | "AUTOMATED_AWS"

Note

This operation only allows to update standard environments.

If the request succeeds, the service returns the HTTP code 200 and the body of the response contains a JSON document with the settings of the environment.

Example

Example of a PUT request:

{
    "name": "env",
    "description": "new description of the environment",
    "minimumUpdateValue": "20190312",
    "minimumUpdateDownloadUrl": "http://denodo.com/update20190312.zip",
    "minimumUpdateMandatory": false,
    "licenseAlias": "DEVELOPMENT",
    "environmentType": "STANDARD"
}

Sample response:

{
    "id": 1,
    "name": "env",
    "uuid": "979475f0-51b5-4f2e-af26-09aa76fa72a0",
    "description": "sample updated environment",
    "minimumUpdateValue": "20190312",
    "minimumUpdateMandatory": false,
    "minimumUpdateDownloadUrl": "http://denodo.com/update20190312.zip",
    "licenseAlias": "DEVELOPMENT",
    "environmentType": "STANDARD"
}

Delete an Environment

Delete an environment, and all the clusters and servers within the environment:

  • URL: /environments/{number:environmentId}

  • Method: DELETE

Example

The following request deletes the environment with identifier 1 and its clusters and servers:

DELETE https://solution-manager.acme.com:10090/environments/1

If the request succeeds, the service returns the HTTP code 204.

Update AWS Global Credentials

Available since 8.0 update 20210715.

This operation updates the global AWS credentials access keys:

  • URL: /configuration/credentials/aws

  • Method: POST

  • Syntax of the body of the request:

    {
    "accessKeyId": <text>, /* Mandatory. Access key id */
    "secretAccessKey": <text>  /* Mandatory. Secret access key */
}

Consider this:

  • Both parameters are mandatory (accessKeyId and secretAccessKey).

  • You can indicate the value of secretAccessKey in plain text or encrypted. To encrypt this value, use the script <SOLUTION_MANAGER_HOME>/bin/encrypt_password.

Note

This operation only allows to update global AWS credentials.

If the request succeeds, the service returns the HTTP code 200.

Example

Example of a POST request to update AWS global credentials:

{
    "accessKeyId" : "accessKeyId",
    "secretAccessKey" : "clearOrEncryptedSecretAccessKey"
}

Update AWS Environment Credentials

Available since 8.0 update 20210715.

This operation updates the credentials of a specific AWS environment:

  • URL: /environments/{number:environmentId}/credentials

  • Method: POST

  • Syntax of the body of the request:

    {
    "accessKeyId": <text>, /* Mandatory. Access key id */
    "secretAccessKey": <text>  /* Mandatory. Secret access key */
}

Consider this:

  • Both parameters are mandatory (accessKeyId and secretAccessKey).

  • You can indicate the value of secretAccessKey in plain text or encrypted. To encrypt this value, use the script <SOLUTION_MANAGER_HOME>/bin/encrypt_password.

If the request succeeds, the service returns the HTTP code 200.

Example

Example of a POST request to update the credentials for AWS environment with id 1:

POST https://solution-manager.acme.com:10090/environments/1/credentials

{
    "accessKeyId" : "accessKeyId",
    "secretAccessKey" : "clearOrEncryptedSecretAccessKey"
}

Update Azure Global Credentials

Available since 8.0 update 20220126.

This operation updates the global Azure credentials access keys:

  • URL: /configuration/credentials/azure

  • Method: POST

  • Syntax of the body of the request:

    {
    "subscriptionId": <text>, /* Mandatory */
    "clientId": <text>,  /* Mandatory */
    "tenantId": <text>,  /* Mandatory */
    "secret": <text>  /* Mandatory */
}

Consider this:

  • All the parameters are mandatory.

  • You can indicate the value of secret in plain text or encrypted. To encrypt this value, use the script <SOLUTION_MANAGER_HOME>/bin/encrypt_password.

Note

This operation only allows to update global Azure credentials.

If the request succeeds, the service returns the HTTP code 200.

Example

Example of a POST request to update AWS global credentials:

{
    "subscriptionId" : "subscriptionId",
    "clientId" : "clientId",
    "tenantId" : "tenantId",
    "secret" : "clearOrEncryptedSecret"
}

Update Azure Environment Credentials

Available since 8.0 update 20220126.

This operation updates the credentials of a specific Azure environment:

  • URL: /environments/{number:environmentId}/credentials

  • Method: POST

  • Syntax of the body of the request:

     {
    "subscriptionId": <text>, /* Mandatory */
    "clientId": <text>,  /* Mandatory */
    "tenantId": <text>,  /* Mandatory */
    "secret": <text>  /* Mandatory */
}

Consider this:

  • Both parameters are mandatory.

  • You can indicate the value of secret in plain text or encrypted. To encrypt this value, use the script <SOLUTION_MANAGER_HOME>/bin/encrypt_password.

If the request succeeds, the service returns the HTTP code 200.

Example

Example of a POST request to update the credentials for AWS environment with id 1:

POST https://solution-manager.acme.com:10090/environments/1/credentials

{
    "subscriptionId" : "subscriptionId",
    "clientId" : "clientId",
    "tenantId" : "tenantId",
    "secret" : "clearOrEncryptedSecret"
}

Start Automated Mode Cluster

Available since 8.0 update 20210715.

This operation starts a cluster that was created in automated mode:

  • URL: /clusters/{number:clusterId}/start

  • Method: POST

If the request succeeds, the service returns the HTTP code 204.

Example

Example of a POST request to start an AWS cluster with id 1:

POST https://solution-manager.acme.com:10090/clusters/1/start

Stop Automated Mode Cluster

Available since 8.0 update 20210715.

This operation stops a cluster that was created in automated mode:

  • URL: /clusters/{number:clusterId}/stop

  • Method: POST

If the request succeeds, the service returns the HTTP code 204.

Example

Example of a POST request to stop an AWS cluster with id 1:

POST https://solution-manager.acme.com:10090/clusters/1/stop

Restart Automated Mode Cluster

Available since 8.0 update 20210715.

This operation restarts a cluster created in automated mode:

  • URL: /clusters/{number:clusterId}/restart

  • Method: POST

If the request succeeds, the service returns the HTTP code 204.

Example

Example of a POST request to restart an AWS cluster with id 1:

POST https://solution-manager.acme.com:10090/clusters/1/restart

Recreate Automated Mode Cluster

Available since 8.0 update 20210715.

This operation recreates partially or completely a cluster that was created in automated mode.

Important

If you made manual changes in some of the servers, you will lose those changes when recreating the cluster. If you want to keep them, use the operation to recreate from servers.

  • URL: /clusters/{number:clusterId}/recreate

  • Method: POST

  • Syntax of the body of the request:

    {
    "servers" : [ /* List with the type of product cluster servers to recreate */
       {
         "typeNode": <server type> /* Server type to recreate */
       }
    ],
    "withZeroDowntime": <boolean> /* To specify if the recreate process is performed minimizing downtime (true) or not (false) */
}

<server type>::= "VDP" | "SCHEDULER" | "VDP_DATA_CATALOG"

If the request succeeds, the service returns the HTTP code 204.

Partial recreate cluster example without minimizing downtime

Example of a POST request to recreate only Virtual DataPort product cluster for an AWS cluster with id 1 without minimizing downtime:

POST https://solution-manager.acme.com:10090/clusters/1/recreate

{
  "servers": [
    {
      "typeNode": "VDP"
    }
  ],
  "withZeroDowntime": false
}

Complete recreate cluster example with minimizing downtime option

Example of a POST request to recreate a complete cluster for an AWS cluster with id 1 with minimizing downtime option:

POST https://solution-manager.acme.com:10090/clusters/1/recreate

{
  "servers": [
    {
      "typeNode": "VDP"
    },
    {
      "typeNode": "SCHEDULER"
    },
    {
      "typeNode": "VDP_DATA_CATALOG"
    }
  ],
  "withZeroDowntime": true
}

Recreate From Servers Automated Mode Cluster

Available since 8.0 update 20210715.

This operation recreates an automated mode cluster using a server as template.

Important

We recommend to invoke this operation if you performed manual changes in a server and you want to replicate the changes in the corresponding product cluster.

Note

It is not possible to perform this operation minimizing downtime.

  • URL: /clusters/{number:clusterId}/recreateFromServers

  • Method: POST

  • Syntax of the body of the request:

    {
    "servers" : [ /* List with the type of product cluster servers to recreate */
       {
         "typeNode": <server type>, /* Server type to recreate */
         "instanceId": <text> /* Instance id of the server that will be used as the base for the recreation process */
       }
    ]
}

<server type>::= "VDP" | "SCHEDULER" | "VDP_DATA_CATALOG"

If the request succeeds, the service returns the HTTP code 204.

Partial recreate cluster from servers example

Example of a POST request to recreate from server only Virtual DataPort product cluster for an AWS cluster with id 1:

POST https://solution-manager.acme.com:10090/clusters/1/recreateFromServers

{
  "servers": [
    {
      "typeNode": "VDP",
      "instanceId": "virtualDataPortServerInstanceId"
    }
  ]
}

Complete recreate from servers example

Example of a POST request to recreate from server a complete cluster for an AWS cluster with id 1:

POST https://solution-manager.acme.com:10090/clusters/1/recreateFromServers

{
  "servers": [{
      "typeNode": "VDP",
      "instanceId": "virtualDataPortServerInstanceId"
    },
    {
      "typeNode": "SCHEDULER",
      "instanceId": "schedulerServerInstanceId"
    },
    {
      "typeNode": "VDP_DATA_CATALOG",
      "instanceId": "dataCatalogServerInstanceId"
    }
  ]
}

Install Denodo Update Automated Mode Cluster

Available since 8.0 update 20210715.

This operation installs an update of Denodo in a cluster that was created in automated mode. The update has to be located in an AWS S3 bucket.

  • URL: /clusters/{number:clusterId}/installDenodoUpdate

  • Method: POST

  • Syntax of the body of the request:

     {
  "denodoProductClusterUpdateDtos": [
    {
      "updateType": "S3", /* Type of update. Only S3 allowed */
      "typeNode": <server type>, /* Type of the server where the update is installed */
      "arnProfileForS3Access": <text>, /* ARN of the instance profile role that grants access to the S3 bucket where the update file is stored */
      "s3UpdatePath": <text> /* Complete path to the Denodo update file */
    }
  ],
  "withZeroDowntime": <boolean> /* To specify if the Denodo update installation process is performed minimizing downtime (true) or not (false) */
}

 <server type>::= "VDP" | "SCHEDULER" | "VDP_DATA_CATALOG"

If the request succeeds, the service returns the HTTP code 204.

Install update in a specific server type example

Example of a POST request to install a denodo update only in the Virtual DataPort servers for an AWS cluster with id 1 without minimizing downtime:

POST https://solution-manager.acme.com:10090/clusters/1/installDenodoUpdate

{
  "denodoProductClusterUpdateDtos": [
    {
      "updateType": "S3",
      "typeNode": "VDP",
      "arnProfileForS3Access": "arn:aws:iam::accountId:instance-profile/instanceProfileRoleName",
      "s3UpdatePath": "s3://bucketaNme/folderPath/denodoUpdateFile.zip"
    }
  ],
  "withZeroDowntime": false
}

Install update in all the types of servers example

Example of a POST request to install a specific update in each type of server for an AWS cluster with id 1 with minimizing downtime enabled:

POST https://solution-manager.acme.com:10090/clusters/1/installDenodoUpdate

{
  "denodoProductClusterUpdateDtos": [
    {
      "updateType": "S3",
      "typeNode": "VDP",
      "arnProfileForS3Access": "arn:aws:iam::accountId:instance-profile/instanceProfileRoleName",
      "s3UpdatePath": "s3://bucketName/folderPath/denodoUpdateFile.zip"
    }, {
      "updateType": "S3",
      "typeNode": "VDP_DATA_CATALOG",
      "arnProfileForS3Access": "arn:aws:iam::accountId:instance-profile/instanceProfileRoleName",
      "s3UpdatePath": "s3://bucketName/folderPath/denodoUpdateFile.zip"
    }, {
      "updateType": "S3",
      "typeNode": "SCHEDULER",
      "arnProfileForS3Access": "arn:aws:iam::accountId:instance-profile/instanceProfileRoleName",
      "s3UpdatePath": "s3://bucketName/folderPath/denodoUpdateFile.zip"
    }
  ],
  "withZeroDowntime": true
}

Get the List of Virtual DataPort Properties Associated to an Environment

Obtain the list of the Virtual DataPort properties defined on an environment.

  • URL: /environments/{number:environmentId}/vdpProperties

  • Method: GET

  • URL parameters. All of them are optional and can be combined:

    • propertyName: this parameter specifies an exact property name. If the URL contains this parameter, the operation ignores the parameters below.

    • databaseName: filters properties by database name.

    • elementType: filters properties by element type (for example, view or data source).

    • elementTypeName: filters properties by element type name (for example, JDBC, XML, etc.).

    • elementName: filters properties by element name.

The URL path must include the environment identifier.

The response has this format:

{
    "environmentProperties": [
        {
            "id": <number>,
            "name": <text>,
            "value": <text>,
            "propertyType": "VDP",
            "parentId": <number>,
            "undefined": <boolean>
        },
        { ... }
   ]
}

Example #1

The following example represents a response that returns the properties of the environment with identifier 4.

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/4/vdpProperties"
Response
 {
     "environmentProperties": [
         {
             "id": 30,
             "name": "users.smadmin.PASSWORD",
             "value": "mYgfbAayggeImPPOGfklFLfgt ...",
             "propertyType": "VDP",
             "parentId": 3,
             "undefined":false
         },
         {
             "id": 32,
             "name": "users.smadmin.PASSWORD.ALGORITHM",
             "value": "SHA512",
             "propertyType": "VDP",
             "parentId": 3,
             "undefined":false
         },
         {
             "id": 31,
             "name": "users.smadmin.PASSWORD.ENCRYPTED",
             "value": "ENCRYPTED",
             "propertyType": "VDP",
             "parentId": 3,
             "undefined":false
         },
         {
             "id": 32,
             "name": "undefinedProperty",
             "value": "",
             "propertyType": "VDP",
             "parentId": 1,
             "undefined": true
         }
     ]
}

Example #2

The following URL uses the parameter propertyName to obtain the value of the property users.smadmin.PASSWORD.ALGORITHM in the environment with id #2.

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/2/vdpProperties?propertyName=users.smadmin.PASSWORD.ALGORITHM"

This parameter cannot be combined with others.

Example #3

The following URL uses the parameter databaseName to obtain the properties defined for the database “admin”:

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/2/vdpProperties?databaseName=admin"

Example #4

The following URL uses the parameter elementType to obtain the properties of the data sources:

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/2/vdpProperties?elementType=datasources"

Example #5

The following URL uses the parameter elementTypeName to obtain the properties of all the JDBC data sources:

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/2/vdpProperties?elementTypeName=jdbc"

Example #6

The following URL uses the parameter elementName to obtain the properties of the elements whose name is “oracle12c”:

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/2/vdpProperties?elementName=oracle12c"

Example #7

The following URL uses the parameters databaseName, elementType and elementTypeName to obtain the properties of the LDAP data sources of the database admin:

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/2/vdpProperties?databaseName=admin&elementType=datasources&elementTypeName=ldap"

Create and Delete Environment Properties

If you execute a POST request to the following URL you can create an environment property:

  • URL: /environments/{number:environmentId}/vdpProperties

  • Method: POST

The request body must include the list of properties, according to the following format:

[
   {
        "name" : <text>,
        "value" : <text>
        "undefined" : <boolean>, /* optional */
        "valueEncrypted" : <boolean> /* optional */
   },
   { ... }
]

The undefined property is not mandatory, if you do not indicate it, this value is false by default.

The Solution Manager stores some properties as encrypted, such as passwords, depending on the name of the property. For this properties, the Solution Manager accepts the following values:

  • clear value

  • value encrypted with the encrypt_password script located in <SOLUTION_MANAGER_HOME>/bin

  • value encrypted by Denodo server (VDP)

The valueEncrypted property is not mandatory. This property can be used to check that the value encrypted with the encrypt_password is valid.

If valueEncrypted is false, the value is consider as clear text.

If valueEncrypted is true, the value is consider as encripted. If the encrypted value is invalid an error will be thrown.

If valueEncrypted is not defined, the value is considered first as a value encrypted with encrypt_password script and if it is not valid it is considered a clear value.

The example below shows a POST request which creates some properties:

[
    {
        "name": "users.smadmin.PASSWORD",
        "value": "7mclUPUm5bGx2L3KBLmzQsnO1o533AwYCAfk+oztHHqZIZ33Ow7w ... "
    }, {
        "name": "users.smadmin.PASSWORD.ALGORITHM",
        "value": "SHA512"
    }, {
        "name": "users.acme.PASSWORD",
        "value": "mypassword",
        "valueEncrypted" : false
    }, {
        "name": "users.acme.PASSWORD.ALGORITHM",
        "value": "SHA512"
    }, {
        "name": "undefinedProperty",
        "value": "",
        "undefined": true
    }, {
        "name": "databases.admin.datasources.jdbc.acmeOracle10gDs.USERPASSWORD",
        "value": "C6zZSBoi55Oxgfxir6AX6YH7Ve5RjCfuQAPTpXsCYeQDkIg6xvVT ... "
    }, {
        "name": "databases.admin.datasources.jdbc.dsAcmeOracle11g.USERPASSWORD",
        "value": "C6zZSBoi55Oxgfxir6AX6YH7Ve5RjCfuQAPTpXsCYeQDkIg6xvVT ... ",
        "valueEncrypted": true
    }, {
        "name": "databases.admin.datasources.jdbc.dsAcmeOracle12c.USERPASSWORD",
        "value": "y0DVUNiFjBzyME8Oes6ErRZDT+ppEFScSfjSnRnLh36eAjhervMM ... "
    }, {
        "name": "databases.admin.datasources.jdbc.dsAcmeSqlServer.USERPASSWORD",
        "value": "y0DVUNiFjBzyME8Oes6ErRZDT+ppEFScSfjSnRnLh36eAjhervMM ... ",
        "valueEncrypted": true
    }, {
        "name": "databases.admin.datasources.jdbc.dsAcmeMySql4.USERPASSWORD",
        "value": "denodo"
    }, {
        "name": "databases.admin.datasources.jdbc.dsAcmeMySql5.USERPASSWORD",
        "value": "denodo",
        "valueEncrypted": false
    }
]

This example shows the different values supported to add user PASSWORD and datasource USERPASSWORD:

  • value ‘mypassword’ encrypted by Denodo server for user smadmin

  • clear value ‘mypassword’ for user acme

  • value ‘denodo’ encrypted by Denodo server for acmeOracle10gDs and acmeOracle11gDs

  • value ‘denodo’ encrypted with encrypt_password script for dsAcmeOracle12c and dsAcmeSqlServer

  • clear value ‘denodo’ for dsAcmeMySql4 and dsAcmeMySql5

The response body contains the new properties with their identifiers:

[
    {
        "id": 30,
        "name": "users.smadmin.PASSWORD",
        "value": "7mclUPUm5bGx2L3KBLmzQsnO1o533AwYCAfk+oztHHqZIZ33Ow7w ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 31,
        "name": "users.smadmin.PASSWORD.ALGORITHM",
        "value": "SHA512",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 32,
        "name": "users.acme.PASSWORD",
        "value": "zAo2EsLelqX34qRZkIOti7mqYebZfMHSpo/Gg2VVm2JgteBRznki ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 33,
        "name": "users.acme.PASSWORD.ALGORITHM",
        "value": "SHA512",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 34,
        "name": "undefinedProperty",
        "value": "",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": true
    }, {
        "id": 35,
        "name": "databases.admin.datasources.jdbc.acmeOracle10gDs.USERPASSWORD",
        "value": "C6zZSBoi55Oxgfxir6AX6YH7Ve5RjCfuQAPTpXsCYeQDkIg6xvVTj ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 37,
        "name": "databases.admin.datasources.jdbc.dsAcmeOracle11g.USERPASSWORD",
        "value": "C6zZSBoi55Oxgfxir6AX6YH7Ve5RjCfuQAPTpXsCYeQDkIg6xvVTj ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 39,
        "name": "databases.admin.datasources.jdbc.dsAcmeOracle12c.USERPASSWORD",
        "value": "MqBvb2IsfX4MITlV1W3SxoYfNhX4xS/KJAsKP85i2Q8a4G+oCiYK ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 41,
        "name": "databases.admin.datasources.jdbc.dsAcmeSqlServer.USERPASSWORD",
        "value": "t0cDdrY54hKNyOibbbdisaUUk+P0z/glf+XV2TwAnalxLtrv8fJi ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 43,
        "name": "databases.admin.datasources.jdbc.dsAcmeMySql4.USERPASSWORD",
        "value": "M/qun/6aOiyklDw1MWAmrLt9k7rQcz77Zt8MRE0w7XdzqxcOjYvS ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }, {
        "id": 45,
        "name": "databases.admin.datasources.jdbc.dsAcmeMySql5.USERPASSWORD",
        "value": "4SQ9CRkgv3jwi4DWJAicjF1rU63q47bxocI7gpd+rbusc65qFlwM ... ",
        "propertyType": "VDP",
        "parentId": 4,
        "undefined": false
    }
]

The Solution Manager will return the property password values as encrypted.

If you send a DELETE request to the following URL, you can delete an environment property:

  • URL: /vdpProperties/{number:vdpPropertyId}

  • Method: DELETE

The next example deletes a property with the identifier 5:

DELETE https://solution-manager.acme.com:10090/vdpProperties/5

If the property has been successfully deleted, the response status code is 204.

Get the List of Clusters

The following request returns the list of clusters of an environment:

  • URL: /environments/{number:environmentId}/clusters

  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the list of clusters in JSON format. Each cluster can contain the following information:

{
    "clusters": [
        {
            "id": <number>,
            "name": <text>,
            "uuid": <uuid>,
            "enabled": <boolean>,
        },
        { ... }
    ]
}

The following example returns a list with 2 clusters.

{
    "clusters": [
        {
            "id": 7,
            "name": "Cluster 2",
            "uuid": "a5c4fdea-9545-44d3-b462-44ee4ca3f567",
            "enabled": true
        },
        {
            "id": 8,
            "name": "Cluster 3",
            "uuid": "5a7cd9f1-6444-4900-aafd-b11148681a39",
            "enabled": false
        }
    ]
}

Create a Cluster

If you execute a POST request to the following URL you can create a cluster:

  • URL: /clusters

  • Method: POST

Note

This operation only allows to create clusters in standard environments.

The request body has to follow this format:

{
    "name": <text>,
    "description": <text>, /* optional */
    "environmentId": <number>,
    "enabled": <boolean>,
    "externalDesignStudioUrl": <text>, /* optional */,
    "vdpUrlBalancer": <text>, /* optional */,
    "externalSchedulerAdminToolUrl": <text>, /* optional */,
    "schUrlBalancer": <text>, /* optional */,
    "dcUrlBalancer": <text>, /* optional */
}

If the servers are running behind a load balancer you can fill additional information regarding how to access the corresponding tool in the main panel:

  • externalDesignStudioUrl: URL of the Design Studio that will appear under “My Applications” for the cluster.

  • vdpUrlBalancer: URL of the Virtual DataPort servers load balancer that will appear under “My Applications” for the cluster.

  • externalSchedulerAdminToolUrl: URL of the Scheduler Administration Tool load balancer that will appear under “My Applications” for the cluster.

  • schUrlBalancer: URL of the Scheduler servers load balancer that will appear under “My Applications” for the cluster.

  • dcUrlBalancer: URL of the Data Catalog load balancer that will appear under “My Applications” for the cluster.

The environmentId is the environment identifier that can be obtained in Get the List of Environments

If the cluster has been successfully inserted, the response status code is 201.

Basic cluster creation example

The following example shows a POST request which creates a cluster in standard mode:

{
    "name": "clusterSample",
    "description": "A cluster sample",
    "environmentId": 1,
    "enabled": true
}

The response body contains the added cluster with its identifier:

{
    "id": 10,
    "name": "clusterSample",
    "uuid": "30facc8e-7973-4817-9e95-8a6e0ebd3b0e",
    "description": "A cluster sample",
    "order": 1,
    "environmentId": 1,
    "enabled": true
}

The returned order indicates the order of the cluster within the environment.

Create a cluster with some external load balancers URLs

The following example shows a POST request which creates a cluster in environment with id 1 with load balancer information to access the different servers in the main panel:

{
    "name": "Cluster sample with LB",
    "description": "Cluster sample with Load Balancers",
    "environmentId": 1,
    "enabled": true,
    "externalDesignStudioUrl": "http://load-balancer.acme.org:9090/denodo-design-studio",
    "vdpUrlBalancer": "//load-balancer.acme.org:9999",
    "externalSchedulerAdminToolUrl": "http://load-balancer.acme.org:9090/webadmin/denodo-scheduler-admin",
    "schUrlBalancer": "//load-balancer.acme.org:8000",
    "dcUrlBalancer": "http://load-balancer.acme.org:9090/denodo-data-catalog"
}

Get a Cluster

The following request returns the list of clusters of an environment:

  • URL: /clusters/{number:clusterId}

  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the cluster in JSON format with the following information:

{
    "id": <number>,
    "name": <text>,
    "uuid": <uuid>,
    "description": <text>,
    "order": <number>,
    "environmentId": <number>,
    "enabled": <boolean>
}

The following example returns the cluster with id 10.

{
    "id": 10,
    "name": "clusterSample",
    "uuid": "a5c4fdea-9545-44d3-b462-44ee4ca3f567",
    "description": "A cluster sample",
    "order": 1,
    "environmentId": 1,
    "enabled": true
}

Get Cluster Status

The following request returns information regarding the status of a cluster:

  • URL: /clusters/{number:clusterId}/status

  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the following information about the cluster status in JSON format with the following information:

{
    "clusterId": <number>,
    "status": <cluster status>,
    "lastOperationType": <operation type>,
    "lastOperationStatus": <operation status>
}

<cluster status>::=
    "AWAITING_SERVICES"
  | "AWAITING_SERVICES_ONE_REGISTERED"
  | "DELETED"
  | "DELETING"
  | "ERROR"
  | "INITIALIZING"
  | "OK"
  | "PENDING"
  | "RESTARTING"
  | "RECREATING_CLUSTER_ZERO_DOWNTIME"
  | "RECREATING_FROM_SERVERS"
  | "STARTING"
  | "STOPPED"
  | "STOPPING"
  | "WARNING"
  | "PENDING_RECREATION"
  | "PENDING_CONFIGURATION"

<operation type>::=
    "CREATING_CLUSTER"
  | "MODIFYING_CLUSTER"
  | "STARTING"
  | "STOPPING"
  | "RESTARTING"
  | "RECREATING_CLUSTER_ZERO_DOWNTIME"
  | "LAUNCHING_CLUSTER_UPDATE"
  | "DELETING_CLUSTER"
  | "LAUNCHING_CLUSTER_DEPLOYMENT"
  | "RECREATING_CLUSTER"
  | "RECREATING_CLUSTER_FROM_SERVERS"

<operation status>::=
    "IN_PROGRESS"
  | "OK"
  | "ERROR"
  | "PENDING"
  | "WARNING"
  | "SKIPPED"

In the response the following fields are common for any type of cluster:

  • clusterId: Id of the cluster.

  • status: Status of the cluster. You can see the different status for a cluster in the overview screen here. Standard clusters will be in “OK” status.

The following fields are specific for automated mode clusters:

  • lastOperationType: Last operation performed with the cluster (creation, start, stop, deployment, update…)

  • lastOperationStatus: Status of the last operation in the cluster.

The following example returns the status of an automated cluster with id 10 after an stop operation.

{
    "clusterId": 10,
    "status": "STOPPED",
    "lastOperationType": "STOPPING",
    "lastOperationStatus": "OK"
}

Update a Cluster

If you execute a PUT request to the following URL you can update a cluster:

  • URL: /clusters/{number:clusterId}

  • Method: PUT

Note

This operation only allows to update clusters in standard environments.

The request body has to follow this format:

{
    "name": <text>,
    "description": <text>,  /* optional */
    "environmentId": <number>,
    "enabled": <boolean>,
    "externalDesignStudioUrl": <text>, /* optional */,
    "vdpUrlBalancer": <text>, /* optional */,
    "externalSchedulerAdminToolUrl": <text>, /* optional */,
    "schUrlBalancer": <text>, /* optional */,
    "dcUrlBalancer": <text>, /* optional */
}

If the cluster has been successfully updated, the response status code is 200.

Update cluster example

The next example shows a PUT request which update the cluster with id 10:

{
    "name": "clusterSample updated",
    "description": "A cluster sample updated",
    "enabled": true
}

The response body contains the udpated cluster:

{
    "id": 10,
    "name": "clusterSample updated",
    "uuid": "a5c4fdea-9545-44d3-b462-44ee4ca3f567",
    "description": "A cluster sample updated",
    "order": 1,
    "environmentId": 1,
    "enabled": true
}

Update a cluster with some external load balancers URLs

The next example shows a PUT request which updates a cluster with id 10 with load balancer information to access the different servers in the main panel:

{
    "name": "Updated cluster sample with LB",
    "description": "Updated cluster sample with Load Balancers",
    "enabled": true,
    "externalDesignStudioUrl": "http://load-balancer.acme.org:9090/denodo-design-studio",
    "vdpUrlBalancer": "//load-balancer.acme.org:9999",
    "externalSchedulerAdminToolUrl": "http://load-balancer.acme.org:9090/webadmin/denodo-scheduler-admin",
    "schUrlBalancer": "//load-balancer.acme.org:8000",
    "dcUrlBalancer": "http://load-balancer.acme.org:9090/denodo-data-catalog"
}

Delete a Cluster

If you send a DELETE request to the following URL, you can delete a cluster:

  • URL: /clusters/{number:clusterId}

  • Method: DELETE

The next example deletes a cluster with the identifier 10:

DELETE https://solution-manager.acme.com:10090/clusters/10

If the cluster has been successfully deleted, the response status code is 204. This operation deletes all the servers contained in the cluster.

Get the List of Scheduler Properties Associated to a Cluster

The following URL returns the list of Scheduler properties for a given cluster:

  • URL: /clusters/{number:clusterId}/schProperties

  • Method: GET

  • Parameters:

    • propertyName: this parameter specifies an exact property name.

    • projectName: this parameter filters properties by project name.

    • elementType: this parameter filters properties by element type (for example, data source).

    • elementTypeName: this parameter filters properties by element type name (for example, VDP).

    • elementName: this parameter filters properties by element name.

The URL path must include the cluster identifier. The following URL returns the Scheduler properties for the cluster with the identifier 3.

curl --user "jsmith" "https://solution-manager.acme.com:10090/cluster/3/schProperties"

Optional Request Parameters to Filter Cluster Properties

The following URL specifies the parameter propertyName and returns a Scheduler property with name SolutionManager.dataSource.ITP.itpds.dbName.

curl --user "jsmith" "https://solution-manager.acme.com:10090/clusters/4/schProperties?propertyName=SolutionManager.dataSource.ITP.itp.dbName"

Note

If propertyName is specified, the other parameters are ignored.

The parameter projectName filters properties by project. The following URL returns all properties matching SolutionManager.*

curl --user "jsmith" "https://solution-manager.acme.com:10090/clusters/2/schProperties?projectName=SolutionManager"

The parameter elementType filters properties by element type. The following URL returns all properties matching *.datasource.*. Example: SolutionManager.dataSource.ITP.itpds.host.

curl --user "jsmith" "https://solution-manager.acme.com:10090/clusters/2/schProperties?elementType=datasource"

The parameter elementTypeName filters properties by element type name. The following URL returns all properties related with ITP. Example: SolutionManager.dataSource.ITP.itpds.host.

curl --user "jsmith" "https://solution-manager.acme.com:10090/clusters/2/schProperties?elementTypeName=ITP"

The parameter elementName filters properties by element name. The following URL returns the properties of the data source named itpds.

curl --user "jsmith" "https://solution-manager.acme.com:10090/clusters/2/schProperties?elementName=itpds"

Except the parameter propertyName, the others can be combined in the same request. For example, the following URL returns all data source properties of the project SolutionManager.

curl --user "jsmith" "https://solution-manager.acme.com:10090/clusters/2/schProperties?projectName=SolutionManager&elementType=datasource"

Create and Delete Cluster Properties

You can execute a POST request to the following URL to create cluster properties:

  • URL: /clusters/{number:clusterId}/schProperties

  • Method: POST

The request body must include the list of properties, according to the following format:

[
   {
        "name" : <text>,
        "value" : <text>,
        "undefined" : <boolean>, /* optional */
        "valueEncrypted" : <boolean> /* optional */
   },
   { ... }
]

The undefined attribute is optional; if you do not indicate it, this value is false by default.

About the attribute valueEncrypted, consider this:

  • The Solution Manager stores encrypted the values of properties that represent passwords of data sources, user accounts and other values. However, when you use the API to define these properties, you can send their value encrypted or in clear text.

    The values the Solution Manager stores encrypted are the ones that if you export the VQL of that element, it has the token ENCRYPTED next to the value.

  • If valueEncrypted is true, it indicates that value is encrypted.

    To encrypt a value, use the script <SOLUTION_MANAGER_HOME>/bin/encrypt_password.

  • If valueEncrypted is false, value is treated as clear text.

  • valueEncrypted is optional; if it is not defined and this property represents a password, the API tries to decrypt the password. If the password cannot be decrypted, it is treated as clear text.

The next example shows a POST request which creates some properties:

[
    {
        "name": "default.dataSource.VDP.vdp.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin"
    }, {
        "name": "default.dataSource.VDP.vdp.login",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp.password",
        "value": "5Aq8JFwEcYWcfIXzZiC8jkxXLqyiKshHGf+TIY0pky/kK1KBkyg3 ... "
    }, {
        "name": "default.dataSource.VDP.vdp2.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin"
    }, {
        "name": "default.dataSource.VDP.vdp2.login",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp2.password",
        "value": "5Aq8JFwEcYWcfIXzZiC8jkxXLqyiKshHGf+TIY0pky/kK1KBkyg3 ... ",
        "valueEncrypted": true
    }, {
        "name": "default.dataSource.VDP.vdp3.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin"
    }, {
        "name": "default.dataSource.VDP.vdp3.login",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp3.password",
        "value": "TCcNJ8G5vxpKrjXAYWQtKtvUiQ/qh8hT9gnXdUzxIxft45Civz8i ... "
    }, {
        "name": "default.dataSource.VDP.vdp4.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin"
    }, {
        "name": "default.dataSource.VDP.vdp4.login",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp4.password",
        "value": "TCcNJ8G5vxpKrjXAYWQtKtvUiQ/qh8hT9gnXdUzxIxft45Civz8i ... ",
        "valueEncrypted": true
    }, {
        "name": "default.dataSource.VDP.vdp5.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin"
    }, {
        "name": "default.dataSource.VDP.vdp5.login",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp5.password",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp6.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin"
    }, {
        "name": "default.dataSource.VDP.vdp6.login",
        "value": "admin"
    }, {
        "name": "default.dataSource.VDP.vdp6.password",
        "value": "admin",
        "valueEncrypted": false
    }, {
        "name": "undefinedProperty",
        "value": "",
        "undefined": true
    }
]

This example shows the different values supported to add datasource password:

  • value ‘admin’ encrypted by Scheduler server for datasource vdp and vdp2

  • value ‘admin’ encrypted with encrypt_password script for vdp3 and vdp4

  • clear value ‘admin’ for vdp5 and vdp6

The response body includes the created properties with their identifiers.

[
    {
        "id": 45,
        "name": "default.dataSource.VDP.vdp.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 46,
        "name": "default.dataSource.VDP.vdp.login",
        "value": "admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 47,
        "name": "default.dataSource.VDP.vdp.password",
        "value": "5Aq8JFwEcYWcfIXzZiC8jkxXLqyiKshHGf+TIY0pky/kK1KBkyg3 ... ",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 49,
        "name": "default.dataSource.VDP.vdp2.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 50,
        "name": "default.dataSource.VDP.vdp2.login",
        "value": "admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 51,
        "name": "default.dataSource.VDP.vdp2.password",
        "value": "5Aq8JFwEcYWcfIXzZiC8jkxXLqyiKshHGf+TIY0pky/kK1KBkyg3 ... ",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 53,
        "name": "default.dataSource.VDP.vdp3.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 54,
        "name": "default.dataSource.VDP.vdp3.login",
        "value": "admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 55,
        "name": "default.dataSource.VDP.vdp3.password",
        "value": "Ag/hk7xFu9t+DdFOwHm7U+fNMHn8QJsJ26gfXMk/UeTgfPcNNyH1 ... ",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 57,
        "name": "default.dataSource.VDP.vdp4.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 58,
        "name": "default.dataSource.VDP.vdp4.login",
        "value": "admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 59,
        "name": "default.dataSource.VDP.vdp4.password",
        "value": "gS6vbKXngsHVE2eIWYMYZIlCmtTRwIBnokVg2sgjj/JlkLMnLj7l ... ",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 61,
        "name": "default.dataSource.VDP.vdp5.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 62,
        "name": "default.dataSource.VDP.vdp5.login",
        "value": "admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 63,
        "name": "default.dataSource.VDP.vdp5.password",
        "value": "WdaU+vTYcAvjPrCBpDZbSrR3CvegkbPBCZtpv/amhDpxLoZMLmmw ... ",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 65,
        "name": "default.dataSource.VDP.vdp6.connectionURI",
        "value": "//solution-manager.acme.com:19999/admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 66,
        "name": "default.dataSource.VDP.vdp6.login",
        "value": "admin",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 67,
        "name": "default.dataSource.VDP.vdp6.password",
        "value": "s0jcp9bWAR8drBZTGn4j3BMbQzpvSVaG96+YdJVw9Jb0AgSyVDp1 ... ",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": false
    },
    {
        "id": 69,
        "name": "undefinedProperty",
        "value": "",
        "propertyType": "SCHEDULER",
        "parentId": 5,
        "undefined": true
    }
]

This operation returns the passwords encrypted.

If you send a DELETE request to the following URL, you can delete a cluster property:

  • URL: /schProperties/{number:schPropertyId}

  • Method: DELETE

The next example deletes a property with identifier 5:

DELETE https://solution-manager.acme.com:10090/schProperties/5

If the property has been successfully deleted, the response status code is 204.

Get the List of Servers

The following request returns the list of servers in an environment:

  • URL: /environments/{number:environmentId}/servers

  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the list of servers with basic information in JSON format. Each server can contain the following information:

{
    "servers": [
        {
            "id": <number>,
            "name": <text>,
            "typeNode": <type-node>,
            "clusterId": <number>,  /* id of the cluster to which it belongs */
            "enabled": <boolean>
        },
        { ... }
    ]
}

<type-node> ::= "VDP" | "SCHEDULER" | "ITP_BROWSER_POOL" | "ITP_VERIFICATION" | "VDP_DATA_CATALOG"

The following example get the servers of the environment with identifier 6.

curl --user "jsmith" "https://solution-manager.acme.com:10090/environments/6/servers"
Response
 {
     "servers": [
         {
             "id": 9,
             "name": "vdpServer",
             "typeNode": "VDP",
             "clusterId": 7,
             "enabled": true
         },
         {
             "id": 10,
             "name": "schedulerServer",
             "typeNode": "SCHEDULER",
             "clusterId": 7,
             "enabled": true
         }
     ]
 }

See get server to get more info about a server.

Create a Server

If you execute a POST request to the following URL you can create a server:

  • URL: /servers

  • Method: POST

Note

This operation only allows to create servers in standard environments.

The request body has to follow this format:

{
    "id": <number> ,
    "name": <text> ,
    "description": <text> , /* optional */
    "typeNode": <node type> ,
    "urlIP": <text> ,
    "urlPort": <number> ,
    "clusterId": <number> ,
    "useKerberos": <boolean> ,
    "usePassThrough": <boolean> ,
    "username": <text> ,
    "password": <text> ,
    "defaultDatabase": <text> ,
    "enabled": <boolean> ,
    "licenseAlias": <text> , /* optional */
    "useDefaultLicenseAlias": <boolean>,
    "environmentType": <environment type>  /* only "STANDARD" <environment type> is supported */
}

<node type>::=
      "VDP"
    | "SCHEDULER"
    | "ITP_BROWSER_POOL"
    | "ITP_VERIFICATION"
    | "VDP_DATA_CATALOG"

<environment type>::= "STANDARD" | "AUTOMATED_AWS"

The clusterId must be the cluster identifier that can be obtained in Get the List of Clusters.

The password accepts the following values:

  • clear password

  • password encrypted with the encrypt_password script located in <SOLUTION_MANAGER_HOME>/bin

If useDefaultLicenseAlias is true, you can ommit the licenseAlias field or use an empty string. If useDefaultLicenseAlias is false, then you must indicate the license alias that can be obtained in Get the List of Licenses Available. If the server has been successfully inserted, the response status code is 201.

The next example shows a POST request which create a server:

{
    "name": "vdpLocal",
    "description": "",
    "typeNode": "VDP",
    "urlIP": "cajun",
    "urlPort": 9999,
    "clusterId": 11,
    "useKerberos": false,
    "usePassThrough": false,
    "username": "admin",
    "password": "admin",
    "defaultDatabase": "admin",
    "enabled": true,
    "licenseAlias": "",
    "useDefaultLicenseAlias": true,
    "environmentType": "STANDARD"
}

In this example password is a clear password. If the password is generated with the encrypt_password script, the password will be similar to:

"password": "8seLz7OWe6SRc9ivmekrkE+NTn8DzGxy",

The response body contains the added server with its identifier:

{
    "id": 12,
    "name": "vdpLocal",
    "uuid": "e8b408c3-8b7d-4d28-a98a-ac448c08b98a",
    "description": "",
    "typeNode": "VDP",
    "urlIP": "cajun",
    "urlPort": 9999,
    "clusterId": 11,
    "useKerberos": false,
    "usePassThrough": false,
    "username": "admin",
    "defaultDatabase": "admin",
    "enabled": true,
    "licenseAlias": "",
    "useDefaultLicenseAlias": true,
    "environmentType": "STANDARD",
    "environmentId": 2
}

Get a Server

The following request returns a server:

  • URL: /servers/{number:serverId}

  • Method: GET

If the request has been successfully executed, the server sends the status code 200. The response body includes the server in JSON format with the following information:

{
    "id": <number>,
    "name": <text>,
    "uuid": <uuid>,
    "description": <text>,
    "typeNode": <node type>,
    "urlIP": <text>,
    "urlPort": <number>,
    "clusterId": <number>,
    "useKerberos": <boolean>,
    "usePassThrough": <boolean>,
    "username": <text>,
    "defaultDatabase": <text>,
    "enabled": <boolean>,
    "licenseAlias": <text>,
    "useDefaultLicenseAlias": <boolean>,
    "environmentType": <environment type>,
    "environmentId": <number>
}

<node type>::=
      "VDP"
    | "SCHEDULER"
    | "ITP_BROWSER_POOL"
    | "ITP_VERIFICATION"
    | "VDP_DATA_CATALOG"

<environment type>::= "STANDARD" | "AUTOMATED_AWS"

Any property with null value will not be included in the JSON.

The following example returns the server with id 12.

{
    "id": 12,
    "name": "vdpLocal",
    "uuid": "e8b408c3-8b7d-4d28-a98a-ac448c08b98a",
    "description": "",
    "typeNode": "VDP",
    "urlIP": "cajun",
    "urlPort": 9999,
    "clusterId": 11,
    "useKerberos": false,
    "usePassThrough": false,
    "username": "admin",
    "defaultDatabase": "admin",
    "enabled": true,
    "licenseAlias": "",
    "useDefaultLicenseAlias": true,
    "environmentType": "STANDARD",
    "environmentId": 2
}

Update a Server

If you execute a PUT request to the following URL you can update a server:

  • URL: /servers/{number:serverId}

  • Method: PUT

Note

This operation only allows to update servers in standard environments.

The request body has to follow this format:

{
    "name": <text>,
    "description": <text>,  /* optional */
    "typeNode": <node type>,
    "urlIP": <text>,
    "urlPort": <number>,
    "clusterId": <number>,
    "useKerberos": <boolean>,
    "usePassThrough": <boolean>,
    "username": <text>,
    "password": <text>,
    "defaultDatabase": <text>,
    "enabled": <boolean>,
    "licenseAlias": <text>,  /* optional */
    "useDefaultLicenseAlias": <boolean>,
    "environmentType": <environment type>
}

<node type>::=
      "VDP"
    | "SCHEDULER"
    | "ITP_BROWSER_POOL"
    | "ITP_VERIFICATION"
    | "VDP_DATA_CATALOG"

<environment type>::= "STANDARD" | "AUTOMATED_AWS"

Note

The password accepts the following values:

  • “********” (8 asterisks), this values does not modify the password value

  • Clear password

  • A password encrypted with the encrypt_password script located in <SOLUTION_MANAGER_HOME>/bin

If the server has been successfully updated, the response status code is 200.

The next example shows a PUT request which update the server with id 12:

{
    "name": "vdpLocal-modif",
    "description": "",
    "typeNode": "VDP",
    "urlIP": "cajun",
    "urlPort": 9999,
    "clusterId": 11,
    "useKerberos": false,
    "usePassThrough": false,
    "username": "admin",
    "password": "********",
    "defaultDatabase": "admin",
    "enabled": true,
    "licenseAlias": "",
    "useDefaultLicenseAlias": true,
    "environmentType": "STANDARD"
}

The response body contains the updated server:

{
    "id": 12,
    "name": "vdpLocal-modif",
    "uuid": "e8b408c3-8b7d-4d28-a98a-ac448c08b98a",
    "description": "",
    "typeNode": "VDP",
    "urlIP": "cajun",
    "urlPort": 9999,
    "clusterId": 11,
    "useKerberos": false,
    "usePassThrough": false,
    "username": "admin",
    "defaultDatabase": "admin",
    "enabled": true,
    "licenseAlias": "",
    "useDefaultLicenseAlias": true,
    "environmentType": "STANDARD",
    "environmentId": 2
}

Delete a Server

If you send a DELETE request to the following URL, you can delete a server:

  • URL: /servers/{number:serverId}

  • Method: DELETE

The next example deletes a property with the identifier 12:

DELETE https://solution-manager.acme.com:10090/servers/12

If the server has been successfully deleted, the response status code is 204.

Export Solution Manager Catalog and Configuration

Available since 8.0 update 20210715.

This operation exports the environments, clusters and servers and some settings of the Solution Manager.

  • URL: /export

  • Method: POST

  • Syntax of the body of the request:

{
    "customPasswd" : <text> /* Optional. Used for sensitive data encryption */
}

Note

If you specify a custom password, you will need to specify the same password when you import the exported content. If you don’t want to encrypt the content, you can leave the body of the request empty.

If the export operation is successful, the response status code is 200.

Example of a POST request to get export content encrypted with a custom password:

POST https://solution-manager.acme.com:10090/export

{
  "customPasswd" : "passwd"
}

Import Solution Manager Catalog and Configuration

Available since 8.0 update 20210715.

This operation imports a file that contains the environments, clusters and servers and some settings of the Solution Manager.

  • URL: /import

  • Method: POST

  • Parameters:

    • overwrite: Optional. Possible values true or false. If the imported file contains information about an environment that already exists, set this to true. Otherwise, it will not be imported.

  • Syntax of the body of the request:

{
    "exportOptions" : {
       "customPasswd" : <text> /* Optional. Used for sensitive data encryption. Only needed if you specified a value for the export operation */
    },
    "importData" : <JSON catalog info> /* Copy the JSON content of the export here */
}

Note

If you specified a custom password during the export process, you will need to specify the same password for the import operation. If you didn’t encrypt the export content, you can leave the exportOptions field in the body of the request empty.

If the operation is successful, the response status code is 200.

Import example without custom password

Example of a POST request to import the content of an export operation:

POST https://solution-manager.acme.com:10090/import

{
  "importData" : {
    "environments": [
      {
          "id": 230,
          "name": "test",
          "uuid": "8a7ad34c-b61a-435b-a428-7df36a04a397",
          "minimumUpdateMandatory": false,
          "licenseAlias": "DEVELOPMENT_1",
          "environmentType": "ON_PREMISES",
          "deploymentConfiguration": {
              "deploymentsEnabled": true,
              "deploymentType": "ONLINE",
              "sharedCache": false,
              "cacheURLPrimary": "",
              "cacheURLSecondary": "",
              "clusterStrategy": "ONE_BY_ONE",
              "serverStrategy": "ONE_BY_ONE",
              "rollbackEnabled": false,
              "backupEnabled": false,
              "dataCatalogSynchronizeEnabled": false,
              "dataCatalogSyncType": "ALL",
              "dataCatalogSyncPriority": "SERVER_WITH_LOCAL_CHANGES",
              "dataCatalogVDPServerToSync": "",
              "environmentSyncDataCatalogs": []
          }
      }
    ]
  }
}

Import example with custom password and overwriting data

Example of a POST request to import the content of an export operation, specifying a custom password and overwriting existing elements:

POST https://solution-manager.acme.com:10090/import?overwrite=true

{
  "exportOptions" : {
    "customPasswd" : "exportPasswd"
  },
  "importData" : {
    "environments": [
      {
          "id": 230,
          "name": "test",
          "uuid": "8a7ad34c-b61a-435b-a428-7df36a04a397",
          "minimumUpdateMandatory": false,
          "licenseAlias": "DEVELOPMENT_1",
          "environmentType": "ON_PREMISES",
          "deploymentConfiguration": {
              "deploymentsEnabled": true,
              "deploymentType": "ONLINE",
              "sharedCache": false,
              "cacheURLPrimary": "",
              "cacheURLSecondary": "",
              "clusterStrategy": "ONE_BY_ONE",
              "serverStrategy": "ONE_BY_ONE",
              "rollbackEnabled": false,
              "backupEnabled": false,
              "dataCatalogSynchronizeEnabled": false,
              "dataCatalogSyncType": "ALL",
              "dataCatalogSyncPriority": "SERVER_WITH_LOCAL_CHANGES",
              "dataCatalogVDPServerToSync": "",
              "environmentSyncDataCatalogs": []
          }
      }
    ]
  }
}

Get the List of Revisions

The following URL returns the list of revisions:

  • URL: /revisions

  • Method: GET

  • Parameters:

    • start: this parameter specifies the first element of the collection to be returned.

    • count: this parameter specifies the maximum number of results to be returned.

The response body includes the list of revisions according to the following format:

{
    "start": <number> , /* specifies the first revision of the collection to be returned */
    "count": <number> , /* maximum number of revisions to be returned */
    "numElements": <number> , /* total number of revisions included in the response */
    "revisions": [{
            "id": <number> ,
            "description": <text> ,
            "name": <text> ,
            "type": { "INSERT" | "DELETE" }, /* alias for CREATE and DROP */
            "replace": <replace-drop Virtual DataPort elements> ,
            "creationUser": <text>,
            "creationTime": <date>, /* date format: yyyy-MM-dd'T'HH:mm:ss.SSZ */
            "lastModifiedUser": <text>,
            "lastModifiedTime": <date>, /* date format: yyyy-MM-dd'T'HH:mm:ss.SSZ */
            "hasVql": <boolean>,
            "hasScheduler": <boolean>,
            "includeJars": <boolean>,
            "includeI18N": <boolean>,
            "includeStatistics": <boolean>,
            "includeServerProperties": <boolean>,
            "includeWebContainerProperties": <boolean>,
            "includeJdbcWrapperProperties": <boolean>,
            "includeVdpDependencies": <boolean>,
            "includeUsersAndPrivileges": <boolean>,
            "useDefaultDatabase": <boolean>,
            "deployedOn": [/* list of environments in which the revision was already deployed */
                {
                    "id": <number> ,
                    "name": <text> ,
                    "description": <text> ,
                    "minimumUpdateMandatory": <boolean>
                }, {
                    ...
                }
            ]
        }, {
            ...
        }
    ]
}

<replace-drop Virtual DataPort elements>::=
      "DO_NOT_REPLACE_EXISTING"
    | "REPLACE_EXISTING"
    | "DROP_ELEMENTS_BEFORE"

The following example represents two revisions in JSON format. The first one was deployed on 2 environment, the second one was not deployed on any environment:

{
   "start": 0,
   "count": 10,
   "numElements": 2,
   "revisions": [
        {
            "id": 3,
            "description": "Third revision",
            "name": "Revision 3",
            "type": "INSERT",
            "replace": "DO_NOT_REPLACE_EXISTING",
            "creationUser": "smadmin",
            "creationTime": "2017-11-11T00:15:34.507+0000",
            "lastModifiedUser": "smadmin",
            "lastModifiedTime": "2017-11-11T00:15:34.507+0000",
            "hasVql": true,
            "hasScheduler": false,
            "includeJars": false,
            "includeI18N": false,
            "includeStatistics": false,
            "includeServerProperties": false,
            "includeWebContainerProperties": false,
            "includeJdbcWrapperProperties": true,
            "includeVdpDependencies": false,
            "includeUsersAndPrivileges": false,
            "useDefaultDatabase": true,
            "deployedOn": [
                {
                    "id": 2,
                    "name": "Environment 2",
                    "description": "Second environment",
                    "minimumUpdateMandatory": false
                },
                {
                    "id": 3,
                    "name": "Environment 3",
                    "description": "Third environment",
                    "minimumUpdateMandatory": false
                }
            ]
        },
        {
            "id": 2,
            "description": "Second revision",
            "name": "Revision 2",
            "type": "DELETE",
            "replace": "DROP_ELEMENTS_BEFORE",
            "creationUser": "smadmin",
            "creationTime": "2017-11-11T00:15:34.429+0000",
            "lastModifiedUser": "smadmin",
            "lastModifiedTime": "2017-11-11T00:15:34.429+0000",
            "hasVql": true,
            "hasScheduler": false,
            "includeJars": false,
            "includeI18N": false,
            "includeStatistics": false,
            "includeServerProperties": false,
            "includeWebContainerProperties": false,
            "includeJdbcWrapperProperties": true,
            "includeVdpDependencies": false,
            "includeUsersAndPrivileges": false,
            "useDefaultDatabase": true
        }
    ]
}

Create a Revision from a VQL File

You can execute a POST request to the following URL to create a revision from a VQL file:

  • URL: /revisions/loadFromVQL

  • Method: POST

The request body has to follow this format:

{
    "name": <text>, /* descriptive name for the revision*/
    "description": <text>,  /* optional. Extensive description about the revision. */
    "content": <text> /* vql file content as **xsd:base64Binary** encoded in **UTF-8** */
}

Note

The field content must be the content of the vql file as xsd:base64Binary encoded in UTF-8. The revision will be created even if the vql is not parameterized with environment properties. We strongly recommend that you always generate vql files with specific environment properties separately. If the vql is generated using the VDP Admin Tool, you should select the option Export environment specific properties separately in the Export and Export database dialogs, otherwise check that the vql does not contain environment property values. Take into account that deploying a revision created from a vql without separate environment properties can generate unexpected results.

Note

The vql files generated when exporting elements using VDP Admin Tool includes the BOM mark to indicate that they are encoded in UTF-8. The BOM mark must be skipped.

The response body contains the added revision with its identifier:

{
    "id": 4,
    "description": "Creating revision using exportTestDB-WithProperties",
    "name": "revFromVQLWithProperties",
    "type": "VQL",
    "replace": "REPLACE_EXISTING",
    "creationUser": "admin",
    "creationTime": "2019-08-27T15:22:59.292+0000",
    "lastModifiedUser": "admin",
    "lastModifiedTime": "2019-08-27T15:22:59.292+0000",
    "hasVql": false,
    "hasScheduler": false,
    "includeJars": false,
    "includeI18N": false,
    "includeStatistics": false,
    "includeServerProperties": false,
    "includeWebContainerProperties": false,
    "includeJdbcWrapperProperties": true,
    "includeVdpDependencies": false,
    "includeUsersAndPrivileges": false,
    "useDefaultDatabase": true
}

Get the List of Deployments

The following URL returns the list of deployments:

  • URL: /deployments

  • Method: GET

  • Parameters:

    • start: this parameter specifies the first deployment of the collection to be returned.

    • count: this parameter specifies the maximum number of deployments to be returned.

    • environmentId: this parameter filters deployments by target environment.

    • status: this parameter filters deployments by execution status (OK, ERROR, IN_PROGRESS).

    • description: this parameter filters deployments by description.

    • user: this parameter filters deployments by user.

    • startDeploymentTime: this parameter filters deployments by start deployment time. Date format is yyyy-MM-dd’T’HH:mm:ssZ.

    • endDeploymentTime: this parameter filters deployments by end deployment time. Date format is yyyy-MM-dd’T’HH:mm:ssZ.

The response body includes the deployments in JSON format, according to the following template:

{
    "start": <number>,
    "count": <number>,
    "numElements": <number>,
    "deployments": [{
            "id": <number>,
            "user": <text>,
            "deploymentTime": <date>, /* date format: yyyy-MM-dd'T'HH:mm:ss.SSZ */
            "description": <text>,
            "state": <deployment status>,
            "multipleErrors": <boolean>,
            "targetEnvironment": {
                "id": <number>,
                "name": <text>,
                "minimumUpdateMandatory": <boolean>
            },
            "revisions": [{
                    "id": <number>,
                    "description": <text>,
                    "name": <text>,
                    "includeJars": <boolean>,
                    "includeI18N": <boolean>,
                    "includeStatistics": <boolean>,
                    "includeServerProperties": <boolean>,
                    "includeWebContainerProperties": <boolean>,
                    "includeJdbcWrapperProperties": <boolean>,
                    "includeVdpDependencies": <boolean>,
                    "includeUsersAndPrivileges": <boolean>
                }, { ... }
            ],
        }, { ... }
    ]
}

<deployment status>::=
      "OK"
    | "ERROR"
    | "IN_PROGRESS"
    | "PENDING"
    | "CANCELLED"

The following example returns a list of 2 deployments:

{
    "start": 0,
    "count": 10,
    "numElements": 2,
    "deployments": [{
            "id": 28,
            "user": "admin",
            "deploymentTime": "2017-11-12T23:05:53.179+0000",
            "description": "",
            "targetEnvironment": {
                "id": 3,
                "name": "Environment 3",
                "minimumUpdateMandatory": false
            },
            "revisions": [{
                    "id": 3,
                    "description": "Third revision",
                    "name": "Revision 3",
                    "includeJars": false,
                    "includeI18N": false,
                    "includeStatistics": false,
                    "includeServerProperties": false,
                    "includeWebContainerProperties": false,
                    "includeJdbcWrapperProperties": true,
                    "includeVdpDependencies": false,
                    "includeUsersAndPrivileges": false
                }
            ],
            "state": "OK",
            "multipleErrors": false
        }, {
            "id": 27,
            "user": "admin",
            "deploymentTime": "2017-11-12T23:05:40.838+0000",
            "description": "",
            "targetEnvironment": {
                "id": 3,
                "name": "Environment 3",
                "minimumUpdateMandatory": false
            },
            "revisions": [{
                    "id": 3,
                    "description": "Third revision",
                    "name": "Revision 3",
                    "includeJars": false,
                    "includeI18N": false,
                    "includeStatistics": false,
                    "includeServerProperties": false,
                    "includeWebContainerProperties": false,
                    "includeJdbcWrapperProperties": true,
                    "includeVdpDependencies": false,
                    "includeUsersAndPrivileges": false
                }
            ],
            "state": "OK",
            "multipleErrors": false
        }
    ]
}

The following URL returns the list of deployments between 2017-11-07T16:50:32+0100 and 2017-11-15T16:50:33+0100. You must specify both parameters, startDeploymentTime and endDeploymentTime, together.

curl --user "jsmith" "https://solution-manager.acme.com:10090/deployments?startDeploymentTime=2017-11-07T16%3A50%3A32%2B0100&endDeploymentTime=2017-11-15T16%3A50%3A33%2B0100"

The following URL returns the list of deployments in progress.

curl --user "jsmith" "https://solution-manager.acme.com:10090/deployments?status=IN_PROGRESS"

Start a New Deployment from a List of Revisions

You can execute a new deployment sending a POST request to the following URL:

  • URL: /deployments

  • Method: POST

The request body must follow the template below.

{
    "revisionIds": [ <number>, ... ],
    "environmentId": <number>,
    "description": <text>
}

This request must include the list of revision identifiers (revisionIds) and also the identifier of the target environment (environmentId). The following example creates a deployment from the revisions 1 and 2, on the target environment identified with the id 3.

{
    "revisionIds": [1, 2],
    "environmentId": 3,
    "description": "My first deployment"
}

It the deployment has been successfully created, the response body contains the numeric deployment identifier.

{
    "deploymentId": 7,
}

If some property is missing in the target environment, the deployment process fails and the response body returns the result of the validation.

{
    "validationResponse": {
        "validation": {
            "resultVqlValidation": "ERROR",
            "outputVqlValidation": "Error validating revision 'Third revision'.\n Missing VQL properties: \ndatabases.admin.datasources.jdbc.oracle_ds.DATABASEURI\ndatabases.admin.datasources.jdbc.oracle_ds.USERNAME\ndatabases.admin.datasources.jdbc.oracle_ds.USERPASSWORD\ndatabases.admin.datasources.jdbc.oracle_ds.USERPASSWORD.ENCRYPTED\nusers.user1.PASSWORD\nusers.user1.PASSWORD.ALGORITHM\nusers.user1.PASSWORD.ENCRYPTED\n\n",
            "errorVqlValidation": "Error validating revision 'Third revision'.\n Some Virtual DataPort properties required by the revision are not defined in the target environment\n\n",
            "missingVqlPropertiesWithServerValues": {
                "users.user1.PASSWORD": "ISTcnym4dJECzqYlA7+Xv6+RJo5s0VupzxEhXqoXC9XHu+5+M03kn3ftHGwW57FB5Q1d4Glcad4g54l9iBdEm55U431gIeob",
                "users.user1.PASSWORD.ALGORITHM": "SHA512",
                "databases.admin.datasources.jdbc.oracle_ds.USERPASSWORD.ENCRYPTED": "ENCRYPTED",
                "databases.admin.datasources.jdbc.oracle_ds.USERPASSWORD": "hJfznA24IFFPM8Z+6qCDO6Kg2Z3OSjP8W+uooHqFUpp8MoJT1FC3gdgsFe8cyh+Xmvu0dPIkFY21fidp75fqE4euFqx9QpH4Y8gcRE3CaeszFlB97AXg4dJ99eJFbWZ7",
                "users.user1.PASSWORD.ENCRYPTED": "ENCRYPTED",
                "databases.admin.datasources.jdbc.oracle_ds.USERNAME": "dblogin",
                "databases.admin.datasources.jdbc.oracle_ds.DATABASEURI": "jdbc:oracle:thin:@host:port:database"
            },
            "resultSchValidation": "OK",
            "outputSchValidation": "",
            "errorSchValidation": "",
            "targetEnvironment": {
                "id": 1,
                "name": "env1",
                "uuid": "9417994b-3657-499a-a3b0-234cab5dfc07",
                "description": "",
                "minimumUpdateValue": "",
                "minimumUpdateMandatory": false,
                "minimumUpdateDownloadUrl": "",
                "licenseAlias": "PRODUCTION_1"
            },
            "state": "ERROR",
            "messageResult": "Some of the Virtual DataPort properties included in the revision are not defined in the target environment. "
        },
        "scriptValidationsResult": []
    }
}

Get the Progress of a Deployment

The following URL returns the deployment status and the list of deployment tasks:

  • URL: /deployments/{number:deploymentId}/progress

  • Method: GET

  • Parameters

    • lastUpdate: filters deployment tasks by last update date.

The response body includes the deployment progress and the list of deployment tasks according to the following template:

{
    "deploymentId": <number>,
    "state": <deployment state>,
    "progress": <number>, /* percent between 0 and 100 */
    "tasks": [{
            "id": <number>,
            "name": <text>,
            "state": <deployment task state>,
            "startDate": <date>,
            "endDate": <date>,
            "deploymentExecutionType": <deployment execution type>,
            "output": <text>,
            "cluster": {
                "id": <number>,
                "name": <text>,
                "enabled": <boolean>
            },
            "server": {
                "id": <number>,
                "name": <text>,
                "enabled": <boolean>,
                "useDefaultLicenseAlias": <boolean>
            }
        }, { ... }
    ]
}

<deployment state> ::=
      "OK"
    | "ERROR"
    | "IN_PROGRESS"

<deployment task state> ::=
      "OK"
    | "ERROR"
    | "IN_PROGRESS"
    | "PENDING"
    | "WARNING"
    | "SKIPPED"
    | "CANCELLED"

 <deployment execution type> ::=
      "VQL"
    | "SCH"
    | "CACHE"
    | "DATACATALOG_SYNC"
    | "SCRIPT_CLUSTER"
    | "SCRIPT_SERVER"
    | "BACKUP"
    | "ROLLBACK"
    | "SERVER_DEPLOYMENT"
    | "CLUSTER_DEPLOYMENT"

The optional request parameter lastUpdate filters tasks by last update date. If it is specified, the response body only include tasks modified since this date.

The following example shows an example of deployment progress with 1 execution task:

{
    "deploymentId": 1,
    "state": "OK",
    "progress": 100,
    "tasks": [{
            "id": 1,
            "name": "Revision Revision 1 VQL deployment",
            "state": "OK",
            "startDate": "2017-11-13T11:18:40.999+0000",
            "endDate": "2017-11-13T11:18:41.065+0000",
            "deploymentExecutionType": "VQL",
            "output": " - Executed 1 of 1 VQL commands",
            "cluster": {
                "id": 7,
                "name": "Cluster 2",
                "enabled": true
            },
            "server": {
                "id": 8,
                "name": "Server 3",
                "enabled": true,
                "useDefaultLicenseAlias": true
            }
        }
    ]
}

Free License Usage

When you stop a Denodo server (e.g. Virtual DataPort server, Scheduler server, etc.), it sends an HTTP request to the License Manager, to notify that is going to stop. When the License Manager receives this request, it frees the corresponding license so it can be used by another server.

If a Denodo server stops working unexpectedly (e.g. the machine where it runs is restarted unexpectedly), you have to manually notify the License Manager that the license that this Denodo server was using, is no longer in use. Otherwise, the license will be considered in use until the grace period expires (5 days since the last time this Denodo server renewed its license).

To free up a license, log in to the Solution Manager. In the Elements Tree, open the definition of the server whose license you want to free up and copy the field Host .

Then, send a request to this endpoint:

  • URL: /externalShutdown

  • Method: GET

  • URL parameters:

    • nodeIp: if the field Host in the Solution Manager is an IP address - not a host name - the value of this parameter has to be this IP address.

    • hostDomainName: if the field Host in the Solution Manager is a host name, the value of this parameter has to be this host name.

    • instanceId: instance id of the automated cloud mode server instance.

    • port: port of the Denodo server.

    • product: the value has to be VDP, SCHEDULER or VDP_DATA_CATALOG.

Consider these:

  • The names of the parameters are case sensitive.

  • You have to add the parameter instanceId, nodeIp or hostDomainName to the URL. When instanceId is specified, nodeIp are hostDomainName are ignored. Otherwise, you have to add the parameter nodeIp or hostDomainName to the URL, not both.

  • If a parameter is missing, the service returns the HTTP code 400 (Bad Request).

  • Unlike with the other endpoints described in this page, do not add the HTTP header Cookie to the requests.

  • Unlike the other endpoints described in this page, the endpoint is the License Manager server, not the Solution Manager server. Therefore, the port is different (by default, 10091, not 10090 like the other operations)

Examples

Example #1

Free the license associated with the Virtual DataPort server that runs on the host denodo-dv1-prod.denodo.com.

curl --user "jsmith" "https://solution-manager.acme.com:10091/externalShutdown?hostDomainName=denodo-dv1-prod.denodo.com&port=9999&product=VDP"

Example #2

Free the license associated with the Virtual DataPort server that runs on the host with IP 192.168.0.120.

curl --user "jsmith" "https://solution-manager.acme.com:10091/externalShutdown?nodeIp=192.168.0.120&port=9999&product=VDP"

Example #3

Free the license associated with an automated cloud mode Virtual DataPort server running in the instance i-08ae3ee3f75ced7d0.

GET https://solution-manager.acme.com:10091/externalShutdown?instanceId=i-08ae3ee3f75ced7d0&port=9999&product=VDP

The response from the service includes a summary of the operation with the result and a message:

{
    "result": { "OK" | "ERROR" },
    "message": <text>
}

Free License Usage by Server Id

This operation provides an alternative method of releasing license usage by specifying the identifier of the server.

  • URL: /servers/{number:serverId}/externalShutdown

  • Method: POST

The response from the service includes a summary of the operation with the result and a message:

{
    "result": { "OK" | "ERROR" },
    "message": <text>
}

Example of a POST request to release the license usage of the server with id 3:

POST https://solution-manager.acme.com:10091/servers/3/externalShutdown

Ping License Manager Server

Use the endpoint “ping License Manager” to check the health of the License Manager.

  • URL: https://denodo-server.acme.com:10091/pingLicenseManager

  • Method: GET

Note that you need to send the request to the License Manager (its default port is 10091), not the Solution Manager.

This endpoint returns the HTTP code 200 and the text OK if the server is up and the connection to the database where its metadata is stored is up. Otherwise, the request fails.

Ping to Solution Manager Server

Use the endpoint “ping Solution manager” to check the health of the Solution Manager server.

  • URL: https://denodo-server.acme.com:10090/pingSolutionManager

  • Method: GET

This endpoint returns the HTTP code 200 and the text OK if the server is up and the connection to the database where its metadata is stored is up. Otherwise, the request fails.