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. Review space access control for more information.

Note: The cURL examples in this tutorial show the command syntax for Windows Command Prompt. If you are using another command line interface, different syntax may be required for line continuation. You may also need to adjust the number and type of quotes surrounding the parameters and their values.

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.

Variable	Description
`<TENANT>`	The hostname for the initial tenant created during account onboarding. Such as `tenantname.region.qlikcloud.com`.
`<ACCESS_TOKEN>`	A bearer token for authorizing `https` requests to the `<TENANT>` tenant. Can be an API key, or a token generated via an OAuth client.
`<SPACE_NAME>`	The name of the space you’ll create data files in.
`<SPACE_ID>`	The ID of the space `<SPACE_NAME>`.
`<OWNER_ID>`	The ID of user who owns the specified data connection.
`<CONNECTION_ID>`	The ID for the data connection created in `<SPACE_NAME>`.
`<CONNECTION_NAME>`	The ID for the data connection to be created in `<SPACE_NAME>`.

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

Note: When performing patch operations, you can opt to select the data connection by name rather than by ID by adding the type=connectionname parameter.

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

Retrieving the data connection definition
Deleting the data connection
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).

Note: While it is possible to update some parts of the connection definition via updating the qConnectStatement, recreation of the data source is the only way to update all properties and credentials.

Next steps

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

Overview
Requirements
Variable substitution and vocabulary
Retrieve connection ID and metadata
Change connection owner
Change connection definition, name, or space
Change all connection properties, or credentials
Next steps