sms.capesoft.com Client
Introduction
This document covers adding support for sms.capesoft.com to your NetTalk
(desktop or web) application.
A completed example can be found in
\clarion\examples\nettalk\webclient\sms.capesoft.com\ABC\smsClient.app
Dictionary Changes
Your application will need at least two new tables added to the dictionary;
SmsSettings and SmsLog.
You can import these tables into your dictionary
by importing the supplied
NetTalkSms.Dctx file
into your dictionary.
You will find this file in the
\clarion\accessory\libsrc\win folder.
SmsSettings Table
This table contains settings which your program will need to connect to
the server. It typically has a single record and contains the URL and
authentication details for the program at this site. It only has to be
set once per site (not once per user.)
The SMS Server URL is
usually set to
https://sms.capesoft.com.
This is the address of the SMS server.
The Program Auth ID is
unique to your program. It is issued to you when you sign up on the
sms.capesoft.com web site. This value should be used at all installs of
your program. It is typically not shown to the user.
The Client
Auth ID is unique to each client install. You do not need to generate
this field - it is Read-Only inside the program. You can choose to
display it to the client (in order to better link them with their
settings in the sms server) or you can choose to hide it from them. When
a new client is added to the system (via the SMS Settings Window) a new
Client ID will automatically be allocated to them, and will be stored in
the clients database.
The Company Name is the name of the client
- the company that is running your program. The contact name, email and
phone number are details for the primary contact at the client's site.
These fields make it easier to identify the client when you are managing
their details in the sms.capesoft.com web site. The user can update
their details at any time by returning to this window.
The
default Country Dialing Code is the international dialing code for the
country where the client is located. This code can then be added to all
numbers where a dialing code does not exist. For example the dialing
code is 1 for the USA, 27 for South Africa, 44 for the UK and so on. A
customer who is operating in South Africa should set this to 27.
SmsLog Table
The log table logs all outgoing, and incoming SMS's.
Application Changes
- Required Global Extensions
- Required Global Variables
- Import Procedures
- Auto Start the ReceiveSMS procedure
- Add SMS buttons to other windows as desired
- Add calls to SendSMSviaSmsServer as
desired
Required Global Extensions
- NetTalk 10 (any Level)
- StringTheory
- jFiles
Required Global Variables
- Glo:User (String255)
- Glo:ReceiveSMSThread (Long)
- Glo:SmsArrived (Long)
Import Procedures
The following procedures can be imported directly from the example, or
by using the supplied TXA file,
NetTalkSMSABC.TXA
or
NetTalkSMSLegacy.TXA. These files are
in
\clarion\accessory\libsrc\win.
The procedures being imported are;
Procedure | Description |
SendSms | A window that can be called from anywhere in
your application. It allows the user to enter a phone number and
message, and allows the calling procedure to prime those fields.
This window is designed to be seen by the user. |
SendSmsviaSmsServer | A window that can be called from
anywhere in your application. This allows you to send an SMS
directly, with no user involvement. This window is typically
hidden from the user (unless an error occurs.) |
ReceiveSms | A background, usually hidden, window that
connects to the server to receive SMS's. this window uses a
combination of a web client object, as well as a web-socket
connection to the server to ensure that SMSs are received as
promptly as possible, and also to make sure no SMSs are missed. |
SmsServerSettings | The global settings window that
allows the user to configure their SMS settings. |
BrowseSmsLog | A browse on the SMSLog table. This
browse uses styles to show sent and received SMSs. This window
can be adapted to look like the windows in your program. |
Auto Start ReceiveSMS Procedure
The RecieveSms procedure is a background procedure which should start
when the program starts. Usually this procedure is invisible, but it can
also display itself if desired.
If you have multiple users on a
LAN, all sharing the same database, then only one instance of the
ReceiveSMS procedure needs to be running. Ideally it belongs in a server
module which runs 24x7 on the network. In the absence of that it can be
run in multiple programs on the LAN - running extra instances of the
procedure does not do any harm.
The example application gives a
good overview of how to manage a background procedure like this one. In
the example the following steps were done to start this procedure as the
program starts.
- A global, unthreaded variable,
glo:ReceiveSMSThread, of type LONG
is created. This stores the thread number of the running
ReceiveSms procedure, and thus allows other procedures to send
events to it.
- A global, unthreaded variable Glo:SmsArrived of type LONG is
created. This is updated to a new value whenever an SMS arrives.
This allows it to be used as a BrowseReset field, or in other places
where it's important to monitor incoming SMSs.
- A menu item, or Toolbar item (?SMSReceive)
is added to the Frame procedure. the embed code for this item is as
follows;
IF glo:ReceiveSMSThread = 0
START(ReceiveSMS,25000)
ELSE
POST(event:UnHide,,glo:ReceiveSMSThread)
END
This has the effect of STARTing the procedure if
it not already running. If it is already running then the existing
procedure is sent an UnHide event so that it can be seen.
- In the Init method of the Frame, at the end of the method, an
event is triggered to Start the receiveSMS procedure
post(EVENT:Accepted,?SMSReceive)
- In the CloseWindow event for the Frame, the SMSReceive procedure
is instructed to close;
IF
glo:ReceiveSMSThread
POST(event:Closewindow,,glo:ReceiveSMSThread)
END
While the above is an example of adding this startup process to the
Frame, it is not the only way to do it. You are free to modify the above
process as suits your needs.
(optional) Add SMS buttons to other Windows as desired.
Anywhere in your application where you capture, or display, phone
numbers an SMS button can be added. This is a simple call to the SendSms
procedure, passing the CountryDialingCode, the phone number and the
Message for the recipient. any, or all, of these parameters can be empty
strings.
The user will have the opportunity to review, or edit,
the message and the phone number before sending.
(optional) Add calls to the SendSmsViaSmsServer procedure as desired
In many cases it is required to send an automated SMS - one not viewed
or reviewed by the user. This is done by calling the SendSmsViaSmsServer
procedure. This procedure takes a single parameter (a group) which
contains multiple components.
SMSParametersGroup
This group is primed before calling the SendSmsViaSmsServer procedure. The fields inside the group,
used by SendSmsViaSmsServer are as follows;
Property | Description |
pTo (string) | The phone number to send the message
to. |
pMessageText (string) | The text of the message to
send. |
pTest (long) | If this is true then the SendSmsViaSmsServer
window will be displayed to the user as it is sending. |
pCountryDialingcode (string) | The country dialing
code for the phone number. If the phone number contains the
dialing code, and starts with a + character, then this field can
be omitted. |
Return Value
The procedure returns a Long indicating whether the process worked
or not.
Value | Meaning |
-1 | The procedure failed to connect to the
server. The server may be offline, the network connection
may be disconnected, or the server URL may be incorrect. |
11 | Server Error: Program Auth Id Invalid. The
Program Auth ID, as entered in the SMS Settings window, is
not valid. |
12 | Server Error: Program for Auth ID has been
Deleted. The Auth ID is valid, but the program with the Auth
ID has been deleted on the SMS server. |
21 | Server Error: The Company, on the SMS server,
assigned to this Program, is Invalid. |
22 | Server Error: Company for Program Auth ID
Deleted |
23 | Server Error: Company for Program Auth ID Not
Clear to Send. The Company needs to be cleared to send SMSs
by the sms.capesoft.com site administrator. |
31 | Server Error: Client Auth Id Invalid. The
Client Auth ID is not correct. Go to the SMSSettings window
in the program, check the settings there, and click on OK. |
32 | Server Error: Wrong Program Auth Id and
Client Auth Id Combination. The Client Auth ID is not
correct. Go to the SMSSettings window in the program, check
the settings there, and click on OK. |
33 | Server Error: Client for Client Auth ID
Deleted. This client has been deleted on the server. Go to
the sms.capesoft.com server and undelete the client. |
34 | Server Error: Client Not Authorized to send
SMSs. You need to set the client on the server to allow
sending. |
41 | Server Error: No Rates set for Client or
Program. Client rates need to be set for the program, and if
desired for the client as well. |
51 | Server Error: No Phone Number Found. The To
Phone number parameter was empty. |
61 | Server Error: No Service Found. The specified
service on the server does not exist. |
200 | The message was sent successfully. |
201 | The message was sent successfully. |
Example
sms group(SMSParametersGroup).
code
sms.CountryDialingCode = cus:CountryDialingCode
sms.pTo =
cus:PhoneNumber
sms.pMessageText = 'Please visit out web
site at www.capesoft.com'
sms.pTest = false
result = SendSMSviaSMSServer(sms)
Normalized Phone Numbers
Users enter phone numbers into the system in a number of different formats. Some include the country code while others do not. Some include formatting,
such as space or bracket characters, others do not. This can make sorting numbers complicated. It can also hinder phone number matching when matching an incoming
SMS to a customer, or employee and so on.
For simplicity, if your program is going to deal with phone numbers
across multiple countries (in say a customers table, or suppliers table)
then you should capture the country dialing code for that number separate
from the number. This makes the whole process more reliable. An
alternative is to allow users to enter the phone numbers all in one string,
starting with the country dialing code. In this case the number must be
prefixed with the + character.
For this reason the smsLog table stores a field called
NormalizedPhone (String 20). This is a simple way of storing the number, which is
consistent. The user is not expected to see this number. If you want
to link incoming SMS's to other tables, like a customers table, then the
best approach is to add a NormalizedPhone field to that table and link on
that field.
For example
In the example application a Customers table exists. This
contains a regular PhoneNumber field (in this case a String 20). It also
contains a (hidden from the user) field called NormailzedPhone. This is a
String(20) field. It needs to be a string because it contains the +
character. A length of 20 should be sufficient for any phone number in the
world.
In the example application , when a Customers field is saved in the form,
then this field is updated and saved. In the example the code is in the
TakeCompleted method.
ThisWindow.TakeCompleted PROCEDURE
net
NetPhone
code
set(Sss:GuidKey)
Access:SmsSettings.Next()
Cus:NormalizedPhone = net.NormalizePhone(Cus:CountryDialingCode,Cus:PhoneNumber,Sss:DefaultCountryDialingCode)
ReturnValue = PARENT.TakeCompleted()
As you can see the
NormalizePhone method takes three parameters. The Country Dialing Code for
the customer, the Phone Number, and the default Sms setting. If you don't
have the Country Dialing Code in a separate field then just use an empty
string there.
Cus:NormalizedPhone = net.NormalizePhone('',Cus:PhoneNumber,Sss:DefaultCountryDialingCode)
In the example application the Customers table is related to the SMSLog
table by linking Cus:NormalizedPhone to Sms:NormalizedPhone. This then makes
it easy to create a filtered message list for the customer (see the
BrowseCustomers procedure).
[End of this document]