Atlassian Confluence: extensible dengan python

Di Alfastrakhovanie kami secara aktif menggunakan "Wiki", mesin yang adalah Atlassian Confluence. Pertama kali saya secara serius menemukannya (dalam upaya untuk membuat konten di dalamnya), saya tidak memiliki "dinamisme" di dalamnya - saya ingin secara terprogram dapat membentuk bagian halaman, berinteraksi dengan sistem lain, dll.

Untuk beberapa waktu dia membenturkan kepalanya ke dinding yang berbeda, tetapi kemudian dia melihat bahwa "tidak ada satu dinding pun di rumah." Saya ingin berbagi pengalaman - bagaimana saya bisa menambahkan speaker ke Confluence. Saya harap ini akan bermanfaat bagi mereka yang menggunakannya. Dan, seperti biasa, untuk semua orang yang ingin tahu.

Wiki dinamis

Awalnya, Confluence menyarankan satu cara universal untuk memperluas fungsionalitasnya - plugin. Mungkin, dia bagus, hanya ada satu kelemahan - ambang masuk yang tinggi (Anda harus banyak belajar).

Setelah berpikir pendek (berdasarkan standar ruang), ada dua cara yang cukup sederhana untuk memperluas fungsinya: makro standar "HTML" dan "HTML Include", dalam artikel ini saya akan fokus pada yang terakhir secara lebih rinci.

Ada satu prinsip operasi untuk metode ini - kode HTML tertanam di halaman Confluence, bisa statis (yang juga bisa menarik, misalnya, untuk format halaman non-standar), dan bisa dinamis (termasuk komponen server).

Contoh: permintaan rekonsiliasi

Mari kita lihat cara yang diusulkan untuk memperluas kemampuan Pertemuan dengan contoh sederhana - daftar persetujuan dokumen.

Apa yang ingin kita lakukan: tambahkan daftar persetujuan ke halaman sehingga semua orang dapat melihat siapa yang harus menyetujui dokumen, apakah itu disetujui dan, jika demikian, kapan.

Untuk kenyamanan, kami akan membuat daftar item tombol dan menulis di dalamnya nama koordinator. Tombol akan aktif jika halaman dilihat oleh koordinator, dan tidak aktif dalam semua kasus lainnya.

Setelah disetujui, tombol "akan berhenti menjadi tombol" - alih-alih tombol setelah persetujuan, kami menggambar pada halaman fakta persetujuan dalam bentuk teks (nama penerima dan tanggal persetujuan). Dalam sebagian besar versi konsep (tanpa desain) mungkin terlihat seperti ini:

Skema interaksi

Komentar - cara kerjanya:

• halaman dalam Confluence berisi beberapa "html include" makro - sebenarnya permintaan HTTP GET dengan parameter (kami akan mempertimbangkan lebih detail di bawah)
• saat merender halaman, permintaan ini (skrip python) dieksekusi di server aplikasi, hasilnya (dihasilkan HTML) digambar di halaman
• dalam proses kerjanya, skrip, misalnya, menghubungi database dengan riwayat penandatanganan halaman, jika halaman tersebut belum "ditandatangani" oleh penandatangan - HTML akan berisi tombol (semuanya seperti dijelaskan di atas)
• ketika Anda mengklik tombol, kirimkan terjadi - skrip python lain disebut (skrip untuk memproses fakta rekonsiliasi)
• skrip ini menyimpan informasi tentang fakta masuk ke basis data dan mengarahkan pengguna kembali ke halaman asli (saat merender fakta penandatanganan mana yang akan diperhitungkan - mengklik tombol "masuk")

Sedikit rumit dalam kata-kata, mari kita coba memperjelas kodenya.

Jadi kita perlu membuat dua skrip

• skrip untuk pembentukan tombol "tanda" (Saya akan menyebutnya skrip "tombol")
• skrip untuk mengetahui fakta penandatanganan (reaksi terhadap klik tombol - saya akan memanggil skripnya "penangan")

Ayo buat mereka, mulai dengan tombol.

Tombol Skrip

Secara skematis, cara kerja skrip tombol:

date = getSignDate() if date: #       . else: if user==signee: #    else: #  inactive  

Script harus berupa dokumen HTML yang valid, isi yang dalam bentuk paling minimal adalah formulir

• aksi formulir berisi URL script "penangan"
• tombol aktif dikirimkan
• bidang formulir tersembunyi berisi parameter tambahan untuk penangan (dalam kasus kami, nama halaman dan info masuk penandatangan)

Perkiraan tampilan skrip (untuk singkatnya, saya membuang semua yang tidak perlu - lihat kode kerja penuh pada github )

 form = cgi.FieldStorage() signee = form["signee"].value #   (  ) actual = form["actual"].value #    id = form["id"].value #  ,    resHtml = """ <!DOCTYPE HTML> <html> <head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /></head> <body> <form name="input" action="http://172.16.108.216/misc/sign_proc.py" method="get"> """ server, token = wikiLogin() #   Confluence userName = getUserName(token, signee) #        res = getSignDate(id, signee) #     if res: #    resHtml += "<p> ({0}, {1})</p>".format(userName, res) #   else: #    if signee.lower() == actual.lower(): #      -   resHtml += '<input type="hidden" name="id" value="{0}">'.format(id) resHtml += '<input type="hidden" name="signee" value="{0}">'.format(signee) resHtml += "   <input type=\"submit\" value=\"{0}\">".format(userName) else: #      -    resHtml += "   <input disabled type=\"submit\" value=\"{0}\">".format(userName) resHtml += "</form></body></html>" #   HTML sys.stdout.buffer.write(b'Content-Type: text/html;charset=utf-8\n\n') sys.stdout.buffer.write(resHtml.encode("utf-8")) 

Script "handler"

Tugas pawang sangat sederhana - untuk memperbaiki fakta dengan menekan tombol "setuju". Kemudian arahkan kembali ke halaman asal permintaan - saat merender halaman, fakta koordinasi sudah akan diperhitungkan (lihat uraian di atas).

Contoh "disingkat" skrip "penangan" (versi lengkap - lihat github)

 form = cgi.FieldStorage() signee = form["signee"].value #   id = form["id"].value #  ,    addSignDate(id, signee) #    resHtml = """ <html> <head> <meta http-equiv="refresh" content="5;url=http://wiki.alfastrah.ru/display/DIT/{0}"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title> </title> </head> <body> <p>    <b>{0}</b>  <b>{1}</b> . <br>      ...</p> </body> </html> """.format(id, signee) sys.stdout.buffer.write(b'Content-Type: text/html;charset=utf-8\n\n') sys.stdout.buffer.write(resHtml.encode("utf-8")) 

Halaman dalam Confluence

Halaman di Confluence berisi tiga HTML makro termasuk dengan parameter yang berbeda (lihat kode di bawah) dan dalam versi paling sederhana terlihat seperti ini:

Kode halaman dalam format markup wiki - di sini Anda dapat melihat parameternya

 <h1> </h1> <p> ,  </p> <h1> </h1> <ul> <li> <ac:structured-macro ac:macro-id="..." ac:name="html-include" ac:schema-version="1"> <ac:parameter ac:name="url"> <ri:url ri:value="http://z14-0510-wiksap.vesta.ru/misc/sign_btn.py?signee=boss&amp;actual=korolevmv&amp;id=wikitools_sign"/> </ac:parameter> </ac:structured-macro> </li> <li> <ac:structured-macro ac:macro-id="..." ac:name="html-include" ac:schema-version="1"> <ac:parameter ac:name="url"> <ri:url ri:value="http://z14-0510-wiksap.vesta.ru/misc/sign_btn.py?signee=korolevmv&amp;actual=korolevmv&amp;id=wikitools_sign"/> </ac:parameter> </ac:structured-macro> </li> <li> <ac:structured-macro ac:macro-id="..." ac:name="html-include" ac:schema-version="1"> <ac:parameter ac:name="url"> <ri:url ri:value="http://z14-0510-wiksap.vesta.ru/misc/sign_btn.py?signee=maxvar&amp;actual=korolevmv&amp;id=wikitools_sign"/> </ac:parameter> </ac:structured-macro> </li> </ul> 

Sedikit tentang pengaturan

Agar skema yang dijelaskan bekerja, perlu untuk mempertimbangkan hal berikut

Ketersediaan HTML Sertakan makro

Kadang-kadang administrator "menyembunyikan" itu - ada banyak masalah tambahan untuk itu (sisi lain dari kemungkinan).

Makro ini gratis dan merupakan bagian dari Confluence - jika Anda tidak memilikinya, hubungi administrator, biarkan mereka melihat ...

Daftar Putih Confluence

Confluence tidak akan mengeksekusi skrip yang di-host pada sumber yang tidak diketahui, host di mana skrip di-host harus dalam apa yang disebut "daftar putih" (hubungi admin). Ini hanya berlaku untuk skrip "tombol" - skrip pawang dipanggil sudah oleh tombol, pembatasan Confluence tidak berlaku untuk itu.

Eksekusi skrip

Script (tombol dan penangan) harus dapat dieksekusi - salin URL ke browser, itu harus bekerja dan menghasilkan HTML, jika ini tidak terjadi, debug itu.

Kesalahan skrip

Jika ada skrip yang mengalami kesalahan - Anda tidak akan melihat sesuatu yang bagus, debug dengan benar sebelum menerbitkan ke Confluence.

Opsi skrip

Pikiran yang ingin tahu dapat memperhatikan parameter skrip - di satu sisi, mereka berlebihan (misalnya, nama halaman tempat tombol persetujuan ditempatkan - diketahui, mengapa diisi?). Di sisi lain, mereka tidak aman ("penyerang" dalam contoh kita dapat mengubah nama penerima untuk miliknya sendiri atau menghapus tombol rekonsiliasi sama sekali).

Redundansi dapat "diatasi" oleh makro pengguna (saya telah bertanya-tanya sejak lama - bagaimana mereka bisa berguna? Saya akan menulis secara singkat di artikel terpisah). Keamanan dalam Confluence dijamin oleh riwayat halaman - semua "gerakan" dicatat, Anda dapat mengubah apa pun, dalam Confluence masih ada "jejak audit" yang luar biasa yang memungkinkan Anda untuk memahami secara terperinci siapa yang mengubah apa dan kapan.

Interaksi Halaman

Dalam praktik kami, ada beberapa kasus ketika kami harus menguraikan kode halaman untuk mengumpulkan data (misalnya, ini adalah cara kami mengelola portofolio proyek). Itu mungkin dan bahkan tidak terlalu sulit. Secara evolusi, kita sampai pada kesimpulan bahwa jika beberapa informasi pada halaman diperlukan hanya untuk kode yang menginterpretasikan informasi ini, maka informasi ini lebih mudah untuk segera dirumuskan dalam kode itu sendiri (dalam bentuk JSON, misalnya): mengeditnya dalam mode pengeditan halaman cukup sederhana , itu ditarik oleh program, tetapi penghematan parsing dan peningkatan keandalan signifikan.

Lebih banyak contoh

Kenapa lagi kita menggunakan makro ini (sebagai ide - tiba-tiba sesuatu terbukti berguna), sangat singkat

Desain halaman : jika Anda ingin merancang halaman dengan cara yang tidak standar - markup menggunakan CSS, yang terkandung dalam blok HTML

Kalender liburan : kami menggunakan beberapa kalender JS sederhana, isi dengan data dari JSON, yang kami edit langsung dalam kode halaman, kami mendapatkan piring yang indah dengan liburan yang dikelompokkan (tahun, bulan, minggu).

Mencetak kartu tugas untuk papan scrum : kami mengatur parameter (nomor tugas dalam Jira dan atribut tambahan) dalam formulir tepat di halaman wiki (di blok HTML), sisi server membentuk kartu dalam bentuk yang sesuai untuk dikirim ke printer.

Manajemen portofolio proyek : kami punya ide seperti itu. Peta diberi skor tepat di wiki (peta skor adalah halaman yang ditandai khusus), peta ini mengumpulkan rencana blok besar, yang digambar dengan indah dalam bentuk bagan gantt.

Glosarium : kemampuan untuk memvisualisasikan istilah - penjelasan untuk setiap kata halaman - dari kamus umum dan menerbitkan entri kamus dalam bentuk "pop-up". Kamus itu sendiri secara otomatis dikumpulkan di bagian bawah halaman.

Bagan : jika Anda perlu menggambar semacam bagan sederhana, maka sangat mudah untuk melakukannya dengan menyematkan blok HTML dengan salah satu paket standar (Google Charts, HighCharts, dll)

Tabel : di atas semua tabel di Confluence Anda dapat "menggantung" Datatable - kami mendapatkan tabel yang difilter dengan "pagination", sangat bagus dan nyaman.

Daftar ini dapat dilanjutkan cukup lama, selama operasi, satu ketidaknyamanan yang signifikan telah diperhatikan: kesalahan dalam kode server tidak dapat ditangkap dengan baik - 500 kesalahan divisualisasikan dengan buruk dan secara praktis tidak mengandung informasi. Kalau tidak, bereksperimen - itu cukup aman.

Untuk meringkas

Cara sederhana yang dijelaskan di atas untuk meningkatkan dinamika Confluence memungkinkan Anda untuk menyelesaikan berbagai masalah. Untuk menggunakannya tidak memerlukan alat dan keterampilan khusus. Penggunaannya cukup aman. Saya merekomendasikannya.

Pada artikel selanjutnya saya akan berbicara tentang pengalaman menggunakan macro khusus di Confluence - yang, menurut saya, benar-benar dapat ditingkatkan dengan bantuan mereka.

Segalanya mungkin dalam pemrograman - hanya masalah waktu dan motivasi saja.