Share
Trang chủ / Tất cả hướng dẫn / Lập trình web / Điều khiển Jira trong nodeJs

Điều khiển Jira trong nodeJs

Hướng dẫn sửa, thêm, xóa issue của jira trong NodeJs, đồng thời thao tác với mọi đối tượng khác trong của Jira bằng module Node-Jira.

Có thể vì một nhu cầu bất kỳ nào đó mà bạn muốn điều khiển jira trong nodejs, ví dụ như viết bot tích hợp jira và slack, hoặc tích hợp jira vào một ứng dụng chat bằng nodejs nào đó, cũng có thể là bạn xây dựng một giao diện dành cho khách hàng của bạn để họ có thể xem được tiến độ thực hiện dự án của bạn … Đó là khi bạn đang tìm và đọc bài hướng dẫn này nhằm tìm ra giải pháp cho vấn đề của bạn, hoặc nếu bạn chỉ đọc để biết thì cũng chả sao. Hôm nay chúng ta sẽ cùng tìm hiểu cách tích hợp Jira vào ứng dụng nodejs sử dụng thư viện JiraApi.

Jira API

Nhờ Jira có hỗ trợ REST API, nên chúng ta có thể thông qua đó mà thao tác với jira một cách dễ dàn, nếu không thì mình đoán là sẽ rất khó để biết được một issue có tồn tại hay không chứ đừng nói tới điều khiển nó. Các API mà Jira hỗ trợ có thể giúp bạn thao tác với hầu hết mọi tính năng của nó. Bạn có thể add, delete hoặc edit issue… và rất nhiều tác vụ khác mà bạn có thể xem lại trang tài liệu của nó :

Authentication

Jira hỗ trợ hai hình thức authentication là basic và OAuth. Để đơn giản nhất, thì trong bài viết này chúng ta sẽ sử dụng basic auth, để sử dụng basic auth, bạn chỉ cần chung cấp username, password của bạn trên jira, còn OAuth thì phức tạp hơn một chút.

Nhưng bù lại, khi sử dụng basic auth, nếu bạn ở trong một mạng không an toàn, thì rất dễ bị sniff username, password. nên trước khi sử dụng hãy đảm bảo mạng của bạn an toàn, hoặc cài đặt ssl cho server của jira.

Jira nodejs
Jira nodejs

Module Jira cho nodeJs

Như bạn đọc trong tài liệu của Jira, bạn có thể sử dụng giao thức http/https để request lên API của nó, vì vậy trong nodejs, bạn sẽ dùng module ‘request’. Tuy nhiên để đỡ tốn thời gian, mình sẽ sử dụng một module được viết bởi Steven Surowiec là node-jira.

Thư viện này hỗ trợ khá đầy đủ, nó đơn giản là dùng module request và code cũng rất dễ hiểu, Nó tiện lợi ở chỗ nó tự động điền username, password và map các API thành các function cho chúng ta.

Init code

Tạo như mục jiraNodeExample, truy cập và mở command line tại thư mục này và dùng lệnh sau để init một project nodejs :

npm init -f

Sau đó bạn sẽ có được file package.json có nội dung gần giống như sau :

{
  "name": "jiraNodeExample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Install module

Giờ gõ lệnh sau để install module vào lưu module đó vào file package.json :

npm install jira --save

Lệnh này sẽ cài đặt, tải các file của thư viện jira về và bỏ vào thư mục node_modules. Đồng thời cũng thêm dependence vào file package.json để sau này nếu bạn có share app này cho bất kỳ ai khác, thì không phải chép thư mục node_modules đi, và nếu bạn muốn update module này thì cũng chỉ cần vào file package.json để sửa lại số phiên bản chứ không cần download code gì cả.

File package.js giờ sẽ được sử thành như sau :

{
  "name": "slackexample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "jira": "^0.9.2"
  }
}

Điều khiển jira

Giờ bạn tạo file index.js, và chúng ta sẽ bắt đầu sử dụng thư viện này để điều khiển jira. Trước tiên ta cần tạo instance của module này :

var JiraApi = require('jira').JiraApi;

var protocol = '',
    jiraHost = '',
    jiraPort = '',
    jiraUser = '',
    jiraPassword = '',
    jiraApiVersion = '';

var jira = new JiraApi(protocol, jiraHost, jiraPort, jiraUser, jiraPassword, jiraApiVersion);

Có lẽ đọc tên các biến chắc bạn cũng đủ hiểu ý nghĩa của nó, trong đó protocal là http nếu bạn không cài ssl cho jira, nếu có ssl thì protocal là https nhé.

Thao tác với issue

Bạn đọc tài liệu cho ba thao tác dưới đây ở trang tài liệu của jira, Nhớ đọc kỹ, vì nếu không thì bạn không thể tiếp tục được :

Lấy thông tin một issue

Để lấy thông tin issue ta sử dụng phương thức findIssue. Phương thức này yêu cầu hai tham số là issue key và callback. Ví dụ như sau :

jira.findIssue('GM-345', function(error, issue){
    if(error !== null){
        console.log(error);
    }else{
        console.log(issue);
    }
});

Nếu như có lỗi xảy ra, thì nó sẽ được truyền vào trong tham số error, nếu không thì tham số error sẽ là null và tham số issue sẽ chứa thông tin về issue mà bạn đang cần. Issue là một object với rất nhiều thông tin, mình không thể ghi ra đây cho các bạn xem được. nên bạn xem trong link sau :

Sửa issue

var updateData = {
    "update": {
        "summary": [
            {
                "set": "Bug in business logic"
            }
        ]
    }
};
jira.updateIssue('GM-345',updateData, function(error, success){
    if(error !== null){
        console.log(error);
    }else{
        console.log(success);
    }
});

Đoạn code ở trên update date summary của issue GM-345. Nếu thành công, thì biến success sẽ là một string “Success”. Để biết biến updateData có thể chứa những thông tin gì, thì bạn cần đọc ở tài liệu mà mình link phía trên.

Các phương thức khác

Cũng tương tự như các thao tác với issue trên, còn nhiều phương thức khác như bản dưới đây, Quy ước là phần return chính là hai tham số truyền vào cho hàm callback nhé, vì các phương thức này đều là async, nên không thể return được, mà chỉ có thể gọi callback để truyền kết quả thôi. Và phương thức nào cũng mặc định kèm theo tham số error khi gọi callback, tham số này chưa nội dung error, vì vậy mình sẽ không viết lại nó.

Và tất cả các phương thức này, nếu có chỗ nào không hiểu, thì bạn phải đọc tại trang API của Jira :

Phương thức Tham số Tham số cho callback
findIssue issueNumber issue : Object chứa nội dung issue
getUnresolvedIssueCount versionNumber count : Số issue chưa resloved
getProject projectKey project : Object chứa thông tin project
findRapidView projectName Lấy thông tin của Rapid View
getLastSprintForRapidView rapidViewId sprints array các sprint có trong rapidview
getSprintIssues rapidViewId
sprintId
Lấy tất cả các issue của sprintId trong RapidViewId
addIssueToSprint issueId
sprintId
Chỉ trả về error nếu có lỗi
issueLink link : Object chưa thông tin issue Link các hai issue lại với nhau
getVersions projectKey versions : Array các version của project
createVersion versionObject: Thông tin của version versionObject : Thông tin của version
updateVersion versionObject versionObject
searchJira searchString
optional
issues : array các issue được tim thấy
searchUsers username
startAt : Vị trí bắt đầu tìm
maxResults
includeActive
includeInactive
users : array các user được tim thấy
getUsersIssues username
open : true nếu chỉ tìm các issue đang open
issues : array issue của username
addNewIssue issueObject : Object chứa thông tin issue Success object
deleteIssue issueKey Success string
updateIssue issueObject Success string
listComponents projectKey components : Array các component của project
listFields void fields : Array các field
listPriorities void Priorities : Array các priority
listTransitions issueKey transitions: Array transition của issue
transitionIssue issueKey
transitionObject
Success string
listProjects void projects : array các project
addComment issueKey
comment string
success string
addWorklog issueKey
worklogObject
newEstimate
success string
listIssueTypes void Types : array các issuetype
registerWebhook webhook object Success object
listWebhooks void webhook : arrray các webhook
getWebhook webhookKey webhookObject
deleteWebhook webhookKey success strign
getCurrentUser void userObject
getBacklogForRapidView rapidViewId backlogObject

Lời kết

Thực ra mình liệt kê như vậy vẫn chưa đầy đủ thông tin, khi bạn code, bạn dùng các kỹ thuật debug để lấy thuộc tính của các tham số trả về trong callback để biết được nó chứa những gì mà tùy nghi sử dụng. Nếu đọc trong jira api Doc mà bạn gặp những API không được hỗ trợ trong module, thì mong là bạn hãy folk module tại github, sửa đổi, test và tạp pr cho tác giả merge vào.

Từ API này, bạn có thể nghĩ ra khá nhiều thứ thú vị. Mình đã từng làm con bot cho slack với chức năng là : khi tên của một issue được mention trong slack, thì bot tự động lấy thông tin của issue và reply vào, như vậy sẽ rất tiện lợi để thảo luận trên slack. Ý tưởng lấy từ group slack của WordPress.org. Bot của họ hoạt động cũng giống mình, chỉ khác ở chỗ họ tích hợp với trac.