XML Service Documentation - Introduction and Config part

To understand this reference guide and be able to write or modify a service you should have:

• Used goText midlet at least once
• Basic knowledge of XML (tags, attributes, xml encodings..)
• Some knowledge of HTTP protocol (what is a GET/POST, post data, most common HTTP return codes)

Introduction

XML Service is the new goText Service format created to be run everywhere, not only on server side like old php/perl/.. based scripts.

The XML Service is made up of a number of tags and attributes that guide the Xml Service Engine to make a series of HTTP post/get/head requests to the SMS website to make all actions required to send a SMS message on user's behalf (usually: login, browse to sms page, post sms message, read success/error strings, logout).

As said above the XML Service format is "universal", that is the format has been made to support both sends executed on a remote server (eg: messages sent using the future goText 3 midlet on a mobile phone, like current services used in goText 1.x and 2.x), and send executed locally on user's device.
As a consequence, a couple of tags or attribute may be ignored in a "local" Xml Engine, but must be executed in a server side Xml Engine.

The Xml Service must simply be well formed to be executed (and should obviously only use tags and attributes defined here), that is no validation against the Xml Service Schema is required (even if it is possible when the schema is declared inside the Xml).

This documentation is updated to the latest public xml service format version, that is xsv="1.0.8".

Xml Service overview

The Xml Service is essentially made up of 2 parts:

• Service configuration
• Sending process steps

The first part describes: features from a final user point of view (maximum messages per day, maximum characters per message, maximum recipients per mesage..), configuration data to instruct the client and Xml Engine setup for this specific service.

The second part is made up of a series of Step, that the Xml Engine has to execute to send the message.

Xml Service: Configuration Part

Everything, both the configuration and sending process in enclosed in the starting, outer node, tag: "service".

<service>
..
</service>

<service>: the outermost tag, mandatory. Its attributes value describe the service.
Service tag attributes (in the form "Property name=description of valid values"):

• name=service friendly name (eg: "O2 Ireland")
• xsv=goText "Xml Service Version", the current version is "1.0.2", and this is the only one that should be used. goText++ Desk version >= 0.8.4 is required to execute services with this format version.
  Changes to the xml specifications breaking compatibility will have a new version number.
• version=service version, starting with "1". A change in this version value means to the client that there's a mandatory updated, that is the user has to update service before using it again. Used for major changes in service fields and configuration
• minorversion=service minor version, starting with "1". A change in this version value means that there is a minor update and the user should have the choice to update service or not
• maxchar=maximum number of characters for a whole message
• maxchar_single=optional field, used to tell the client the maximum size of a single message before website or service message splitting kicks in
• maxchar_part=optional field, used to tell the client the maximum size of a single message when website or service message splitting kicks in.
  If maxchar="500" and maxchar_single="140" and the service uses 5 chars to write split part number in message (eg: "(1/4)") then maxchar_part is 140-5, that is maxchar_part="135".
  This attribute has meaning only when split="false", because in case of split="true" maxchar_part is automatically maxchar_single-5 (if max number of parts is less than 10), else maxchar_single-7.
• split="true" to ask goText to split the message if longer than "maxchar_single". "false" or don't write this property if you don't need splitting or if it is performed by sms website.
• split_trunc="true" (default) to ask goText to split the message exactly at "maxchar_single" length, if longer when splitting in parts. "false" splits the message near "maxchar_single" at the first whitespace (to avoid truncation of words, if service limit for single part is not that strict).
  This is rarely used.
• split_autoloop="true" (default) to ask goText to automatically go to next message part when the send of one part is confirmed. "false" still splits the message (with split="true") but split parts are put in variables named "$msgNUM" with NUM in [1..$msg_parts] and it's up to the service writer to loop or send parts all at once (see system variables).
  This is rarely used.
• savesession="true" to tell the service engine and goText to store session information (eg: captcha services), or "false" to no store session. Default (if not given) is "false"
• char_count_more=a list of comma (,) separated characters that are known to occupy more than 1 char with this service. Usually happens with accented or special characters, like "è,à" that may count as 2 characters instead of 1.
• char_count_for=a list of comma (,) separated numbers indicating how much each character in char_count_more counts.
• unsupported_char=a list of comma (,) separated characters that are known to be unsupported by this service (usually delivered with "?" or garbage).
• replacement_char=a list of comma (,) separated characters to replace to unsupported_char.
• multipart="true" to send data in "multipart/form-data" mode, a better way to send UTF-8 (and other multibyte encoded) data.
  This mode may not work with all servers. If it works you are suggested to use it, otherwise use the standard one.
  "false" (default if absent) sends data in the more common "application/x-www-form-urlencoded" mode.
• user_agent=sets the user-agent http header sent by all request generated from <page> and <captcha> tags.
  It can be one of the following values:
  
  • "firefox3.5", "ie6", "ie8", "safari4" that will be translated to the user agent sent by those browser (the Windows version, besides safari that sends the Mac ua string)
  • "wap" to send a random WAP browser user agent string of common mobile phone models of various makers
  • any other bit of text that will be sent as is
  If you don't specify this attribute no user agent header is sent.
• icon=url used to retrieve a favicon of this sms website to display next to the service name in goText. If no such url exist you can embed a handmade icon encoding it as Base64 and writing in this attribute. If attribute is missing the client usually shows a defaul icon.

The first mandatory subnode of service is "description", and it is self closing (no closing tag):

<service>
  <description />
  ..
</service>

<description>: each of description tag is a short user help with information on this service and how to configure (as it is today in config), for a specific language.
Description tag attributes (in the form "Property name=description of valid values"):

• text=service description for user, with some configuration help, like now
• lang=two letter code of the language for this description ("en", "it", "es", "fr", "tr", "id", ..)

Another mandatory subnode of service is "limit", and it is self closing (no closing tag):

<service>
  ..
  <limit />
  ..
</service>

Limit tag attributes describe limits on the number of available messages (in the form "Property name=description of valid values"):

• type=kind of limit for available messages of this service. Can be one of the following values:
  
  • "num", that is limit is based on the number of remaining messages (like current goText)
  • "credit", that is limit is based on some sort of credit system on the website. This service should make use of synchronization of remaining credits to update this value.
  • "money", that is limit is based remaining monetary credit on the website. This service should make use of synchronization of remaining credits to update this value.
• quantity=number of available messages in case of "num" type, or number of starting credit in case of "credit". It doesn't make sense to write quantity for "money", or with "credit" if there's no reset period.
• reset=period that has to pass before credit reset, expressed in days. It can be 1 for one day, 7 for weekly credit reset, 30 for monthly, 0 in case of "never reset credit" (only synchronized when sending messages)
• cost=how much to subtract for a single message sent. It is 1 for "num" type usually, may be different for "credit" or "money".
  It is optional, if not given is ignored in case of "money" and "credit", and defaulted to 1 for "num" type. However you should really write a value for cost at least with "credit" type, so that remaining credits can be shown as number of sms (the same is true for "money", but many websites have different prices for each country, in which case cost can't be specified).
  

Another mandatory inner tag of service, is the <recipients> tag:

<service>
  ..
  <recipients></recipients>
  ..
</service>

<recipients> tag attributes (in the form "Property name=description of valid values"):

• max=maximum number of supported recipients in a single send / for a single message

The <recipients> tag must contain at least a <recipient> tag describing what kind of recipient(s) the service supports:

<service>
  ..
  <recipients>
     <recipient />
  </recipients>
  ..
</service>

<recipient> tag attributes (in the form "Property name=description of valid values"):

• type=a string value from this set:
  
  • "phone": a mobile phone number (with international country code if "require_icc" is specified in service config)
  • "email": email address
  • "id": any other kind of alphanumeric text, almost probably some kind of user id (eg: of a social network, chat network, and so on).
• allowed_ccc=comma separated list of destination international country codes supported in your service (eg: "+45,+39,+1"). This is only supported if type="phone".
  If the attribute is not specified all valid country codes are supported.
  If the service supports only one country code the user will be able to omit to write the country code, the xml engine will add it to the number automatically.
  If there many (or all) country codes are supported the user must write the country code to be able to send the message.

Then there are serveral other mandatory subnodes of service, the "field" tags:

<service>
  ..
  <field></field>
  ..
</service>

<field>: each of field tags describes one configuration field for the service (username, password, other..).
Field tag attributes (in the form "Property name=description of valid values"):

• required=if the configuration field is required, possible values are only "true" for yes and "false" for no
• name=field name as expected by the service (it will be sent via POST with this name, so no spaces only ascii chars). Can be one of the default names (user, pass, nick) or something else if you need.
• description=user friendly description shown on goText config screen
• type=the data type of the field. can be "txt" (alphanumeric text), "numeric" (any number), "phone" (mobile phone number), "ccphone" (mobile phone number with check on mandatory international country code), "email" (email address), "choice" (a set of values to choose from, see below for explanation)

In the next page we will see how to write information on the Send process.

	Language Forum User User: Pass: goText 2.3! Send SMS, MMS and email for free to WORLDWIDE mobile numbers! (paying only GPRS traffic) MIDP 1.0 application Translated in 6 languages GPL v2 license: You can get Involved! Get It Now! Help Us! More