www.alert-software.

com

DESKALERTS API GUIDE

© 2015

www.deskalerts.com

Reproduction of this guide in whole or in part, by any means whatsoever,

is prohibited without the prior written consent of the publisher.

901 N. Pitt Street, Suite 325

Alexandria, VA 22314

1
 www.alert-software.com

CONTENTS
1. INTEGRATION WITH THIRD-PARTY SOFTWARE ............................................................................................................ 3

2. REST API ........................................................................................................................................................................ 3

2.1 DeskAlerts API – send alerts to Users / Groups / Computers / OUs / IP Groups .................................................... 3

2.2 DeskAlerts API – send instant alerts ....................................................................................................................... 5

2.3 DeskAlerts API – add Users .................................................................................................................................. 5

2.4 DeskAlerts API – add/remove Groups................................................................................................................... 6

2.5 DeskAlerts API – add Users into Groups .............................................................................................................. 8

2.6 DeskAlerts API – Get Alert ................................................................................................................................... 9

3. COMMAND LINE API ................................................................................................................................................... 10

3.1 Synopsis ................................................................................................................................................................ 10

3.2 The following options are available ...................................................................................................................... 11

3.3 Example ................................................................................................................................................................ 13

2
 www.alert-software.com

1. INTEGRATION WITH THIRD-PARTY SOFTWARE

In addition to its other features, DeskAlerts offers a flexible platform that can be integrated with your internal
software to meet virtually any business requirement.

In addition to our standard add-ons, we also offer extensive custom add-ons. We can customize an add-on that
integrates your DeskAlerts solution with any internal system.

Ask sales for more information.

2. REST API

2.1 DeskAlerts API – send alerts to Users / Groups / Computers /

OUs / IP Groups
You can now send alerts to users and groups from within your programs using Send Alert API which is located at :
http://yourserver/deskalerts/api_request.asp

Supported formats: Xml

Supported request methods: POST

Parameters Required:

xml_data

XML data in proper format that will used by server API to send an alert.

api_signature

MD5 of xml_data and API secret that can be found in Deskalerts Control panel settings.

Example of XML for request:

Broadcast alert

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<alert>
<data>
<title><![CDATA[Alert title]]></title>
<text><![CDATA[Alert text]]></text>
<template_id>123</template_id>
<desktop>1</desktop>
<sms>0</sms>
<email>1</email>

3
 www.alert-software.com

</data>
<broadcast/>
</alert>
</darequest>

You can use “desktop”, “sms” and “email” tags in alert/data to specify the type of the alert.
You can use “sms” and “email” tags only if you have such addons installed.

Recipients alert

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<alert>
<data>
<title><![CDATA[Alert title]]></title>
<text><![CDATA[Alert text]]></text>
<template_id>123</template_id>
<desktop>1</desktop>
</data>
<recipients>
<domain name="domain.name">
<recipient type="group" name="group.name1" />
<recipient type="group" name="group.name2" />
<recipient type="user" name="user.name1" />
<recipient type="user" name="user.name2" />
<recipient type="computer" name="computer.name1" />
<recipient type="computer" name="computer.name2" />
<recipient type="ou" name="/Admin/Admin Accounts/Top Level" />
<recipient type="ou" name="/Users/Service Accounts" />
<recipient type="ipgroup" name="ipgroup.name1" />
<recipient type="ipgroup" name="ipgroup.name2" />
</domain>
</recipients>
</alert>
</darequest>
Example response:

<?xml version="1.0" encoding="utf-8"?>

<response>
<method>send_alert</method>
<result>SUCCESS</result>
<id>id of sent alert</id>
<description>Here is the description of error or empty on success</description>
</response>
4
 www.alert-software.com

2.2 DeskAlerts API – send instant alerts

You can now send Instant Alert from within your programs using Send Alert API which is located at :
http://yourserver/deskalerts/api_request.asp

Supported formats: Xml

Supported request methods: POST

Parameters Required:

xml_data

XML data in proper format that will used by server API to send an alert.

api_signature

MD5 of xml_data and API secret that can be found in Deskalerts Control panel settings.

Example of XML for request:

Broadcast alert

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<alert>
<instant>
<alertId>1</alertId>
</instant>
</alert>
</darequest>

To get the emergency alert id for API, hover your mouse over the alert title.

2.3 DeskAlerts API – add Users

Users API is located at http://yourserver/deskalerts/api_request.asp

Supported formats: Xml

Supported request methods: POST

Parameters Required:

xml_data

XML data in proper format that will used by server API to send an alert.

api_signature

5
 www.alert-software.com

MD5 of xml_data and API secret that can be found in Deskalerts Control panel settings.

Example of XML for request:

Add/remove users

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<users>
<domain name="domain.name">
<add>
<user username="user1" password="password1" email="sample@domain.com" phone="1-800-555-
1234" displayname="Mike Lamber" />
<user username="user2" password="password1"/>
<user username="user3" password="password1"/>
</add>
<modify>
<user oldname="user1" username="user7" password="password1" email="sample@domain.com"
phone="1-800-555-1234" displayname="Mike Lamber" />
</modify>
<remove>
<user username="user5"/>
<user username="user6"/>
</remove>
</domain>
</users>
</darequest>

Example response:

<?xml version="1.0" encoding="utf-8"?>

<response>
<method>users</method>
<result>SUCCESS</result>
<description>Here is the description of error or empty on success</description>
</response>

2.4 DeskAlerts API – add/remove Groups

Groups API is located at : http://yourserver/deskalerts/api_request.asp

Supported formats: Xml

Supported request methods: POST

6
 www.alert-software.com

Parameters Required:

xml_data

XML data in proper format that will used by server API to send an alert.

api_signature

MD5 of xml_data and API secret that can be found in Deskalerts Control panel settings.

Example of XML for request:

Add/modify/remove groups

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<groups>
<domain name="domain.name">
<add>
<group name="group.name1" />
<group name="group.name2" />
<group name="group.name3" />
</add>
<modify>
<group oldname="group.name1" name="group.name6" />
</modify>
<remove>
<group name="group.name4" />
<group name="group.name5" />
</remove>
</domain>
</groups>
</darequest>

Example response:

<?xml version="1.0" encoding="utf-8"?>

<response>
<method>groups</method>
<result>SUCCESS</result>
<description>Here is the description of error or empty on success</description>
</response>

7
 www.alert-software.com

2.5 DeskAlerts API – add Users into Groups

Group Members API is located at : http://yourserver/deskalerts/api_request.asp

Supported formats: Xml

Supported request methods: POST

Parameters Required:

xml_data

XML data in proper format that will used by server API to send an alert.

api_signature

MD5 of xml_data and API secret that can be found in Deskalerts Control panel settings.

Example of XML for request:

Add/remove group members

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<members>
<domain name="domain.name">
<group name="group1.name">
<add>
<user username="user1.name" />
<user username="user2.name" />
<user username="user3.name" />
</add>
<remove>
<user username="user3.name" />
<user username="user4.name" />
</remove>
</group>
</domain>
</members>
</darequest>

Example response:

<?xml version="1.0" encoding="utf-8"?>

<response>
<method>group_members</method>
<result>SUCCESS</result>

8
 www.alert-software.com

<description>Here is the description of error or empty on success</description>

</response>

2.6 DeskAlerts API – Get Alert

API Groups Method URL: http://yourserver/deskalerts/api_request.asp

Supported formats: Xml

Supported request methods: POST

Parameters Required:

xml_data

XML data in proper format that will used by server API to get an alert.

api_signature

MD5 of xml_data and API secret that can be found in Deskalerts Control panel settings.

Example of XML for request:

Get alert

<?xml version="1.0" encoding="utf-8"?>

<darequest>
<getalert>
<username>UserName</username>
<hash>32c9193dba2a72e4605916007759486f</hash>
<computer>ComputerName</computer>
<domain>yourdomain.net</domain>
<count>2</count>
<ticker>0</ticker>
</getalert>
</darequest>

Username – name of user

Hash – MD5 of username+API secret (if there are computer and domain parameters, then MD5 of
username+computer+domain+API secret)
Computer – name of computer
Domain – name of domain
Count – number of alerts in response
Ticker – 0 means “get popup type of alerts”, 1 means “get ticker type of alerts”

Example response:
9
 www.alert-software.com

<TOOLBAR>
<ALERT id="alert" href="http://yourserver/deskalerts/get_alert.asp?id=2&amp;user_id=2"
timeout="-1" expire="" plugin="alert:ID3" priority="1" acknown="0" autoclose="0" alert_id="2"
user_id="2" create_date="1308044751" utc="1" title="Test alert" position="" width="500"
height="400" ticker="0" survey="0" schedule="0" urgent="0" history="1"/>
</TOOLBAR>

Href – URL to get alert html body

3. COMMAND LINE API

3.1 Synopsis
DeskAlertsAPI.exe [/url=text] [/key=text] [/conf=text] [/body=text] [/bodyfile=text] [/title=text] [/plaintext]
[/titlefrombody] [/desktop|/desktop=1] [/sms|/sms=1] [/email|/email=1] [/email_sender=text] [/urgent|/ urgent=1]
[/ticker|/ticker=1] [/fullscreen|/fullscreen=1] [/width=integer] [/height=integer] [/acknow] [/lifetime=integer]
[/template_id=integer] [/autoclose=integer [/manualclose]] [/xml=text] [/xmlfile=text] [/bodyisxml]
[/acp|/utf8|/utf16|/encode=integer] [/bodyacp|/bodyutf8|/bodyutf16|/bodyencode=integer]
[/confacp|/confutf8|/confutf16|/confencode=integer] [/user=string [/user=string [/u=string ...]]] [/group=string
[/group=string [/g=string ...]]] [/comp=string [/comp=string [/c=string ...]]] [/ou=string [/ou=string [/o=string ...]]]
[[/u|g|c|o=string] [/domain=string [/u|g|c|o=string]]] [/pause] [/help|/h|/? [command]]

10
 www.alert-software.com

3.2 The following options are available

/url=text Set URL to server API script. For example:
http://yourserver/deskalerts/api_request.asp

/key=text Set API secret key for request signing. You can find it on DeskAlerts Control Panel
system configuration page.

/conf=text Set path to configuration file. Any other options can be read from this file. Without
this option application will try to read DeskAlertsAPI.conf file.

/body=text Set alert text.

/bodyfile=text Set path to file with alert text.

/title=text Set alert title.

/plaintext Start working with alert text as plain text without HTML formatting.

/titlefrombody Cut first line from alert body and use it as alert title.

/user=name Specify user(s) as recipient(s).

/u=name

/group=name Specify group(s) as recipient(s).

/g=name

/domain=name Next recipients will be parsed as members of this domain. Use as

/d=name "/d=yourdomain.local".

/ou=ou_path Specify OU(s) as recipient(s). Use OU path as "/o=yourdomain.local/FirstOU/SubOU".

/o=ou_path

/comp=name Specify computer(s) as recipient(s).

/c=name

/desktop Send alert to desktop.

/desktop=1

/sms Send SMS alert (only if you have SMS add-on installed).
/sms=1

/email Send email alert (only if you have email add-on installed).
/email=1

/email_sender=text Set sender name of email alert.

11
 www.alert-software.com

/urgent Send urgent alert. It appears even if user disabled DeskAlerts Client, always on top of
/urgent =1 any other alerts.

/ticker Send scrolling in ticker alert.

/ticker=1

/fullscreen Send full screen alert.

/fullscreen=1

/width=integer Set alert window width.

/height=integer Set alert window height.

/acknow Send acknowledgement alert. Alert will require reading confirmation.

/lifetime=integer Set alert lifetime. Alert can be received for specified period of time in minutes from
now.

/template_id=integer Set style template id. You can find it on DA Control Panel style templates page.

/autoclose=integer Set auto-close time in minutes. The alert will appear on the screen for the given time
/manualclose period and then it will disappear automatically. And "manualclose" is ability to close
the alert manually in case of auto-close setting active.

/xml=text Set entire XML. Just sign it and send request.

/xmlfile=text Set path to a file with entire XML. Just sign its data and send request.

/bodyisxml Body entire is XML. Just sign it and send request.

/acp Set encoding for all reading files. Where "acp" is system defined ANSI, "utf8" is
/utf8 UTF8=65001, "utf16" is UTF16LE=1200.
/utf16
/encode=integer

/bodyacp Set encoding for reading alert body or xml data from stdin(0) or "bodyfile" or
/bodyutf8 "xmlfile". Where "bodyacp" is system defined ANSI, "bodyutf8" is UTF8=65001,
/bodyutf16 "bodyutf16" is UTF16LE=1200.
/bodyencode=integer

/confacp Set encoding for reading configuration file. Where "confacp" is system defined ANSI,
/confutf8 "confutf8" is UTF8=65001, "confutf16" is UTF16LE=1200.
/confutf16
/confencode=integer

/? Show entire help or help for specified command.

/? command

12
 www.alert-software.com

/alertid=id Set instant alert for sending instant message. To get the emergency alert id for API,
hover your mouse over the alert title.

3.3 Example
a) Example on how to send sample plaint text to desktop, sms, email for all users:

DeskAlertsAPI.exe /url= http://yourserver/deskalerts/api_request.asp /key=Hnsa73qa4 "/body=Example alert text"

"/title=Example alert title" /plaintext /desktop /sms /email /email_sender=admin /broadcast

b) Example on how to send sample plaint text to desktop only for specified user and group in domain:

DeskAlertsAPI.exe /url= http://yourserver/deskalerts/api_request.asp /key=Hnsa73qa4 "/body=Example alert text"

"/title=Example alert title" /plaintext /desktop /sms /email /email_sender=admin /domain=domain.local /user
Administrator " /group=Domain Admins"

с) Example on how to send sample instant alert:

DeskAlertsAPI.exe /url= http://yourserver/deskalerts/api_request.asp /key= Hnsa73qa4 "/alertid=518"

13