You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/05/19 12:02:43 UTC
[2/3] camel git commit: Added camel-salesforce docs to Gitbook
Added camel-salesforce docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/e4366a76
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/e4366a76
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/e4366a76
Branch: refs/heads/master
Commit: e4366a7604c93828cbef5aea2d265b059cab3f9d
Parents: 80e6c75
Author: Andrea Cosentino <an...@gmail.com>
Authored: Thu May 19 13:51:34 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Thu May 19 13:51:34 2016 +0200
----------------------------------------------------------------------
.../src/main/docs/salesforce.adoc | 303 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 304 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/e4366a76/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce.adoc
----------------------------------------------------------------------
diff --git a/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce.adoc b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce.adoc
new file mode 100644
index 0000000..1548a4f
--- /dev/null
+++ b/components/camel-salesforce/camel-salesforce-component/src/main/docs/salesforce.adoc
@@ -0,0 +1,303 @@
+[[Salesforce-Salesforcecomponent]]
+Salesforce component
+~~~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.12*
+
+This component supports producer and consumer endpoints to communicate
+with Salesforce using Java DTOs. +
+ There is a companion maven plugin Camel Salesforce Plugin that
+generates these DTOs (see further below).
+
+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>
+------------------------------------------------------------
+
+[[Salesforce-URIformat]]
+URI format
+^^^^^^^^^^
+
+The URI scheme for a salesforce component is as follows
+
+[source,java]
+------------------------
+salesforce:topic?options
+------------------------
+
+You can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+[[Salesforce-SupportedSalesforceAPIs]]
+Supported Salesforce APIs
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The component supports the following Salesforce APIs
+
+Producer endpoints can use the following APIs. Most of the APIs process
+one record at a time, the Query API can retrieve multiple Records.
+
+[[Salesforce-RestAPI]]
+Rest API
+++++++++
+
+* 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.
+
+[source,java]
+-----------------------------------------------------------
+ ...to("salesforce:upsertSObject?sObjectIdName=Name")...
+-----------------------------------------------------------
+
+[[Salesforce-RestBulkAPI]]
+Rest 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.
+
+[source,java]
+----------------------------------------
+ ...to("salesforce:createBatchJob")..
+----------------------------------------
+
+[[Salesforce-RestStreamingAPI]]
+Rest Streaming API
+++++++++++++++++++
+
+Consumer endpoints can use the following sytax for streaming endpoints
+to receive Salesforce notifications on create/update.
+
+To create and subscribe to a topic
+
+[source,java]
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 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
+
+[source,java]
+-------------------------------------------------------------------
+ from("salesforce:CamelTestTopic&sObjectName=Merchandise__c")...
+-------------------------------------------------------------------
+
+[[Salesforce-Examples]]
+Examples
+~~~~~~~~
+
+[[Salesforce-UploadingadocumenttoaContentWorkspace]]
+Uploading a document to a ContentWorkspace
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create the ContentVersion in Java, using a Processor instance:
+
+[source,java]
+-----------------------------------------------------------------------------------
+public class ContentProcessor implements Processor {
+ public void process(Exchange exchange) throws Exception {
+ Message message = exchange.getIn();
+
+ ContentVersion cv = new ContentVersion();
+ ContentWorkspace cw = getWorkspace(exchange);
+ cv.setFirstPublishLocationId(cw.getId());
+ cv.setTitle("test document");
+ cv.setPathOnClient("test_doc.html");
+ byte[] document = message.getBody(byte[].class);
+ ObjectMapper mapper = new ObjectMapper();
+ String enc = mapper.convertValue(document, String.class);
+ cv.setVersionDataUrl(enc);
+ message.setBody(cv);
+ }
+
+ protected ContentWorkspace getWorkSpace(Exchange exchange) {
+ // Look up the content workspace somehow, maybe use enrich() to add it to a
+ // header that can be extracted here
+ ....
+ }
+}
+-----------------------------------------------------------------------------------
+
+Give the output from the processor to the Salesforce component:
+
+[source,java]
+-----------------------------------------------------------------------------------------------------
+ from("file:///home/camel/library")
+ .to(new ContentProcessor()) // convert bytes from the file into a ContentVersion SObject
+ // for the salesforce component
+ .to("salesforce:createSObject");
+-----------------------------------------------------------------------------------------------------
+
+[[Salesforce-CamelSalesforceMavenPlugin]]
+Camel Salesforce Maven Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This Maven plugin generates DTOs for the Camel
+link:salesforce.html[Salesforce].
+
+[[Salesforce-Options]]
+Options
+^^^^^^^
+
+
+// component options: START
+The Salesforce component supports 16 options which are listed below.
+
+
+
+{% raw %}
+[width="100%",cols="2s,1m,8",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| loginConfig | SalesforceLoginConfig | To use the shared SalesforceLoginConfig as login configuration
+| config | SalesforceEndpointConfig | To use the shared SalesforceLoginConfig as configuration
+| httpClientProperties | Map | Used for configuring HTTP client properties as key/value pairs
+| sslContextParameters | SSLContextParameters | To configure security using SSLContextParameters
+| httpProxyHost | String | To configure HTTP proxy host
+| httpProxyPort | Integer | To configure HTTP proxy port
+| httpProxyUsername | String | To configure HTTP proxy username
+| httpProxyPassword | String | To configure HTTP proxy password
+| isHttpProxySocks4 | boolean | Enable for Socks4 proxy false by default
+| isHttpProxySecure | boolean | Enable for TLS connections true by default
+| httpProxyIncludedAddresses | Set | HTTP proxy included addresses
+| httpProxyExcludedAddresses | Set | HTTP proxy excluded addresses
+| httpProxyAuthUri | String | HTTP proxy authentication URI
+| httpProxyRealm | String | HTTP proxy authentication realm
+| httpProxyUseDigestAuth | boolean | Use HTTP proxy Digest authentication false by default
+| packages | String[] | Package names to scan for DTO classes (multiple packages can be separated by comma).
+|=======================================================================
+{% endraw %}
+// component options: END
+
+
+
+// endpoint options: START
+The Salesforce component supports 36 endpoint options which are listed below:
+
+{% raw %}
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| operationName | common | | OperationName |
+| topicName | common | | String |
+| apexMethod | common | | String | APEX method name
+| apexQueryParams | common | | Map | Query params for APEX method
+| apexUrl | common | | String | APEX method URL
+| apiVersion | common | | String | Salesforce API version defaults to SalesforceEndpointConfig.DEFAULT_VERSION
+| batchId | common | | String | Bulk API Batch ID
+| contentType | common | | ContentType | Bulk API content type one of XML CSV ZIP_XML ZIP_CSV
+| format | common | | PayloadFormat | Payload format to use for Salesforce API calls either JSON or XML defaults to JSON
+| httpClient | common | | SalesforceHttpClient | Custom Jetty Http Client to use to connect to Salesforce.
+| includeDetails | common | | Boolean | Include details in Salesforce1 Analytics report defaults to false.
+| instanceId | common | | String | Salesforce1 Analytics report execution instance ID
+| jobId | common | | String | Bulk API Job ID
+| notifyForFields | common | | NotifyForFieldsEnum | Notify for fields options are ALL REFERENCED SELECT WHERE
+| notifyForOperationCreate | common | | Boolean | Notify for create operation defaults to false (API version = 29.0)
+| notifyForOperationDelete | common | | Boolean | Notify for delete operation defaults to false (API version = 29.0)
+| notifyForOperations | common | | NotifyForOperationsEnum | Notify for operations options are ALL CREATE EXTENDED UPDATE (API version 29.0)
+| notifyForOperationUndelete | common | | Boolean | Notify for un-delete operation defaults to false (API version = 29.0)
+| notifyForOperationUpdate | common | | Boolean | Notify for update operation defaults to false (API version = 29.0)
+| reportId | common | | String | Salesforce1 Analytics report Id
+| reportMetadata | common | | ReportMetadata | Salesforce1 Analytics report metadata for filtering
+| resultId | common | | String | Bulk API Result ID
+| sObjectBlobFieldName | common | | String | SObject blob field name
+| sObjectClass | common | | String | Fully qualified SObject class name usually generated using camel-salesforce-maven-plugin
+| sObjectFields | common | | String | SObject fields to retrieve
+| sObjectId | common | | String | SObject ID if required by API
+| sObjectIdName | common | | String | SObject external ID field name
+| sObjectIdValue | common | | String | SObject external ID field value
+| sObjectName | common | | String | SObject name if required or supported by API
+| sObjectQuery | common | | String | Salesforce SOQL query string
+| sObjectSearch | common | | String | Salesforce SOSL search string
+| updateTopic | common | false | boolean | Whether to update an existing Push Topic when using the Streaming API defaults to false
+| bridgeErrorHandler | consumer | false | boolean | Allows for bridging the consumer to the Camel routing Error Handler which mean any exceptions occurred while the consumer is trying to pickup incoming messages or the likes will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions that will be logged at WARN/ERROR level and ignored.
+| exceptionHandler | consumer (advanced) | | ExceptionHandler | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions that will be logged at WARN/ERROR level and ignored.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+|=======================================================================
+{% endraw %}
+// endpoint options: END
+
+
+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 -DclientId=<clientid> -DclientSecret=<clientsecret> -DuserName=<username> -Dpassword=<password>
+---------------------------------------------------------------------------------------------------------------------------------
+
+The generated DTOs use Jackson and XStream annotations. All Salesforce
+field types are supported. Date and time fields are mapped to Joda
+DateTime, and picklist fields are mapped to generated Java Enumerations.
+
+[[Salesforce-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+
http://git-wip-us.apache.org/repos/asf/camel/blob/e4366a76/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index f80232b..f157edd 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -226,6 +226,7 @@
* [RMI](rmi.adoc)
* [Routebox](routebox.adoc)
* [RSS](rss.adoc)
+ * [Salesforce](salesforce.adoc)
* [Scp](scp.adoc)
* [SJMS](sjms.adoc)
* [SJMS Batch](sjms-batch.adoc)