diff --git a/salesforce-pubsub/1.2/antora.yml b/salesforce-pubsub/1.2/antora.yml new file mode 100644 index 0000000000..9f95f81c73 --- /dev/null +++ b/salesforce-pubsub/1.2/antora.yml @@ -0,0 +1,18 @@ +name: salesforce-pubsub-connector +version: '1.2' +display_version: 1.2 (Mule 4) +title: Salesforce Pub/Sub Connector +nav: +- modules/ROOT/nav.adoc +asciidoc: + attributes: + page-component-desc: Enables access to the Salesforce Pub/Sub API. + page-connector-type: Connector + page-connector-level: Select + page-exchange-group-id: com.mulesoft.connectors + page-exchange-asset-id: mule4-salesforce-pubsub-connector + page-runtime-version: 4.3.0 + page-release-notes-page: release-notes::connector/salesforce-pubsub-connector-release-notes-mule-4.adoc + page-vendor-name: salesforce + page-vendor-title: Salesforce + page-notice-banner-message: Standard support for Java 8 and 11 ends in March 2025 for Mule 4.8 Edge and August 2026 for 4.6 LTS. Plan your upgrade path for apps that are running on Java 8 or 11 accordingly. diff --git a/salesforce-pubsub/1.2/modules/ROOT/attachments/salesforce-pubsub-whitepaper.pdf b/salesforce-pubsub/1.2/modules/ROOT/attachments/salesforce-pubsub-whitepaper.pdf new file mode 100644 index 0000000000..ac92ccf0fb Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/attachments/salesforce-pubsub-whitepaper.pdf differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/image-source-files/pubsub-channel-listener-config.graffle b/salesforce-pubsub/1.2/modules/ROOT/image-source-files/pubsub-channel-listener-config.graffle new file mode 100644 index 0000000000..2434cefa21 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/image-source-files/pubsub-channel-listener-config.graffle differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/basic-authentication.png b/salesforce-pubsub/1.2/modules/ROOT/images/basic-authentication.png new file mode 100644 index 0000000000..de98dff8c6 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/basic-authentication.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/oauth-jwt.png b/salesforce-pubsub/1.2/modules/ROOT/images/oauth-jwt.png new file mode 100644 index 0000000000..ac6710cbe5 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/oauth-jwt.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/oauth-saml.png b/salesforce-pubsub/1.2/modules/ROOT/images/oauth-saml.png new file mode 100644 index 0000000000..63e878785e Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/oauth-saml.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/oauth-username-password.png b/salesforce-pubsub/1.2/modules/ROOT/images/oauth-username-password.png new file mode 100644 index 0000000000..ec80eb14a8 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/oauth-username-password.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/oauth2.png b/salesforce-pubsub/1.2/modules/ROOT/images/oauth2.png new file mode 100644 index 0000000000..1f2de1ae82 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/oauth2.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/publish-an-event.png b/salesforce-pubsub/1.2/modules/ROOT/images/publish-an-event.png new file mode 100644 index 0000000000..cfb2815e2c Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/publish-an-event.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/pubsub-channel-listener-config.png b/salesforce-pubsub/1.2/modules/ROOT/images/pubsub-channel-listener-config.png new file mode 100644 index 0000000000..ae27ac16e6 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/pubsub-channel-listener-config.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/salesforce-pub-publish-timeout.png b/salesforce-pubsub/1.2/modules/ROOT/images/salesforce-pub-publish-timeout.png new file mode 100644 index 0000000000..d04bb6441e Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/salesforce-pub-publish-timeout.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/images/subscribe-to-a-channel.png b/salesforce-pubsub/1.2/modules/ROOT/images/subscribe-to-a-channel.png new file mode 100644 index 0000000000..95bce1bce1 Binary files /dev/null and b/salesforce-pubsub/1.2/modules/ROOT/images/subscribe-to-a-channel.png differ diff --git a/salesforce-pubsub/1.2/modules/ROOT/nav.adoc b/salesforce-pubsub/1.2/modules/ROOT/nav.adoc new file mode 100644 index 0000000000..aa1a538c64 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/nav.adoc @@ -0,0 +1,7 @@ +.xref:index.adoc[Salesforce Pub/Sub Connector] +* xref:index.adoc[Salesforce Pub/Sub Connector Overview] +* xref:salesforce-pubsub-connector-studio.adoc[Using Anypoint Studio to Configure Salesforce Pub/Sub Connector] +* xref:salesforce-pubsub-connector-message-tracking-example.adoc[Salesforce Pub/Sub Connector - Tracking Platform Events Example] +* xref:salesforce-pubsub-connector-xml-maven.adoc[Salesforce Pub/Sub Connector XML and Maven Support] +* xref:salesforce-pubsub-connector-examples.adoc[Salesforce Pub/Sub Connector Examples] +* xref:salesforce-pubsub-connector-reference.adoc[Salesforce Pub/Sub Connector Reference] diff --git a/salesforce-pubsub/1.2/modules/ROOT/pages/index.adoc b/salesforce-pubsub/1.2/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000000..b51cfa45d8 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/pages/index.adoc @@ -0,0 +1,63 @@ += Salesforce Pub/Sub Connector 1.2 + +Anypoint Connector for Salesforce Pub/Sub (Salesforce Pub/Sub Connector) enables you to connect to the Pub/Sub API, which provides a single interface for publishing and subscribing to platform events, including real-time event monitoring events and change data capture events. This connector complements Anypoint Connector for Salesforce (Salesforce Connector) and provides additional ways to interface with Salesforce's ecosystem. The Salesforce Pub/Sub API enables you to publish and subscribe to events and request schemas and topic information with one API. + +For information about compatibility and fixed issues, refer to the Salesforce Pub/Sub Connector Release Notes. + +== Before You Begin + +To use this connector, you must be familiar with: + +* The Salesforce Pub/Sub Connector’s API +* Anypoint Connectors +* Mule runtime engine (Mule) +* Elements and global elements in a Mule flow +* How to create a Mule app using Anypoint Studio + +Before creating an app, you must have: + +* Credentials to access the Salesforce Pub/Sub target resource +* Anypoint Platform +* Anypoint Studio version 7.3.5 or later + +== Common Use Cases For the Connector + +These are some common use cases for Salesforce Pub/Sub Connector: + +* Subscribe to event monitoring real-time events +* Subscribe to a standard or high volume platform event, such as `AppointmentSchedulingEvent` +* Publish a platform event (high volume only) back into Salesforce to restrict a user’s profile when they log in to Salesforce after working hours +* Subscribe to change data capture events and syn order data in an external inventory system + +For examples of these use cases, refer to xref:salesforce-pubsub-connector-examples.adoc[Salesforce Pub/Sub Connector Examples]. + +== Connection Types + +Salesforce Pub/Sub connections use the following authentication types: + +* Basic Authentication + +Uses a username and a password for authentication + +NOTE: The `Basic Authentication` connection type is only supported for Salesforce API v61.0 and earlier versions. + +* OAuth v2.0 + +Delegates user authentication to the service hosting the user account +* OAuth JWT + +Uses OAuth 2.0 with a JSON Web Token (JWT) request for user authentication +* OAuth Username Password + +Uses OAuth 2.0 with a username and a password for authentication +* OAuth SAML + +Uses OAuth 2.0 with a signed SAML 2.0 assertion to request an access token + +For information about configuring authentication types, refer to xref:salesforce-pubsub-connector-studio.adoc#configure-global-element[Configure a Global Element for the Connector]. + +== Next Step + +After you complete the prerequisites, you are ready to create an app and configure the connector using xref:salesforce-pubsub-connector-studio.adoc[Anypoint Studio]. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* xref:connectors::introduction/intro-use-exchange.adoc[Use Exchange to Discover Connectors, Templates, and Examples] +* xref:salesforce-pubsub-connector-reference.adoc[Salesforce Pub/Sub Connector Reference] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-examples.adoc b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-examples.adoc new file mode 100644 index 0000000000..8be5149945 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-examples.adoc @@ -0,0 +1,274 @@ += Salesforce Pub/Sub Connector 1.2 Examples + +The following examples show several Mule flows for Salesforce Pub/Sub Connector: + +* <> +* <> +* <> + + +== Before You Begin + +These examples require: + +* Java 8, 11, or 17 +* Anypoint Studio 7.5 or later +* Mule runtime engine (Mule) 4.3.0 or later +* DataWeave + +== Configure a Connection + +To secure connections, you must specify the connection field +values. To do this: + +* <> +* <> +* <> + +[[create-config-file]] +=== Create a Configuration File for a Connection + +Create a configuration file that includes properties for a connection: + +. Create a file named `mule-app.properties` in the `/src/main/resources/` folder. +. In the `mule-app.properties` file, create a set of properties for the connection, +similar to the ones that follow, replacing the bracketed text (including the brackets) +with the correct values for your configuration: ++ +---- +m4-config.username= +m4-config.password= +m4-config.securityToken= +m4-config.url= +---- ++ +The properties used vary depending on the selected connection configuration. + +For more information about creating a properties file, refer to xref:mule-runtime::mule-app-properties-to-configure.adoc[Configuring Property Placeholders]. + +[[configure-conn]] +=== Configure the Connection Global Elements + +Configure global elements for connection: + +. Create a new Mule project. +. In the *Mule Palette* view, click *Search in Exchange* and enter `Salesforce Pub/Sub`. +. Add *Salesforce Pub/Sub Connector* to the *Selected modules* section and click *Finish*. +. Click the *Global Elements* tab and click *Create*. +. Select *Connector Configuration > Salesforce Pub/Sub Config* and click *OK*. +. Enter the values to configure either Basic Authentication, OAuth v2.0, OAuth JWT, OAuth Username Password, or OAuth SAML. Note that the `Basic Authentication` connection type is only supported for Salesforce API v61.0 and earlier versions. +. Click the *Test Connection* button to ensure there is connectivity with the Salesforce Pub/Sub API. A successful message should pop up. +. Click *OK*. +. Open the HTTPS Listener config in *Global Element Configuration*. +. Click the *TLS* tab and select *TLS Configuration > Edit inline*. +. Specify the *Key Store Configuration* with the generated keystore details to enable HTTPS on this configuration. +. Click *OK*. + +[[configure-global]] +=== Configure a Global Element for the Properties File + +Configure a global element for the `mule-app.properties` file so that Mule knows +where to find it: + +. Click the *Global Elements* tab and click *Create*. +. In the *Choose Global Type* dialog, select *Configuration properties* and click *OK*. +. In the *File* field, enter `mule.app.properties`. +. Click *OK*. + + +[[publish-an-event]] +== Publish an Event + +This example Mule flow publishes an event and uses the following operations: + +* *HTTP Listener* + +Accepts data from HTTP requests. +* *Transform Message* + +Outputs the data in Java. +* *Publish event* + +Publishes the given list of events to the specified event topic. Only high-volume platform events, including real-time event monitoring events and change data capture events, are allowed. ++ +Enter the following values: ++ +[%header,cols="30s,70a"] +|=== +|Field |Value +|Topic| Name of the topic used for message publishing, for example, `/event/gRPCMunitTestDoNotDelete__e` +|Job Id| `payload` +|=== + +image::publish-an-event.png["Studio flow for the Publish event operation"] + +=== XML for This Example + +Paste this code into the Studio XML editor to quickly load the flow for this example into your Mule app: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + + + + + + + + + + + +---- + + +[[publish-request]] +== Configure Publish Request Timeout + +This example shows how to configure the *Publish Request Timeout* and *Publish Request Time Unit* parameters to control the timeout behavior for publish operations. This is useful when you want to ensure that publish requests don't wait indefinitely and have specific timeout requirements. This example Mule flow configures timeout settings. + +The key timeout configuration parameters are: + +[%header,cols="30s,70a"] +|=== +|Field |Value +|Publish Request Timeout| `60` (60 units of time before timeout) +|Publish Request Time Unit| `SECONDS` (timeout unit specification) +|=== + +image::salesforce-pub-publish-timeout.png["Global element properties window for the Publish event operation with timeout configuration"] + +=== XML for This Example + +Paste this code into the Studio XML editor to quickly load the flow for this example into your Mule app: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + + + + + + + + + + +---- + + + + +[[subscribe-to-a-channel]] +== Subscribe to a Channel + +This example Mule flow subscribes to a channel and uses the following operations: + +* *Subscribe channel listener* + +Subscribes to a streaming channel. This source provides channel-related notification settings for new events that occur after you subscribe. ++ +NOTE: A channel must be published to Salesforce before a subscription to the channel is created. ++ +Enter the following values: ++ +[%header,cols="30s,70a"] +|=== +|Field |Value +|Channel name| Name of the streaming channel to subscribe to, for example, `/event/gRPCMunitTestDoNotDelete__e` +|Replay option| One of the given implementations, for example, `Earliest`. For more information on how to use `Replay id from object store` in *Replay option*, refer to xref:salesforce-pubsub-connector-studio.adoc#store-objectstore[Store the Replay ID in the Object Store]. +|Batch events size| Total number of events included in a server batch. Lower values indicate small memory footprint with more server calls, while bigger values indicate bigger memory footprint with fewer API calls. A new batch of events is requested by the connector after the flow consumes the existing events, for example, `1000` +|=== +* *Logger* + +Shows the HTTP response from the *Subscribe channel listener* source + +image::subscribe-to-a-channel.png["Studio flow for the Subscribe channel listener source"] + +=== XML for This Example + +Paste this code into the Studio XML editor to quickly load the flow for this example into your Mule app: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + + + + + + + + + +---- + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-message-tracking-example.adoc b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-message-tracking-example.adoc new file mode 100644 index 0000000000..5255ca3744 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-message-tracking-example.adoc @@ -0,0 +1,70 @@ += Salesforce Pub/Sub Connector 1.2 - Tracking Salesforce Platform Events Example + +One way to use Salesforce Pub/Sub Connector is to track whether a Salesforce platform event is received from MuleSoft and processed. You can keep track of processed messages using a combination of Salesforce and Mule runtime engine (Mule). + +For a detailed example of one approach to message tracking, see xref:attachment$salesforce-pubsub-whitepaper.pdf[Keeping Track of the Processed and Received Messages]. + +== Replay ID and MuleSoft Object Store + +To implement message tracking, it's important to understand the core concepts of the Salesforce Streaming API, the Replay ID attribute, and MuleSoft object store. + +[[replay-id]] +=== Replay ID + +On the Salesforce Event Bus, each published event message is assigned an opaque ID, which is contained in the Replay (`replay_id`) attribute. The system populates the Replay ID field value when the event message is delivered to subscribers and refers to the position of the event message within the event stream. + +The event stream has a message durability of 72 hours for high-volume platform events so, using the Replay ID, it's possible to receive event messages from the event stream that fall within that period. The MuleSoft subscriber must carefully track the processed Replay IDs to ensure it doesn't miss or duplicate process events in case of downtime or restart (either intentional or unintentional). + +To enable advanced Replay ID tracking to ensure that the event message is received and processed correctly, you are given control over the replay behavior with the Salesforce Pub/Sub Connector in the connector configuration UI. + +This example configuration uses the *Replay id from object store* option for the *Replay option* property and specifies a dedicated object store in the *Object Store Name* field: + +image::pubsub-channel-listener-config.png["Subscribe channel listener General properties configuration panel"] + + +The following table shows the Replay ID options: + +[%header%autowidth.spread] +|=== +| Replay Option | Description | Usage +| `Custom replay id` | The Subscriber receives all stored events after the event specified by its replay ID value, and new events. | Catch up on missed events after a certain event message, for example, after a connection failure. To subscribe with a specific replay ID, save the replay ID of the event message to retrieve stored events after, and then use it when you resubscribe. +| `Latest` | If no replay option is specified, this is the default. The Subscriber receives new events that are broadcast after the client subscribes. | It is best to subscribe with the `Latest` option to receive new event messages. To get earlier event messages, don't use this option. +| `Earliest` | The Subscriber receives all events, including past events that are within the 72-hour retention window. | Catch up on missed events and retrieve all stored events, for example, after a connection failure. Using this option can slow performance if a large number of event messages are stored. +| `Replay id from object store` | The Subscriber receives only events with a replay ID higher than the specified value in object store. If no value is found, it defaults to `Earliest`. Provide values for the *Object Store Name* and the *Object Store Key* fields to connect to the desired object store and retrieve the replay ID value. | For more information on how to use `Replay id from object store`, refer to xref:salesforce-pubsub-connector-studio.adoc#store-objectstore[Store the Replay ID in the Object Store]. +|=== + +[[mulesoft-object-store]] +=== MuleSoft Object Store + +Mule runtime engine (Mule) uses object stores to persist data for later retrieval. Mule uses object stores in various filters, routers, and other message processors that store states between messages. + +For CloudHub deployments, the free Object Store v2 limits usage to 10 transactions per second (TPS) per application. The premium add-on for Object Store v2 increases the limit to 100 TPS per application. + +[[example-message-tracking]] +== Example of Tracking Messages + +One of the challenges of the Salesforce-provided event-based integration is knowing whether a particular message is received and processed by the subscriber. To achieve this goal, additional logic is required. + +For details about the implementation logic for one approach to message tracking, see xref:attachment$salesforce-pubsub-whitepaper.pdf[Keeping Track of the Processed and Received Messages]. + +[[batch-event-size]] +== Batch Event Size + +A key feature of Salesforce Pub/Sub Connector is that it allows you to control the number of messages received and processed in a given period of time using the *Batch event size* (`BatcheventSize`) attribute of the *Subscribe Channel Listener* operation to specify the total number of events included in a server batch. + +=== Batch Event Size Example + +In a test case, 500 records were created in Salesforce using Apex code. After all the processing completed in Salesforce, the "delta" time between creating the log entry during record creation and the log entry from the confirmation message was analyzed and MuleSoft worker statistics were reviewed. + +In summary: + +* Using `BatcheventSize=1` vs the maximum value of 100 triples the time until Salesforce records the processing, which is still in the area of milliseconds. +* A CloudHub 0.1 vCore worker is sufficient to handle the load. There is no performance improvement when using a 0.2 core worker. + +For more details about this test case, see xref:attachment$salesforce-pubsub-whitepaper.pdf[BatcheventSize - How Does it Work?]. + +== See Also + +* xref:attachment$salesforce-pubsub-whitepaper.pdf[Have my Published Salesforce Platform Events Been Received by My Mule App?] +* https://developer.salesforce.com/docs/platform/pub-sub-api/guide/event-message-durability.html[Event Message Durability] +* https://developer.salesforce.com/docs/platform/pub-sub-api/guide/expanded-event-bus.html[Pub/Sub API and the Expanded Event Bus] diff --git a/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-reference.adoc b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-reference.adoc new file mode 100644 index 0000000000..ef19cf28c4 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-reference.adoc @@ -0,0 +1,725 @@ += Salesforce Pub/Sub Connector 1.2 Reference + +Anypoint Connector for Salesforce Pub/Sub (Salesforce Pub/Sub Connector) enables you to connect to the Pub/Sub API, which provides a single interface for publishing and subscribing to platform events, including real-time event monitoring events and change data capture events. + + +[[PubsubConfig]] +== Configuration + +Default Configuration for Salesforce Pub/Sub Connector. + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +|Name | String | Name for this configuration. Connectors reference the configuration with this name. | | x +| Connection a| * <> +* <> +* <> +* <> +* <> + | Connection types for this configuration. Note that the `Basic Authentication` connection type is only supported for Salesforce API v61.0 and earlier versions. | | x +| Name a| String | ID used to reference this configuration. | | x +| Expiration Policy a| <> | Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration. | | +|=== + +[[PubsubConfig_Basic]] +=== Basic Authentication Connection Type + +Uses a username and a password for authentication. Note that the `Basic Authentication` connection type is only supported for Salesforce API v61.0 and earlier versions. + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Connection Timeout a| Number | How long the connector waits before timing out when establishing a connection to the remote service. Values less than one millisecond are converted to `0`. | `0` | +| Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Connection Timeout* field. | `SECONDS` | +| Login Request Timeout a| Number | How long the client waits to receive the answer for the login request before timing out. Values less than one millisecond are converted to `0`. | `0` | +| Login Request Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Login Request Timeout* field. | `SECONDS` | +| Proxy configuration a| <> | Configures a proxy for outbound connections. The requests to the gRPC API (towards the gRPC host and gRPC port) are proxied through the proxy server configured using this field. | | +| Username a| String | Username used to initialize the session. | | x +| Password a| String | Password used to authenticate the user. | | x +| Security Token a| String | User's security token. The security token can be omitted if your IP has been added to the allowlist on Salesforce. | | +| Authorization URL a| String | Web service URL responsible for user authentication. The URL for the endpoint that is configured to handle SOAP authentication requests. | | +| TLS configuration a| <> | Configures TLS. If using the HTTPS protocol, you must configure TLS. | | +| gRPC host a| String | Host in which the proxy requests are sent to the gRPC API (towards the gRPC host). The proxy requests to the gRPC host go through the proxy. | `api.pubsub.salesforce.com` | +| gRPC port a| Number | Port in which the proxy requests are sent to the gRPC API (towards the gRPC port). The proxy requests to the gRPC port go through the proxy. | `7443` | +| Publish Request Timeout a| Number | Specifies the amount of time the client waits for a publish request to complete before timing out. Values less than one millisecond are converted to 0 (no deadline). | `0` | +| Publish Request Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Publish Request Timeout* field. | `SECONDS` | +| Reconnection a| <> | Configures a reconnection strategy to use when a connector operation fails to connect to an external server. | | +|=== + +[[PubsubConfig_ConfigWithOauth]] +=== OAuth v2.0 Connection Type + +include::connectors::partial$oauth2-description.adoc[] + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Connection Timeout a| Number | How long the connector waits before timing out when establishing a connection to the remote service. Values less than one millisecond are converted to `0`. | `0` | +| Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Connection Timeout* field. | `SECONDS` | +| Login Request Timeout a| Number | How long the client waits to receive the answer for the login request before timing out. Values less than one millisecond are converted to `0`. | `0` | +| Login Request Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Login Request Timeout* field. | `SECONDS` | +| Proxy configuration a| <> | Configures a proxy for outbound connections. The requests to the gRPC API (towards the gRPC host and gRPC port) are proxied through the proxy server configured using this field. | | +| Api Version a| Number | API version used. Defaults to the latest API version supported by the connector. | | +| TLS configuration a| <> | Configures TLS. If using the HTTPS protocol, you must configure TLS. | | +| gRPC host a| String | Host in which the proxy requests are sent to the gRPC API (towards the gRPC host). The proxy requests to the gRPC host go through the proxy. | `api.pubsub.salesforce.com` | +| gRPC port a| Number | Port in which the proxy requests are sent to the gRPC API (towards the gRPC port). The proxy requests to the gRPC port go through the proxy. | `7443` | +| Publish Request Timeout a| Number | Specifies the amount of time the client waits for a publish request to complete before timing out. Values less than one millisecond are converted to 0 (no deadline). | `0` | +| Publish Request Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Publish Request Timeout* field. | `SECONDS` | +| Reconnection a| <> | Configures a reconnection strategy to use when a connector operation fails to connect to an external server. | | +| Consumer Key a| String | OAuth consumer key, as registered with the service provider. | | x +| Consumer Secret a| String | OAuth consumer secret, as registered with the service provider. | | x +| Authorization Url a| String | URL of the service provider's authorization endpoint. | `\https://login.salesforce.com/services/oauth2/authorize` | +| Access Token Url a| String | URL of the service provider's access token endpoint. | `\https://login.salesforce.com/services/oauth2/token` | +| Scopes a| String | OAuth scopes to request during the OAuth dance. This value defaults to the scopes in the annotation. | | +| Resource Owner Id a| String | Resource owner ID to use with the authorization code grant type. | | +| Before a| String | Name of the flow to execute immediately before starting the OAuth dance. | | +| After a| String | Name of the flow to execute immediately after receiving an access token. | | +| Listener Config a| String | Configuration for the HTTP listener that listens for requests on the access token callback endpoint. | | x +| Callback Path a| String | Path of the access token callback endpoint. | | x +| Authorize Path a| String | Path of the local HTTP endpoint that triggers the OAuth dance. | | x +| External Callback Url a| String | URL that the OAuth provider uses to access the callback endpoint if the endpoint is behind a proxy or accessed through an indirect URL. | | +| Object Store a| String | Configures the object store that stores data for each resource owner. If not configured, Mule uses the default object store. | | +|=== + +[[PubsubConfig_Jwt]] +=== OAuth JWT Connection Type + +Uses OAuth 2.0 with a JSON Web Token (JWT) request for user authentication. + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Connection Timeout a| Number | How long the connector waits before timing out when establishing a connection to the remote service. Values less than one millisecond are converted to `0`. | `0` | +| Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Connection Timeout* field. | `SECONDS` | +| Login Request Timeout a| Number | How long the client waits to receive the answer for the login request before timing out. Values less than one millisecond are converted to `0`. | `0` | +| Login Request Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Login Request Timeout* field. | `SECONDS` | +| Proxy configuration a| <> | Configures a proxy for outbound connections. The requests to the gRPC API (towards the gRPC host and gRPC port) are proxied through the proxy server configured using this field. | | +| Api Version a| Number | API version used. Defaults to the latest API version supported by the connector. | | +| Consumer Key a| String | Consumer key for the Salesforce connected app. | | x +| Key Store a| String | Path to the keystore used to sign data during authentication. | | x +| Store Password a| String | Password of the keystore. | | x +| Certificate Alias a| String | Alias of the certificate. | | +| Principal a| String | Username of the desired Salesforce user to take action on behalf of. | | x +| Token Endpoint a| String | URL pointing to the server responsible for providing the authentication token. According to Salesforce, the *Token Endpoint* field is `\https://login.salesforce.com/services/oauth2/token` or `\https://acme.force.com/customers/services/oauth2/token` (in which `\acme.force.com/customers` is your community URL) if implementing for a community. | `\https://login.salesforce.com/services/oauth2/token` | +| Audience Url a| String | Audience identifies the authorization server as an intended audience. The authorization server must verify that the authorization server is an intended audience for the token. Use the authorization server's URL for the audience value: `\https://login.salesforce.com`, `\https://test.salesforce.com`, or `\https://community.force.com/customers` if implementing for a community. | | +| TLS configuration a| <> | Configures TLS. If using the HTTPS protocol, you must configure TLS. | | +| gRPC host a| String | Host in which the proxy requests are sent to the gRPC API (towards the gRPC host). The proxy requests to the gRPC host go through the proxy. | `api.pubsub.salesforce.com` | +| gRPC port a| Number | Port in which the proxy requests are sent to the gRPC API (towards the gRPC port). The proxy requests to the gRPC port go through the proxy. | `7443` | +| Publish Request Timeout a| Number | Specifies the amount of time the client waits for a publish request to complete before timing out. Values less than one millisecond are converted to 0 (no deadline). | `0` | +| Publish Request Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Publish Request Timeout* field. | `SECONDS` | +| Reconnection a| <> | Configures a reconnection strategy to use when a connector operation fails to connect to an external server. | | +|=== + +[[PubsubConfig_OauthUserPass]] +=== OAuth Username Password Connection Type + +Uses OAuth 2.0 with a username and a password for authentication. + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Connection Timeout a| Number | How long the connector waits before timing out when establishing a connection to the remote service. Values less than one millisecond are converted to `0`. | `0` | +| Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Connection Timeout* field. | `SECONDS` | +| Login Request Timeout a| Number | How long the client waits to receive the answer for the login request before timing out. Values less than one millisecond are converted to `0`. | `0` | +| Login Request Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Login Request Timeout* field. | `SECONDS` | +| Proxy configuration a| <> | Configures a proxy for outbound connections. The requests to the gRPC API (towards the gRPC host and gRPC port) are proxied through the proxy server configured using this field. | | +| Api Version a| Number | API version used. Defaults to the latest API version supported by the connector. | | +| Consumer Key a| String | Consumer key for the Salesforce connected app. | | x +| Consumer Secret a| String | Your application's client secret (consumer secret in Remote Access Detail). | | x +| Username a| String | Username used to initialize the session. | | x +| Password a| String | Password used to authenticate the user. | | x +| Security Token a| String | User's security token. The security token can be omitted if your IP has been added to the allowlist on Salesforce. | | +| Token Endpoint a| String | URL pointing to the server responsible for providing the authentication token. According to Salesforce, the *Token Endpoint* field is `\https://login.salesforce.com/services/oauth2/token` or `\https://acme.force.com/customers/services/oauth2/token` (in which `\acme.force.com/customers` is your community URL) if implementing for a community. | `\https://login.salesforce.com/services/oauth2/token` | +| TLS configuration a| <> | Configures TLS. If using the HTTPS protocol, you must configure TLS. | | +| gRPC host a| String | Host in which the proxy requests are sent to the gRPC API (towards the gRPC host). The proxy requests to the gRPC host go through the proxy. | `api.pubsub.salesforce.com` | +| gRPC port a| Number | Port in which the proxy requests are sent to the gRPC API (towards the gRPC port). The proxy requests to the gRPC port go through the proxy. | `7443` | +| Publish Request Timeout a| Number | Specifies the amount of time the client waits for a publish request to complete before timing out. Values less than one millisecond are converted to 0 (no deadline). | `0` | +| Publish Request Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Publish Request Timeout* field. | `SECONDS` | +| Reconnection a| <> | Configures a reconnection strategy to use when a connector operation fails to connect to an external server. | | +|=== + +[[PubsubConfig_Saml]] +=== OAuth SAML Connection Type + +Uses OAuth 2.0 with a signed SAML 2.0 assertion to request an access token. + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Connection Timeout a| Number | How long the connector waits before timing out when establishing a connection to the remote service. Values less than one millisecond are converted to `0`. | `0` | +| Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Connection Timeout* field. | `SECONDS` | +| Login Request Timeout a| Number | How long the client waits to receive the answer for the login request before timing out. Values less than one millisecond are converted to `0`. | `0` | +| Login Request Time unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Login Request Timeout* field. | `SECONDS` | +| Proxy configuration a| <> | Configures a proxy for outbound connections. The requests to the gRPC API (towards the gRPC host and gRPC port) are proxied through the proxy server configured using this field. | | +| Api Version a| Number | API version used. Defaults to the latest API version supported by the connector. | | +| Consumer Key a| String | Consumer key for the Salesforce connected app. | | x +| Key Store a| String | Path to the keystore used to sign data during authentication. | | x +| Store Password a| String | Password of the keystore. | | x +| Certificate Alias a| String | Alias of the certificate. | | +| Principal a| String | Username of the desired Salesforce user to take action on behalf of. | | x +| Token Endpoint a| String | URL pointing to the server responsible for providing the authentication token. According to Salesforce, the *Token Endpoint* field is `\https://login.salesforce.com/services/oauth2/token` or `\https://acme.force.com/customers/services/oauth2/token` (in which `\acme.force.com/customers` is your community URL) if implementing for a community. | `\https://login.salesforce.com/services/oauth2/token` | +| TLS configuration a| <> | Configures TLS. If using the HTTPS protocol, you must configure TLS. | | +| gRPC host a| String | Host in which the proxy requests are sent to the gRPC API (towards the gRPC host). The proxy requests to the gRPC host go through the proxy. | `api.pubsub.salesforce.com` | +| gRPC port a| Number | Port in which the proxy requests are sent to the gRPC API (towards the gRPC port). The proxy requests to the gRPC port go through the proxy. | `7443` | +| Publish Request Timeout a| Number | Specifies the amount of time the client waits for a publish request to complete before timing out. Values less than one millisecond are converted to 0 (no deadline). | `0` | +| Publish Request Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Publish Request Timeout* field. | `SECONDS` | +| Reconnection a| <> | Configures a reconnection strategy to use when a connector operation fails to connect to an external server. | | +|=== + + +== Sources +* <> + + +[[SubscribeChannelListener]] +=== Subscribe Channel Listener +`` + +Subscribes to a streaming channel. This source provides channel-related notification settings for new events that occur after you subscribe. + +NOTE: A channel must be published to Salesforce before a subscription to the channel is created. + + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | Name of the configuration to use. | | x +| Channel Name a| String | Name of the streaming channel to subscribe to. | | x +| Replay Option a| One of: + +* LATEST +* EARLIEST +* CUSTOM +* REPLAY ID FROM OBJECT STORE a| Interface with the following implementations: + +* `Latest` ++ +Subscriber receives new events that are broadcast after the client subscribes. + +* `Earliest` ++ +Subscriber receives all events, including past events that are within the retention window of the server and new events sent after subscription. + +* `Custom replay id` ++ +Subscriber receives only events with a replay ID higher than the specified value. + +* `Replay id from object store` ++ +Subscriber receives only events with a replay ID higher than the specified value in object store. If no value is found, it defaults to `Earliest`. Provide values for the *Object Store Name* and the *Object Store Key* fields to connect to the desired object store and retrieve the replay ID value. For more information on how to use `Replay id from object store`, refer to xref:salesforce-pubsub-connector-studio.adoc#store-objectstore[Store the Replay ID in the Object Store]. | | x +| Batch events size a| Number | Total number of events included in a server batch. Lower values indicate small memory footprint with more server calls, while higher values indicate bigger memory footprint with less API calls. A new batch of events is requested by the connector after the flow consumes the existing events. The maximum value is `100`.| `100` | +| Config Ref a| ConfigurationProvider | Name of the configuration used to execute this component. | | x +| Primary Node Only a| Boolean | Determines whether to execute this source on only the primary node when running Mule instances in a cluster. | `true` | +| Streaming Strategy a| * <> +* <> +* Non-Repeatable Stream | Configures how Mule processes streams. Repeatable streams are the default behavior. | | +| Redelivery Policy a| <> | Defines a policy for processing the redelivery of the same message. | | +| Reconnection Strategy a| * <> +* <> | Retry strategy in case of connectivity errors. | | +|=== + +==== Output + +[%autowidth.spread] +|=== +|Type |Any +| Attributes Type a| Any +|=== + +==== Associated Configurations + +* <> + +== Operations +* <> +* <> + + +[[PublishEvent]] +=== Publish Event +`` + + +Publishes the given list of events to the specified event topic. Only high-volume platform events, including real-time event monitoring events and change data capture events, are allowed. + + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | Name of the configuration to use. | | x +| Topic a| String | Topic for the event you want to publish. The format of the topic is `+/event/EventName__e+`. For example, for `+Order_Event__e+`, the topic is `+/event/Order_Event__e+`. | | x +| Events a| Array of Object | List of events to publish that match the schema of the current topic. | `#[payload]` | +| Config Ref a| ConfigurationProvider | Name of the configuration used to execute this component. | | x +| Target Variable a| String | Name of the variable that stores the operation's output. | | +| Target Value a| String | Expression that evaluates the operation’s output. The outcome of the expression is stored in the *Target Variable* field. | `#[payload]` | +| Reconnection Strategy a| * <> +* <> | Retry strategy in case of connectivity errors. | | +|=== + +==== Output + +[%autowidth.spread] +|=== +|Type |Array of Object +|=== + +==== Associated Configurations + +* <> + +==== Throws + +* MULE:ANY +* SALESFORCE-PUB-SUB:CONNECTIVITY +* SALESFORCE-PUB-SUB:INVALID_INPUT +* SALESFORCE-PUB-SUB:RETRY_EXHAUSTED +* SALESFORCE-PUB-SUB:SECURITY +* SALESFORCE-PUB-SUB:SERVER_ERROR + + +[[Unauthorize]] +=== Unauthorize +`` + + +Deletes all the access token information of a given resource owner ID so that it is impossible to execute any operation for that user without doing the authorization dance again. + +[%header%autowidth.spread] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | Name of the configuration to use. | | x +| Resource Owner Id a| String | ID of the resource owner for whom to invalidate access. | | +| Config Ref a| ConfigurationProvider | Name of the configuration used to execute this component. | | x +|=== + + +==== Associated Configurations + +* <> + + +== Object Types + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[[CrlFile]] +=== CRL File + +Specifies the location of the certification revocation list (CRL) file. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Path a| String | Path to the CRL file. | | +|=== + +[[CustomOcspResponder]] +=== Custom OCSP Responder + +Configures a custom OCSP responder for certification revocation checks. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Url a| String | URL of the OCSP responder. | | +| Cert Alias a| String | Alias of the signing certificate for the OCSP response. If specified, the alias must be in the truststore. | | +|=== + +[[CustomReplayId]] +=== Custom Replay Id + +Configures a custom replay ID. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Replay Id a| Number | Subscriber receives all events after the event specified by its *Replay Id* value. The value is ignored if the replay option is set on `Earliest`, `Latest`, or `Replay id from object store`. | | x +|=== + +[[ExpirationPolicy]] +=== Expiration Policy + +Configures an expiration policy strategy. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Idle Time a| Number | Configures the maximum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration. | | +| Time Unit a| Enumeration, one of: + +** NANOSECONDS +** MICROSECONDS +** MILLISECONDS +** SECONDS +** MINUTES +** HOURS +** DAYS | Time unit for the *Max Idle Time* field. | | +|=== + +[[KeyStore]] +=== Keystore + +Configures the keystore for the TLS protocol. The keystore you generate contains a private key and a public certificate. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Path a| String | Path to the keystore. Mule resolves the path relative to the current classpath and file system. | | +| Type a| String | Type of keystore. | | +| Alias a| String | Alias of the key to use when the keystore contains multiple private keys. By default, Mule uses the first key in the file. | | +| Key Password a| String | Password used to protect the private key. | | +| Password a| String | Password used to protect the keystore. | | +| Algorithm a| String | Encryption algorithm that the keystore uses. | | +|=== + +[[ProxyConfiguration]] +=== Proxy + +Configures a proxy for outbound connections. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Host a| String | Host in which the proxy requests are sent. | | x +| Port a| Number | Port in which the proxy requests are sent. | | x +| Username a| String | Username to authenticate against the proxy. | | +| Password a| String | Password to authenticate against the proxy. | | +|=== + +[[Reconnect]] +=== Reconnect + +Configures a standard reconnection strategy, which specifies how often to reconnect and how many reconnection attempts the connector source or operation can make. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Frequency a| Number | How often to attempt to reconnect, in milliseconds. | | +| Blocking a| Boolean | If `false`, the reconnection strategy runs in a separate, non-blocking thread. | | +| Count a| Number | How many reconnection attempts the Mule app can make. | | +|=== + +[[ReconnectForever]] +=== Reconnect Forever + +Configures a forever reconnection strategy by which the connector source or operation attempts to reconnect at a specified frequency for as long as the Mule app runs. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Frequency a| Number | How often to attempt to reconnect, in milliseconds. | | +| Blocking a| Boolean | If `false`, the reconnection strategy runs in a separate, non-blocking thread. | | +|=== + +[[Reconnection]] +=== Reconnection + +Configures a reconnection strategy for an operation. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Fails Deployment a| Boolean | Configures a reconnection strategy to use when a connector operation fails to connect to an external server. | | +| Reconnection Strategy a| * <> +* <> | Reconnection strategy to use. | | +|=== + +[[RedeliveryPolicy]] +=== Redelivery Policy + +Configures the redelivery policy for executing requests that generate errors. You can add a redelivery policy to any source in a flow. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Redelivery Count a| Number | Maximum number of times that a redelivered request can be processed unsuccessfully before returning a `REDELIVERY_EXHAUSTED` error. | | +| Message Digest Algorithm a| String | Secure hashing algorithm to use if the *Use Secure Hash* field is `true`. If the payload of the message is a Java object, Mule ignores this value and returns the value that the payload's `hashCode()` returned. | | +| Message Identifier a| <> | One or more expressions that determine if a message was redelivered. This property can be set only if the *Use Secure Hash* field is `false`. | | +| Object Store a| ObjectStore | Configures the object store that stores the redelivery counter for each message. | | +|=== + +[[RedeliveryPolicyMessageIdentifier]] +=== Redelivery Policy Message Identifier + +Configures how to identify a redelivered message and how to find out when the message was redelivered. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Use Secure Hash a| Boolean | If `true`, Mule uses a secure hash algorithm to identify a redelivered message. | | +| Id Expression a| String | One or more expressions that determine when a message was redelivered. You can set this property only if the *Use Secure Hash* field is `false`. | | +|=== + +[[RepeatableFileStoreStream]] +=== Repeatable File Store Stream + +Configures the repeatable file-store streaming strategy by which Mule keeps a portion of the stream content in memory. If the stream content is larger than the configured buffer size, Mule backs up the buffer's content to disk and then clears the memory. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| In Memory Size a| Number a| Maximum amount of memory that the stream can use for data. If the amount of memory exceeds this value, Mule buffers the content to disk. To optimize performance: + +* Configure a larger buffer size to avoid the number of times Mule needs to write the buffer on disk. This increases performance, but it also limits the number of concurrent requests your application can process, because it requires additional memory. + +* Configure a smaller buffer size to decrease memory load at the expense of response time. | | +| Buffer Unit a| Enumeration, one of: + +** BYTE +** KB +** MB +** GB | Unit for the *In Memory Size* field. | | +|=== + +[[RepeatableInMemoryStream]] +=== Repeatable In Memory Stream + +Configures the in-memory streaming strategy by which the request fails if the data exceeds the MAX buffer size. Always run performance tests to find the optimal buffer size for your specific use case. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Initial Buffer Size a| Number | Initial amount of memory to allocate to the data stream. If the streamed data exceeds this value, the buffer expands by *Buffer Size Increment*, with an upper limit of *Max In Memory Size value*. | | +| Buffer Size Increment a| Number | This is by how much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower means that the buffer should not expand, meaning that a `STREAM_MAXIMUM_SIZE_EXCEEDED` error is raised when the buffer gets full. | | +| Max Buffer Size a| Number | Maximum size of the buffer. If the buffer size exceeds this value, Mule raises a `STREAM_MAXIMUM_SIZE_EXCEEDED` error. A value of less than or equal to `0` means no limit. | | +| Buffer Unit a| Enumeration, one of: + +** BYTE +** KB +** MB +** GB | Unit for the *Initial Buffer Size*, *Buffer Size Increment*, and *Buffer Unit* fields. | | +|=== + +[[ReplayIdFromObjectStore]] +=== Replay Id From Object Store + +Configures a replay ID from object store. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Os Name a| String | Name of the object store from where to get the latest replay ID. The value is ignored if the replay option is set on `Earliest`, `Latest`, or `Custom replay id`. | | x +| Os Key a| String | Name of the key that contains the latest replay ID. The value is ignored if the replay option is set on `Earliest`, `Latest`, or `Custom replay id`. | | x +|=== + +[[StandardRevocationCheck]] +=== Standard Revocation Check + +Configures standard revocation checks for TLS certificates. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Only End Entities a| Boolean a| Which elements to verify in the certificate chain: + +* `true` ++ +Verify only the last element in the certificate chain. + +* `false` ++ +Verify all elements in the certificate chain. | | +| Prefer Crls a| Boolean a| How to check certificate validity: + +* `true` ++ +Check the Certification Revocation List (CRL) for certificate validity. + +* `false` ++ +Use the Online Certificate Status Protocol (OCSP) to check certificate validity. | | +| No Fallback a| Boolean a| Whether to use the secondary method to check certificate validity: + +* `true` ++ +Use the method that wasn't specified in the *Prefer Crls* field (the secondary method) to check certificate validity. + +* `false` ++ +Do not use the secondary method to check certificate validity. | | +| Soft Fail a| Boolean a| What to do if the revocation server can't be reached or is busy: + +* `true` ++ +Avoid verification failure. + +* `false` ++ +Allow the verification to fail. | | +|=== + +[[Tls]] +=== TLS + +Configures TLS to provide secure communications for the Mule app. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Enabled Protocols a| String | Comma-separated list of protocols enabled for this context. | | +| Enabled Cipher Suites a| String | Comma-separated list of cipher suites enabled for this context. | | +| Trust Store a| <> | Configures the TLS truststore. | | +| Key Store a| <> | Configures the TLS keystore. | | +| Revocation Check a| * <> +* <> +* <> | Configures a revocation checking mechanism. | | +|=== + +[[TrustStore]] +=== Truststore + +Configures the truststore for TLS. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Path a| String | Path to the truststore. Mule resolves the path relative to the current classpath and file system. | | +| Password a| String | Password used to protect the truststore. | | +| Type a| String | Type of truststore. | | +| Algorithm a| String | Encryption algorithm that the truststore uses. | | +| Insecure a| Boolean | If `true`, Mule stops performing certificate validations. Setting this to `true` can make connections vulnerable to attacks. | | +|=== + +== See Also + +* https://developer.salesforce.com/docs/platform/pub-sub-api/guide/pub-sub-endpoints.html[Pub/Sub API Endpoints] +* https://developer.salesforce.com/docs/platform/pub-sub-api/guide/use-pub-sub-api.html[Use Pub/Sub API] +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-studio.adoc b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-studio.adoc new file mode 100644 index 0000000000..d55285b505 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-studio.adoc @@ -0,0 +1,259 @@ += Using Anypoint Studio to Configure Salesforce Pub/Sub Connector 1.2 + + +Anypoint Studio (Studio) editors help you design and update your Mule applications, properties, and configuration files. + +To add and configure a connector in Studio: + +. <>. +. <>. +. <>. +. <>. +. <>. +. <>. + +When you run the connector, you can view the app log to check for problems in real time, as described in <>. + +If you are new to configuring connectors in Studio, refer to xref:connectors::introduction/intro-config-use-studio.adoc[Using Anypoint Studio to Configure a Connector]. If, after reading this topic, you need additional information about the connector fields, refer to the xref:salesforce-pubsub-connector-reference.adoc[Salesforce Pub/Sub Connector Reference]. + +[[create-mule-project]] +== Create a Mule Project + +In Studio, create a new Mule project in which to add and configure the connector: + +. In Studio, select *File > New > Mule Project*. +. Enter a name for your Mule project and click *Finish*. + +[[add-connector-to-project]] +== Add the Connector to Your Mule Project + +Add Salesforce Pub/Sub Connector to your Mule project to automatically populate the XML code with the connector's namespace and schema location and add the required dependencies to the project's `pom.xml` file: + +. In *Mule Palette*, click *(X) Search in Exchange*. +. In *Add Dependencies to Project*, type `Salesforce Pub/Sub` in the search field. +. Click in *Available modules*. +. Click *Add*. +. Click *Finish*. + +Adding a connector to a Mule project in Studio does not make that connector available to other projects in your Studio workspace. + +[[configure-source]] +== Configure a Source + +A source initiates a flow when a specified condition is met. +You can configure one of these sources to use with Salesforce Pub/Sub Connector: + +* Subscribe Channel Listener + +Subscribes to a streaming channel. This source provides channel-related notification settings for new events that occur after you subscribe. ++ +NOTE: A channel must be published to Salesforce before a subscription to the channel is created. + +* HTTP Listener + +Initiates a flow each time it receives a request on the configured host and port +* Scheduler + +Initiates a flow when a time-based condition is met + +For example, to configure a *Subscribe channel listener* source, follow these steps: + +. In the *Mule Palette* view, select *Subscribe channel listener*. +. Drag *Subscribe channel listener* to the Studio canvas. +. Optionally change the value of the *Display Name* field. +. Select a *Channel Name* from the dropdown field. +. Select a *Replay Option* from the four types available: + +* `Latest` ++ +Subscriber receives new events that are broadcast after the client subscribes. + +* `Earliest` ++ +Subscriber receives all events, including past events that are within the retention window of the server and new events sent after subscription. + +* `Custom replay id` ++ +Subscriber receives only events with a replay ID higher than the specified value. + +* `Replay id from object store` ++ +Subscriber receives only events with a replay ID higher than the specified value in object store. If no value is found, it defaults to `Earliest`. Provide values for the *Object Store Name* and the *Object Store Key* fields to connect to the desired object store and retrieve the replay ID value. For more information on how to use `Replay id from object store`, refer to <>. + + +. Optionally, specify a value for the *Batch events size* field. +. Click the plus sign (*+*) next to the *Connector configuration* field to configure a global element that can be used by all instances of the *Subscribe channel listener* source in the app. +. In the *Security* tab, optionally specify the TLS information for the connector. +. In the *Advanced* tab, optionally specify reconnection information, including a reconnection strategy. +. Click *Test Connection* to confirm that Mule can connect with the specified server. +. Click *OK*. + +[[store-objectstore]] +=== Store the Replay ID in the Object Store + +To use the `Replay id from object store` option for the *Subscribe channel listener* source, you must first save the replay ID value in the object store: + +. Add the *Subscribe channel listener* source, as described in <>, to the Studio flow. +. In the *Mule Palette* view, select *Store* from *Object Store Connector*. +. Drag *Store* to the Studio canvas. +. Optionally change the value of the *Display Name* field. +. Add a value for the *Key* field, such as replay ID. This is the key that is used later, when retrieving the replay ID from the object store. +. Set a value for the *Value* field. This is the replay ID value that you want to store. In this example, it is `payload.replayId`. +. Optionally, change the default values for the *Fail if present* and *Fail on null value* fields. The value for *Fail if present* must always be `false` as you must use the same key to store a new value for the replay ID. +. Click the plus sign (*+*) next to the *Object store* field to configure the object store. This is the object store in which the replay ID value is stored and from where the source retrieves the replay ID value. +. The values declared here for the *Object store* and *Key* fields are the same values that are used for the `Replay id from object store` option on the source. + +[[add-connector-operation]] +== Add a Connector Operation to the Flow + +When you add a connector operation to your flow, you are specifying an action for that connector to perform. + +To add an operation for Salesforce Pub/Sub Connector, follow these steps: + +. In *Mule Palette*, select *Salesforce Pub/Sub* and then select the desired operation. +. Drag the operation onto the Studio canvas, next to the input source. + +[[configure-global-element]] +== Configure a Global Element for the Connector + +When you configure a connector, configure a global element that all instances of that connector in the app can use. Configuring a global element requires you to provide the authentication credentials that the connector requires to access the target Salesforce Pub/Sub system. Salesforce Pub/Sub Connector supports Basic Authentication, OAuth v2.0, OAuth JWT, OAuth Username Password, and OAuth SAML. + +NOTE: The `Basic Authentication` connection type is only supported for Salesforce API v61.0 and earlier versions. + +To configure the global element for Salesforce Pub/Sub Connector, follow these steps: + +. Select the operation in the Studio canvas. +. In the *General* configuration screen for the operation, click the *Add* icon to access the global element configuration fields. +. In the *General* tab, in *Connection*, select the authentication method to configure: +* <> +* <> +* <> +* <> +* <> + ++ +You can reference a configuration file that contains ANT-style property placeholders (recommended), or you can enter your authorization credentials in the global configuration properties. For information about the benefits of using property placeholders and how to configure them, refer to xref:connectors::introduction/intro-connector-configuration-overview.adoc[Anypoint Connector Configuration]. +. In the *Advanced* tab, optionally specify reconnection information, including a reconnection strategy. +. Click *Test Connection* to confirm that Mule can connect with the specified server. +. Click *OK*. + +[[basic-authentication]] +=== Basic Authentication + +Enter the following information in the *General* tab of the *Global Element Properties* screen to configure Basic Authentication: + +[%header,cols="30s,70a"] +|=== +|Field |User Action +|Name |Enter the configuration name. +|Connection | Select *Basic Authentication*. +|=== + +The following image shows an example of configuring Basic Authentication: + +image::basic-authentication.png["Basic Authentication selected in the Connection section and authentication fields completed in the General tab"] + +[[oauth2]] +=== OAuth v2.0 + +include::connectors::partial$oauth2-description.adoc[] + +Enter the following information on the *General* tab of the global element configuration screen to configure OAuth v2.0 authentication: + +[%header,cols="30s,70a"] +|=== +|Field |User Action +|Name |Enter the configuration name. +|Connection | Select *OAuth v2.0*. +|Consumer Key | Enter the OAuth consumer key, as registered with the service provider. +|Consumer Secret | Enter the OAuth consumer secret, as registered with the service provider. +|Listener Config | Enter the configuration for the HTTP listener that listens for requests on the access token callback endpoint. +|Callback Path | Enter the path of the access token callback endpoint. +|Authorize Path | Enter the path of the local HTTP endpoint that triggers the OAuth dance. +|=== + +The following image shows an example of configuring OAuth v2.0 authentication: + +image::oauth2.png["OAuth v2.0 selected in the Connection section and authentication fields completed in the General tab"] + +[[oauth-jwt]] +=== OAuth JWT + +Enter the following information on the *General* tab of the global element configuration screen to configure OAuth JWT authentication: + +[%header,cols="30s,70a"] +|=== +|Field |User Action +|Name |Enter the configuration name. +|Connection | Select *OAuth JWT*. +|Consumer Key | Enter the consumer key for the Salesforce connected app. +|Key Store | Enter the path to the keystore used to sign data during authentication. +|Store Password | Enter the password of the keystore. +|Principal | Enter the username of the desired Salesforce user to take action on behalf of. +|=== + +The following image shows an example of configuring OAuth JWT authentication: + +image::oauth-jwt.png["OAuth JWT selected in the Connection section and authentication fields completed in the General tab"] + +[[oauth-username-password]] +=== OAuth Username Password + +Enter the following information on the *General* tab of the global element configuration screen to configure OAuth Username Password authentication: + +[%header,cols="30s,70a"] +|=== +|Field |User Action +|Name |Enter the configuration name. +|Connection | Select *OAuth Username Password*. +|Consumer Key | Enter the consumer key for the Salesforce connected app. +|Consumer Secret | Enter your application's client secret (consumer secret in Remote Access Detail). +|Username | Enter the username used to initialize the session. +|Password | Enter the password used to authenticate the user. +|Principal | Enter the username of the desired Salesforce user to take action on behalf of. +|=== + +The following image shows an example of configuring OAuth Username Password authentication: + +image::oauth-username-password.png["OAuth Username Password is selected in the Connection section and authentication fields completed in the General tab"] + +[[oauth-saml]] +=== OAuth SAML + +Enter the following information on the *General* tab of the global element configuration screen to configure OAuth SAML authentication: + +[%header,cols="30s,70a"] +|=== +|Field |User Action +|Name |Enter the configuration name. +|Connection | Select *OAuth SAML*. +|Consumer Key | Enter the consumer key for the Salesforce connected app. +|Key Store | Enter the path to the keystore used to sign data during authentication. +|Store Password | Enter the password of the keystore. +|Principal | Enter the username of the desired Salesforce user to take action on behalf of. +|=== + +The following image shows an example of configuring OAuth SAML authentication: + +image::oauth-saml.png["OAuth SAML selected in the Connection section and authentication fields completed in the General tab"] + + +[[configure-other-fields]] +== Configure Additional Connector Fields + +After you configure a global element for Salesforce Pub/Sub Connector, configure the other required fields for the connector. The required fields vary depending on which connector operation you use. + + +[[view-app-log]] +== View the App Log + +To check for problems, you can view the app log as follows: + +* If you’re running the app from Anypoint Platform, the app log output goes to the Anypoint Studio console window. +* If you’re running the app using Mule from the command line, the app log output goes to your operating system console. + +Unless the log file path is customized in the app’s log file (`log4j2.xml`), you can also access the app log in the default location `MULE_HOME/logs/.log`. You can configure the location of the log path in the app log file `log4j2.xml`. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* xref:connectors::introduction/intro-config-use-studio.adoc[Using Anypoint Studio to Configure a Connector] +* xref:salesforce-pubsub-connector-reference.adoc[Salesforce Pub/Sub Connector Reference] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-xml-maven.adoc b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-xml-maven.adoc new file mode 100644 index 0000000000..4608990aa1 --- /dev/null +++ b/salesforce-pubsub/1.2/modules/ROOT/pages/salesforce-pubsub-connector-xml-maven.adoc @@ -0,0 +1,74 @@ += Salesforce Pub/Sub Connector 1.2 - XML and Maven Support + +Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio: + +* If you manually code a Mule runtime engine (Mule) app in XML (either from the Anypoint Studio XML editor or from a text editor), you can access the connector from your app by adding reference statements to both your XML Mule flow and the Apache Maven `pom.xml` file. +* If you add the connector in Studio, Studio automatically populates the XML code with the connector's namespace and schema location and it also adds a dependency to the `pom.xml` file. + +== Add a Namespace for the Connector + +Paste the following code inside the `mule` tag of the header of your configuration XML: + +[source,xml,linenums] +---- +http://www.mulesoft.org/schema/mule/salesforce-pub-sub +http://www.mulesoft.org/schema/mule/salesforce-pub-sub/current/mule-salesforce-pub-sub.xsd +---- + +This example shows how the namespace statements are placed in the XML: + +[source,xml,linenums] +---- + +---- + +== Add a POM File Dependency + +The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies +for a Mule app. When you code a Mule app manually, include this XML snippet in +your `pom.xml` file to enable access to this connector: + +[source,xml,linenums] +---- + + com.mulesoft.connectors + mule4-salesforce-pubsub-connector + x.x.x + mule-plugin + +---- + +Replace `` with the version that corresponds to the connector you are using. + +To obtain the most up-to-date `pom.xml` file information: + +. Go to https://www.mulesoft.com/exchange/[Anypoint Exchange]. +. In Exchange, click *Login* and supply your Anypoint Platform username and password. +. In Exchange, search for `Salesforce Pub/Sub`. +. Select the connector. +. Click *Dependency Snippets* near the upper right of the screen. + +== Next Step + +After completing your namespace and `pom.xml` file, you can try the xref:salesforce-pubsub-connector-examples.adoc[Examples]. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* https://help.mulesoft.com[MuleSoft Help Center]