Skip to content

Home

Jump to bottom Edit New page
sukchr edited this page Jan 11, 2012 · 11 revisions

Logira

Installation

Install via NuGet: PM> Install-Package Logira

Configure JIRA connection

You need to tell Logira where your JIRA installation is and the credentials to use for the JIRA account

using Logira;

...

Jira.Configure("https://your-jira-site.com", "username", "password");

Logira will append the URL of your JIRA installation with the following path to the SOAP service: /rpc/soap/jirasoapservice-v2. The above example will therefore access the JIRA SOAP service at https://your-jira-site.com/rpc/soap/jirasoapservice-v2.

Create an issue

Minimal example

Here's the minimalistic example for creating an issue.

new IssueBuilder()
   .Project("TST")
   .Summary("Issue summary")
   .Create();

This will create an issue inside the project with project key "TST" and with the summary set to "Issue summary". The issue type will be "Bug" (issue type with id 1).

Issue created with minimal info

A note on summary length

By default, Logira will truncate the summary if it is longer than 50 chars. The truncation will be indicated by a trailing "..." in the summary. The full summary will be included in the description if this happens.

You can change the max length of the summary like this:

Jira.MaxSummaryLength = 255;

JIRA has a restriction on the summary length set to 255, meaning you will get an exception if you try to create an issue with a summary longer than 255 chars.

Getting a reference to the issue

IssueBuilder.Create() returns a Logira.Issue object that contains the key and URL of the newly created issue.

var issue = new IssueBuilder()
   ...
   .Create();

Console.WriteLine(issue.Key); // --> "TST-123"
Console.WriteLine(issue.Url); // --> "https://your-jira-site.com/browse/TST-123"

Uploading attachments

You can set attachments to be uploaded with the issue by invoking Attachment on the IssueBuilder. You need to base64 encode the data.

new IssueBuilder()
   .Project("TST")
   .Summary("Issue with two attachments")
   .Attachment("application.log", "base64encoded binary")
   .Attachment("access.log", "base64encoded binary")
   .Create();

Setting additional issue properties

In addition to the minimal requirements of setting the issue project and summary, you can set following information on the issue:

Issue description

Set the issue description as a string value.

new IssueBuilder()
   .Project("TST")
   ...
   .Description("Issue description")
   ...
   .Create();

If you have an exception object, you can use that as the description:

try
{
    ... something ... 
}
catch (Exception ex)
{
   new IssueBuilder()
      ...
      .Description(ex)
      ...
      .Create();
}

The exception message and stacktrace will be output. The chain of inner exceptions will also be added to the description.

Issue with exception details

You can set description with both string and exception in the same issue.

try
{
    ... something ... 
}
catch (Exception ex)
{
   new IssueBuilder()
      ...
      .Description("An exception was thrown")
      .Description(ex)
      ...
      .Create();
}

JIRA has rich text fields that supports using macros. Logira provides some of these macros as classes which enables you to insert macros into the description like this:

new IssueBuilder()
   ...
   .Description(new CodeMacro {Title="Foo.cs", Code="... some code ..."})
   ...
   .Create();

The above example is equivalent to

new IssueBuilder()
   ...
   .Description("{code:title=Foo.cs}... some code ...{code}")
   ...
   .Create();

The following macros are available (see http://confluence.atlassian.com/display/JIRA/Editing+Rich-Text+Fields for more information):

  • CodeMacro
  • HtmlMacro
  • NoFormatMacro
  • PanelMacro
  • QuoteMacro

Issue type

Setting the issue type is a little more complicated because JIRA operates with integer values for the various issue types. The default issue type is set to 1, which usually means "Bug". You can override this by setting a different integer value for your issue type.

new IssueBuilder()
   ...
   .Type(2) //2 == New feature
   ...
   .Create();

Check out this link if you need to find the issue type IDs in your JIRA installation: http://confluence.atlassian.com/display/JIRA/Finding+the+Id+for+Issue+Types.

Logira.IssueType defines some constants that you can use to make the setup more readable.

new IssueBuilder()
   ...
   .Type(IssueType.NewFeature) //IssueType.NewFeature == 2 == New feature
   ...
   .Create();

Environment

Specify environment like this:

new IssueBuilder()
    .Project("TST")
    .Summary("Issue with environment")
    .Environment("OS version: " + Environment.OSVersion) //--> "OSVersion: Microsoft Windows NT 6.1.7600.0"
    .Create();

You can invoke Environment multiple times.

new IssueBuilder()
    .Project("TST")
    .Summary("Issue with environment")
    .Environment("OS version: " + Environment.OSVersion) //--> "OSVersion: Microsoft Windows NT 6.1.7600.0"
    .Environment("ProcessorCount: " + Environment.ProcessorCount) //--> "ProcessorCount: 2"
    .Create();

If you want to output (almost) everything from System.Environment:

new IssueBuilder()
    .Project("TST")
    .Summary("Issue with environment")
    .Environment().FromServer()
    .Create();

If you want to output everything from the current System.Web.HttpRequest:

new IssueBuilder()
    .Project("TST")
    .Summary("Issue with environment")
    .Environment().FromClient()
    .Create();

Affects version

You can specify the affects version both as a string constant and by retrieving metadata from the (calling) assembly (specifically the version attributes that can be set on the assembly). If the versions you specify on the issue doesn't exist in the project, Logira will create them automatically. For this to happen, the user that Logira is configured with needs to have administrator permissions in the project.

Setting affects version as a string

The example below specifies a constant string value as the version. A version will be created in JIRA with the name "1.2" under the "TST" project.

new IssueBuilder()
    .Project("TST")
    .Summary("with affects version")
    .AffectsVersion("1.2")
    .Create();

You can specify multiple versions like this:

new IssueBuilder()
    .Project("TST")
    .Summary("with affects version")
    .AffectsVersion("1.2", "1.3", "1.4")
    .Create();

Setting affects version from assembly metadata

The code below will use the entire informational version and set the affects version to "1.5.31.478495".

[assembly: AssemblyInformationalVersion("1.5.31.478495")]

...

new IssueBuilder()
    .Project("TST")
    .Summary("with affects version")
    .AffectsVersion().AssemblyInformationalVersion() //--> 1.5.31.478495
    .Create();

If you need only parts of the version or in some other way want to control the version name, you can use the overload that passes you the retrieved version so that you can build your own version string. The example below will set the affects version to "v. 1.5".

[assembly: AssemblyInformationalVersion("1.5.31.478495")]

...

new IssueBuilder()
    .Project("TST")
    .Summary("with affects version")
    .AffectsVersion().AssemblyInformationalVersion(version => "v. " + version.Major + "." + version.Minor) //--> v. 1.5
    .Create();

As mentioned, you can also retrieve assembly version and assembly file version:

[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("2.0.0.0")]

...

new IssueBuilder()
    .Project("TST")
    .Summary("with affects version")
    .AffectsVersion().AssemblyVersion() //--> 1.0.0.0
    .AffectsVersion().AssemblyFileVersion() //--> 2.0.0.0
    .Create();

If you have any other metadata on the assembly that you want to use as affects version:

new IssueBuilder()
   .Project("TST")
   .Summary("with affects version")
   .AffectsVersion().Assembly(assembly => assembly.GetCustomAttribute<SomeOtherAttributeThatContainsUsefulData>().SomeData)
    .Create();

Logging

Logira outputs the JIRA communication using log4net with log level DEBUG.

DEBUG Logira.Jira (null) - JIRA was configured with url, username, password: 'https://your-jira.com/jira/rpc/soap/jirasoapservice-v2', 'test', 'tes****'
DEBUG Logira.Jira (null) - Service.login returned token: P8I4E*****
DEBUG Logira.Jira (null) - Creating issue:
{
  "project": "TST",
  "summary": "Issue with attach",
  "type": "1"
}
DEBUG Logira.Jira (null) - Successfully created issue:
{
  "affectsVersions": [],
  "attachmentNames": [],
  "components": [],
  "created": "\/Date(1325507721370)\/",
  "customFieldValues": [
    {
      "customfieldId": "customfield_10034",
      "values": [
        "true"
      ]
    },
    {
      "customfieldId": "customfield_10033",
      "values": [
        "0"
      ]
    },
    {
      "customfieldId": "customfield_10032",
      "values": [
        "gmail.com"
      ]
    },
    {
      "customfieldId": "customfield_10120",
      "values": [
        "3992"
      ]
    },
    {
      "customfieldId": "customfield_10030",
      "values": [
        "test"
      ]
    },
    {
      "customfieldId": "customfield_10220",
      "values": [
        "16976"
      ]
    }
  ],
  "fixVersions": [],
  "key": "TST-116",
  "priority": "6",
  "project": "TST",
  "reporter": "test",
  "status": "1",
  "summary": "Issue with attach",
  "type": "1",
  "updated": "\/Date(1325507721370)\/",
  "votes": 0,
  "id": "33492"
}
DEBUG Logira.Jira (null) - Adding attachments to issue TST-116: hello.txt, foo.txt
Add a custom footer
Add a custom sidebar

Clone this wiki locally