Update Connector

Updates a connector.

Connectors allow you to retrieve information from external systems and update it through Haven OnDemand APIs. You can use connectors to create an index of data in an external repository, schedule and automate workflows, send notifications, or facilitate migration to other locations.

The Update Connector API updates the parameters for an existing connector. Using the Update Connector API (instead of deleting and recreating the connector) retains the existing status of the index, which prevents unnecessary reindexing.

Quick Start

The Update Connector API has a single required parameter, connector, which specifies the name of the connector that you want to update. Use one or more of the other API parameters to specify the changes that you want to make.

You can modify any of the options that you set when you created the connector. The parameters take the same values as the equivalent parameters in the Create Connector API. You cannot change the connector name or flavor.

The description parameter allows you to update the description for the connector. This description appears in the response for the List Resources API, and in the API Try pages for other Connector APIs.

/1/api/[sync|async]/updateconnector/v1?connector=myconnector&description=Web connector for Haven OnDemand site crawl

The config, destination, and schedule parameters allow you to update the configuration for the connector. For these parameters, you provide the new JSON object, which overwrites the existing value for the connector. You must provide the whole configuration, even if you are changing only some of the values. For example, if you have the following configuration for the destination for a Web Cloud connector:

 { "action" : "addtotextindex", "index" : "myindex" }

You can change the index parameter by supplying the following JSON object:

 { "action" : "addtotextindex", "index" : "mynewindex" }

Optional values are overwritten if you do not specify them. If you created the original connector with optional parameters that you want to keep, you must add them in the updated configuration. If you do not specify the parameters, the updated configuration uses the default values.

For example, the following configuration includes values for the optional parameters manipulate_reference_prefix and new_reference_prefix in a File System connector:

{
	"directoryPathCSVs" : "C:\\users,C:\\Documents",
	"directoryRecursive": true,
	"servicePort": 8002,
	"aciPort": 8000,
	"manipulate_reference_prefix": "C:\\",
	"new_reference_prefix": "\\\\share.example.com\\"
}

For more information about the format and available parameters for these JSON objects, see Connectors and the individual connector flavor documentation.

When you update the config or destination configurations for a connector with credentials, you must also update the credentials and credentials_policy parameters.

The credentials parameter updates the credentials that the connector uses to connect to the repository. Credentials are required for Dropbox Cloud and SharePoint Onsite flavor connectors, and optional for Web Cloud flavor connectors. The credentials_policy parameter provides information about when the connector can decrypt the credentials. For security reasons, you must update credentials_policy whenever you update credentials.

For more information about credentials, see Connector Credentials.

The remove_credentials parameter allows you to remove optional credentials from a connector. For example, Web Cloud flavor connectors have optional credentials configuration parameters.

/1/api/[sync|async]/updateconnector/v1?connector=myconnector&remove_credentials=true

Tip: If there are dependencies between optional credentials configuration parameters and config configuration parameters, you must also update the config configuration, see Connectors and the individual connector flavor documentation.

The invalidate_previous_state parameter allows you to overwrite the state of any previous connector runs. This option is similar to the ignore_previous_state parameter for the Start Connector API.

/1/api/[sync|async]/updateconnector/v1?connector=myconnector&invalidate_previous_state=true

For Dropbox Cloud flavor connectors, HavenOnDemand recommends that you set invalidate_previous_state to true when you update the credentials parameter. When the account credentials change, it changes the state that the connector has stored, so you must use invalidate_previous_state to ensure that the connector can reconnect to the repository.

Tip: If the only update you want to make to a connector is to remove a schedule, you can use the Cancel Connector Schedule API, which does only that.

Synchronous
https://api.havenondemand.com/1/api/sync/updateconnector/v1
Asynchronous
https://api.havenondemand.com/1/api/async/updateconnector/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
connector
resource The name of the connector to update. Maximum length of 100 characters.
Optional
Name Type Description
config
json A JSON object defining the connector configuration.
credentials
json The user credentials to use to access the source repository.
credentials_policy
json The user credentials_policy to verify the validity of the keys for decryption.
description
string A brief description of the connector. Maximum length is 255 characters.
destination
json A JSON object defining the destination to which the connector must send retrieved data. Currently it can send data only to a text index.
schedule
json A JSON string containing the details of the schedule.
invalidate_previous_state
boolean Set to true to overwrite the state of any previous connector runs for the specified connector. This option is similar to the ignore_previous_state parameter for the Start Connecter API, but this operation is permanent. If you change the credentials for a Dropbox_cloud flavor connector, Haven OnDemand recommends that you invalidate the previous connector state, to ensure that the connector overwrites the old credentials. Default value: false.
remove_credentials
boolean Set to true to remove any stored credentials for the specified connector. Default value: false.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Update Connector Response {
connector ( string ) The name of the connector.
message ( string ) Indicates that the connector was updated.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "connector": {
            "type": "string"
        },
        "message": {
            "type": "string"
        }
    },
    "required": [
        "connector",
        "message"
    ],
    "type": "object"
}


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.