SMS handler setup/id

Ikhtisar

Sebuah SMS handler adalah sebuah fungsi yang mengendalikan proses menerima dan menguraikan data dari sebuah SMS masuk, memeriksa data, memasukkannya ke dalam tabel dan memberikan respon apapun yang diperlukan oleh pesan tersebut. Pembuatan fungsi SMS handler terotomatisasi dan dapat dicapai dengan menyediakan metadata melalui interface laman. Proses ini meliputi:

• Mengatur informasi pesan umum (format, perizinan, tujuan, tabel data, pesan eror dll)
• Mengatur detil untuk masing-masing bidang
• Mengisi tabel referensi
• Membuat tabel data
• Membuat serangkaian pesan untuk pesan keluar

Langkah-langkah ini dijelaskan secara terperinci di bawah ini.

Atribut-atribut Pesan

Interface untuk menyunting atribut-atribut pesan tersedia melalui Admin | Membuat SMS Handler | Sunting pilihan menu Pesan SMS. Bidang-bidangnya adalah:

Kode mulai

Setiap pesan memiliki satu kode mulai. Ini hanya berisi huruf saja (tidak ada angka, simbol, spasi atau tanda baca), dan harus ditulis dengan huruf besar. Setidaknya ada satu huruf, namun bisa lebih panjang. Lebih singkat lebih baik, walaupun tetap memungkinkan untuk mudah dimengerti dan unik. Normalnya adalah dua atau tiga huruf.

Nama

Nama untuk pesan tersebut adalah sebuah nama pendek yang mendeskripsikan tujuan dari pesan itu atau tipe data yang sedang dikumpulkan. Hendaknya ditulis dalam bahasa Indonesia dan bahasa Inggris.

Perizinan

Ini mengontrol siapa yang diizinkan untuk mengirimkan tipe pesan ini. Daftar drop down menunjukan seluruh perizinan grup yang terdefinisikan, biasanya dinamai dalam format 'dapat_melakukansesuatu'. Jika ada perizinan yang sesuai dengan tipe laporan ini, yang bisa digunakan, tetapi biasanya akan diminta untuk mendefinisikan perizinan baru. Setelah terdefinisi, dan diasosiasikan dengan pesan SMS, grup pengguna yang berbeda dapat memberikan izin ini atau tidak, tergantung pada tanggung jawab mereka.

Mendefinisikan perizinan baru

Pada menu, kunjungi Admin | Perizinan | Sunting Perizinan.

Name

Enter a new name for the permission in the form 'can_xxx'. For a permission for a particular SMS message, the normal name for the permission is 'can_send_message_type'. For example, for an OB message, the corresponding permission would be 'can_send_ob'.

Enable by default

This sets all groups to have this permission by default. Normally this should be set to 'no' so that groups have to be explicitly give this permission, unless it is sure that almost all users should be able to use this permission.

User permission

Set this to 'no' as we are creating a group permission.

Simpan izin dan kemudian kembali ke Edit Pesan SMS, pilih izin yang telah Anda buat.

Tujuan dan Teks Bantuan

Tujuan dan teks bantuan saat ini tidak digunakan tetapi akan digunakan dalam dokumentasi dan antarmuka di masa depan.

Nama Tabel

Nama tabel adalah nama dari tabel pangkalan data yang sudah ada di mana data yang diterima akan dimasukkan. Ketik nama tabel.

Pesan kesalahan

Pesan kesalahan adalah kunci untuk string yang akan digunakan sebagai pesan kesalahan jika format umum pesan tidak benar. Biasanya itu adalah dalam bentuk message_type_ kesalahan. Misalnya, untuk pesan OB, namanya adalah OB_error.

Balas SQL

Balas SQL adalah SQL 'pilih' permintaan yang mengontrol apa pesan yang dikembalikan ke pengirim. Ini harus selalu ditentukan.

SQL akan mengirimkan pesan balasan ke pengirim. Pilih sesuatu yang sangat sederhana, seperti: 'Terima kasih. Pesan Anda telah diterima'

Namun, semua pesan balasan harus mengkonfirmasi isi pesan yang disampaikan, dikonversikan dari versi kode ke dalam teks yang jelas. Oleh karena itu balasan SQL biasanya lebih kompleks, dan query data yang baru dimasukkan (dipilah oleh id pesan), bergabung ke tabel rujukan, dan menyusun hasilnya. Hal ini juga biasanya menggunakan string bahasa khusus dari tabel terjemahan untuk menyajikan pesan dalam bentuk yang benar.

Variabel yang telah ditentukan dan dapat dimasukkan dalam SQL (hampir selalu digunakan) adalah:

• sms_userid: user ID dari orang yang mengirim pesan. Ini digunakan untuk mendapatkan bahasa yang tepat.
• sms_msgid: ID pesan untuk pesan saat ini. Ini digunakan untuk mendapatkan data yang dikirimkan.

Fungsi bantuan yang dapat dimasukkan dalam balasan SQL meliputi:

• get_string (varchar kunci, userid integer): mengembalikan string yang telah ditentukan (diindeks dengan kunci) dalam bahasa pilihan pengguna
• get_user_lang (userid integer): mengembalikan kode bahasa bagi pengguna. Hal ini berguna jika langsung mengakses data dari field array yang diterjemahkan.
• add_checkdigit (kode integer): ketika mengembalikan kode numerik (kasus ID, Program ID, dll), check digit digunakan untuk memastikan bahwa tidak ada kesalahan ketik. Fungsi ini menambahkan check digit ke kode baku. Semua kode ID harus memiliki check digit yang telah ditambahkan, seolah-olah mereka digunakan dalam pesan tanpa check digit, hal ini akan diartikan sebagai kesalahan oleh sistem.
• format (format_string varchar, input_string varchar, ...): Ini adalah fungsi PostgreSQL standar untuk memformat string dengan daftar variabel yang diganti. String harus berisi satu atau lebih pemegang tempat % s, yang diganti dengan nilai variabel tertentu.
• string_agg (string varchar, pemisah varchar): fungsi lain SQL standar yang mengumpulkan string dari beberapa baris (ketika menggunakan 'kelompok dengan' klausa) menjadi nilai tunggal bersambung, dengan setiap baris string yang dipisahkan oleh separator. Hal ini berguna ketika pesan mungkin memasukkan data ke dalam beberapa baris, dan balasan perlu meringkas data dari baris tersebut.

Contoh balasan SQL untuk pesan OB:

pilih format (get_string ('OB_reply', sms_userid), dinfo, s.species [1], l.name)
dari (
pilih t.caseid, string_agg (format ('%s (%s %s)', d.name, dosis, unit),',') sebagai dinfo
dari pengobatan t
gabung obat d pada d.id = obat
di mana t.msgid = kelompok sms_msgid dengan t.caseid) sebagai dd
kiri gabung cadre_reports c pada c.id = dd.caseid
kiri gabung lokasi l pada l.id = c.locationid
kiri gabung spesies s pada s.id = c . speciesid

Pesan peringatan SQL

Pesan peringatan SQL digunakan untuk mengirim pesan SMS langsung ke pengguna lain dari pengirim asli, mengingatkan mereka tentang isi SQL asli atau informasi lainnya. Jika tidak ada pesan peringatan yang diperlukan, field ini harus dibiarkan kosong.

Bagian ini adalah pernyataan 'pilih' mengembalikan satu atau lebih rekaman dengan dua field: nomor telepon (varchar, dari field users.phone), dan isi pesan (varchar).

Variabel dan fungsi sama yang dijelaskan di atas tersedia untuk digunakan dalam pesan ini. Contoh Alert SQL untuk pesan Q adalah:

pilih u2.phone,
  format (get_string ('Q_alert', 2), u.firstname||coalesce (||u.surname,),
  local_phone (u.phone), to_char (report_date,'HH:MM:SS'), pertanyaan)
dari pertanyaan q
gabung pengguna u pada u.id = q.userid
gabung pengguna u2 pada (bukan u2.del) dan (u2.phone bukan nol) dan (u2.groupid <2)
gabung lokasi l pada l.id = u2.location
gabung lokasi l2 pada l2.id = u.location
di mana q.msgid = sms_msgid

Dilindungi

Tandai 'ya' untuk melindungi pesan agar tidak ditimpa dengan pesan lain pada saat proses pembuatan pesan. Fungsi pesan yang telah memiliki modifikasi tertentu kode harus ditandai sebagai dilindungi untuk menghindari agar data tidak ditimpa dengan pesan otomatis.

Bidang atribut

Setelah atribut pesan ditentukan, field untuk pesan perlu ditentukan. Hal ini dilakukan dari menu: Admin|Create SMS Handler|Edit SMS Fields

Pesan

Pilih pesan yang telah ditentukan dalam langkah sebelumnya

Perintah

Ketik integer untuk menentukan urutan field dalam SMS

Nama

Masukkan nama dalam bahasa Inggris dan Indonesia. Ini muncul dalam dokumentasi dan digunakan secara internal. Mungkin berisi spasi. Ini harus menjelaskan secara singkat apa isi field ini.

Jenis data

Jenis data berikut ini didefinisikan:

Kode numerik

Ini adalah nomor yang berisi check digit. Kegunaan utamanya adalah kasus ID, tetapi digunakan dalam sejumlah situasi lain di mana pengguna harus mengirim dan menerima kode numerik.

Kode Cari

Ini adalah alpha (huruf saja) kode (satu atau lebih dari satu huruf), yang digunakan untuk mencari nilai dari tabel rujukan. Ini adalah cara yang paling umum untuk menyebut nilai tabel rujukan.

Integer

Ini adalah integer sederhana, digunakan untuk menghitung data yang dikirimkan (jumlah hewan yang dipotong, divaksinasi, sakit, dll)

Lokasi

Ini adalah kode lokasi, yang dapat digunakan full version (8 digit dalam sistem baru, 10 digit di sistem lama), atau singkat (hanya angka terakhir sesuai wilayah tanggung jawab pengguna)

Boolean

Kode teks huruf tunggal yang dapat menggunakan dua nilai, default ke Y (Ya, yes), dan T (TIDAK, no). SQL dapat digunakan untuk menentukan alternatif lain.

Teks

Teks bebas dengan karakter apapun. Ini biasanya harus menjadi field terakhir dalam pesan karena sulit untuk diurai.

Float

Angka yang mungkin berisi titik desimal, misalnya, dosis obat atau koordinat.

Kode integer

Integer digunakan untuk mencari sebuah nilai dari tabel rujukan. Biasanya ini tidak lazim digunakan (kode alfa biasanya digunakan).

Teks array

Field ini berisi satu atau lebih dari satu kode cari (kode alfa merujuk ke nilai dalam tabel). Nilai-nilai ini diurai dan dimasukkan ke dalam field array tunggal dalam tabel data. Dengan cara ini, beberapa nilai dapat diperlakukan sebagai jenis field tunggal. Misalnya ini digunakan untuk tanda-tanda dan diagnosa banding. Perawatan diperlukan untuk memastikan penguraian yang ambigu (field sebelumnya, atau dikelilingi oleh field numerik).

Opsional

Hal ini menunjukkan jika field tersebut adalah opsional atau bukan.

Urutan Kelompok

Pesan SMS dapat berisi kelompok field yang berulang. Misalnya pesan populasi POP dapat berisi beberapa pasang ([spesies] [jumlah ] ... ). Ketika field tersebut bukan bagian dari kelompok pengulangan, field ini harus memiliki urutan kelompok 0. Jika field adalah bagian dari kelompok, maka setiap elemen kelompok harus diberi nomor berurutan. Hanya satu kelompok berulang yang diizinkan dalam pesan.

Lookup SQL

Bagian ini merupakan penyataan pilihan dengan tujuan yang berbeda tergantung pada jenis field. Bila tidak diperlukan, dapat dibiarkan kosong. Jika digunakan, harus mengandung nilai  % s tunggal yang diganti dengan nilai field. Jenis pesan balasan bervariasi tergantung jenis fieldnya.

Kode Lookup

SQL mengembalikan id dari tabel rujukan dari nilai yang dikirimkan. Dalam hal ini SQL diperlukan. Sebagai contoh:

pilih id dari obat di mana upper(code) = upper(trim(%s))

Integer

SQL adalah opsional. Jika tersedia digunakan untuk memeriksa berbagai hal. Ini harus mengembalikan nilai boolean tunggal. Sebagai contoh:

pilih %s antara 0 dan 1000

Teks array

SQL diperlukan. Ini mengembalikan sebuah array nilai ID untuk kode dalam array input. Persyaratannya agak khusus:

• Dua % s parameter
  • Yang pertama : pilih % s dari
  • Yang kedua : (pilih unnest (regexp_matches(%s,'([a-z]+)', 'igx')) sebagai kode) sebagai dat
• gabung ke tabel utama: kiri luar gabung penyakit s di upper (dat.code) = upper (s.code)
  • tabel harus dengan alias 's'
• lainnya gabung klausa dan filter

Sebagai contoh:

pilih %s dari
 (pilih unnest(regexp_matches(%s,'([a-z]+)', 'igx')) sebagai kode) sebagai dat
kiri luar gabung penyakit s di upper(dat.code) = upper(s.code)
AND NOT del
AND (valid_from IS NULL OR valid_from <= CURRENT_DATE)
AND (valid_to IS NULL OR valid_to >= CURRENT_DATE)

Boolean

SQL adalah opsional. Jika tersedia, ini mengembalikan nilai boolean untuk kode yang dikirimkan. sebagai contoh:

pilih huruf besar(trim(%s)) 
 jika 'K' maka benar
 jika 'Y' maka benar
 jika 'T' maka salah 
 jika 'N' maka salah
lainnya nol akhir

Field name

The field in the database table into which the data received will be inserted.

Error message

A key reference to an string in the translation table that will be used as the error message for this field. The key should contain one replaceable parameter (%s) which is replaced with the (invalid) value submitted.

Reference tables

Reference tables are in the reference schema. Structure varies but most have at least the following fields:

• id: unique record id
• code: an alpha code
• hier_code: a dot separated hierarchical code in the form 1.1.1. This is used to arrange data at different levels of detail, allowing more flexible analysis
• name: varchar[] - a text array field with the name in Indonesian at index 1, and English at index 2
• valid_from and valid_to: dates indicating the period of validity of the item. Valid_to may be null indicating ongoing validity.
• modified_by: user id of the last user to modify the value
• modified_on: timestamp of the last modification
• del: boolean flag for deleted

In addition, there may be classifications referring to other tables (eg species) or flags (eg zoonosis, OIE etc for diseases)

Data tables

Data tables are stored in the 'data' schema. Their structure depends on the data required, but they must have have the following fields which are automatically updated:

• id: unique record id
• userid: integer referencing the user ID of the submitting user (from the 'users' table);
• report_date: timestamp of data submission
• msgid bigint: the unique id of the incoming SMS message
• created_on and modified_on: dates
• created_by and modified_by: user IDs
• del: deleted flag

Message strings

Translated message strings are stored against a key in the translation table, and can be edited using the menu Admin | Message codes and translations | SMS messsage text.

The key or string code is used to access the message. By convention, this code starts with the message start code, followed by an underscore and then an abbreviation of the purpose. For example a message with an error due to an invalid drug code when sending a treatment (OB) message might be OB_invdrug.

The strings are stored in Indonesian and English (and this can be expanded to other languages if required).

Most messages have data inserted into them, so are used with the SQL format() function. For this to work, they need to have place holders for the data to insert, in the form %s. For example:

Laporan tindak lanjut dari %s (ID kasus %s) %s. %s

would have the following data substituted into it: village name, case ID, the numbers of animals and whether the outbreak is resolved or ongoing.

Building the message function

Once the metadata, tables and strings for an SMS handler function have been set up, the function needs to be generated before it can be used. Use the menu Admin | Create SMS handler | Create handler function, and select the function to generate. Once generated, the function will be saved in the SMS schema, and be immediately available for use.

Testing the message function

To test a new function, use the menu Admin | Test SMS Message. This allows a message to be composed and submitted to the system as if it were being sent by SMS. The message is inserted into the inbox, normal processing follows, and any response messages are inserted into the outbox. However no SMS is actually sent (the outgoing messages are displayed on the web interface). Note that any data submitted is inserted into the database so be sure to delete any test data afterwards.

The message is handled as if it were sent from the specified phone number, defaulting to the phone number of the current user. This makes it possible to submit messages on behalf of other users, or to test messages coming from users in different locations and languages.