From bf7512643b27201c0023d49b4ad80712f06066f4 Mon Sep 17 00:00:00 2001 From: "R.J. Robinson" Date: Mon, 27 Nov 2023 15:11:03 -0500 Subject: [PATCH 1/2] Update README.md --- README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 87 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index eb55f720..b39b6b49 100644 --- a/README.md +++ b/README.md @@ -11,27 +11,103 @@ Join our Slack channel! You can find us [here](https://jira-ruby-slackin.herokua ## Example usage -```ruby -require 'rubygems' -require 'jira-ruby' +# Jira Ruby API - Sample Usage + +This sample usage demonstrates how you can interact with JIRA's API using the [jira-ruby gem](https://github.com/sumoheavy/jira-ruby). + +### Dependencies + +Before running, install the `jira-ruby` gem: + +```shell +gem install jira-ruby +``` +### Sample Usage +Connect to JIRA +Firstly, establish a connection with your JIRA instance by providing a few configuration parameters: + • private_key_file: The path to your RSA private key file. + • consumer_key: Your consumer key. + • site: The URL of your JIRA instance. + +```ruby options = { - :username => 'username', - :password => 'pass1234', - :site => 'http://mydomain.atlassian.net:443/', - :context_path => '', - :auth_type => :basic + :private_key_file => "rsakey.pem", + :context_path => '', + :consumer_key => 'your_consumer_key', + :site => 'your_jira_instance_url' } client = JIRA::Client.new(options) +``` -project = client.Project.find('SAMPLEPROJECT') +### Retrieve and Display Projects -project.issues.each do |issue| - puts "#{issue.id} - #{issue.summary}" +After establishing the connection, you can fetch all projects and display their key and name: +```ruby +projects = client.Project.all +projects.each do |project| + puts "Project -> key: #{project.key}, name: #{project.name}" end ``` +### Handling Fields by Name +The jira-ruby gem allows you to refer to fields by their custom names rather than identifiers. Make sure to map fields before using them: + +```ruby +client.Field.map_fields +old_way = issue.customfield_12345 +# Note: The methods mapped here adopt a unique style combining PascalCase and snake_case conventions. +new_way = issue.Special_Field +``` + +### JQL Queries +To find issues based on specific criteria, you can use JIRA Query Language (JQL): + +```ruby +client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created]) +``` + +### Several actions can be performed on the Issue object such as create, update, transition, delete, etc: +### Creating an Issue +```ruby +issue = client.Issue.build +labels = ['label1', 'label2'] +issue.save({ + "fields" => { + "summary" => "blarg from in example.rb", + "project" => {"key" => "SAMPLEPROJECT"}, + "issuetype" => {"id" => "3"}, + "labels" => labels, + "priority" => {"id" => "1"} + } +}) +``` + +### Updating/Transitioning an Issue +```ruby +issue = client.Issue.find("10002") +issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA ```markdown +!"}}) + +issue_transition = issue.transitions.build +issue_transition.save!('transition' => {'id' => transition_id}) +``` +### Deleting an Issue +```ruby +issue = client.Issue.find('SAMPLEPROJECT-2') +issue.delete +``` +### Other Capabilities +Apart from the operations listed above, this API wrapper supports several other capabilities like: + • Searching for a user + • Retrieving an issue's watchers + • Changing the assignee of an issue + • Adding attachments and comments to issues + • Managing issue links and much more. + +Not all examples are shown in this README, refer to the complete script example for a full overview of the capabilities supported by this API wrapper. + ## Links to JIRA REST API documentation * [Overview](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs) From 2fd47bc86f2657fe3eab23d5c58e20e18d241a6a Mon Sep 17 00:00:00 2001 From: "R.J. Robinson" Date: Mon, 27 Nov 2023 15:20:58 -0500 Subject: [PATCH 2/2] Update README.md --- README.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b39b6b49..43dbbc18 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,10 @@ gem install jira-ruby ### Sample Usage Connect to JIRA Firstly, establish a connection with your JIRA instance by providing a few configuration parameters: - • private_key_file: The path to your RSA private key file. - • consumer_key: Your consumer key. - • site: The URL of your JIRA instance. +There are other ways to connect to JIRA listed below | [Personal Access Token](#configuring-jira-to-use-personal-access-tokens-auth) +- private_key_file: The path to your RSA private key file. +- consumer_key: Your consumer key. +- site: The URL of your JIRA instance. ```ruby options = { @@ -46,6 +47,7 @@ client = JIRA::Client.new(options) After establishing the connection, you can fetch all projects and display their key and name: ```ruby projects = client.Project.all + projects.each do |project| puts "Project -> key: #{project.key}, name: #{project.name}" end @@ -56,7 +58,9 @@ The jira-ruby gem allows you to refer to fields by their custom names rather ```ruby client.Field.map_fields + old_way = issue.customfield_12345 + # Note: The methods mapped here adopt a unique style combining PascalCase and snake_case conventions. new_way = issue.Special_Field ``` @@ -87,17 +91,18 @@ issue.save({ ### Updating/Transitioning an Issue ```ruby issue = client.Issue.find("10002") -issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA ```markdown -!"}}) +issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}}) issue_transition = issue.transitions.build issue_transition.save!('transition' => {'id' => transition_id}) ``` + ### Deleting an Issue ```ruby issue = client.Issue.find('SAMPLEPROJECT-2') issue.delete ``` + ### Other Capabilities Apart from the operations listed above, this API wrapper supports several other capabilities like: • Searching for a user @@ -106,7 +111,7 @@ Apart from the operations listed above, this API wrapper supports several other • Adding attachments and comments to issues • Managing issue links and much more. -Not all examples are shown in this README, refer to the complete script example for a full overview of the capabilities supported by this API wrapper. +Not all examples are shown in this README; refer to the complete script example for a full overview of the capabilities supported by this API wrapper. ## Links to JIRA REST API documentation @@ -163,7 +168,7 @@ key. > After you have entered all the information click OK and ensure OAuth authentication is > enabled. -For 2 legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth` +For two legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth` ## Configuring JIRA to use HTTP Basic Auth