You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by je...@apache.org on 2022/01/08 17:35:08 UTC
[camel] branch main updated: CAMEL-11001: camel-salesforce: Add getting started
This is an automated email from the ASF dual-hosted git repository.
jeremyross pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new e94fae1 CAMEL-11001: camel-salesforce: Add getting started
e94fae1 is described below
commit e94fae17fee1be571cc9d74a9ad1cf1ffcdd8e3b
Author: Jeremy Ross <je...@gmail.com>
AuthorDate: Sat Jan 8 11:34:04 2022 -0600
CAMEL-11001: camel-salesforce: Add getting started
Also remove redundant information in README.md that's already
in the component doc.
---
.../camel-salesforce-component/README.md | 66 +---------------------
.../src/main/docs/salesforce-component.adoc | 65 ++++++++++-----------
2 files changed, 34 insertions(+), 97 deletions(-)
diff --git a/components/camel-salesforce/camel-salesforce-component/README.md b/components/camel-salesforce/camel-salesforce-component/README.md
index 3409020..c158667 100644
--- a/components/camel-salesforce/camel-salesforce-component/README.md
+++ b/components/camel-salesforce/camel-salesforce-component/README.md
@@ -1,71 +1,7 @@
# Camel Salesforce component #
This component supports producer and consumer endpoints to communicate with Salesforce using Java DTOs.
-There is a companion maven plugin [camel-salesforce-plugin](https://github.com/apache/camel/tree/main/components/camel-salesforce/camel-salesforce-maven-plugin) that generates these DTOs.
-
-The component supports the following Salesforce APIs
-
-## REST API ##
-
-Producer endpoints can use the following APIs. Most of the APIs process one record at a time, the Query API can retrieve multiple Records.
-
-* getVersions - Gets supported Salesforce REST API versions
-* getResources - Gets available Salesforce REST Resource endpoints
-* getGlobalObjects - Gets metadata for all available SObject types
-* getBasicInfo - Gets basic metadata for a specific SObject type
-* getDescription - Gets comprehensive metadata for a specific SObject type
-* getSObject - Gets an SObject using its Salesforce Id
-* createSObject - Creates an SObject
-* updateSObject - Updates an SObject using Id
-* deleteSObject - Deletes an SObject using Id
-* getSObjectWithId - Gets an SObject using an external (user defined) id field
-* upsertSObject - Updates or inserts an SObject using an external id
-* deleteSObjectWithId - Deletes an SObject using an external id
-* query - Runs a Salesforce SOQL query
-* queryMore - Retrieves more results (in case of large number of results) using result link returned from the 'query' API
-* search - Runs a Salesforce SOSL query
-
-For example, the following producer endpoint uses the upsertSObject API, with the sObjectIdName parameter specifying 'Name' as the external id field.
-The request message body should be an SObject DTO generated using the maven plugin.
-The response message will either be NULL if an existing record was updated, or [CreateSObjectResult] with an id of the new record, or a list of errors while creating the new object.
-
- ...to("salesforce:upsertSObject?sObjectIdName=Name")...
-
-## Bulk API ##
-
-Producer endpoints can use the following APIs. All Job data formats, i.e. xml, csv, zip/xml, and zip/csv are supported.
-The request and response have to be marshalled/unmarshalled by the route. Usually the request will be some stream source like a CSV file,
-and the response may also be saved to a file to be correlated with the request.
-
-* createJob - Creates a Salesforce Bulk Job
-* getJob - Gets a Job using its Salesforce Id
-* closeJob - Closes a Job
-* abortJob - Aborts a Job
-* createBatch - Submits a Batch within a Bulk Job
-* getBatch - Gets a Batch using Id
-* getAllBatches - Gets all Batches for a Bulk Job Id
-* getRequest - Gets Request data (XML/CSV) for a Batch
-* getResults - Gets the results of the Batch when its complete
-* createBatchQuery - Creates a Batch from an SOQL query
-* getQueryResultIds - Gets a list of Result Ids for a Batch Query
-* getQueryResult - Gets results for a Result Id
-
-For example, the following producer endpoint uses the createBatch API to create a Job Batch.
-The in message must contain a body that can be converted into an InputStream (usually UTF-8 CSV or XML content from a file, etc.) and header fields 'jobId' for the Job and 'contentType' for the Job content type, which can be XML, CSV, ZIP\_XML or ZIP\_CSV. The put message body will contain [BatchInfo] on success, or throw a [SalesforceException] on error.
-
- ...to("salesforce:createBatchJob")..
-
-## Streaming API ##
-
-Consumer endpoints can use the following syntax for streaming endpoints to receive Salesforce notifications on create/update.
-
-To create and subscribe to a topic
-
- from("salesforce:CamelTestTopic?notifyForFields=ALL¬ifyForOperations=ALL&sObjectName=Merchandise__c&updateTopic=true&sObjectQuery=SELECT Id, Name FROM Merchandise__c")...
-
-To subscribe to an existing topic
-
- from("salesforce:CamelTestTopic&sObjectName=Merchandise__c")...
+There is a companion maven plugin [camel-salesforce-plugin](https://github.com/apache/camel/tree/main/components/camel-salesforce/camel-salesforce-maven-plugin) that generates these DTOs.
## Developing the Camel Salesforce component
diff --git a/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc
index b8b6fce..e31a2b0 100644
--- a/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc
+++ b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce-component.adoc
@@ -24,6 +24,36 @@ to look at the https://github.com/apache/camel/tree/main/components/camel-salesf
setup your environment for running integration tests.
====
+== Getting Started
+
+Follow these steps to get started with the Salesforce component.
+
+. *Create a salesforce org*. If you don't already have access to a salesforce org, you can create a https://developer.salesforce.com/signup[free developer org].
+. *Create a Connected App*. In salesforce, go to Setup > Apps > App Manager, then click on *New Connected App*. Make sure to check *Enable OAuth Settings* and include relevant OAuth Scopes, including the scope called *Perform requests at any time*. Click *Save*.
+. *Get the Consumer Key and Consumer Secret*. You'll need these to configure salesforce authentication. View your new connected app, then copy the key and secret and save in a safe place.
+. *Add Maven depdendency*.
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-salesforce</artifactId>
+</dependency>
+----
+Spring Boot users should use the starter instead.
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel.springboot</groupId>
+ <artifactId>camel-salesforce-starter</artifactId>
+</dependency>
+----
+
+. *Generate DTOs*. Optionally, generate Java DTOs to represent your salesforce objects. This step isn't a hard requirement per se, but most use cases will benefit from the type safety and auto-completion. Use the <<MavenPlugin,maven plugin>> to generate DTOs for the salesforce objects you'll be working with.
+. *Configure authentication*. Using the OAuth key and secret you generated previously, configure salesforce <<AuthenticatingToSalesforce,authentication>>.
+. *Create routes*. Starting creating routes that interact with salesforce!
+
// component-configure options: START
@@ -39,7 +69,7 @@ include::partial$component-endpoint-options.adoc[]
// endpoint options: END
-== Authenticating to Salesforce
+== Authenticating to Salesforce [[AuthenticatingToSalesforce]]
The component supports three OAuth authentication flows:
@@ -1928,39 +1958,10 @@ String allCustomFieldsQuery = QueryHelper.queryToFetchFilteredFieldsOf(new Accou
[[MavenPlugin]]
== Camel Salesforce Maven Plugin
-This Maven plugin generates DTOs for the Camel.
-
-Maven users will need to add the following dependency to their `pom.xml`
-for this component:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.camel</groupId>
- <artifactId>camel-salesforce</artifactId>
- <version>x.x.x</version>
- <!-- use the same version as your Camel core version -->
-</dependency>
-----
-
-For obvious security reasons it is recommended that the clientId,
-clientSecret, userName and password fields be not set in the pom.xml.
-The plugin should be configured for the rest of the properties, and can
-be executed using the following command:
-
-[source,java]
-----
-mvn camel-salesforce:generate -DcamelSalesforce.clientId=<clientid> -DcamelSalesforce.clientSecret=<clientsecret> \
- -DcamelSalesforce.userName=<username> -DcamelSalesforce.password=<password>
-----
-
-The generated DTOs use Jackson annotations. All Salesforce
-field types are supported. Date and time fields are mapped to
-`java.time.ZonedDateTime` by default, and picklist fields are mapped to
-generated Java Enumerations.
+The Maven plugin generates Java DTOs to represent salesforce objects.
Please refer to
https://github.com/apache/camel/tree/main/components/camel-salesforce/camel-salesforce-maven-plugin[README.md]
-for details on how to generate the DTO.
+for details on how to use the plugin.
include::spring-boot:partial$starter.adoc[]