Panduan Upgrade OJS 2 ke OJS 3

Versi 1.2
17 Juli 2024
Hak Cipta: Public Knowledge Project
Karya ini dilisensikan secara terbuka melalui
CC BY-NC-SA
Diterjemahkan oleh Maria Lamury dan Dwi Fajar Saputra

Panduan ini memberikan best practice untuk melakukan upgrade Open Journal System (OJS) versi 2.x ke versi 3.3.0 (LTS), termasuk pedoman troubleshooting untuk masalah upgrade yang sering terjadi. Panduan ini digunakan sebagai panduan pendukung pada dokumentasi How to Upgrade dan How to Upgrade and Troubleshooting. Sebelum melanjutkan, review dokumentasi ini untuk mempelajari tentang alur kerja upgrade OJS dan cara bekerja dengan instalasi OJS Anda.

Syarat Utama: Pencadangan Data (Backup) dan Perangkat Pendukung

Sebagai persiapan untuk alur kerja di bawah ini, Anda harus menyelesaikan keseluruhan proses backup dari instalasi OJS yang telah Anda gunakan di production. Selain backup awal ini, Anda perlu melakukan backup secara menyeluruh dari bagian OJS yang sudah dilakukan instalasi, jika sudah selesai upgrade mohon dapat melakukan backup juga secara bertahap.

Kegunaan dari backup pada kasus ini akan memungkinkan Anda dapat mengembalikan instalasi ke versi sebelumnya jika diperlukan (restore), membuat penyesuaian yang diperlukan pada instalasi Anda untuk memperbaiki error upgrade, dan kemudian dapat melakukan upgrade kembali. Dokumentasi How to Upgrade mencakup instruksi detail untuk backup instalasi OJS Anda. Jika Anda perlu memulihkan instalasi Anda ke versi pra-upgrade, file config OJS, database, serta folder files yang berisi berbagai file seperti draft artikel, artikel yang diterbitkan dan lain-lain perlu dikembalikan dari hasil yang sudah di-backup.

💡

Penting: Harus selalu ada backup versi production OJS Anda sebelum mencoba upgrade ke versi yang baru.

Jika upgrade gagal dengan pesan error, atau notifikasi lain sehingga upgrade tidak selesai dengan sepenuhnya, Anda harus mengembalikan instalasi OJS ke versi pra-upgrade menggunakan backup Anda. Setelah Anda mengembalikan instalasi ke versi pra-upgrade, Anda perlu mengatasi error upgrade, lalu mencoba upgrade kembali. Proses ini mungkin perlu diulang beberapa kali (trial error) hingga upgrade berhasil diselesaikan. Upgrade akan berhasil jika Anda melihat pesan berikut: Successfully upgraded to version X.X.X.X

💡

Penting: Jangan lanjutkan ke proses upgrade versi berikutnya jika langkah upgrade saat ini belum berhasil diselesaikan. Hal ini akan menyebabkan hilangnya data dan mengakibatkan error pada upgrade berikutnya.

Disarankan agar setiap langkah upgrade yang didokumentasikan di bawah ini dijalankan langsung pada server melalui command-line, bukan melalui web browser. Ini akan memungkinkan Anda untuk mengontrol dan memantau pelaksanaan kode skrip upgrade OJS. Untuk memastikan bahwa proses upgrade memiliki memori yang memadai dan tidak habis waktu (run time error), pengaturan PHP CLI berikut disarankan saat menjalankan kode skrip upgrade OJS:

php -d memory_limit=-1 tools/upgrade.php upgrade

Syarat Utama: Database OJS

Pengkodean Karakter dan Pengaturan Collation

Sebelum memulai, periksa database OJS Anda dan catat penggunaan karakter MySQL dan pengaturan Collation Anda:

SHOW VARIABLES LIKE 'char%';
SHOW VARIABLES LIKE 'collation%';

Hasil kueri pertama akan mengkonfirmasi apakah Anda menggunakan kumpulan karakter latin1 , utf8 atau utf8mb4 di MySQL. Hasil kueri kedua akan memberi informasi tentang pengaturan collation MySQL Anda. Koneksi MySQL dan pengaturan collation harus konsisten dengan kumpulan karakter database OJS Anda.

Misalnya, jika database OJS menggunakan kumpulan karakter latin1, maka Anda juga harus menggunakan collation yang kompatibel, misalnya latin1_general_ci atau latin1_swedish_ci. Alternatif lain, jika database OJS Anda menggunakan pengkodean karakter utf8 yang lama, susunannya harus utf8_general_ci atau utf8_unicode_ci. Dan jika database OJS menggunakan kumpulan karakter utf8mb4 yang lebih baru maka Anda harus menggunakan salah satu kumpulan karakter yang didukung untuk kumpulan karakter ini, misalnya. utf8mb4_general_ci atau utf8mb4_0900_ai_ci.

Hapus Tabel Indeks Pencarian

Tabel indeks pencarian OJS berisi banyak data dan data ini harus dihapus dari database OJS Anda sebelum memulai proses upgrade OJS 2.x. Hal ini akan mengurangi ukuran database OJS secara signifikan, mengurangi waktu untuk menjalankan langkah-langkah upgrade dan membuat backup instalasi OJS Anda. Setelah langkah terakhir upgrade ke OJS 3.3.0 selesai, indeks pencarian akan bekerja kembali, yang akan mengisi kembali tabel indeks pencarian pada database OJS Anda (tidak ada data yang akan hilang).

Untuk menghapus data indeks pencarian dari database OJS Anda, Anda perlu terhubung ke database OJS dan menjalankan perintah kueri MySQL berikut:

TRUNCATE submission_search_objects;
TRUNCATE submission_search_object_keywords;
TRUNCATE submission_search_keyword_list;

Tentukan Mesin MySQL

OJS 3.3.0 tidak dapat digunakan dengan mesin MySQL MyISAM dan memerlukan tabel database InnoDB. Untuk memeriksa apakah Anda perlu meng-konversi tabel MyISAM yang ada ke InnoDB, sambungkan ke database OJS Anda dan jalankan kueri berikut, ganti OJS_DBNAME dengan nama database OJS Anda:

SELECT DISTINCT Engine, COUNT(0) FROM information_schema.tables WHERE table_schema = 'OJS_DBNAME'

Jika kolom Engine dalam hasil kueri menyertakan MyISAM maka Anda perlu meng-konversi tabel database MyISAM ke InnoDB menggunakan alur kerja yang dijelaskan di bagian "Convert MyISAM to InnoDB Tables" di bawah. Sebaliknya, jika kolom Engine pada hasil kueri hanya menyertakan mesin InnoDB maka tidak diperlukan konversi tabel dan Anda dapat langsung melanjutkan ke bagian "Grant REFERENCES Privilege".

Konversi Tabel MyISAM ke InnoDB

Alur kerja ini hanya perlu diselesaikan jika Anda telah meng-konfirmasi bahwa Anda memiliki satu atau lebih tabel MyISAM pada database OJS Anda. Untuk meng-konversi database OJS 2.x Anda dari tabel MyISAM ke tabel InnoDB, Anda perlu menyelesaikan langkah-langkah berikut:

1. Export database OJS ke dalam file teks, mis. melalui mysqldump

2. Buka file teks dump database menggunakan text editor yang kompatibel dengan UTF8, misalnya vi, nano atau vi.

3. Ganti semua MyISAM dengan definisi tabel InnoDB pada dump database

4. Simpan text file dump database yang terbaru

5. Impor dump database yang terbaru ke database OJS yang baru

Alur kerja berikut menjelaskan setiap langkah di atas secara lebih detail.

Pertama, Anda perlu membuat dump database untuk database OJS dan menyimpannya ke text file, misalnya ojs_database.sql

Sekarang Anda dapat meng-konversi semua definisi tabel dalam file dump database menggunakan text editor. Misalnya, pada text editor vi Anda dapat membuka dump database MySQL dan menjalankan perintah search-and-replace berikut. Tujuannya adalah untuk mengganti setiap definisi tabel MyISAM dengan mesin InnoDB untuk semua tabel database MyISAM. Anda akan diminta untuk me-review dan meng-konfirmasi setiap penggantian untuk setiap definisi tabel.

:%s/ENGINE=MyISAM/ENGINE=InnoDB/gc

💡

Jangan lupa untuk menyimpan file dump database yang telah diperbarui.

Langkah selanjutnya adalah menghapus database OJS Anda di MySQL karena masih berisi table definition MyISAM yang lama. Kita kemudian akan membuat database OJS baru untuk menerima tabel definition InnoDB yang diperbarui dan melakukan import file dump database yang dikonversi ke database OJS yang baru.

Untuk menghapus database OJS yang ada dan membuat database OJS baru yang kosong, perintah MySQL berikut perlu dijalankan menggunakan akun pengguna MySQL dengan hak Istimewa (privilege) DROP dan CREATE, misalnya. baik pengguna OJS MySQL atau pengguna root MySQL.

💡

Penting: Pastikan Anda memiliki backup database OJS Anda sebelum menjalankan perintah MySQL di bawah ini.

Anda perlu mengganti nama database OJS_DBNAME dan character set OJS_DBCHARSET dengan yang sebenarnya, contoh kueri yang digunakan:

DROP DATABASE OJS_DBNAME;
CREATE DATABASE OJS_DBNAME DEFAULT CHARSET 'OJS_DBCHARSET';

Sekarang Anda memiliki database OJS baru yang kosong, Anda dapat meng-import data pada database OJS menggunakan file dump database MySQL yang diperbarui termasuk table definitions InnoDB yang baru.

Untuk perintah impor MySQL di bawah ini, Anda perlu mengganti pengaturan koneksi database OJS_DBNAME dan OJS_DBUSER, pengaturan character set OJS_DBCHARSET, dan nama file dump database OJS_DBDUMPFILE dengan nilai sebenarnya:

mysql OJS_DBNAME -u OJS_DBUSER -p --default-character-set=OJS_DBCHARSET < OJS_DBDUMPFILE

Anda akan diminta password database untuk pengguna OJS MySQL seperti yang ditentukan dalam file OJS config.inc.php pada line database Anda. Hal ini tergantung pada ukuran database OJS Anda, perintah import mungkin memerlukan waktu yang lama untuk selesai, misalnya. hingga 1 jam atau lebih untuk database yang sangat besar.

Berikan REFERENCE Hak Istimewa (Privilege)

Pengguna database OJS akan memerlukan hak Istimewa (privilege) REFERENCES yang diberikan melalui MySQL sebagai persiapan untuk upgrade ke OJS 3.3.0.

Perintah MySQL di bawah ini perlu dijalankan dengan menggunakan akun pengguna MySQL dengan hak Istimewa (privilege) GRANT, misalnya. akun pengguna root MySQL. Anda perlu mengganti OJS_DBNAME, OJS_DBUSER, dan OJS_DBPASSWD dengan nilai untuk database OJS Anda seperti yang ditentukan di config.inc.php:

GRANT REFERENCES ON OJS_DBNAME.* TO OJS_DBUSER@'localhost' IDENTIFIED BY 'OJS_DBPASSWD';

Tahapan Persiapan

Sebelum melanjutkan ke langkah upgrade yang pertama, hal-hal berikut harus diselesaikan terlebih dahulu:

• Backup segala komponen yang menjalankan OJS 2 antara lain web root OJS 2.x contoh folder files, folder public_html (public), dan database OJS MySQL

• Tentukan kumpulan karakter database OJS MySQL dan pengaturan susunannya

• Hapus data indeks pencarian dari database OJS MySQL

• Pastikan semua tabel menggunakan mesin InnoDB pada database OJS MySQL

• Berikan hak Istimewa (privilege) pada REFERENCE kepada pengguna database OJS MySQL

Langkah Pertama: Masuk ke OJS 2.4.8-5

Jika instalasi Anda menjalankan versi yang lebih lama dari OJS 2.4.6 maka Anda harus melakukan upgrade terlebih dahulu ke OJS 2.4.6. Versi yang lebih lama dari OJS tersebut tidak memiliki kolom wajib pada tabel sessions dan upgrade ke OJS 2.4.6 akan menambahkan kolom yang belum tersedia ini.

Jika instalasi Anda menjalankan OJS 2.4.6 atau versi yang lebih baru, Anda perlu melakukan upgrade ke OJS 2.4.8-5. Upgrade ini perlu dijalankan menggunakan versi lama PHP 7.x (PHP 8.x tidak akan berfungsi)

Skenario 1 versi yang direkomendasikan: OJS 3.2.1-5

Setelah instalasi Anda menjalankan OJS 2.4.8-5, Anda siap untuk beralih ke OJS 3.2.1-5.

Jika jurnal Anda menerbitkan gambar sampul artikel, pastikan Anda menerapkan patch ini pada instalasi OJS 3.2.1-5 Anda, jika Anda menerapkannya melalui the release tarball. Patch ini ditambahkan setelah OJS 3.2.1-5 dirilis dan memberikan perbaikan untuk bug upgrade OJS 2.x di dalam issue berkaitan dengan gambar sampul artikel.

Sebelum Anda memulai upgrade ke OJS 3.2.1-5, Anda perlu me-review file tambahan OJS 2.4.8-5 Anda.

File Tambahan: Submission Files atau Public Galleys?

Pastikan Kembali isi dari folder files, apakah terdapat file tambahan yang berisi file submission atau public galleys?

Dalam persiapan untuk upgrade OJS 3.2.1-5, Anda perlu memutuskan bagaimana file tambahan (supplement files) harus dimigrasi dari OJS 2.4.8-5. Secara default, upgrade OJS 3.2.1-5 akan mengubah semua file tambahan menjadi artikel galleys yang dapat diakses oleh pembaca melalui landing page artikel.

Hal ini tergantung bagaimana editor dan penulis menggunakan file tambahan di OJS 2.x, konversi ke artikel galleys ini mungkin tidak sesuai atau cocok untuk jurnal Anda. Misalnya, beberapa jurnal yang menjalankan OJS 2.x menggunakan file tambahan untuk menyimpan Letter of Agreement (LOA), copyright transfer form, dan lain-lain — dokumen-dokumen ini dianggap pribadi dan tidak diberikan untuk akses publik. Pada OJS 2.x, jika jurnal me-nonaktifkan fitur Reading Tools, maka link ke file tambahan akan dikeluarkan dari landing page artikel.

Jika Anda ingin me-nonaktifkan konversi file tambahan ke public galleys selama proses upgrade ke OJS 3.2.1-5, dan sebagai gantinya meng-konversi file tambahan menjadi file private submission di OJS 3.2.1-5, maka Anda perlu apply a patch pada instalasi OJS tersebut sebelum memulai upgrade dari OJS 2.4.8-5.

Setelah upgrade ke OJS 3.2.1-5 selesai, harap review contoh artikel yang termasuk file tambahan untuk memastikan bahwa file ini telah dimigrasi dengan benar dari OJS 2.4.8-5, untuk memastikan bahwa file tambahan bersifat publik terlihat sebagai artikel galleys atau dibatasi dari akses publik dan disimpan sebagai file private submission pada OJS 3.2.1-5.

Langkah Terakhir: OJS 3.3.0

Setelah Anda berhasil melakukan upgrade ke OJS 3.2.1-5 maka Anda dapat melakukan upgrade ke OJS 3.3.0 terbaru yang sudah termasuk long-term support dari PKP.

Secara umum, upgrade dari OJS 3.2.1 ke OJS 3.3.0 akan selesai lebih cepat karena tidak ada update pada folder private files OJS dimana file submission dan file galley disimpan.

Pembangunan Ulang Indeks Pencarian

Karena kita sudah menghapus data indeks pencarian OJS sebelum memulai alur kerja upgrade, sekarang kita perlu menjalankan kembali indeks pencarian melalui perintah PHP berikut, yang dijalankan di folder OJS sebagai peran root access:

php tools/rebuildSearchIndex.php

Mengatasi Masalah Umum

Error Versi Plugin

• Masalah: Langkah terakhir dalam upgrade, addPluginVersions, akan gagal jika ada plugin pada folder plugin OJS yang tidak sinkron dengan versi plugin di database. Jika versi plugin di folder plugins lebih lama dari versi plugin yang tercatat di database, kode skrip upgrade OJS akan menyampaikan notifikasi error "Cannot Downgrade Plugin".

• Solusi: Karena update versi plugin adalah langkah terakhir dalam proses kode skrip upgrade OJS, error di atas menunjukkan bahwa proses upgrade OJS telah selesai dengan pengecualian pada pemeriksaan versi plugin yang terbaru. Pada tahap ini Anda dapat melanjutkan dengan salah satu dari dua cara berikut:
  1. Perbarui tabel versions OJS secara manual dan sisipkan baris baru untuk versi OJS 3.3.0, pastikan Anda menandai versi OJS ini sebagai versi saat ini. Langkah Ini akan menyelesaikan upgrade ke OJS 3.3.0 secara manual.
     
     Anda dapat melakukan hal ini dengan menjalankan dua kueri MySQL berikut:
     

     UPDATE versions SET current = '0' WHERE product = ‘ojs2’;

     Pada kueri MySQL di bawah ini, harap sesuaikan keempat parameter versi OJS agar sesuai dengan versi sebenarnya yang Anda upgrade. Kueri di bawah ini diasumsikan sebagai OJS 3.3.0-17.

     INSERT INTO versions VALUES ('3', '3', '0', '17', now(), '1', 'core', 'ojs2', '', '0', '1');

     Setelah tabel versions di-update secara manual, Anda dapat menghapus plugin tertentu yang menyebabkan error dari folder plugin OJS dan kemudian meng-instal ulang plugin secara manual sebagai Journal Manager melalui Plugin Gallery OJS. Selain itu, semua plugin lain yang ditandai sebagai tersedia untuk di-upgrade pada Plugin Gallery, harus di-upgrade melalui Plugin Gallery ke versi plugin terbaru yang kompatibel dengan OJS 3.3.0.

  2. Alternatif lain, Anda dapat menghapus plugin khusus yang menyebabkan error dari folder OJS plugins, mengembalikan instalasi Anda ke OJS 3.2.1 (restore) dengan menggunakan backup pre-upgrade, dan lakukan kembali upgrade 3.3.0. Tergantung pada bagaimana plugins menyebabkan error pada proses upgrade, Anda mungkin harus mengulangi tahap ini beberapa kali. Setelah upgrade ke OJS 3.3.0 berhasil diselesaikan, Anda perlu meng-instal secara manual semua plugin yang dihapus dari folder plugin OJS sebagai Journal Manager melalui Plugin Gallery OJS. Selain itu, semua plugin lain yang ditandai sebagai plugin yang tersedia untuk di-upgrade di Plugin Gallery harus di-upgrade ke versi terbaru yang kompatibel dengan OJS 3.3.0.

Notifikasi Null Review Round ID

• Masalah: Upgrade dari OJS 3.2.1 ke OJS 3.3.0 gagal karena null review_round_ids pada tabel review_assignments.

• Solusi: Pertama, kembalikan instalasi Anda ke OJS 3.2.1 dengan menggunakan backup pra-upgrade (restore) Anda. Setelah database di-restore, jalankan kueri UPDATE berikut di MySQL untuk mengatur review_round_id secara manual pada tabel review_assignments:

  UPDATE review_assignments, review_rounds SET review_assignments.review_round_id = review_rounds.review_round_id WHERE review_assignments.submission_id = review_rounds.submission_id AND review_assignments.round = review_rounds.round;

  Dengan mengikuti UPDATE di atas, Anda dapat memeriksa apakah masih ada kolom null review_round_id yang tersisa melalui kueri SELECT berikut:

  SELECT * FROM review_assignments WHERE review_round_id IS NULL;

  Jika kueri di atas mengembalikan satu baris atau lebih maka Anda perlu memeriksa setiap baris secara manual dan menentukan apakah baris tersebut sesuai dengan submission yang valid pada instalasi OJS Anda. Jika tidak, maka baris null dapat dihapus dari tabel review_assignments.

TinyMCE

• Masalah: Kadang-kadang plugin TinyMCE tidak dapat di-instal atau diaktifkan setelah upgrade. Hal ini menyebabkan notifikasi error "API Key Missing" saat melihat dashboard OJS 3.x, serta formulir input dan setting tidak dapat digunakan.

• Solusi: Pada ​​OJS 3.x, sebagai Journal Manager, aktifkan plugin TinyMCE melalui Settings > Website > Plugin.

Pengaturan Bahasa

• Masalah: Terkadang jurnal tidak dapat meng-upgrade/memindahkan pengaturan bahasa yang di-instalnya (pengaturan UI, bahasa submission, pengaturan bahasa metadata). Pada OJS 3.x, hal ini dapat dilihat jika Anda membuka dashboard sebagai Journal Manager atau Editor — banyak tab yang tidak memiliki formulir input dan setting.

• Solusi: Pada ​​OJS 3.x, sebagai Journal Manager, aktifkan beberapa bahasa jurnal yang biasa dipakai misalnya English dan Indonesia melalui Settings > Journal > Language.

Masalah Pengkodean Karakter Database

• Masalah: Database OJS menyertakan campuran tabel Latin1 dan UTF8 atau tabel Latin1 dengan data UTF8 yang mengakibatkan error pada tampilan dengan karakter beraksen pada homepage jurnal, halaman artikel, atau pada hasil pencarian.

• Solusi: Anda perlu me-review database OJS Anda untuk mengidentifikasi sumber error dan memperbaiki database Anda untuk memastikan bahwa Anda memiliki konsistensi pada seluruh pengkodean karakter, collation, dan data yang disimpan. Review bagian Panduan Character Encoding section pada PKP Docs troubleshooting.

Error Foreign Key MySQL

• Masalah: Kueri MySQL gagal dengan error foreign key.

• Solusi: OJS 3.3.0 memerlukan tabel database InnoDB. Jika database MySQL Anda menggunakan tabel MyISAM, Anda perlu meng-konversi tabel tersebut ke InnoDB sebelum menjalankan upgrade ke OJS 3.3.0. Silakan lihat bagian "Convert MyISAM ke InnoDB Tables" untuk informasi tambahan.

Error Hak Istimewa (privilege) MySQL

• Masalah: Kueri MySQL gagal dengan error izin referensi (reference permission).

• Solusi: Akun pengguna database OJS memerlukan hak Istimewa (privilege) REFERENCES yang diberikan sebagai persiapan untuk upgrade dari 3.2.1 ke 3.3.0. Silakan lihat bagian "Grant REFERENCES Privilege" untuk informasi tambahan.

Sumber Informasi tambahan

Jika Anda menemukan permasalahan yang tidak tercakup dalam panduan ini, Anda dapat mencari jawaban dan mendapatkan saran untuk menyelesaikan masalah Anda melalui PKP Forum yang disampaikan oleh komunitas pengguna OJS global dan staf PKP. Jika Anda tidak mendapatkan hasil pencarian yang Anda inginkan, kirimkan pertanyaan dan laporkan permasalahan Anda ke forum tersebut.