SFTP BatchLoader

Modified on Mon, 04 Feb 2013 11:13 by CM — Categorized as: FTP, XML API

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:


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:



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>