Update analytics data connections

Overview

This topic shows you how to update various properties of an analytic data connection, including owner, space, name, credentials, and more. To do this, you will use the data-connection API.

Requirements

• Review the prerequisites in the create data connections tutorial.
• Appropriate space or tenant level role to update, delete and recreate the connection. For more information, see Working in spaces on Qlik Help.

Variable substitution and vocabulary

Throughout this tutorial, variables will be used to communicate value placement. The variable substitution format is <VARIABLE_NAME>. Here is a list of variables referred to in this tutorial.

Retrieve connection ID and metadata

To update a data connection, you need to know its name or ID. You can send a GET request to retrieve connection metadata. For example, you can pass in the space ID which you want to search for the connection in, and the connection name to retrieve connections in that space which match the provided name:

curl -L "https://<TENANT>/api/v1/data-connections/<CONNECTION_NAME>?type=connectionname&space=<SPACE_ID>&parseConnection=true" ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-H "Content-Type: application/json" ^
-H "Accept: application/json"

This will return an HTTP 200 with a response which describes the connection:

{
    "created": "2023-08-10T10:49:56.914Z",
    "datasourceID": "File_AmazonS3ConnectorV2",
    "id": "<CONNECTION_ID>",
    "links": {
        "self": {
            "href": "https://<TENANT>/api/v1/data-connections/<CONNECTION_ID>"
        }
    },
    "connectionProperties": {
        "bucketName": "bucket-name",
        "region": "us-east-1"
    },
    "privileges": [
        "change_owner",
        "change_space",
        "delete",
        "list",
        "read",
        "update"
    ],
    "qArchitecture": 0,
    "qConnectStatement": "CUSTOM CONNECT TO \"provider=QvWebConnectorPackage.exe;sourceType=File_AmazonS3ConnectorV2;region=us-east-1;bucketName=bucket-name;\"",
    "qCredentialsID": "5d7deb43-2a41-4ed3-81f9-0d02c37d8a89",
    "qEngineObjectID": "<CONNECTION_ID>",
    "qID": "<CONNECTION_ID>",
    "qLogOn": 1,
    "qName": "<CONNECTION_NAME>",
    "qSeparateCredentials": false,
    "qType": "QvWebStorageProviderConnectorPackage.exe",
    "qri": "qri:file:s3://KKj_7B9Gj09qbldOzS6-7NkcFiLT5XRm2jPoS9FY3KI",
    "space": "<SPACE_ID>",
    "tenant": "Hj5p89bylz1r2AUC6joLNuHzVx5Ya8cF",
    "updated": "2023-08-10T10:49:56.914Z",
    "user": "<OWNER_ID>",
    "version": "V1"
}

Use the <CONNECTION_ID> from the response to update it. You may also need other parts of this response if you are updating other properties. Passing the parameter parseConnection=true returns the connection properties in the same format as required to create new connections, rather than bundled into the connection string in qConnectStatement.

Change connection owner

You can make batch requests to update connection metadata for space and owner if you have the TenantAdmin role on the tenant. Many requests can be grouped together in a single POST call.

If your user does not have an administrator role, you cannot change the owner of a connection.

Assuming you wish to update both the space and owner of a single connection, and the new target space is of type shared:

curl -L "https://<TENANT>/api/v1/data-connections/actions/update" ^
-H "Accept: application/json" ^
-H "Content-Type: application/json" ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-d "{
    \"connections\": [
        {
            \"id\": \"<CONNECTION_ID>\",
            \"ownerId\": \"<OWNER_ID>\",
            \"spaceId\": \"<SPACE_ID>\",
            \"spaceType\": \"shared\"
        }
    ]
}"

To change only the owner, remove the spaceId and spaceType attributes.

You will receive an HTTP 207 multi-status response, with the payload containing a separate status per data connection you requested be updated.

{
    "data": [
        {
            "id": "<CONNECTION_ID>",
            "status": 204
        }
    ]
}

In this example, a status of 204 is shown, which indicates the updates were successfully made to the connection.

Change connection definition, name, or space

You can change most data connection metadata and some properties using the data connections PATCH method. When making changes to the name of a data connection, know that Qlik Sense applications use this name value to specify which connections are used during reloads, so ensure you make corresponding changes to any Qlik Sense apps if the data connection is already in use.

The following properties can be updated via a PATCH:

• qConnectStatement - the configuration of the connector, minus credentials.
• qCredentialsID - the credentials used with the data connection.
• qName - the name of the data connection.
• space - the space in which the data connection resides.

To update the connection name and space using the connection ID:

curl -L -X PATCH "https://<TENANT>/api/v1/data-connections/<CONNECTION_ID>" ^
-H "Authorization: Bearer <ACCESS_TOKEN>" ^
-H "Accept: application/json" ^
-H "Content-Type: application/json" ^
-d "{
    \"patchData\": [
        {
            \"op\": \"replace\",
            \"path\": \"/qName\",
            \"value\": \"<CONNECTION_NAME>\"
        },
        {
            \"op\": \"replace\",
            \"path\": \"/space\",
            \"value\": \"<SPACE_ID>\"
        }
    ]
}"

The result will be an empty response with an HTTP 204 code, if successful.

Change all connection properties, or credentials

If you wish to change connection specifics which are unsupported by the patch operation, or update the credentials of the connection, you will need to rebuild the connection, by:

1. Retrieving the data connection definition
2. Deleting the data connection
3. Re-creating the data connection, in the same space and with the same name

Data connections are identified only by their name to Analytics apps, so only the name and the access control (defined by the space) need to match. It is even possible to change the data source, as long as the new source driver has the same capabilities as the original source driver (for example, you could replace an AWS S3 cloud storage connector with a Google Cloud storage connector, but not with a SQL server connector).

Next steps

Now that you know how to update a data connection, why not look at how to delete existing data connections?