goText Xml Service Format (v1.0.9) Documentation

Index:

Preamble

Version

Introduction

Audience

Xml Service Format

Xml Encoding Declaration

<service>: the top level (outermost) tag

Message split enabled (on goText side) and maximum message length

Message split disabled (on goText side) and maximum message length

Configuration and description

<recipients>: supported recipients

<limit/>: available messages

<field>: configuration fields

<languages>: service-specific localized message

Send steps

<page>: a step used to send an HTTP Request

<post>: a (form) post field / post data

<header>: defines a custom HTTP request header

<captcha>: a step used to retrieve a captcha image file

Session persistence and Xml Engine state persistence

<save>: saves a variable in the goText-session

<dummy>: a step used to assign or calculate variables

<fork>: a step used to make conditional jumps to other steps

<condition>: expresses the fork condition and outcomes

Addon: Additional Features

How to return data in addons with System Variables

System variables available in addons

<usesend>: a special tag that allows to “import” a <send> step inside the <addon>

Variables in Xml Services

System Variables

<var> tag: developer defined variables

Assigned Variables

Search in Variables

Exact Match Search

Text between other strings

Regular expression search

Full HTTP header extraction

Calculated Variables

Basic Mathematical Operations

Random Mathematical Operation

String extraction between other strings

String search

Regex search

String replace

Regex replace

Substring: extract part of a string

Join two strings

Length: calculate the length of a string

Base64 encoding

Html entities decode

Appendix A: Format Version Changelog

Changes from v1.0.8 to v1.0.9

Previous Changes

Appendix B: The Author


Preamble

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

Version

The Xml Service Format changes from times to times.

Everything written in this document applies only to version 1.0.9 of the format, that is to services with xsv=”1.0.9”.

Introduction

The XML Service is a simple Xml text file with some special tags crafted to instruct a Xml Service Engine that interprets the Xml Service(s) on what steps need to be performed to send a SMS message with a given SMS website.

The Xml Service Engine is a software that simply reads this special tags and makes a series of HTTP post/get/head requests to the SMS website to mimic the user actions when he browses a website to send a SMS with a Web Browser, and does controls to check if everything goes fine or if there is some error string returned by the server.

Actually the Xml Service Engine (part of a goText server or a client like goText++ Desk!) is a sort of interface-less programmable browser, with site specific automated browsing directives in the form of Xml Service(s).

Old goText services used to be available only on the server side and worked only along with the midlet on mobile phones; the Xml Service(s) instead are meant to to be run everywhere.

The Xml Service 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 or personal computer (eg: with goText++ Desk!).

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 by the engine (and should obviously only use tags and attributes defined in this document), that is no validation against the Xml Service Schema is required (even if it is possible when the schema is declared inside the Xml).

Audience

This technical document is targeted to people who want to write new Xml Services to add support for a currently unsupported SMS website or edit existing Xml Services.

It can be also used to write a new Xml Service Engine, or understand the source code of a existing engine available on gotext.org.

If you are novice to the Xml Services development you are suggested to read this document along with some existing Xml Service file opened in your favourite text (or xml) editor.

If you have already wrote some Xml Service in the past you’ll find a complete and detailed reference to all and every single feature supported.


Xml Service Format

All Xml Service tags can be logically grouped in the following areas:

  1. XML Encoding Declaration
  2. <service>: the top level (outermost) tag
  3. Configuration and description
  4. Send steps
  5. <addon>(s): additional features

Please note that usually (until otherwise noted) all tags must be defined in the order they are shown in this document: order matters in Xml Services!

  1. Xml Encoding Declaration

This part is optional (even if strongly recommended), and is the standard XML Encoding Declaration.

It is a text like the following one:

<?xml version="1.0" encoding="windows-1252"?>

and it is used to describe what character your text/XML editor is using to save your file.

If you don’t know what does this mean you should not write this special tag..anyway if you use Windows almost probably your editor will save the file in “windows-1252” encoding, while if you are using Linux or any other Unix like environment the editor will almost probably save the file with “UTF-8” encoding.

Note: This is quite important if you want to have the service working if you are going to use non-ASCII characters or special chars (like: à, ò, æ...) inside the service!!

  1. <service>: the top level (outermost) tag

The <service> tag is the top level tag and contains all other service tags.

It also supports quite a few attributes (many of which are mandatory) that give the first half of service features and descriptions (the rest is found on the Configuration and description part).

This is the <service> tag with the first half of its attributes and their data type.

Other attributes that are used to specify the message length and automatic message splitting are detailed in a separated chapter below.

Mandatory attributes are bold:

<service name="STRING" xsv="1.0.9" version="INTEGER" remote_version="INTEGER" description="STRING_OR_LANGVAR" icon="STRING"

savesession="BOOLEAN"

unsupported_char="STRING-LIST" replacement_char="STRING-LIST"

char_count_more="STRING-LIST" char_count_for="INTEGER-LIST"

user_agent="STRING" multipart="BOOLEAN" author="STRING" (..)>

(..)

</service>

Attributes description and use:

Attribute

Type

Description and values

name

STRING

friendly name for the service (eg: "O2 Ireland").

Note: a goText application can use this value to provide a default name for this service when it is added by the user.

xsv

VERSION

goText "Xml Service Format Version" number, as described in this document.
Changes to the xml specifications that break backward compatibility will have a new version number.

version

INTEGER

Version of the service (starting with “1”), used by Xml Service Engines to check if there are updates to the service.

It should be updated every time you change something in the service, besides when the change is reported using a updated remote_version value (see below).

remote_version

INTEGER

Version of the remote service configuration sent by a goText Server to a goText client for this service, starting with “1”.
Update this number when you change something in the service features that is sent in the remote service configuration, so that the client can inform the user on the need to update the service (please refer to the “
goText Service Protocol Version 3 “ document to know what fields are interested).

description

STRING

or LANGVAR

A short descriptive text with a summary of service features and configuration help text.
Supports
Language Variables.

icon

STRING

Url of 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: encode it as Base64, and write the encoded base64 text in this attribute.

If attribute is missing the client usually shows a default icon.

savesession

BOOLEAN

"true" to tell the service engine and goText to store session information (used in captcha services for example), or "false" to no store sessions.

Default (if not given) is "false".

char_count_more

STRING

-LIST

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

STRING

-LIST

A list of comma (,) separated numbers indicating how much each character in char_count_more actually counts.

unsupported_char

STRING

-LIST

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.

replacement_char

INTEGER

-LIST

A list of comma (,) separated numbers indicating how much each character in char_count_more counts.

user_agent

STRING

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 this attribute is absent no user agent header is sent.

multipart

BOOLEAN

"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.

author

STRING

Nickname or name of the author of the Xml Service.

It may be displayed in the client.

The attributes used to specify the maximum message length change when automatic message splitting on goText side is enabled or disabled.

Message split enabled (on goText side) and maximum message length

The following attributes enable the use of message splitting on goText side: this way goText (the Xml Service engine) splits the message in multiple sms messages when the text is longer than a specific length.

This allows to send long messages also when the website limits the length of a message to 160 characters or less.

<service (..) 

split="true" maxchar_single="INTEGER" split_max_parts="INTEGER"  maxchar_part="INTEGER" maxchar="INTEGER" split_autoloop="BOOLEAN" split_trunc="BOOLEAN">(..)</service>

Attributes description and use:

Attribute

Type

Description and values

split

BOOLEAN

“true" enables the automatic message splitting performed by goText (Xml Service Engine).

The message is split in parts if it is longer than maxchar_single.

Note: split defaults to “false” if not given!

maxchar_single

INTEGER

Used to tell the client the maximum size of a single message before website or service message splitting kicks in.

It is used to automatically calculate maxchar and maxchar_part.

split_max_parts

INTEGER

Maximum number of parts the message will be split into by goText.

This value, along with maxchar_single is used to automatically calculate the maximum number of characters and maxchar_part.

maxchar

INTEGER

optional attribute, allows to override the maximum number of characters for a whole message.

Note: this is rarely used with split=”true”.

maxchar_part

INTEGER

optional attribute, used to override the value that indicates to the client the maximum size of a single message when the length of the message is more than than the one that makes the (website or service) message splitting kick-in (length > maxchar_single).

Note: this is rarely used if split=”true”. It makes sense almost only if split_autoloop=”false”.

How to use this attribute: if maxchar="500" and maxchar_single="140" and the website uses 3 chars to write split part number in message (eg: "1/4") then maxchar_part is 140-3, that is maxchar_part="137".

split_autoloop

BOOLEAN

"true" (default behaviour if not given) to ask goText to automatically go to the next message part when the send of one part is confirmed.

This also enables split parts numbering (eg: “(1/3)”).

"false" still splits the message (if 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 (refer to “System Variables” chapter).

Note: this is rarely used, and also disables split parts numbering.

split_trunc

BOOLEAN

"true" (default if not given) to ask goText to split the message exactly at maxchar_single length, when splitting in parts.

"false" splits the message near maxchar_single at the first whitespace (to avoid truncation of words, useful when service limit for single part is not strict).

Note: this is rarely used.

Message split disabled (on goText side) and maximum message length

The following attributes disable the use of message splitting on goText side: this way the message is sent in a single block, and it is used when there is no need to split the message (eg: when the website splits the message on its own and already offers longer messages):

<service (..) 

split="false" maxchar="INTEGER" maxchar_single="INTEGER" maxchar_part="INTEGER">(..)</service>

Attributes description and use:

Attribute

Type

Description and values

split

BOOLEAN

“false" disables the automatic message splitting performed by goText (Xml Service Engine).

Note: the message could be still split into parts on sms website side.

Note: split defaults to “false” if not given!

maxchar

INTEGER

The maximum number of characters for a whole message (mandatory with split=”false”).

maxchar_single

INTEGER

Optional attribute. If given it is used to tell the client the maximum size of a single message before website or service message splitting kicks in.

Note: this is used for split part highlighting/count purposes on client side.

maxchar_part

INTEGER

Optional attribute. If given it is used to indicate to the client the maximum size of a single message when the length of the message is more than the one that makes the (website or service) message splitting kick-in (length > maxchar_single).

Note: this is used for split part highlighting/count purposes on client side.

  1. Configuration and description

While the outermost <service> tag gives some information about the service, a lot more detailed information is expressed using some tags and their attributes.

All of the following tag are child of the <service> one (mandatory ones are bold)::

<recipients>: supported recipients

This mandatory tag is used to specify how many recipients are support for a single send (multiple-recipient feature) and what kind of recipients are supported.

It has a single attribute, and must contain at least a single inner tag of the <recipient/> type (it may contain multiple <recipient/> inner tags if the service supports different type of recipients).

This are the recipient tags with all possible attributes and their data type. Mandatory ones are bold:

<recipients max="INTEGER">

<recipient type="STRING" allowed_ccc="CCC-LIST" />

</recipients>

<recipients> Attributes description and use:

Attribute

Type

Description and values

max

INTEGER

Maximum number of multiple contemporary recipients possible.

<recipient> Attributes description and use:

Attribute

Type

Description and values

type

STRING

The type of recipients supported by this service, as one of the values from this set:

  • "phone": a mobile phone number.
  • "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

CCC-LIST

This optional attribute is valid and meaningful only with type=”phone”.

It can contain a comma separated list of Country Calling Codes supported by this service in the “+” form (eg: “+44,+39,+62”).

There are three possible scenarios:

  1. A single country code specified: the service supports a single country; the goText client may accept recipients without country calling code and add the one specified here automatically.
  2. A list of country codes specified: the user must provide recipients with country calling codes, and the ccc must be one of this list or the send must be blocked by the client
  3. No country code specified (or attribute empty): the service sends message worldwide, the user must provide recipients with country calling codes and the ccc must be a valid one.

<limit/>: available messages

This tag is used to describe how many messages are supported by this service, and what kind of service is provided.

There must be at least one <limit/> tag in a service, but there can be also more than one if the service has multiple limits.

This is the tag with all possible attributes and their data type. Mandatory ones are bold:

<limit type="STRING" quantity="FLOAT" reset="INTEGER" cost="FLOAT" kind="STRING" />

Attributes description and use:

Attribute

Type

Description and values

type

STRING

The type of limit for available messages with this service. Must be one of the following values:

  • "num": limit is based on the number of remaining messages (like current goText)
  • "credit": 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": limit is based remaining monetary credit on the website. This service should make use of synchronization of remaining credits to update this value.

quantity

FLOAT

Number of available messages in case of "num" type, or (decimal/integer) number of starting credits in case of "credit".

It doesn't make sense to write quantity for "money", or with "credit" if there's no reset period.

Defaults to “0” if not given.

There are some magic values for qty related to the type:

  • 0 + “num”: client shows infinite remaining messages
  • 0 + “money”: client starts with a remaining quantity of zero, and if service supports synchronization shows the actual remaining monetary value on first sync.

reset

INTEGER

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)

Defaults to “0” if not given.

cost

FLOAT

How much to subtract for a single message sent.

Usually it’s 1 for "num" type, and it may be different for "credit" or "money" or even 0 (when the service uses credit sync with the website).

Defaults to “0” if not given.

kind

STRING

Kind of messages available for this limit, and it must be one of this values:

  • “free”: delicious free messages ;)
  • “pay”: paid messages
  • "free+pay": a limit that comprises both free and paid messages.
  • “trial”: a limited (usually one shot) trial amount of messages (in this case there usually is another limit with a different kind).

<field>: configuration fields

A field tag describes one configuration field for the service (eg: username, password, other..).

There must be at least one <field/> tag in a service, but there can be also more than one if the service has multiple configuration fields (which usually is the case).

It may contain multiple inner tags of the <value/> type (with a specific type value..see below for explanation).

This is the tag with all possible attributes and their data type. Mandatory ones are bold:

<field required="BOOLEAN" name="STRING" description="STRING_OR_LANGVAR" type="STRING">

        <value value="STRING" display="STRING_OR_LANGVAR" default="BOOLEAN" />

        (..)

  </field>

<field> attributes description and use:

Attribute

Type

Description and values

required

BOOLEAN

Tells whether this configuration fields must be filled for the service to be used (“true”), or if is an optional field (“false”).
All “true” fields must be filled for the service to be used.

name

STRING

Internal short name of the field that will be sent to the Xml Service Engine, and identifies the configuration field (as a corresponding variable name) when the service is executed.
There is a
magic value for the field name: if a field is named “pass” the goText clients usually show the field with a text field that shows asterisk instead of the text entered by the user (the common password field).

description

STRING or LANGVAR

A short descriptive text that can be used to name the configuration field to the user.

Supports Language Variables.

type

STRING

The value type (and usually client constraint) of this field, and must be one of the following values:

  • "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.

A field whose type is "choice" is represented as a drop down list, with single selection. What to show in this list, and the corresponding values must be specified with the inner <value> tag(s) of this tag.

<value> (inner tag) attributes description and use:

Attribute

Type

Description and values

default

BOOLEAN

"true" can be specified only on one choice value, and marks the one selected by default

value

STRING

Value that will be assigned to the configuration field that will be sent to the Xml Service Engine.

display

STRING or LANGVAR

A short descriptive text shown to user in the drop down entry.

Supports Language Variables.

<languages>: service-specific localized message

This tag uses the same format used in the Standard Xml Service Phrasebook, as described in the Xml Language Format documentation (please refer to that document) and is used to define localized messages/variables that are specific to this service and makes no sense to include in the Standard Xml Service Phrasebook.


  1. Send steps

Send steps are a varying number of tags found inside the <send> tag (which is a direct child tag of the <service> one).

<send>

(..)

</send>

The <send> tag has no attributes, and contains multiple child tags that describe the logic, checks, and HTTP requests that needs to be performed against the sms website to send a message.

There are four kind of steps, each one modeled in a different tag (with its attributes and sub-tags):

All steps have three common attributes, the id (a unique identifier for the given step inside the service) and login/logout attributes.

<(..) id="STRING" login="BOOLEAN" logout="BOOLEAN" (..)>

Attribute

Type

Description and values

id

STRING

Identifier of this step that is unique to all steps in this service.
Can only contain alphanumeric characters, with the only exception of the underscore symbol "_" which is allowed.

login

BOOLEAN

“true” if this step has to be executed only when logging in into the website, “false” (deafult value) if it is a step used after the login phase.

This is used to optimize the send to multiple recipients or multiple parts: pages marked as login=”true” are only executed for the first part and recipient.

NOTE: the engine considers the user to be logged in when the first step with this attribute with value “false” is encountered and executed successfully.

logout

BOOLEAN

“true” if this step has to be executed only when logging out from the website, “false” (default value) if it is a step used before the logout phase.

Steps marked as logout=”true” are only executed once when the send of all parts and recipients finishes.

Important Note: to properly understand the send process, and the above mentioned tags used to model that process, you should already know of Variables in Xml Services: you are suggested to read that chapter first.


<page>: a step used to send an HTTP Request

This step is used to send a HTTP request to the remote sms website. The most common types of requests can be sent (GET, POST, HEAD) in http or https connection, along with get/post data.

The url and data sent can be retrieved from Variables, and the HTTP response content can be used to extract data using the Search In Variables.

The <page> tag supports two kind of child tags:

This is the <page> tag with all possible attributes and their data type. Mandatory ones are bold:

<page id="STRING" url="STRING_OR_VARS" type="STRING" redir="BOOLEAN"  referer="STRING_OR_VARS" login="BOOLEAN" logout="BOOLEAN" charset="STRING" timeout="INTEGER" wait_before="INTEGER_OR_VAR" encode_percent="BOOLEAN">

(..)

        <var (..) />

        <post name="STRING_OR_VARS" value="STRING_OR_VARS" encode="BOOLEAN" />

        <header name="STRING" value="STRING_OR_VARS" />

(..)

</page>

Attributes description and use (description of attributes common to all steps [id, login, logout] have been omitted):

Attribute

Type

Description and values

url

STRING or VARS

The http/https address of the page to send the request to, and can contain a (get) query string.

Supports Variables.

type

STRING

The type of HTTP request to perform, must be one of the following (self-explaining) values:

  • "get"
  • "post": this is the only request type that supports the child tag <post>
  • "head"

redir

BOOLEAN

“true” to tell the Xml Engine to automatically follow HTTP redirects (eg: HTTP code 301), “false” to not follow redirect automatically.

referer

STRING or VARS

This value can be empty to not send the referer page url, or one of the following:

  • “auto”: the Xml Engine will automatically determine the previous url and send it as a referer to this page.
  • any string and/or variable: the resulting string will be sent as referer url.

Supports Variables.

charset

STRING

Forces the character set used to urlencode the data sent to this page, and the character set used to read the HTML received as reply to this page request.

When this attribute is not specified the engine automatically determine what encoding should be used by reading the Content-Type HTTP response header. If this header is absent,  the UTF-8 charset is used by default.

Note1: sometimes a website specifies a wrong charset in the header and overrides the setting using a <meta> tag inside the HTML. In this cases the charset attribut needs to be set to the same encoding as the one in the meta-tag (common values are "ISO-8859-1" or "Windows-1252").

Note2: A proper value to this attribute usually solves missing missing symbols and/or accented letters (replaced by question marks or other symbol) in messages received by users in problematic and/or badly designed SMS websites.

timeout

INTEGER

Number of seconds this page request can wait for reply before timing out. If not given the default Xml Engine timeout will be used (20 seconds for goText++ Desk!).

Can be increased to enable the use of slow websites/subsites or decreased to quickly inform the user of timeout in case the website is usually fast.

Note: this is rarely used.

wait_before

INTEGER or VAR

Number of milliseconds to pause the service execution before sending the first HTTP request specified in this tag: useful to simulate forced waits on the website.

Default values if not specified is "0" (zero = no delay).

Supports a single Variable whose value must be an integer.

encode_percent

BOOLEAN

It enables or disables the percent encoding of the percent character itself in query strings (default is "true", and it should be changed to "false" only if you see that it is required for the request to work).

Note: this is rarely used.

<post>: a (form) post field / post data

The <post> tag is an inner tag of the <page> one, that is used to specify the post data when (and only if) the <page> request is of type=”post”.

<page (..)>

        <post name="STRING_OR_VARS" value="STRING_OR_VARS" encode="BOOLEAN" />

(..)

</page>

<post> (inner tag) attributes description and use:

Attribute

Type

Description and values

name

STRING or VARS

The name of the post field to be sent in the request body.

It must be equal to a name attribute of a HTML input element inside a form of the original website page (eg: <input name=”SOMETHING” />).

Supports Variables.

value

STRING or VARS

Value to be sent for this post field, it is what the user would write on the website or a fixed value specified in the HTML form inside the original website page (eg: <input name=”SOMETHING” value=”SOMEVALUE”>).

Supports Variables.

encode

BOOLEAN

“true” (default value) to have the Xml Engine automatically urlencode the name and value.

Set it to “false” if you provide a name and value which are already urlencoded (eg: extracted with a var from inside a webpage).

<header>: defines a custom HTTP request header

This child tag of the <page> one is used to send a custom HTTP header to the server.

This is rarely used, but can be necessary when dealing with flash-based (or similar technologies) websites.

<page (..)>

        <header name="STRING" value="STRING_OR_VARS" />

(..)

</page>

<header> (inner tag) attributes description and use:

Attribute

Type

Description and values

name

STRING

The name of the HTTP header field that will be sent.

value

STRING or VARS

Value to be sent for this header.

Supports Variables.


<captcha>: a step used to retrieve a captcha image file

Many websites today require the user to fill a confirmation code usually shown in a image inside the page: this is commonly called captcha.

This tag is used to retrieve the captcha image (with the use of an HTTP request) and show it to the user: the execution of the service will stop here until the user sends back the code shown on the image.

The Xml Engine will automatically resume the service execution on the first step after the <captcha> one where the execution stopped.

All <page> attributes and child tags are supported in <captcha>, plus an additional attribute and child tag.

This is the <captcha> tag with its attributes and their data type (besides those in common with the <page> tag). Mandatory ones are bold:

<captcha (..) zoom="FLOAT_OR_VAR">

(..)

        <save name="VAR" />

(..)

</captcha>

Attributes description and use:

Attribute

Type

Description and values

zoom

FLOAT or VAR

Optionally used to specify a zoom factor that the engine will apply to the captcha image (“2” for 2x, while “0.5” stands for “0.5x” or half image).

Supports a single Variable whose value must be an integer.

Note: this is usually used in conjunction with a variable whose name equals a configuration field (<field>) where the user can configure the zoom factor at his will.

Session persistence and Xml Engine state persistence

The captcha tag requires the session attribute of the <service> tag to be “true” (session persistence must be enabled), so that the browsing session (cookies) for the user are saved and restored when he sends back the captcha text.

Additionally, when the <captcha> tag is executed the following data (and variables) relative to the Xml Engine state is automatically saved:

Note: if you need any other Variable to be saved and restored you need to explicitly ask the Xml Engine to save it using the <save> tag as explained below.

<save>: saves a variable in the goText-session

This tag is used to save a variable which is not automatically saved in the Engine state when the <captcha> tag is executed.

<captcha (..)>

        <save name="VAR" />

(..)

</captcha>

<save> (inner tag) attributes description and use:

Attribute

Type

Description and values

name

VAR

The name of a variable that must be saved, and restore when the send resumes with the code sent back by the user.


<dummy>: a step used to assign or calculate variables

This step does nothing on its own: it is only used to house <var> inner tags of the Assigned and Calculated type.

This is the <dummy> tag with all possible attributes and their data type. Mandatory ones are bold:

<dummy id="STRING" login="BOOLEAN" logout="BOOLEAN">

(..)

        <var (..) />

(..)

</dummy>

The description of <dummy> tag attributes has been omitted because they have been already described (they are common to all steps).


<fork>: a step used to make conditional jumps to other steps

This step does nothing on its own: it is only used to house one or more<condition> inner tags.

Those <condition> child tags are executed one by one in the order they appear in the Xml Service file, and they express the conditions that allow to jump to another step, or return an error to the user, or confirm the successful send of a message part.

This is the <fork> tag with all possible attributes and their data type. Mandatory ones are bold:

<fork id="STRING" login="BOOLEAN" logout="BOOLEAN">

(..)

        <condition (..) />

(..)

</fork>

The description of <fork> tag attributes has been omitted because they have been already described (they are common to all steps).

<condition>: expresses the fork condition and outcomes

This tag express a condition that can change the linear execution of a Xml Service file.

All conditions are expressed with the use of a single attribute, the type attribute, and they operate on one or two elements (var1 and eventually var2).

If a condition is satisfied all ok_* attributes defined are executed, else if it is not satisfied all ko_* attributes defined are executed.

<fork id="STRING" login="BOOLEAN" logout="BOOLEAN">

(..)

        <condition type="STRING" var1="STRING_OR_VARS" var2="STRING_OR_VARS" ok_id="STEP_ID" ko_id="STEP_ID" ok_error="STRING_OR_VARS" ko_error="STRING_OR_VARS" ok_confirm="BOOLEAN" ko_confirm="BOOLEAN"  />

(..)

</fork>

<condition> tag attributes description and use:

Attribute

Type

Description and values

type

STRING

Type of condition that will be evaluated. It must be one of the following values:

  • "empty": the condition is verified if the variable in var1 is empty, or it is a zero-length string.
  • "not_empty": the condition is verified if the variable in var1 contains some value, or it is a string with some content.
  • “equal”: the condition is verified if the variable (or constant value) var1 equals another variable (or constant value) in var2.
  • “not_equal”: the condition is verified if the variable (or constant value) var1 does not equal another variable (or constant value) in var2.
  • “less”: the condition is verified if the variable (or constant value) var1 has a value that is less than another variable (or constant value) in var2.
    Note:
    var1 and var2 are considered to be numbers (integer or floating point).
  • “greater”: the condition is verified if the variable (or constant value) var1 has a value that is greater than another variable (or constant value) in var2.
    Note:
    var1 and var2 are considered to be numbers (integer or floating point).
  • “less_or_equal”: the condition is verified if the variable (or constant value) var1 has a value that is less than or equal to another variable (or constant value) in var2.
    Note:
    var1 and var2 are considered to be numbers (integer or floating point).
  • “greater_or_equal”: the condition is verified if the variable (or constant value) var1 has a value that is greater than or equal to another variable (or constant value) in var2.
    Note:
    var1 and var2 are considered to be numbers (integer or floating point).
  • “var_inlist”: the condition is verified if the variable (or constant value) var1 is an element of a coma-separated list of values contained in another variable (or constant value) in var2
    (Eg: the condition is verified if
    var1=”apple” and var2=”pear,apple,strawberry”).
  • “listitem_invar”: the condition is verified one element of a coma-separated list of values contained in a variable (or constant value) in var2 equals or is contained in another variable (or constant value) in var1.
    (Eg: the condition is verified if
    var1=”+393401234567” and var2=”+41,+39,+1”).

var1

STRING or VARS

The first element of all condition types, always required. Its meaning and use depends on type.

Supports Variables.

var2

STRING or VARS

The second element of all condition types, it is required only by some type. Its meaning and use depends on type.

Supports Variables.

ok_id

STEP ID

If the condition is verified the execution will jump to the unique identifier of another step specified here.

ko_id

STEP ID

If the condition is not verified the execution will jump to the unique identifier of another step specified here.

ok_error

STRING or VARS

If the condition is verified the execution will stop and the error defined in this attribute will be returned to the user.

ko_error

STRING or VARS

If the condition is not verified the execution will stop and the error defined in this attribute will be returned to the user.

ok_confirm

BOOLEAN

If “true” when the condition is verified the send of the (current part of the) message is confirmed.

Use this attribute to say to the Xml Engine “message is sent, loop to the next recipient or message part (if any).
Note: all steps after the current one (besides logout ones) will still be executed even if send is confirmed. To avoid this you have to use another <condition> tag.

ko_confirm

BOOLEAN

If “true” when the condition is not verified the send of the (current part of the) message is confirmed.

Use this attribute to say to the Xml Engine “message is sent, loop to the next recipient or message part (if any).
Note: all steps after the current one (besides logout ones) will still be executed even if send is confirmed. To avoid this you have to use another <condition> tag.


  1. Addon: Additional Features

As a complement to the message sending process (the <send> and child tags), the Xml Service Format (starting from v1.0.9) enable service writers to include additional features that go beyond the send.

Additional features can display some text to the user, or display no text at all and only synchronize limits information.

The best of all is that additional features can be manually and/or automatically triggered in response to some actions, and each service can have zero, one or unlimited addons!

An additional feature is defined using the  <addon> tag (which is a direct child tag of the <service> one).

<addon name="STRING" short_desc="STRING_OR_LANGVAR" long_desc="STRING_OR_LANGVAR" trigger="STRING" allow_manual="BOOLEAN" interval="INTEGER_OR_FIELDVAR" condition="STRING_OR_FIELDVAR" delay="INTEGER_OR_FIELDVAR" display="BOOLEAN" return_format="STRING" >

(..)

</addon>

The <addon> can contain multiple child tags that describe the logic, checks, and HTTP requests that needs to be performed against the sms website to perform the additional feature.

There are four kind of supported steps, each one modeled in a different tag (with its attributes and sub-tags):

The only <send> step currently unsupported in addons is <captcha> (this may change in future versions of this standard).

These are <addon> attributes, their description and use:

Attribute

Type

Description and values

name

STRING

The internal name of this addon, never displayed to the user.

It must be unique to this Xml Service, and can only contain alphanumeric characters and the underscore symbol.
Example: a
valid name is “test_addon_1", while a wrong name is "this is 1 test..addon".

short_desc

STRING or LANGVAR

It should be a short descriptive name of this additional feature that is shown to the user in a client (eg: “Credit Synchronization”).

Supports Language Variables.

long_desc

STRING or LANGVAR

It should be a long help text that describes what this additional feature does, usually shown to the user in a client (eg: “Synchronizes the remaining credit of your account with the current value on the website.”).

Supports Language Variables.

trigger

STRING

Determines if the additional feature will be automatically started by the goText client application with some kind of trigger or not.

It can be one of the following values:

  • “false”: the addon will not be automatically started
  • “send”: each time a message send finishes this addon is started automatically
  • “config_complete”: each time the user saves the service configuration with all required fields filled, the addon is automatically started.
  • “timer”: the addon will be automatically executed from the application startup to the end, every interval seconds (see below).

allow_manual

BOOLEAN

“true” (default value) to enable the user to manually start this addon whenever he wants: this is normally shown as button or list of addons available when the user select this service.

“false” if there is no point in running this addon manually.

interval

INTEGER or FIELDVAR

Number of seconds that need to elapse between the end of a timed execution of this addon and the start of the next one.

Note: this only applies to trigger=”timer”, and it is required with this trigger type.

Supports a single Field Variable,a variable that corresponds to a <field> name (to something the user has set in service configuration).

one_shot

BOOLEAN

“false” (the default) to periodically repeat the timed addon with the give interval seconds.

“true” to execute this timed addon only once.

condition

INTEGER or FIELDVAR

If this has value “0” (zero) or is empty (“”) the addon is disabled and will not be executed, any other value means that the addon is enabled.

Supports a single Field Variable,a variable that corresponds to a <field> name (to something the user has set in service configuration).

Note: this is useful to let the user disable the addon with a <field> in service configuration.

delay

INTEGER

Number of seconds that the client should wait before starting the addon execution when the trigger is verified.

Note: this can be used for example to let the remote website update the send status if there is some info related to it to be extracted in a trigger=”send”.

display

BOOLEAN

“false” (the default) if the addon does not need to display any data to the user (it is used only to synchronize limits).
“true” if this additional feature needs to display some data to the user.

return_format

STRING

Determines the format of the data returned and displayed to the user when display=”true”.

Actually there is only one value supported:

  • “txt”: plain text string

Note: future Xml Service Format versions may added richer data formats.

How to return data in addons with System Variables

There are two ways to return data in addons:

  1. Using limit synchronization variables (see $sms_rem_N in the System Variables chapter): this is the only way to return something when display=”false”.
  2. The $addon_reply system variable specific for the additional features: everything that a <var> tag inside the <addon> writes in $addon_reply will be shown to the user at the end of the addon execution.

System variables available in addons

In addons you have access to the following system variables:

<usesend>: a special tag that allows to “import” a <send> step inside the <addon>

Additional features add a new special tag that enable quick addon writing by virtually importing steps already defined in the send process: this way you write less, the service is smaller, and easier to maintain.

<usesend id="dummy_page" />

This is the only attribute supported in <usesend>:

Attribute

Type

Description and values

id

STRING

The unique identifier of the <send> step that is needed inside the addon execution process.


Variables in Xml Services

Variable is a key concept, and one of the most used (and versatile) features of Xml Services.

A Variable is a sort of named box that you use to read in (and store) text, numbers, and other data used in the sending process, and read it back to make checks, comparisons or to compose data that needs to be sent to the sms website.

There are two main kind of variables:

All variables can be manipulated (either read or write) with the above mentioned <var> tag, and they can be also used inside selected attributes of those and other tags, where there is the need to have a dynamic behaviour.

The Xml Service writer is free to create and use as many variables as he needs, and those variables can be named to whatever the developer wants until the following naming conditions are met:

Example: a valid name is "$unique_id_1", while a wrong name is "this is the-id!"

System Variables

The system (predefined) variables are available to the service developer and the Xml Engine already at the first step at the send process.

This is the list of system variables::

<var> tag: developer defined variables

Var tag attributes tells the service where to read the data you need, how to read, and how do you want to name the variable that contains this data.

It can also be used to confirm the send of a (part of the) message or to return an error message to the user.

Assignment to some System Variables (as seen above) can result in additional information returned to the user.

The <var> tag supports a lot of attributes, many of which are mutually exclusive. Depending on the attributes of the <var> tag used three main group of variables can be identified:

In all modes there is only a common attribute:

<var name="VARNAME" (..) />

Attribute

Type

Description and values

name

VARNAME

The name you want to give to the variable.
As said above it must start with a dollar symbol, and can only contain alphanumeric chars without spaces or special characters (that is only letters from "a" to "z", numbers, only symbol allowed is the underscore "_").

A valid name is "$unique_id", while a wrong name is "this is the-id!"

Assigned Variables

Those whose value is directly specified inside the Xml Service file, in this way:

<var (..) value="STRING_OR_VAR" />

Attribute

Type

Description and values

value

STRING or VAR

The value that needs to be assigned to the variable.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Search in Variables

Search-in variables are those whose content is read from a specific part of a HTTP Response, and thus can be used only inside <page> or <captcha> tags. The exact http protocol source is specified inside the in attribute:

<var (..) in="STRING" 

empty="STRING" not_empty="STRING" error_message="STRING_OR_VAR"

(..) />

Those listed are attributes common to all kind of searches (the other attributes are reported below in their valid combinations for clarity):

Attribute

Type

Description and values

in

STRING

The source where data needs to be read:

  • "page" : tells to search in page content
  • "header" : search in http response headers
  • "url" : search in last browsed url. Can be different from the requested page url if automatic redirect following has been enabled on last page.

empty

STRING

If after the search the variable is empty, some action can be triggered based off the value of this attribute.

Valid values are:

  • "error": the service will return an error if the variable is empty or not found.
  • "confirm": if the variable is empty the send of the (current part of the) message is confirmed. Use this to say “message is sent, loop to the next recipient or message part (if any).
    Note: all steps after the current one (besides logout ones) will still be executed even if send is confirmed. To avoid this you have to use a <fork> tag.
  • Any other string you like to have as default value if variable ends empty (defaults to an empty string if attribute is absent).

not_empty

STRING

Same as empty attribute, but the action is triggered when the variable has a value (is not empty) when the search ends.

Valid values are the same as above (“error”, “confirm”, any string).

error_message

STRING or VAR

Error message returned to the user when the variable is empty and empty=”error” (or when the variable is not empty and not_empty=”error”).

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

The other required attributes vary based off the kind of search to perform:

Exact Match Search

Tries to find an exact match of a string, and puts inside this variable the matched string position inside the in source. The variable ends with an empty value is no such match can be found.

<var (..) search="match" match="STRING_OR_VARIABLE" />

Attribute

Type

Description and values

search

STRING

“match” triggers the “search for exact match” search type. This search is case sensitive.

match

STRING or VAR

The exact string to be matched inside the in source.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Text between other strings

Tries to extract a string between other two strings, and puts the resulting string inside this variable. The variable ends with an empty value if the boundary strings were not found.

<var (..) search="between" begin="STRING_OR_VAR" end="STRING_OR_VAR" />

Attribute

Type

Description and values

search

STRING

“between” triggers the extraction of a string between two other strings.

begin

STRING or VAR

The string used as starting mark of the desired data.

If missing the string is extracted from start to end string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

end

STRING or VAR

The string used as ending mark of the desired data.

If missing the string is extracted from begin string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Regular expression search

Tries to extract a string using a regular expression, and puts the resulting string inside this variable. The variable ends with an empty value if the expression can’t be matched.

<var (..) search="regex" regex="STRING" />

Attribute

Type

Description and values

search

STRING

“regex” triggers the use of a “regular expression”-based search.

regex

STRING

The regular expression that needs to be matched against the in source.

You must include a capturing group in this expression to extract data.

Note: Only the first match data is extracted.

If you write more than one capturing group the captured values will be named with the <var> name attribute followed by a number starting by 1 (eg: if you set <var name="datepart">, and you have 3 capturing groups in the regular epxression, and the RE is matched, this will result in 3 variables named datepart1, datepart2, datepart3).

Full HTTP header extraction

Tries extract the full content of a single header inside the HTTP response header, and puts the resulting string inside this variable. The variable ends with an empty value if no such header is found.

<var (..) in="header" headername="STRING" />

Attribute

Type

Description and values

search

STRING

The full header extraction can be used only when in=“header”.

headername

STRING

The name of the HTTP response header whose full content needs to be extracted (Eg: “Location”).

Calculated Variables

Calculated variables are those whose value is the result of some mathematical or string based elaboration or calculation.

The required attributes for this variable group vary based off the kind of operation to perform.

Below is the (quite long) list of supported operations:

Basic Mathematical Operations

Executes a mathematical operation between the given operands and puts the numeric result inside the variable value. The result is undefined if one or both terms are not numbers.

<var (..) operation="STRING" term1="NUMBER_OR_VAR" term2="NUMBER_OR_VAR" />

Attribute

Type

Description and values

operation

STRING

The mathematical operation to perform, must be one of the following (self-explaining) values:

  • "sum"
  • "subtract"
  • "multiply"
  • "divide”

term1

NUMBER or VAR

The number (decimal or integer) used as first term of the operation.

It can also be a Variable (that will be automatically replaced with its value from the Xml Engine).

term2

NUMBER or VAR

The number (decimal or integer) used as first term of the operation.

It can also be a Variable (that will be automatically replaced with its value from the Xml Engine).

Random Mathematical Operation

Generates a random number in the specified range, and puts the numeric result inside the variable value. The generated random number will be between term1 and term2 (included).

The result is undefined if one or both terms are not numbers.

<var (..) operation="STRING" term1="INTEGER_OR_VAR" term2="INTEGER_OR_VAR" />

Attribute

Type

Description and values

operation

STRING

“random” triggers the execution of the random number generation.

term1

INTEGER or VAR

The integer number used as lower bound for the random operation.

It can also be a Variable (that will be automatically replaced with its value from the Xml Engine).

term2

INTEGER or VAR

The integer number used as upper bound for the random operation.

It can also be a Variable (that will be automatically replaced with its value from the Xml Engine).

String extraction between other strings

Tries to extract a string between other two strings, and puts the resulting string inside this variable. The variable ends with an empty value if the boundary strings were not found.

<var (..) operation="between" original="STRING_OR_VARS" begin="STRING_OR_VARS" end="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“between” triggers the extraction of a string between two other strings.

original

STRING or VARS

The string where the between operation will be applied.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

begin

STRING or VARS

The string used as starting mark of the desired data.

If missing the string is extracted from start to end string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

end

STRING or VARS

The string used as ending mark of the desired data.

If missing the string is extracted from begin string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Example:

String search

Searches a string inside another string.

If the searched string is found the destination variable will contain the starting position (as a numeric index), else if the string is not found the variable will be empty.

<var (..) operation="search" original="STRING_OR_VARS" search="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“search” triggers the search for a string inside another one.

original

STRING or VARS

The string to be searched.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

search

STRING or VARS

The string that will be searched inside original.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Regex search

Extracts part of a string using a Regular Expression based search. The variable ends with an empty value if the expression can’t be matched.

<var (..) operation="regexsearch" original="STRING_OR_VARS" search="STRING" />

Attribute

Type

Description and values

operation

STRING

“regexsearch” triggers the rexex based search for a string inside another one.

original

STRING or VARS

The string to be searched.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

search

STRING

The regular expression whose match will be searched in original.

You must include a capturing group in this expression to extract data.

Note: Only the first match data is extracted.

If you write more than one capturing group the captured values will be named with the <var> name attribute followed by a number starting by 1 (eg: if you set <var name="datepart">, and you have 3 capturing groups in the regular epxression, and the RE is matched, this will result in 3 variables named datepart1, datepart2, datepart3).

String replace

Replaces all occurrences of a string with another string. The destination variable will contain the string with the replacements applied.

<var (..) operation="replace" original="STRING_OR_VARS" search="STRING_OR_VARS" replace="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“replace” triggers the search and replace of a string inside another one.

original

STRING or VARS

The string to be searched.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

search

STRING or VARS

The string that will be searched inside original.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

replace

STRING or VARS

The string that will be used as replacement.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Regex replace

Replaces all Regular Expression matches with the given replacement string. The destination variable will contain the string with the replacements applied.

<var (..) operation="regexreplace" original="STRING_OR_VARS" search="STRING" replace="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“regexreplace” triggers the regex based search and replace.

original

STRING or VARS

The string to be searched.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

search

STRING

The regular expression whose match will be replaced in original with replace.

replace

STRING or VARS

The string that will be used as replacement.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Substring: extract part of a string

Used to extract a part of string given the start and ending index of the part.

The variable ends with an empty value if the boundaries are wrong.

<var (..) operation="substring" original="STRING_OR_VARS" begin="INTEGER_OR_VAR" end="INTEGER_OR_VAR" />

Attribute

Type

Description and values

operation

STRING

“substring” triggers the extraction of a string between two indexes.

original

STRING or VARS

The string where the substring operation will be applied.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

begin

INTEGER or VAR

The starting position of the text to be extracted (starting from zero).

If missing the string is extracted from start to end string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine, and evaluated to integer).

end

INTEGER or VAR

The ending position of the text to be extracted; if this is negative that many characters will be removed from the end of the string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine, and evaluated to integer).

Examples:

Join two strings

Joins two strings into one, useful especially with variables.

<var (..) operation="join" term1="STRING_OR_VARS" term2="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“joing” triggers the string join operation.

term1

STRING or VARS

The first part of the resulting string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

term2

STRING or VARS

The second part of the resulting string.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Note: <var name="$joinedvar" operation="join" term1="$first_var" term2="$second_var" /> is completely equivalent to an assigned variable in the following form: <var name="$joinedvar" value="$first_var$second_var" />

Length: calculate the length of a string

Used to calculate the length of a given string.

<var (..) operation="length" original="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“length” triggers the execution of the length calculation.

original

STRING or VARS

The string whose length will be calculated.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

Base64 encoding

Used to encode a string in a base64 form.

<var (..) operation="base64" original="STRING_OR_VARS" to_charset="STRING" />

Attribute

Type

Description and values

operation

STRING

“base64” triggers the execution of the conversion of a string in its base64 representation.

original

STRING or VARS

The string whose length will be calculated.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).

to_charset

STRING

A base64 representation of a string varies depending on the encoding used for the string during the conversion. By default the Xml Engine will use UTF-8. If the website expectes any other encoding you can specify the encoding name (eg: “Windows-1252”) in this attribute.

Html entities decode

Used to decode all HTLM entities inside a string with the corresponding characters (eg: “&lt;span&gt;” when decoded becomes “<span>”).

<var (..) operation="entities_decode" original="STRING_OR_VARS" />

Attribute

Type

Description and values

operation

STRING

“entities_decode” triggers the execution of the html entity decode function.

original

STRING or VARS

The string containing the HTML entities that need to be decoded.

It can also contain one or more other Variable (that will be automatically replaced with its value from the Xml Engine).


Appendix A: Format Version Changelog

This appendix highlights the main changes between format version updates. This is helpful for software developers, and also to Xml Service writers who need to update their services to the latest format version.

Changes from v1.0.8 to v1.0.9

Changed:

Added:

Previous Changes

Previous changes are not available in this document because it has been released along with v1.0.9 of the standard, and previous versions are not supported anymore.


Appendix B: The Author

This document has been written by Fulvio Sciarretta, known as Zydio on the goText Project.

Zydio is a developer of the goText Project from the late 2006, and co-admin from the 2007, and the mind and hands behind the goText++ project (goText++ Desk!) and the creator of the Xml Service Format described in this document.