QOD v3.0 Client Aps

QOD v3.0 is the first BME application to have functions which allow you to write your own clients (so instead of using a web browser, you could for example write a client for your Blackberry, Windows CE machine, or just a Windows desktop application). They're very simple to use, and if people decide they like it, I'll implement similar features on all parts of BME.

NOTE: There are not currently any clients written and available for download. As soon as there are, I'll post them here (so TELL ME if you write one).

In writing a client for QOD v3.0, you have access to four basic commands, all accessed over a standard port 80 http connection. The result is handed back over a standard http connection as well (so you can always issue test commands via a browser to see what you should expect, although because no html tags are included there won't be line wrapping):

http://cgi.bmezine.com/qod3.exe?search=/totalqa

This will return the number of current question/answer strings in the database. It returns it as a single number inside quotes. For example right now it would return "5881". New questions are always added at the end of the database, so by comparing this number with your local database, you know what you need to retrieve.

http://cgi.bmezine.com/qod3.exe?search=/totalstaff

This will return the total number of current staff members. Please note that retired staff members and even outright deleted staff members are included in this list. New staffers are always added at the end of the database, so by comparing this number with your local database, you know what you need to retrieve.

http://cgi.bmezine.com/qod3.exe?search=/retrieveqa&start=1&finish=5

This retreives Q&A entries from the QOD database in the range specified. The higher the number, the more recent the question was added. The Q&A database is generally static (ie. once something is added, it stays the same forever), so you should only ever need to download recent additions. The answers are returned in the following comma-separated, quote-enclosed, one-record-per-line format:

"question#", "asker", "question", "answer", "staffer", "prev", "next"

I'll quickly address what each of these is:

  1. "question#" - This is literally just the question number. Obviously you can infer it from your query, but I've included it to make things simple.
  2. "asker" - This is the name of the person asking the question. If it starts with "iam:" then you can assume that it was asked by the IAM member of that name. This field is URL encoded, so you'll need to decode it.
  3. "question" - This is the text of the question. It may contain HTML, so if you're displaying in a non-HTML you'll need to parse it. In addition, this field is URL encoded, so you'll need to decode it as well.
  4. "answer" - This is the text of the answer. It may contain HTML, so if you're displaying in a non-HTML you'll need to parse it. In addition, this field is URL encoded, so you'll need to decode it as well.
  5. "staffer" - This is the ID of the staff member that answered this question. Please note that it is their numeric ID, not their name.
  6. "prev" - If this question is a follow-up to a previous question, this is that question's record number. Remember, when you see a "prev" record come through on a new question, you should update the "next" field in the record that it's pointing at as well.
  7. "next" - If this question has been followed-up by another question, this is that question's record number. That said, if you're downloading new questions, you'll rarely see this having any value other than "0".
Finally, please note that although the software does allow you to download thousands of records at a time, it might make more sense to download smaller pieces.

http://cgi.bmezine.com/qod3.exe?search=/retrievestaff&start=1&finish=5

This command downloads details of the staff members specified. Please note that the staff details change periodically as descriptions are edited and so on. I recommend that every time the software downloads questions that it downloads any new staff members, but that one a weekly basis it downloads the entire staff list to make sure everything is up to date. The answers are returned in the following comma-separated, quote-enclosed, one-record-per-line format:

"staff#", "name", "iam", "status", "picture", "description"

I'll quickly address what each of these is:

  1. "staff#" - This is the person's staff ID#. This is the staff number that is used to point at them in the Q&A database.
  2. "name" - This is the staffer's name. This field is URL encoded, so you'll need to decode it.
  3. "iam" - This is the staffer's IAM page (if they have one). This field is URL encoded, so you'll need to decode it.
  4. "status" - This field returns either "active" or "retired", depending on their status.
  5. "pic" - This returns either "nopic" if no image has been uploaded for this staff member, or returns the URL of a 100x100 JPG image of them if they have one.
  6. "description" - This returns the staffer's description, as they've entered it. It may be blank for some people, and it may contain HTML for others (so be prepared to parse it). This field is URL encoded, so you'll need to decode it as well.
Well, that's all there is to it. Pretty easy! If you want your tool to be able to submit questions and things like that as well, just look at the source for the ask forms and you'll see exactly what you have to submit.

Good luck!

Shannon
devteam@bmezine.com