File interface
The file interface is an important and widely used interface for integrating applications with SysMan. The file interface lets SysMan scan a given folder for files containing messages to be sent.
To enable the File interface, check the Enable File interface checkbox.
You can configure one file path to a folder that SysManX will monitor.
You can specify a file type extension to search for, for example "*.TXT" to scan only for files of type text. You may also specify a pattern with wildcards, for example "SMS_*.TXT" to only process files that starts with "SMS_" and has file extension type ".TXT". Nore that Regular Expressions (RegEx) are not allowed.
Files that has been processed by SysManX will by default be deleted. If you want to keep them, you can specify a filetype/extension that it will be renamed to. If a file already exists with the same name as the renamed file it will be overwritten.
If you are renaming the files instead of deleting them we recommend that you limit the number of renamed files by other means (such as a batch-job to move or delete them). The folder should preferrably not contain other files, as a large number of files of other filetypes may slow down the file scanning process.
When using the Free Text File Format (see below) the filename must be a valid number or a Numberlist. If the filename cannot be set to a valid Numberfile (for example if it contains a timestamp) you can specify a default number or Numberlist to send the message to.
Changes are applied when you click the Save button.
The files in the folder can be in various file formats and encodings. The following topics will cover the supported file formats and how to use them.
Legacy SysMan File format
This is a file format used and supported by older SysManSMS Server installations. It is present for backward compatibility.
To use this format, the file should be on the following format:
¡CmdType¡Number¡Message¡client_name¡host_type¡
Sample:
¡SMS¡11223344¡Backup started¡BACKUP_PROGRAM¡Fclient¡
¡SMS¡11223344*¡Backup finished, number of error=0¡BACKUP_PROGRAM¡Fclient¡
Field description:
- CmdType This should always be ”SMS”
- Number This string specifies a legal mobile number. Adding a star “*” to the number to send the SMS as “flash"-message. Adding a plus “+” will enable delivery status. Adding a hash “#” will result in a WakeUp call to the number (no SMS text is sent for WakeUp calls).
- Message This is your SMS message text.
- Client_name Name of the application creating the file, max 64 chars. Included for backward compatibility.
- Host_Type Type of client, this is normally ”Fclient”. Included for backward compatibility.
The character ¡ (decimal value 161) is illegal in the message text since it is used as field separator in the formatting.
To have line breaks in your message text, just insert a
Free Text File format
With the Free Text file format you can send messages by simply creating a textfile containing the message text to send, and name the file with the mobile number of the receiver, or the name of an existing Numberlist.
Example:
This is my free text SMS message.
Save the above text as a file in the folder that SysManX is scanning, and name it with your mobile number and extension of ".TXT" (or other extension as configured above). For example if you name the file "92929292.txt", the message text in this file will be sent to the mobile number 92091312.
If the name of the file matches the name of a Numberlist, then the message will be sent to all active receivers in that Numberlist.
If you need to send multiple messages to the same number or numberlist, you can prefix the filename with "UNIQ-nnnnn-", where nnnnn is a unique number to avoid getting multiple files with the same name. For example, to send two messages to 92929292, create two files named as follows:
UNIQ-22222-92929292.txt
UNIQ-33333-92929292.txt
You may also put multiple messages in a single file. Multiple messages in the same file are separated by a line with a single space only.
SysManX will auto-detect the encoding of files. It supports UTF-8, UTF-16, ISO-8859-1, ASCII as well as many other encodings.
XML file format
The XML file format provides support for reading an XML file containing information about one or more messages to send. If the first line of the file starts with "<!xml" then SysManX will try to parse the file as an XML document. The format is simple with no schema validation:
<?xml version="1.0" encoding="UTF-8"?>
<Messages>
<SMS>
<Number>+4712345678</Number>
<Message>This is my SMS text message</Message>
</SMS>
<SMS>
<Number>+4799999999</Number>
<Number>+4711111111</Number>
<Message>This is my SMS text message</Message>
<LogDeliveryStatus>true</LogDeliveryStatus>
<SendAsFlash>false</SendAsFlash>
<WakeupCall>false</WakeupCall>
<SendTime>2021-08-10T10:00:00</SendTime>
<ExternalId>CUSTOMER_ID_1234</ExternalId>
<IsMasked>true<IsMasked>
</SMS>
</Messages>
The XML must contain a single Messages element with one or more SMS child elements. Each SMS element must contain at least one Number element and one Message element. All other elements are optional.
The Number element can be either a valid mobile number or the name of a Numberlist.
The Message element is the message text to send.
The LogDeliveryStatus element is a boolean value and indicates if a delivery report from the mobile network should be requested or not.
The SendAsFlash element is a boolean value and indicates if the message should be sent as a Flash message or not.
The WakeupCall element is a boolean value and indicates if the message should be a wakeup call or not. If the message is a WakeupCall the modem will only issue a call and not send any SMS message.
The SendTime element can be used to schedule delivery of the message to the given date and time.
The ExternalId element can be set to any string value and can be used to identify the message by an external id. It is possible to query a message based on the ExternalId using the JSON REST API.
The IsMasked element is a boolean value and indicates if the message text should be masked or hidden as "***" by the system.
JSON file format
The JSON file format provides support for reading a JSON file containing information about one or more messages to send. If the first line of the file starts with "{" then SysManX will try to parse the file as an JSON document according to the format shown below:
{
"messages": [
{
"receivers": ["+4711223344"],
"message": "Message text",
},{
"receivers": ["+4711223344", "+4599887766"],
"message": "Message text",
"isFlash": false,
"isDial": false,
"requestDeliveryReport": false,
"delayedSendDateTime": "2021-08-10T10:00:00",
"externalId": "CUSTOMER_ID_1222",
"isMasked": true
},
]
}
The JSON file must contain a messages object at the top level that is an array of messages to be sent. Each object in the array must at least contain an array of receivers and the message to send. All other fields are optional and can be left out. The example above shows a file with two message objects where the first one is a minimal object and the second one also includes all optional fields.
The receivers field is an array of one or more numbers or a name of a Numberlist.
The meaning of each field is in line with the fields in the XML file format above and should be self explanatory.