Bài 23 — JIRA REST API cho BA — JIRA and Confluence for BA

Mở đầu — vì sao bài này quan trọng

Hãy hình dung một buổi sáng thứ Hai điển hình của bạn — một Business Analyst. Sếp gửi cho bạn một file Excel 350 dòng requirements vừa thu thập từ workshop với khách hàng, kèm câu nói nhẹ nhàng nhưng đầy sức nặng: "Em import hết vào JIRA giúp anh trước trưa nay nhé." Nếu bạn ngồi tạo từng issue thủ công, mỗi issue mất 40 giây, thì 350 dòng tương đương gần 4 tiếng đồng hồ — chưa kể mỏi tay và sai sót.

Hoặc một tình huống khác: Giám đốc dự án muốn xem dashboard tiến độ trên Power BI, nhưng dữ liệu nằm trong JIRA. Mỗi tuần bạn phải export CSV thủ công, dán vào Power BI, refresh — một việc lặp đi lặp lại nhàm chán.

Đây chính là lúc JIRA REST API trở thành "vũ khí bí mật" của BA. REST API (Application Programming Interface) là cách để chương trình của bạn "nói chuyện" trực tiếp với JIRA mà không cần mở trình duyệt và click chuột. Nhiều BA nghĩ rằng API là chuyện của developer — nhưng thực tế, hiểu được API ở mức cơ bản giúp bạn tự động hóa những việc tốn hàng giờ xuống còn vài phút, và quan trọng hơn, giúp bạn trao đổi chính xác với dev/IT khi cần tích hợp hệ thống.

Bài này không biến bạn thành lập trình viên. Mục tiêu là giúp bạn hiểu khi nào cần API, đọc được tài liệu API, và tự thực hiện được các thao tác cơ bản — đủ để giải quyết phần lớn nhu cầu hằng ngày của một BA.

Khái niệm cốt lõi

REST API là gì — giải thích cho người không phải dev

Hãy tưởng tượng JIRA như một nhà hàng. Giao diện web là phòng ăn đẹp đẽ bạn vẫn dùng. Còn REST API là cánh cửa bếp: bạn gửi một "order" (yêu cầu) theo đúng quy chuẩn, và nhà bếp trả về "món ăn" (dữ liệu). Bạn không cần biết bếp nấu thế nào — chỉ cần gọi đúng món, đúng cách.

Mỗi yêu cầu API có 4 thành phần chính:

Method (phương thức): hành động bạn muốn làm. Bốn loại quen thuộc nhất:

- GET — lấy dữ liệu (đọc issue, đọc danh sách). - POST — tạo mới (tạo issue mới). - PUT — cập nhật toàn bộ một issue. - DELETE — xóa.

Endpoint (đường dẫn): địa chỉ của tài nguyên. Ví dụ: https://yourcompany.atlassian.net/rest/api/3/issue/PROJ-123.
Headers (đầu mục): thông tin kèm theo, gồm xác thực (authentication) và định dạng dữ liệu (thường là application/json).
Body (nội dung): dữ liệu bạn gửi đi (khi tạo hoặc cập nhật), viết bằng định dạng JSON.

JSON — ngôn ngữ trao đổi dữ liệu

JSON (JavaScript Object Notation) là cách viết dữ liệu mà cả người lẫn máy đều đọc được. Ví dụ một issue đơn giản dưới dạng JSON:

{
  "fields": {
    "project": { "key": "BA" },
    "summary": "Khách hàng cần màn hình đăng nhập bằng OTP",
    "issuetype": { "name": "Story" },
    "priority": { "name": "High" }
  }
}

Bạn thấy đấy — nó chỉ là các cặp "tên: giá trị" lồng nhau trong dấu ngoặc nhọn. Một khi quen mắt, đọc JSON dễ như đọc một bảng tính.

Xác thực — API Token thay vì mật khẩu

Bạn không bao giờ dùng mật khẩu thật trong API. Atlassian Cloud yêu cầu dùng API Token: vào id.atlassian.com → Security → Create API token. Token này kết hợp với email của bạn theo cơ chế Basic Authentication. Trong các công cụ, bạn chỉ cần điền email + token là xong. Đây là điểm cực kỳ quan trọng về bảo mật mà BA hay bỏ qua — sẽ nói kỹ ở phần lỗi thường gặp.

Ba cấp độ "dùng API" cho BA

Không phải BA nào cũng cần viết code. Có ba cấp độ thực hành:

Cấp 1 — Postman / công cụ giao diện: Postman là phần mềm cho phép gọi API bằng cách điền form, không cần lập trình. Đây là điểm khởi đầu lý tưởng cho BA.
Cấp 2 — REST API qua tích hợp sẵn: dùng Power Query trong Excel/Power BI để "kéo" dữ liệu JIRA về mà không viết script.
Cấp 3 — Script đơn giản: vài dòng Python để xử lý hàng loạt. Bạn không cần là dev, chỉ cần copy-sửa mẫu có sẵn.

Tình huống thực tế

Tình huống 1 — Tiki: Import 350 requirements từ Excel trong 8 phút

Tại một đội BA của sàn thương mại điện tử (lấy bối cảnh giống Tiki), chị Lan — BA trưởng — vừa hoàn thành workshop thu thập yêu cầu cho dự án nâng cấp giỏ hàng. Kết quả là file Excel 350 dòng, mỗi dòng gồm: tiêu đề requirement, mô tả, độ ưu tiên, và module liên quan.

Thay vì nhập tay, chị dùng một script Python ngắn (khoảng 30 dòng) đọc file Excel rồi gọi POST /rest/api/3/issue lặp qua từng dòng. Trước khi chạy thật, chị dùng một endpoint kiểm tra trên 5 dòng đầu để chắc rằng mapping cột đúng. Toàn bộ 350 issue được tạo trong 8 phút, kèm đầy đủ summary, description, priority và label theo module.

Bài học rút ra: Việc tốn 4 giờ thủ công đã rút xuống còn vài phút. Quan trọng hơn, chị Lan không phải dev — chị chỉ học cách sửa một script mẫu mà bạn dev đưa, và tự kiểm soát phần "mapping dữ liệu" — đúng phần thuộc chuyên môn BA. Một BA hiểu API trở thành cầu nối, không còn là "người chờ dev làm hộ".

Tình huống 2 — VNG: Đẩy dữ liệu JIRA sang Power BI cho ban lãnh đạo

Một studio game (bối cảnh tương tự VNG) cần báo cáo tiến độ 6 dự án song song cho ban giám đốc mỗi sáng thứ Hai. Trước đây, anh Tuấn — BA — phải export 6 file CSV, ghép lại, rồi dán vào Power BI — mất khoảng 90 phút mỗi tuần và thường trễ giờ họp.

Anh chuyển sang dùng Power Query kết nối trực tiếp tới endpoint JQL: GET /rest/api/3/search?jql=project in (G1,G2,...) AND updated >= -7d. Power BI tự gọi API, nhận về JSON, và "bung" (expand) các trường thành bảng. Anh đặt lịch refresh tự động lúc 7h sáng thứ Hai. Từ đó, dashboard luôn sẵn sàng trước giờ họp, không cần một thao tác tay nào.

Bài học rút ra: API không chỉ để tạo dữ liệu mà còn để lấy dữ liệu ra phục vụ phân tích. Với BA, đây là kỹ năng vàng: bạn biến JIRA từ một công cụ quản lý task thành một nguồn dữ liệu cho mọi báo cáo BI. Lưu ý: endpoint /search của JIRA trả tối đa 100 issue mỗi lần gọi, nên với dữ liệu lớn cần dùng tham số startAt để phân trang (pagination).

Tình huống 3 — Một ngân hàng số: Đồng bộ trạng thái sang Slack

Một fintech tại TP.HCM muốn mỗi khi một issue chuyển sang trạng thái "Ready for UAT", thì tự động báo vào kênh Slack của đội QA. Anh Phát — BA kiêm điều phối — không tự code phần này, nhưng nhờ hiểu API, anh viết được spec tích hợp chính xác cho dev: gọi GET /rest/api/3/issue/{key}?fields=status,assignee để lấy trạng thái, lọc điều kiện, rồi gửi sang Slack webhook.

Bài học rút ra: Đôi khi giá trị lớn nhất của việc hiểu API không phải là tự làm, mà là giao tiếp chính xác với kỹ thuật. Khi BA viết được "gọi endpoint nào, lấy field gì, điều kiện ra sao", buổi họp với dev rút từ 1 tiếng vòng vo xuống 15 phút thẳng vào việc.

Hướng dẫn từng bước

Hãy thực hiện thao tác API đầu tiên của bạn — lấy thông tin một issue bằng Postman. Đây là "Hello World" của thế giới API.

Bước 1 — Tạo API Token. Vào https://id.atlassian.com/manage-profile/security/api-tokens → Create API token → đặt tên (ví dụ "Postman-BA") → copy token và lưu ngay (nó chỉ hiện một lần).

Bước 2 — Cài Postman (miễn phí tại postman.com) và tạo một request mới.

Bước 3 — Cấu hình request GET.

Method: chọn GET.
URL: https://yourcompany.atlassian.net/rest/api/3/issue/BA-1 (thay yourcompany và BA-1 bằng của bạn).

Bước 4 — Thiết lập xác thực. Tab Authorization → Type chọn Basic Auth → Username điền email Atlassian → Password dán API Token.

Bước 5 — Gửi và đọc kết quả. Nhấn Send. Bạn sẽ thấy một khối JSON trả về với fields.summary, fields.status.name, fields.assignee.displayName... Đó chính là dữ liệu issue của bạn.

Bước 6 — Thử tìm kiếm bằng JQL. Đổi URL thành: https://yourcompany.atlassian.net/rest/api/3/search?jql=project=BA AND status="In Progress"&maxResults=10 Bạn vừa lấy về danh sách issue đang làm dở — bằng API.

Bước 7 — Thử tạo một issue (POST). Đổi method sang POST, URL là .../rest/api/3/issue, tab Headers thêm Content-Type: application/json, tab Body chọn raw → JSON và dán đoạn JSON tạo issue ở phần trên. Nhấn Send — issue mới xuất hiện trong JIRA.

Bước 8 — Nâng lên bulk. Khi đã quen Postman, nhờ dev đưa script Python mẫu dùng thư viện requests, vòng lặp for qua các dòng Excel (đọc bằng pandas). Bạn chỉ cần sửa phần mapping cột — phần logic nghiệp vụ vốn là thế mạnh của BA.

Lỗi thường gặp & mẹo

Lỗi 1 — Dùng mật khẩu thật thay vì API Token. Atlassian Cloud đã chặn xác thực bằng mật khẩu từ lâu. Triệu chứng: lỗi 401 Unauthorized. Luôn dùng email + API Token.

Lỗi 2 — Hard-code token vào file chia sẻ. Đừng bao giờ dán token thẳng vào script rồi gửi qua email/Slack. Token bị lộ tương đương trao chìa khóa tài khoản. Mẹo: lưu token trong biến môi trường (environment variable) hoặc file .env không commit lên Git.

Lỗi 3 — Quên phân trang. Endpoint /search chỉ trả tối đa 100 issue (mặc định 50). Nếu thiếu dữ liệu, kiểm tra trường total trong response và lặp lại với startAt=0, 100, 200....

Lỗi 4 — Nhầm tên field nội bộ. Trên giao diện bạn thấy "Story Points", nhưng trong API nó là customfield_10016. Mẹo: gọi GET /rest/api/3/field để lấy bản đồ tên field → ID, hoặc dùng endpoint /rest/api/3/issue/{key}/editmeta để biết field nào sửa được.

Lỗi 5 — Lỗi 400 khi tạo issue do thiếu field bắt buộc. Một số dự án bắt buộc field như "Components" hoặc "Reporter". Đọc kỹ message lỗi trong response — JIRA chỉ rõ field nào thiếu.

Mẹo vàng — Rate limit. Atlassian giới hạn số lần gọi API mỗi phút. Khi bulk hàng trăm issue, thêm độ trễ nhỏ (ví dụ time.sleep(0.3)) giữa các lần gọi để tránh lỗi 429 Too Many Requests.

Mẹo — Luôn test trên dự án sandbox trước. Tạo một project test riêng để thử POST/DELETE, tránh làm hỏng dữ liệu thật. API tạo và xóa rất nhanh — và sai sót cũng nhân lên rất nhanh.

Bài tập thực hành

Khởi động: Tạo một API Token và dùng Postman gọi GET để lấy thông tin issue đầu tiên trong dự án của bạn. Chụp lại response và đánh dấu 3 trường: summary, status.name, assignee.displayName.

Tìm kiếm: Viết một câu JQL tìm tất cả issue có priority = High chưa được assign, rồi gọi qua endpoint /search. So sánh số lượng total với kết quả tìm trên giao diện web — chúng phải khớp.

Tạo issue: Dùng POST tạo 1 Story mới có summary, description và priority. Xác nhận issue xuất hiện trên board.

Mini-import: Lập một file Excel 5 dòng requirements giả định. Nhờ một script mẫu (hoặc tự viết với sự hỗ trợ), import cả 5 dòng vào JIRA. Mục tiêu là hiểu luồng "đọc Excel → mapping → POST".

Tư duy tích hợp: Viết một đoạn spec ngắn (5–7 dòng) mô tả: "Mỗi khi issue chuyển sang Done, gửi thông báo sang Slack" — gồm endpoint nào, field nào cần lấy, điều kiện lọc. Đây là bài luyện kỹ năng giao tiếp với dev.

Tóm tắt

JIRA REST API là cầu nối giúp BA vượt qua giới hạn của giao diện click chuột. Bạn đã hiểu rằng API gồm bốn thành phần — method, endpoint, headers, body — và dữ liệu trao đổi qua định dạng JSON, xác thực bằng email kết hợp API Token chứ không phải mật khẩu.

Quan trọng nhất, bạn nhận ra ba thời điểm BA thực sự cần API: bulk import requirements từ Excel, export dữ liệu sang công cụ BI như Power BI/Tableau, và tích hợp với hệ thống ngoài như Slack. Qua ba tình huống của Tiki, VNG và một fintech, ta thấy giá trị không chỉ nằm ở việc tự động hóa tiết kiệm hàng giờ, mà còn ở khả năng giao tiếp chính xác với đội kỹ thuật.

Bạn không cần trở thành lập trình viên. Hãy bắt đầu từ Postman, làm chủ vài endpoint cốt lõi (/issue, /search, /field), nắm các lỗi thường gặp về xác thực, phân trang và rate limit. Khi đã thoải mái, một script Python ngắn sẽ mở ra cả thế giới tự động hóa. Một BA biết dùng API là một BA biến mình từ người vận hành thủ công thành người kiến tạo quy trình.