Retrieve Config

Retrieves a connector configuration.

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

The Retrieve Config API retrieves information about the configuration of one of your connectors.

Quick Start

The Retrieve Config API has a single required parameter, connector, to specify the name of the connector configuration to retrieve.

/1/api/[async|sync]/retrieveconfig/v1?connector=myconnector

You can optionally set the output parameter to specify whether you want to return the configuration attributes for the connector, or the configuration file. The default value for this parameter depends on the flavor of your connector:

  • For cloud flavor connectors the default value is config_attributes

  • For onsite flavor connectors the default value is config_file

You can use both types of output for both connector flavors. The value of the output parameter affects the JSON response that the API returns.

When you set output to config_attributes, the API returns the configuration attributes in the following format:

{
  "name": "myconnector",
  "flavor": "web_cloud",
  "config": {
    "config": {
      "url": "http://www.havenondemand.com",
      "max_pages": 10
    },
    "destination": {
      "action": "addtotextindex",
      "index": "test"
    },
    "schedule": {
      "frequency": {
        "frequency_type": "seconds",
        "interval": 21600
      }
    },
    "credentials": {
      "login_value": "login",
      "password_value": "password"
    },
    "credentials_policy": {
      "notification_email": "test@test.com"
    },
    "description": "some description"
  }
}

When you set output to config_file, the API returns the configuration file in the following format:

{
  "name": "myconnector",
  "flavor": "web_cloud",
  "config": "CgoKCi8vIE9ubHkgY3Jhd2xzIDIgcGFnZXMgd2l0aCB0aGlzIHR1cm5lZCBvbiwgY3VycmVudGx5IHdvcmtpbmcgd2l0aCBjb25uZWN0b3IgdGVhbSB0byBhdHRlbXB0IHRvIGdldCB0aGlzIGZpeGVkCi8vW0RlZmF1bHRdCi8vCi8vU3RvcmVTaXRlU3RydWN0dXJlID0gVFJVRQovL0RhdGFzdG9yZUZpbGUgPSBEcml2ZXI9e0Nvbm5lY3Rvci9PREJDIDUuMSBEcml2ZXIgRFNOfTtTRVJWRVI9aW9kLXNlcnZpY2VzO1BPUlQ9MzMwNjtEQVRBQkFTRT13ZWJjb25uZWN0b3I7VUlEPWRidV93ZWJjb25uZWN0b3I7UFdEPWRidV93ZWJjb25uZWN0b3IKLy8KCi8vLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0gRmV0Y2hUYXNrcyAtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS8vCltGZXRjaFRhc2tzXQpOdW1iZXI9MQowPUZldGNoVGFzazkKCi8vLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0gRmV0Y2hUYXNrIC0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLy8KW0ZldGNoVGFzazldClVSTD1odHRwOi8vd3d3Lmdvb2dsZS5jb20KRGlyZWN0b3J5PUZldGNoVGFzazkKTG9nRmlsZT1GZXRjaFRhc2s5LmxvZwoKVXJsTXVzdEhhdmVSZWdleD0KVXJsQ2FudEhhdmVSZWdleD0KCkxpbmtBdHRyaWJ1dGVzPWhyZWYKClNwaWRlckFzPU1vemlsbGEvNS4wIChXaW5kb3dzIE5UIDYuMjsgV2luNjQ7IHg2NCkgQXBwbGVXZWJLaXQvNTM3LjM2IChLSFRNTCwgbGlrZSBHZWNrbykgQ2hyb21lLzMyLjAuMTY2Ny4wIFNhZmFyaS81MzcuMzYKCi8vLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0gUHJveHkgUGFyYW1ldGVycyAtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS8vClByb3h5SG9zdD1wcm94eS1hdGMuYXRsYW50YS5ocC5jb20KUHJveHlQb3J0PTgwODgKCi8vLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0gW0RlZmF1bHRdIExpbWl0cyBQYXJhbWV0ZXJzIC0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0vLwpNYXhQYWdlcz0xMApTaXRlRHVyYXRpb249MzYwMApNYXhMaW5rc1BlclBhZ2U9MTAwMApNYXhQYWdlU2l6ZT0zMDAwMDAwMApNaW5QYWdlU2l6ZT00MDk2ClBhZ2VUaW1lb3V0PTEyMHMKU3RheU9uU2l0ZT10cnVlCkZvbGxvd1JlZGlyZWN0PXRydWUKRGVwdGg9MwpGb2xsb3dSb2JvdFByb3RvY29sPXRydWUKRm9ybXNTZWN0aW9uPUZvcm05CkluZ2VzdENvbmZpZ1NlY3Rpb249SW5nZXN0aW9uCgpbRm9ybTldCklucHV0U2VsZWN0b3IwPWlucHV0W25hbWU9XQpJbnB1dFNlbGVjdG9yMT1pbnB1dFtuYW1lPV0KRm9ybVVybFJlZ2V4PQpTdWJtaXRTZWxlY3Rvcj0KCgpbSW5nZXN0aW9uXQpFbmFibGVJbmdlc3Rpb249VHJ1ZQpJbmdlc3RlclR5cGU9SU9ECkluZ2VzdEFjdGlvbnM9TUVUQTpjb25uZWN0b3I9d2ViMgpJZG9sT25EZW1hbmRIb3N0PWxvY2FsaG9zdDo4ODI0Cklkb2xPbkRlbWFuZEFwaUtleT06YWJjZGUyMjItYzI1ZS0xMWU0LTg0ZTMtZDQ4NTY0YTZjMGVmOmFiY2RlNDQ0LWMyNWUtMTFlNC04NGUzLWQ0ODU2NGE2YzBlZjphYmNkZTExMS1jMjVlLTExZTQtODRlMy1kNDg1NjRhNmMwZWYKSWRvbE9uRGVtYW5kSW5kZXhOYW1lPXFtczEKU1NMTWV0aG9kPVNTTFYyMwpTU0xDZXJ0aWZpY2F0ZT0vb3B0L0F1dG9ub215L1NTTC9jZXJ0LnBlbQpTU0xQcml2YXRlS2V5PS9vcHQvQXV0b25vbXkvU1NML2tleS5wZW0KSW5nZXN0QmF0Y2hTaXplPTEwCg=="
}

The config response field contains the base64-encoded connector configuration.

When you run your onsite connector, the connector requests the configuration from Haven OnDemand by using the Retrieve Config API, and retrieves this base64-encoded configuration file. If you want to use the Retrieve Config API to view the configuration information for your onsite flavor connector, you can set output to config_attributes. Cloud flavor connectors do not require the configuration file, so the default output format is the attributes in this case.

By default, the response does not include any parameters that you have not set in your connector configuration (that is, any parameters that are set to their internal default value). If you want to retrieve the configuration with the default values, you can set include_defaults to true. This parameter is available only when you set output to config_attributes.

When you create a connector, you can configure credentials and a credentials_policy for the connector to use to access the repository. These parameters are required for some connector flavors, and optional for others. For more information, see the individual connector flavor documentation (listed on the Connectors page).

You can optionally retrieve the credentials and credentials_policy configuration for the connector by setting the include_credentials and include_credentials_policy parameters in the Retrieve Config API. These parameters accept a list of properties to include in the API response. The exact credentials and credentials policy properties available depends on the flavor of the connector.

When you request connector credentials, you must provide a decryption token, to allow Haven OnDemand to decrypt and return the credentials information. Haven OnDemand sends the decryption token to the email address defined in your credentials policy, and you supply it to the Retrieve Config API in the token parameter. If you send a token that is not valid to the API, the API automatically generates and sends a new token to this email address.

The following example returns the login_value and password_value properties from the Web_cloud flavor connector credentials, and the notification_email property from the credentials policy. It uses the decryption token xwfpohfjnm.

/1/api/[async|sync]/retrieveconfig/v1?connector=myconnector&include_credentials=login_value&include_credentials=password_value&include_credentials_policy=notification_email&token=xwfpohfjnm

Synchronous
https://api.havenondemand.com/1/api/sync/retrieveconfig/v1
Asynchronous
https://api.havenondemand.com/1/api/async/retrieveconfig/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 retrieve the configuration for. The name can have a maximum length of 100 characters.
Optional
Name Type Description
include_defaults
boolean Set this parameter to true to include configuration options that are using the default values in the response. This option is available only when Output is set to config_attributes. See Connectors. Default value: false.
include_credentials
array<string> A list of the credentials property names to return. This option is available only when Output is set to config_attributes. For information about the available credentials properties, see the individual connector flavor documentation. See Connectors.
include_credentials_policy
array<string> A list of the credentials_policy property names to return. This option is available only when Output is set to config_attributes. For information about the available credentials policy properties, see the individual connector flavor documentation. See Connectors.
output
enum The type of output to return. For onsite flavor connectors, the default value is config_file. For cloud flavor connectors, the default value is config_attributes. The response output changes according to the value of this parameter.
token
string The decryption token to use for decrypting connector credentials and credentials_policy (you receive the token by email). This parameter applies only if a decryption is required for retrieving the specified connector configuration. If the token that you provide is not valid, Haven OnDemand sends a new token to the configured email address for the connector credentials policy.
Enumeration Types

This API's parameters use the enumerations described below:

output
The type of output to return. For onsite flavor connectors, the default value is config_file. For cloud flavor connectors, the default value is config_attributes. The response output changes according to the value of this parameter.
config_attributes Configuration Attributes
The configuration attributes for the connector.
config_file Configuration File
The configuration file for the connector.

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.
Retrieve Config Response {
One of the following: Configuration File Response (This response is returned when output=config_file) or Configuration Attributes Response (This response is returned when output=config_attributes)
}
Configuration File Response {
name ( string ) The name of the connector.
flavor ( string ) The flavor of the connector.
config ( string ) The base64-encoded connector configuration.
licenseKey ( string , optional) The license key for onsite flavor connectors only.
validation ( string , optional) The connector validation key for onsite flavor connectors only.
verification ( string , optional) The verification string for onsite flavor connectors only.
}
Configuration Attributes Response {
name ( string ) The name of the connector.
flavor ( string ) The flavor of connector.
config ( Config ) The configured attributes for this connector. The exact format of the following properties is determined by the flavor of connector. For more information, see the individual flavor documentation. See Connectors.
}
Configuration Attributes Response:Config {
config ( object , optional) The configured config attributes for this connector.
destination ( object , optional) The configured destination attributes for this connector.
schedule ( object , optional) The configured schedule attributes for this connector.
credentials ( object , optional) The configured credentials attributes for this connector.
credentials_policy ( object , optional) The configured credentials_policy attributes for this connector.
description ( string , optional) The connector description.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "oneOf": [
        {
            "properties": {
                "name": {
                    "type": "string"
                },
                "flavor": {
                    "type": "string"
                },
                "config": {
                    "type": "string"
                },
                "licenseKey": {
                    "type": "string"
                },
                "validation": {
                    "type": "string"
                },
                "verification": {
                    "type": "string"
                }
            },
            "required": [
                "name",
                "flavor",
                "config"
            ],
            "type": "object"
        },
        {
            "properties": {
                "name": {
                    "type": "string"
                },
                "flavor": {
                    "type": "string"
                },
                "config": {
                    "see_also": "Connectors",
                    "properties": {
                        "config": {
                            "type": "object"
                        },
                        "destination": {
                            "type": "object"
                        },
                        "schedule": {
                            "type": "object"
                        },
                        "credentials": {
                            "type": "object"
                        },
                        "credentials_policy": {
                            "type": "object"
                        }
                    },
                    "type": "object"
                }
            },
            "required": [
                "name",
                "flavor",
                "config"
            ],
            "type": "object"
        }
    ],
    "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.