This document describes how to use the BatchLoader Interface of the
PSWinCom SMS Gateway over Secure FTP. This document is intended
for developers, integrators and system operators only, and basic
knowledge of SFTP and SSH is required.
Also refer to the product web for more information.
BatchLoader
PSWinCom SMS Gateway provides a service called BatchLoader that
can be used to submit SMS bulk jobs. The service is suitable for
sending large quantities of SMS messages without the need for any
special software. The messages will be throttled and delivered at high
speed to its destinations.
BatchLoader can be accessed either through a web-interface, or using
Secure FTP.
This document emphasizes to cover the communication and file
formats needed to use the Secure FTP version of the service.
Communication and file transfer¶
Before using the Secure FTP version of the BatchLoader service you
need credentials for connecting to the PSWinCom BatchLoader server.
These credentials are *not* the same as for your Gateway Account.
They will be provided to you when signing up for the SecureFTP option
of the service.
You will need to provide two files for each batch-job you want to
submit:
- Datafile containing all receivers (and optional the message to
each receiver) - XML formatted orderfile that describes the job
These two files are described in the following sections.
The BatchLoader will look for any unprocessed orderfiles in the dropbox
and immediately process them.
You should always upload the datafile before uploading the orderfile to
avoid that the job is being failed or cut-of due to a missing or partial
datafile.The orderfile
must have the file-extension .order when it is uploaded.
After the BatchLoader has processed the job, the orderfile will be
renamed to the extension .order.done
Old files will be stored for up to a month before being deleted, unless
the client deletes the files.
Datafile format
Currently two possible formats are supported:
- Plain textfile with tabulator separated receiver-number and
message-text. (text-tab)
- Plain textfile with one receivernumber per line. (text-fixed)
Sample datafile with receivernumber and message text (text-tab):
4740404040<TAB>Hi, this is a message for person A<CR><LF>
4741414141<TAB>Hi, this is a message for person B<CR><LF>
4742434445<TAB>Hi, this is a message for person C<CR><LF>
Sample datafile with only receivernumbers (text-fixed):
4740404040<CR><LF>
4741414141<CR><LF>
4742434445<CR><LF>
When using this format, the message text must be specified in the
orderfile.
Orderfile format
The orderfile specifies all information required to process and send the
SMS messages. The file must contain one-element named Order, that
has the following required attributes:
| Attribute |
Description |
| username |
Username of the PSWinCom Gateway account to use
when submitting messages. |
| password |
The password of the account.2 |
| format |
The format of the datafile. Currently supported
formats are specified in 2.2. |
The Order-element may have the following child-elements:
| Element |
Description |
| Filename |
Name of datafile. Should not contain any path
information. Required element. |
| FixedText |
Must be set when format=”text-fixed” and should
not be present with “text-tab”. Contains the fixed
message text that will be sent to all receivers. |
| SenderId |
Sendernumber or identity for the SMS message.
Numeric or alphanumeric up to 11 characters. No
national characters are accepted. Required element. |
| Prefix |
Prefix to add to each receivernumber when the
length of the receivernumber is less than the number of digits specified in the lessThan attribute
of the Prefix element. Required element. |
| Skip |
Number of intitial lines to skip. Useful to avoid
problems when datafile contains header information.
Required Element. |
| DeliverTime |
Use this element to use deferred delivery. If this
element is present and not empty it will be parsed as
the date and time when the messages should be
delivered. Format: yyyyMMddhhmm. Sample:
200905061430 are the date 6th of may 2009 at
14:30. It is only possible to set a date and time up
to one week ahead. If the specified time has passed,
the message will be rejected. |
| ReceiptEmail |
Email-address where a transcript of the job should
be sent when completed. Element must be present,
but may be empty. |
A sample orderfile is provided below to show how it may be set up:
<?xml version="1.0"?>
<Order username="test" password="test" format="text-fixed">
<Filename>sms-receivers.txt</Filename>
<FixedText>Hi, this is a bulk SMS message</FixedText>
<SenderId>SMSJob</SenderId>
<Prefix lessThan="10">47</Prefix>
<Skip>0</Skip>
<DeliverTime>200905061430</DeliverTime>
<ReceiptEmail>jobwatcher@acme.com</ReceiptEmail>
</Order>