# DMaaP connection objects

DMaaP Connection Objects are JSON objects that:

1. At Runtime - this is generated by the DCAE Platform and passed to the component in its application_configuration to be used to connect to the DMaaP feed or topic. Components will receive the entire object with all properties populated (default will be `null) unless specified otherwise.
2. During dcae_cli testing - this is provided through the command-line argument `--dmaap-file` to test the component with manually provisioned feeds and topics. Developers are not required to provide the entire object.  The required properties are labeled below with "*Required as input*".

## Message Router

Publishers and subscribers have the same generated `Dmaap Connection Object` structure.  Here's an example for any given config-key:
(This is what will be in application_configuration)

```json
{
    "type": "message_router",
    "aaf_username": "some-user",
    "aaf_password": "some-password",
    "dmaap_info": {
        "client_role": "com.dcae.member",
        "client_id": "1500462518108",
        "location": "mtc00",
        "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
    }
}
```

At the top-level:

Property Name | Type | Description
------------- | ---- | -----------
type | string | *Required as input*.  Must be `message_router` for message router topics
aaf_username | string | AAF username message router clients use to authenticate with secure topics
aaf_password | string | AAF password message router clients use to authenticate with secure topics
dmaap_info | JSON object | *Required as input*. Contains the topic connection details

The `dmaap_info` object contains:

Property Name | Type | Description
------------- | ---- | -----------
client_role | string | AAF client role that's requesting publish or subscribe access to the topic
client_id | string | Client id for given AAF client
location | string | DCAE location for the publisher or subscriber, used to set up routing
topic_url | string | *Required as input*. URL for accessing the topic to publish or receive events

The --dmaap-file argument (to the component `run` or `dev` command), must minimally contain:

```json
{
    "type": "message_router",
    "dmaap_info": {
        "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
    }
}
```

## Data Router

### Publisher

Here's an example of what the generated `Dmaap Connection Object` for Data Router Publisher looks like:
(This is what will be in application_configuration)

```json
{
    "type": "data_router",
    "dmaap_info": {
        "location": "mtc00",
        "publish_url": "https://we-are-data-router.us/feed/xyz",
        "log_url": "https://we-are-data-router.us/feed/xyz/logs",
        "username": "some-user",
        "password": "some-password",
        "publisher_id": "123456"
    } 
}
```

At the top-level:

Property Name | Type | Description
------------- | ---- | -----------
type | string | *Required as input*.  Must be `data_router` for data router feeds
dmaap_info | JSON object | *Required as input*. Contains the feed connection details

The `dmaap_info` object contains:

Property Name | Type | Description
------------- | ---- | -----------
location | string | DCAE location for the publisher, used to set up routing
publish_url | string | *Required as input*. URL to which the publisher makes Data Router publish requests
log_url | string | URL from which log data for the feed can be obtained
username | string | Username the publisher uses to authenticate to Data Router 
password | string | Password the publisher uses to authenticate to Data Router
publisher_id | string | Publisher id in Data Router

The --dmaap-file argument (to the component `run` or `dev` command), must minimally contain:

```json
{
    "type": "data_router",
    "dmaap_info": {
        "publish_url": "https://we-are-data-router.us/feed/xyz"
    }
}
```

### Subscriber

Here's an example of what the generated `Dmaap Connection Object` for a Data Router Subscriber looks like:
(This is what will be passed in application_configuration)

```json
{
    "type": "data_router",
    "dmaap_info": {
        "location": "mtc00",
        "delivery_url": "https://my-subscriber-app.dcae:8080/target-path",
        "username": "some-user",
        "password": "some-password",
        "subscriber_id": "789012"
    } 
}
```

At the top-level:

Property Name | Type | Description
------------- | ---- | -----------
type | string | *Required as input*.  Must be `data_router` for data router feeds
dmaap_info | JSON object | *Required as input*. Contains the feed connection details

The `dmaap_info` object contains:

Property Name | Type | Description
------------- | ---- | -----------
location | string | DCAE location for the subscriber, used to set up routing
delivery_url | string | URL to which the Data Router should deliver files
username | string | Username Data Router uses to authenticate to the subscriber when delivering files
password | string | Password Data Router uses to authenticate to the subscriber when delivering files
subscriber_id | string | Subscriber id in Data Router

The --dmaap-file argument (to the component `run` or `dev` command), must minimally contain:

```json
{
    "type": "data_router",
    "dmaap_info": {
    }
}
```

It is the recommended security practice that `username` and `password` are specified.
You cannot provide the `delivery_url` in your dmaap-file, because it's not constructed until deployment time. Therefore, after the test deployment, go back to the Data Router Feed and provide the delivery_url (in order to start receiving the feeds). 

### Data Router Example

(After the Data Router feed has been manually provisioned)

```
$ dcae_cli component run --dmaap-file $dmaap_file $component-name
DCAE.Run | WARNING | Your component is a data router subscriber. Here are the delivery urls:

        some-sub-dr: http://135.205.226.128:32838/identity
```

(Update the Data Router Feed to provide the delivery_url).