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/04/28 12:21:48 UTC
[2/2] camel git commit: Added camel-jira docs to Gitbook
Added camel-jira 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/c4a88026
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/c4a88026
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/c4a88026
Branch: refs/heads/master
Commit: c4a880268c431537df3b940b908029675b6bf188
Parents: c3d42cd
Author: Andrea Cosentino <an...@gmail.com>
Authored: Thu Apr 28 12:20:34 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Thu Apr 28 12:20:34 2016 +0200
----------------------------------------------------------------------
components/camel-jira/src/main/docs/jira.adoc | 108 +++++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 109 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/c4a88026/components/camel-jira/src/main/docs/jira.adoc
----------------------------------------------------------------------
diff --git a/components/camel-jira/src/main/docs/jira.adoc b/components/camel-jira/src/main/docs/jira.adoc
new file mode 100644
index 0000000..4706cf5
--- /dev/null
+++ b/components/camel-jira/src/main/docs/jira.adoc
@@ -0,0 +1,108 @@
+[[JIRA-JIRA]]
+JIRA
+~~~~
+
+*Available as of Camel 2.15*
+
+The JIRA component interacts with the JIRA API by encapsulating
+Atlassian's https://marketplace.atlassian.com/plugins/com.atlassian.jira.jira-rest-java-client[REST
+Java Client for JIRA]. It currently provides polling for new issues and
+new comments. It is also able to create new issues.
+
+Rather than webhooks, this endpoint relies on simple polling. Reasons
+include:
+
+* Concern for reliability/stability
+* The types of payloads we're polling aren't typically large (plus,
+paging is available in the API)
+* The need to support apps running somewhere not publicly accessible
+where a webhook would fail
+
+Note that the JIRA API is fairly expansive. Therefore, this component
+could be easily expanded to provide additional interactions.
+
+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-jira</artifactId>
+ <version>${camel-version}</version>
+</dependency>
+---------------------------------------
+
+[[JIRA-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,text]
+-------------------------
+jira://endpoint[?options]
+-------------------------
+
+[[JIRA-Options:]]
+JIRA Options
+^^^^^^^^^^^^^
+
+
+// component options: START
+The JIRA component has no options.
+// component options: END
+
+
+
+// endpoint options: START
+The JIRA component supports 10 endpoint options which are listed below:
+
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| type | common | | JIRAType | *Required* Operation to perform such as create a new issue or a new comment
+| password | common | | String | Password for login
+| serverUrl | common | | String | *Required* URL to the JIRA server
+| username | common | | String | Username for login
+| 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.
+| delay | consumer | 6000 | int | Delay in seconds when querying JIRA using the consumer.
+| jql | consumer | | String | JQL is the query language from JIRA which allows you to retrieve the data you want. For example jql=project=MyProject Where MyProject is the product key in Jira.
+| 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).
+|=======================================================================
+// endpoint options: END
+
+
+[[JIRA-JQL:]]
+JQL:
+^^^^
+
+The JQL URI option is used by both consumer endpoints. Theoretically,
+items like "project key", etc. could be URI options themselves.
+ However, by requiring the use of JQL, the consumers become much more
+flexible and powerful.
+
+At the bare minimum, the consumers will require the following:
+
+[source,text]
+--------------------------------------------------------------
+jira://[endpoint]?[required options]&jql=project=[project key]
+--------------------------------------------------------------
+
+One important thing to note is that the newIssue consumer will
+automatically append "ORDER BY key desc" to your JQL. This is in order
+to optimize startup processing, rather than having to index every single
+issue in the project.
+
+Another note is that, similarly, the newComment consumer will have to
+index every single issue *and* comment in the project. Therefore, for
+large projects, it's *vital* to optimize the JQL expression as much as
+possible. For example, the JIRA Toolkit Plugin includes a "Number of
+comments" custom field -- use '"Number of comments" > 0' in your query.
+Also try to minimize based on state (status=Open), increase the polling
+delay, etc. Example:
+
+[source,text]
+----------------------------------------------------------------------------------------------------------------------------------------------
+jira://[endpoint]?[required options]&jql=RAW(project=[project key] AND status in (Open, \"Coding In Progress\") AND \"Number of comments\">0)"
+----------------------------------------------------------------------------------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/c4a88026/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 421fec2..b511dff 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -173,6 +173,7 @@
* [Jetty](jetty.adoc)
* [Jgroups](jgroups.adoc)
* [Jing](jing.adoc)
+ * [JIRA](jira.adoc)
* [Kafka](kafka.adoc)
* [Metrics](metrics.adoc)
* [Mock](mock.adoc)