Create Salesforce Publisher page (#136)

* Update comment regarding authorization flow
Axway · Feb 28, 2022 · cb27911 · cb27911
1 parent b00786a
commit cb27911
Show file tree

Hide file tree

Showing 6 changed files with 43 additions and 41 deletions.
diff --git a/content/en/docs/install/_index.md b/content/en/docs/install/_index.md
@@ -347,7 +347,7 @@ kubectl get ingress -o=jsonpath='{.items[?(@.metadata.name=="streams-hub")].stat
 
 Then upgrade your Streams installation with the [Helm parameter](/docs/install/helm-parameters-reference/#ingress-parameters) `ingress.host` set with the DNS name retrieved previously. For more information, see [Helm upgrade](/docs/install/upgrade/).
 
-{{< alert title="Note" >}} _k8s.yourdomain.tld_ is used throughout this documentation as an example hostname value.{{< /alert >}}
+{{< alert title="Note" >}} *k8s.yourdomain.tld* is used throughout this documentation as an example hostname value.{{< /alert >}}
 
 ### Ingress TLS
 

diff --git a/content/en/docs/install/test-with-docker-compose.md b/content/en/docs/install/test-with-docker-compose.md
@@ -77,7 +77,7 @@ docker-compose up -d
 
 ### Ensure all the services are up and running
 
-You can run the _process status_ command to check the status of the containers:
+You can run the *process status* command to check the status of the containers:
 
 ```bash
 docker-compose ps

diff --git a/content/en/docs/publishers/publisher-http-poller.md b/content/en/docs/publishers/publisher-http-poller.md
@@ -98,7 +98,8 @@ The HTTP poller publisher can fetch data from an API that is secured with [OAuth
 
 The OAuth2 authorization workflow is implemented with the following limitations:
 
-* The workflow is initiated on the authorization server URL on every polling. Refresh token mechanism is not implemented.
+* The OAuth2 authorization workflow is initiated on the authorization server URL for the first polling, and the retrieved access token is reused for following requests until it expires.
+* Refresh token mechanism is not implemented.
 * Only access token of type [Bearer](https://datatracker.ietf.org/doc/html/rfc6749#section-7.1) is supported.
 * The authorization request is made via a `POST` method on the authorization server, and the client credentials are sent either via `header` or `body`.
 

diff --git a/content/en/docs/publishers/publisher-kafka.md b/content/en/docs/publishers/publisher-kafka.md
@@ -5,7 +5,7 @@ weight: 3
 date: 2020-04-02T00:00:00.000Z
 description: Learn how to configure a topic associated to a Kafka Publisher.
 ---
-{{< alert title="Beta feature" color="warning" >}}Kafka publisher is still experimental, and will be enhanced in future releases.{{< /alert >}}
+{{< alert title="Beta feature" color="warning" >}}This feature is released in beta.{{< /alert >}}
 
 Streams can act as a consumer of your dedicated Apache Kafka cluster. It consumes records from one configured topic, then publishes those records into Streams platform to broadcast data to any of Streams [subscribers](../../subscribers).
 

diff --git a/content/en/docs/publishers/publisher-sfdc.md b/content/en/docs/publishers/publisher-sfdc.md
@@ -3,61 +3,61 @@ title: Salesforce Publisher
 linkTitle: Salesforce Publisher
 weight: 4
 date: 2020-07-02
-description: Learn how to configure a topic associated to a Salesforce Publisher.
+description: The Salesforce Publisher provides the capability to capture changes from Salesforce.com via Salesforce Streaming API PushTopics or Salesforce Platform Events. Learn how to configure a topic associated to a Salesforce Publisher.
 ---
 
-{{< alert title="Beta feature" color="warning" >}}
-Salesforce Publisher is still experimental, and will be enhanced in future releases.
-{{< /alert >}}
+{{< alert title="Beta feature" color="warning" >}}This feature is released in beta.{{< /alert >}}
 
-## Salesforce Publisher
+PushTopics provide the ability to subscribe to changes related to Salesforce Objects (SObjects) whereas Platform Events allow Salesforce users to define their own publish/subscribe events. After integrated with Streams, Salesforce events can then be broadcast by any of Streams [subscribers](/docs/subscribers).
 
-The Salesforce Publisher provides the capability to capture changes from Salesforce.com via Salesforce Streaming API PushTopics or Salesforce Platform Events. PushTopics provide the ability to subscribe to change events related to Salesforce Objects (SObjects). Platform Events allow Salesforce users to define their own publish/subscribe events.
-Once integrated with Streams, Salesforce events can be then broadcast by any of Streams [subscribers](../../subscribers).
+## Setup a new connected App in Salesforce
 
-## Setup a new Connected App in Salesforce
+You must create a connected App in Salesforce to secure Streams connection to Salesforce with JWT Bearer token flow. The OAuth 2.0 JWT bearer token flow allows the client to post a JWT to the Salesforce OAuth token endpoint. Then, Salesforce processes the JWT, which includes a digital signature, and issues an access token based on prior approval of the app.
 
-You must [create a Connected App](https://help.salesforce.com/articleView?id=connected_app_create.htm&type=5) in Salesforce to secure Streams connection to Salesforce with JWT Bearer token flow.
-With the OAuth 2.0 JWT bearer token flow, the client posts a JWT to the Salesforce OAuth token endpoint. Salesforce processes the JWT, which includes a digital signature, and issues an access token based on prior approval of the app.
-
-To setup your Salesforce _Connected App_ properly, follow these steps:
-
-  1. Create and configure [_Connected App_ basic settings](https://help.salesforce.com/articleView?id=connected_app_create.htm).
+To setup your Salesforce Connected App, follow [Create a Connected App](https://help.salesforce.com/articleView?id=connected_app_create.htm) in Salesforce documentation.
 
-  2. Enable [Oauth settings for API integration](https://help.salesforce.com/articleView?id=connected_app_create_api_integration.htm):
-     * Make sure to configure your Oauth settings for *JWT OAuth flow* by selecting `Use Digital Signatures`.
-     * You must upload the public key of your digital certificate.
-     * You can create a Private Key and Self-Signed Digital Certificate by following this [guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_key_and_cert.htm).
-     * Note that when using *JWT OAuth flow* the `Callback URL` is not used. However it is mandatory in Salesforce's UI, so you can enter any value such as `http://localhost`.
-     * Select the OAuth scopes to apply to the connected app:
-       * `Access and manage your data (api)`
-       * `Perform requests on your behalf at any time (refresh_token, offline_access)`
-
-  3. After a connected app is installed in your org, you can [manage access](https://help.salesforce.com/articleView?id=connected_app_manage.htm) to it. Configure permissions and policies for the app, explicitly defining who can use the connected app and where they can access the app from.
-     * Manage [Oauth Access Policies](https://help.salesforce.com/articleView?id=connected_app_manage_oauth.htm):
-       * Under OAuth Policies, click the *Permitted Users* dropdown menu and select `Admin approved users are pre-authorized`.
-       * Set *Refresh Token Policy* to `Refresh token is valid until revoked`.
-     * Make sure the [IP Relaxation and Continuous IP Enforcement](https://help.salesforce.com/articleView?id=connected_app_continuous_ip.htm) settings of the _Connected App_ settings are compatible with the settings of your Salesforce Org.
-     * Give users access to the _Connected App_ by configuring the [profiles or permission sets](https://help.salesforce.com/articleView?id=connected_app_manage_additional_settings.htm).
+After your connected App is created, follow the [Enable OAuth Settings for API Integration](https://help.salesforce.com/articleView?id=connected_app_create_api_integration.htm) section to integrate your App with the Salesforce API.
+
+When enabling the OAuth settings, ensure the following:
+
+* Configure your Oauth settings for _JWT OAuth flow_ by selecting `Use Digital Signatures`.
+* You must upload the public key of your digital certificate.
+* You can create a Private Key and Self-Signed Digital Certificate by following [Create a Private Key and Self-Signed Digital Certificate](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/fdx_dev_auth_key_and_cert.htm).
+* Note that when using _JWT OAuth flow_ the `Callback URL` is not used. However it is mandatory in Salesforce's UI. To workaround this, you can enter any value, such as `http://localhost`.
+* Select the OAuth scopes to apply to the connected app:
+    * Access and manage your data (api)
+    * Perform requests on your behalf at any time (refresh_token, offline_access)
+
+## Manage access to your connected App
+
+After a connected App is installed in your organization, you can [manage the app access](https://help.salesforce.com/articleView?id=connected_app_manage.htm) by configuring permissions and policies for the app. For example, you can define who can use the connected app and where they can access the app from.
+
+From Salesforce UI, configure the access to your connected App:
+
+* Manage [Oauth Access Policies](https://help.salesforce.com/articleView?id=connected_app_manage_oauth.htm):
+    * Under OAuth Policies, click the **Permitted Users** dropdown menu and select **Admin approved users are pre-authorized**.
+    * Set **Refresh Token Policy** to **Refresh token is valid until revoked**.
+* Make sure the [IP Relaxation and Continuous IP Enforcement](https://help.salesforce.com/articleView?id=connected_app_continuous_ip.htm) settings of the Connected App settings is compatible with the settings of your Salesforce Org.
+* Give users access to the connected App by configuring the [profiles or permission sets](https://help.salesforce.com/articleView?id=connected_app_manage_additional_settings.tm).
 
 ## Salesforce publisher configuration
 
 The Salesforce publisher requires some specific configuration.
 
 | Configuration Entry           | Mandatory |  Default value | Description |
 | ----------------------------- | --------- | -------------- | ----------- |
-| loginUrl                      | Yes       | None           | The login url of your Salesforce instance, i.e. <https://login.salesforce.com> |
-| instanceUrl                   | Yes       | None           | The url of your Salesforce instance. |
+| loginUrl                      | Yes       | None           | The login URL of your Salesforce instance, for example, <https://login.salesforce.com> |
+| instanceUrl                   | Yes       | None           | The URL of your Salesforce instance. |
 | privateKey                    | Yes       | None           | The private key (PKCS#1 or PKCS#8) of the Digital Certificate setup in your Salesforce Connected App. |
-| clientId                      | Yes       | None           | The client id or customer id of your Salesforce Connected App. |
+| clientId                      | Yes       | None           | The client ID or customer ID of your Salesforce Connected App. |
 | username                      | Yes       | None           | The username, login or email of your Salesforce account. |
-| channel                       | Yes       | None           | The Salesforce PushTopics or Channel id to subscribe to. |
-| retryMaxAttempts              | no        | 3              | The max number of retries in case of errors |
-| retryBackOffInitialDuration   | no        | PT1S           | Period after which the first retry is attempt (ISO-8601 format).  Min = PT0S (0s) ; Max = PT10S (10s) |
+| channel                       | Yes       | None           | The Salesforce PushTopics or Channel ID to subscribe to. |
+| retryMaxAttempts              | no        | 3              | The max number of retries in case of errors. |
+| retryBackOffInitialDuration   | no        | PT1S           | Period after which the first retry is attempt (ISO-8601 format). Min = PT0S (0s); Max = PT10S (10s) |
 | retryBackOffMaxDuration       | no        | PT10S          | Period max between two attempt (ISO-8601 format). Min = PT0S (0s) ; Max = PT60S (60s) |
 | retryBackOffFactor            | no        | 0.5            | The factor used to determine the next retry duration |
 
-Here is an example of a configuration of the Salesforce Publisher:
+The following is an example of a configuration of the Salesforce Publisher:
 
 ```json
 {

diff --git a/content/en/docs/subscribers/subscriber-webhook.md b/content/en/docs/subscribers/subscriber-webhook.md
@@ -51,7 +51,8 @@ The Webhook subscriber can post data to an API that is secured with [OAuth2](htt
 
 The OAuth2 authorization workflow is implemented with the following limitations:
 
-* The OAuth2 authorization workflow is initiated on the authorization server URL each time data is posted. Refresh token mechanism is not implemented.
+* The OAuth2 authorization workflow is initiated on the authorization server URL for the first polling, and the retrieved access token is reused for following requests until it expires.
+* Refresh token mechanism is not implemented.
 * Only access token of type [Bearer](https://datatracker.ietf.org/doc/html/rfc6749#section-7.1) is supported.
 * The authorization request is made via a `POST` method on the authorization server, and the client credentials are sent either via `header` or `body`.