Updates Documentation for Sendgrid (#36)

Author: JeffNeff

docs/images/sendgrid-target/create-bridge-1.png

@@ -11,5 +11,6 @@ The following is a list of Triggermesh event destinations known as `Targets`. So
 * [Twilio](./twilio.md): Send an SMS via Twilio in response to events.
 * [Slack](./slack.md): Forward events to Slack as messages to deliver immediately, scheduled, or as an update to a pre-existing message.
 * [Splunk](./splunk.md): Forward arbitrary events to Splunk.
+* [SendGrid](./sendgrid.md): Forward arbitrary events to SendGrid.
 * [Zendesk](./zendesk.md): Perform actions in Zendesk upon reception of certain events.
 * [Elasticsearch](./elasticsearch.md): Forward events to Elasticsearch.

docs/images/sendgrid-target/create-bridge-2.png

@@ -1,159 +1,76 @@
-# Sendgrid event target for Knative Eventing
-
-This event target integrates with Sendgrid, using received Cloud Event messages to create E-mail messages.
-
-## Contents
-
-- [Sendgrid event target for Knative Eventing](#sendgrid-event-target-for-knative-eventing)
-  - [Contents](#contents)
-  - [Prerequisites](#prerequisites)
-  - [Controller Deployment](#controller-deployment)
-    - [From code](#from-code)
-    - [Deploy From Image](#deploy-from-image)
-        - [If you are not a ko user or just do not want to build and deploy from source you can also follow these steps to use one of our published images to deploy.](#if-you-are-not-a-ko-user-or-just-do-not-want-to-build-and-deploy-from-source-you-can-also-follow-these-steps-to-use-one-of-our-published-images-to-deploy)
-  - [Creating a Sendgrid Target adapter.](#creating-a-sendgrid-target-adapter)
-        - [Once the Sendgrid Target Controller has been deployed, and all other needed assets are present, we can create integrations by adding SendgridTargets objects.](#once-the-sendgrid-target-controller-has-been-deployed-and-all-other-needed-assets-are-present-we-can-create-integrations-by-adding-sendgridtargets-objects)
-    - [Status](#status)
-    - [Sendgrid Target as an event Sink](#sendgrid-target-as-an-event-sink)
-      - [Once deployed, Sendgrid Target Adapters are addressable. This means you can use it as a Sink for Knative components! Below you can find an example.](#once-deployed-sendgrid-target-adapters-are-addressable-this-means-you-can-use-it-as-a-sink-for-knative-components-below-you-can-find-an-example)
-    - [Talking to the Sendgrid Target](#talking-to-the-sendgrid-target)
+# Event Target for SendGrid
 
-## Prerequisites
-
-A Sendgrid account is required to run this target:
-
-* Register a Sendgrid account
-* Retrieve from Sendgrid an API token
-
-
-## Controller Deployment
-
-### From code
-
-You can use the [ko](https://github.com/google/ko) tool to compile and deploy from source 
-by executing the following command from the root directory of the Sendgrid target folder. 
-
-```console
-ko apply -f ./config
-```
-
-OR
-
-### Deploy From Image
-
-##### If you are not a ko user or just do not want to build and deploy from source you can also follow these steps to use one of our published images to deploy.
-
-1. Navigate to the [config/](https://github.com/triggermesh/knative-targets/tree/Sendgrid-merge-fix/sendgrid/config) folder and open the '500-controller.yaml' file for editing.
-
-2. Replace line #37: 
-```
-image: ko://github.com/triggermesh/knative-targets/sendgrid/cmd/controller
-```
-With:
-```
-tmjeff/sendgridcontroller:latest
-```
+This event target receives [CloudEvents][ce] and utilizes [SendGrid][sg] to enable the creation and delivery of Email messages via event-data and event-occurrence, respectively.
 
-3. Replace line #55
-```
-value: ko://github.com/triggermesh/knative-targets/sendgrid/cmd/adapter
-```
-With:
-```
-tmjeff/sendgridadapter:latest
-```
-
-4. Now we can build and deploy by moving up one directory to the [sendgrid/](https://github.com/triggermesh/knative-targets/tree/Sendgrid-merge-fix/sendgrid) folder and executing the following:
-
-```shell
-kubectl apply -f config/
-```
-
-
-## Creating a Sendgrid Target adapter. 
-
-##### Once the Sendgrid Target Controller has been deployed, and all other needed assets are present, we can create integrations by adding SendgridTargets objects.
+## Prerequisites
 
-1. Start by navigating to the [samples/](https://github.com/triggermesh/knative-targets/tree/Sendgrid-merge-fix/sendgrid/samples) folder, open the file named '100-secret.yaml', and update the 'apiKey' value with a valid Sendgrid API Key.
+* Register a [SendGrid account][sgSU]
+* Retrieve a [SendGrid API token][api]
 
-2. Next move on to the '200-target.yaml' file in the same folder. Here was can imput some *optional* default values. If you do not require default values and want to pass these values dynamically via parameters in the CE body, you may omit some or all of these by deleteing the lines and leaving only the 'apiKey' portion.
+## Deploying an Instance of the Target
 
-    * A list of (optional) supported spec options: defaultFromEmail, defaultToEmail, defaultToName, defaultFromName, defaultMessage
+Open the Bridge creation screen and add a target of type `SendGrid`.
 
-3. Last file in the folder is ' 300-trigger.yaml' Here you can make modifications or leave it as is to subscribe to the default broker in the namespace you deploy. 
+![Adding a SendGrid target](../images/sendgrid-target/create-bridge-1.png)
 
+In the Target creation form, provide a name for the event Target, and add the following information:
 
-### Status
+* **Default sender name**: Define a default 'name' to be assigned in the `From:` section of the email to be created, if the received event does not contain a **FromName** property.
+* **Default sender email**: Define a default email address to be assigned in the `From:` section of the email to be created, if the received event does not contain a **FromEmail** property.
+* **Default recipient name**: Define a default name to be assigned in the `To:` section of the email to be created, if the received event does not contain a **FromEmail** property.
+* **Default recipient email**: Define a default 'email address' to be assigned in the `To:` section of the email to be created, if the received event does not contain a **ToEmail** property.
+* **Default subject**: Define a default subject to be assigned to the outgoing email to be created, if the received event does not contain a **subject** property.
+* **API Secret**: Reference to a [TriggerMesh secret][tm-secret] containing an [API token][api] for authenticating requests
 
-* The SendgridTarget requires only one Secret, the APIKey, to be provided. 
+**Note:** If there is not a default value specified for all of the optional fields, the event received by that deployment *MUST* contain all of the information noted in the [Event Types](#event-types), save **Message**, or the Target **will** **fail**
 
-* Once its presences is confirmed, the Sendgrid Target Controller will create a Knative Service for the Adapter.  
+![SendgridTarget form](../images/sendgrid-target/create-bridge-2.png)
 
-* A Status summary is added to the SendgridTarget object informing of the all conditions that the target needs.
+After clicking the `Save` button, the console will self-navigate to the Bridge editor. Proceed by adding the remaining components to the Bridge.
 
-* When ready the `status.address.url` will point to the internal point where Cloud Events should be sent.
+After submitting the bridge, and allowing some configuration time, a green checkmark on the main _Bridges_ page indicates that the bridge with a SendGrid event Target was successfully created.
 
-### Sendgrid Target as an event Sink
+![Bridge status](../images/bridge-status-green.png)
 
-#### Once deployed, Sendgrid Target Adapters are addressable. This means you can use it as a Sink for Knative components! Below you can find an example. 
+For more information about using SendGrid, please refer to the [SendGrid documentation][docs].
 
-* The included example trigger ['300-trigger.yaml'](https://github.com/triggermesh/knative-targets/blob/Sendgrid-merge-fix/sendgrid/samples/300-trigger.yaml) Is as follows. 
+### Event Types
 
-```yaml
-apiVersion: eventing.knative.dev/v1beta1
-kind: Trigger
-metadata:
-  name: sendgrid-sample-trigger
-spec:
-  broker: default
-  subscriber:
-    ref:
-      apiVersion: targets.triggermesh.io/v1alpha1
-      kind: SendgridTarget
-      name: triggermesh-email
-```
+Depending on how the target is to be used, defaults can be configured for all available parameters and the Target can accept arbitrary events. Or none of the defaults can be set and these parameters can be passed in at runtime via the event payload.
 
-* Once this, along with the other aformentioned requirements, have been deployed. It is now possible to implement something like the [awskinesis-sinkbinding.yaml](https://github.com/triggermesh/aws-event-sources/blob/master/config/samples/awskinesis-sinkbinding.yaml) example from the [aws-event-sources](https://github.com/triggermesh/aws-event-sources).
+The SendGrid event Target accepts a [JSON][ce-jsonformat] payload with the following properties that will overwrite their respective `spec` parameters.
 
-* By replacing the section starting at line [#18](https://github.com/triggermesh/aws-event-sources/blob/93df64d5b298cc73acfb93f835646cc1d06429c4/config/samples/awskinesis-sinkbinding.yaml#L18) with:
+| Name  |  Type |  Comment | Required
+|---|---|---|---|
+| **FromName** | string | Sender's name |false |
+| **FromEmail** | string | Sender's email | false |
+| **ToName** | string | Recipient's name | false |
+| **ToEmail** | string | Recipient's email | false |
+| **Message** | string | Contents of the message body | false |
+| **Subject** | string | Assigns a subject to the email | false |
 
-```
-  sink:
-    ref:
-      apiVersion: targets.triggermesh.io/v1alpha1
-      kind: ConfluentTarget
-      name: triggermesh-confluent
-```
+When a **Message** property is **not** present, the entire cloud event is passed into the email `body` by default.
 
-* You can now deploy this .yaml file. This will complete the setup of the sinkbinding!
+**Note:** If there is not a default value specified for all of the optional fields, the event received by that deployment *MUST* contain all of the information noted in the [Event Types](#event-types), save **Message**, or the Target **will** **fail**
 
-*****Please note that to deploy the [awskinesis-sinkbinding.yaml](https://github.com/triggermesh/aws-event-sources/blob/master/config/samples/awskinesis-sinkbinding.yaml) example there are other resources that need to be deployed. Please see the [DEVELOPMENT.md](https://github.com/triggermesh/aws-event-sources/blob/master/DEVELOPMENT.md) doc hosted there for full details***** 
+### Example
 
+An example email sent from the Sendgrid Target with the **Message** parameter omitted will look as follows:
 
-### Talking to the Sendgrid Target
-
-* Depending on how you want to use the target. You can set up defaults for all the avalible paraments and pass absolutely nothing to have a static message sent to a defined user. Or you can pass in key:value params to dynamically set all of the variables.
-
-An example of a Cloudevent being passed via a Curl command:
+```email
+from: richard <[email protected]>
+to:	bob <[email protected]>
+date:	Sep 12, 2020, 12:41 AM
+subject: Hello World
 
+Validation: valid Context Attributes, specversion: 1.0 type: dev.knative.samples.helloworld source: dev.knative.samples/helloworldsource id: 536808d3-88be-4077-9d7a-a3f162705f79 time: 2020-09-12T04:41:00.000610299Z datacontenttype: application/json Extensions, knativearrivaltime: 2020-09-12T04:41:00.006331845Z knativehistory: default-kne-trigger-kn-channel.midimansland.svc.cluster.local Data, { "event":"data"} 
 ```
-curl -v "10.152.183.229" \
-       -X POST \
-       -H "Ce-Id: 536808d3-88be-4077-9d7a-a3f162705f79" \
-       -H "Ce-Specversion: 1.0" \
-       -H "Ce-Type: dev.knative.samples.helloworld" \
-       -H "Ce-Source: dev.knative.samples/helloworldsource" \
-       -H "Content-Type: application/json" \
-       -d '{"FromEmail":"[email protected].","ToEmail":"[email protected]", \
-         "FromName":"SendgridTarget","ToName":"endUser","Message":"hello"}'
-```
-
-A list of possible keys:
-- message
-- fromname
-- fromemail
-- toname
-- toemail
 
-**If the "Message" key:value is omited. The body of the email will contain the entire cloud event**
+[sgSU]:https://signup.sendgrid.com/
+[sg]:https://sendgrid.com/
+[api]:https://sendgrid.com/docs/ui/account-and-settings/api-keys/
 
+[ce]: https://cloudevents.io/
+[ce-jsonformat]: https://github.com/cloudevents/spec/blob/v1.0/json-format.md
+[tm-secret]:https://docs.triggermesh.io/guides/secrets/
+[docs]: https://sendgrid.com/docs/