Batch Access API

This manual describes the Batch Access API of the IACBOX and what is possible with it.

Hint

  • The Batch Access API is available on IACBOX version 5.0.7615 (p7742) or newer.

  • Some functions were added later on. Ensure to update to the most recent version of the IACBOX in order to access all functions listed in this manual.

  • The requesting client must have access to the IACBOX WebAdmin interface.

General

With the Batch Access API it is possible to export and import data, as well as to trigger some actions on the IACBOX.

Export Data:

  • Statistics

  • Connection Tracking

  • Application Log

  • System Log

  • Messaging Data

  • Current User Info

  • License Info

  • System Info

  • Version

  • Ticket Templates

  • GDPR Data Processing Register Report

  • Ticket Data

Ticket Commands:

  • Create

  • Log off

  • Revoke

Autologin Devices:

  • Create an Autologin Device

  • Delete an Autologin Device

  • Import a List of Autologin Devices

System Commands:

  • System Reboot/Poweroff (UPS operation support)

  • System Backup

  • Start Online Update

  • Update Log List

  • Export Update Log

Usage

In order to obtain or send data, a HTTP POST must be sent to the Batch Access API interface. This can be done using scripted tools as well as with PHP or other programming environment. In this manual we use cURL for demonstration purposes. cURL is a simple command line tool for alot of different Operating System and also available as PHP extension.

The software (source and binaries (e.g. Windows binaries, x64 SSL version) can be obtained here: https://curl.haxx.se/download.html

After downloading & extracting the binaries into the system32 directory, so that cURL will become available within the Windows command line.

Authentication

The access is restricted by a username and a password. For easy test the user sysop could be used, but this is not recommended as the password has to be saved in the script. Instead create a new user on the system and allow only the needed rights to this user. Some general actions that don’t map to a certain menu need the right for System / Services.

Use the command insecure if you don’t want libcurl to verify the SSL/TLS certificate of the peer.

With the lang data you specify the WebAdmin language that should be used for the cURL call. This has influence on some of the exportable data and means that the returend data will be in the specified language. The following languages are available:

  • en_US = english

  • de_DE = german

  • it_IT = italian

  • fr_FR = francais

In all examples below please replace <USERNAME> and <PASSWORD> with your created user.

Export Data

This section will explain how to extract data from the IACBOX according to the list on top of this manual.

Statistics

Statistics includes tickets or revenue, which both are available in csv or xls format. Exports can be filtered by from_date and to_date. Optional fields are:

  • export_id: Returns the ticket ids as first column value. With the ticket id it is possible to send further commands.

  • search_text: Search for specific ticket names or ticket descriptions, also MAC addresses (e.g. AA:BB:CC:11:22:33 and aabbcc112233) are recognized.

  • issuer: Search for tickets which were created by a specific user/service (e.g. sysop).

  • revoked: Either show all tickets that have been revoked (1) or all tickets which have not been revoked (0).

cURL command to retrieve tickets from device AA:BB:CC:11:22:33 between 01.01.2019 and 31.01.2019 which were revoked:

1
2
3
4
curl --insecure -o tickets.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=statistics&download=tickets&dataformat=csv&from_date=2019.01.01 00:00:00
&to_date=2019.01.31 23:59:59&export_id=1&search_text=AA:BB:CC:11:22:33
&issuer=sysop&revoked=1" https://192.168.1.1/batch.php

Connection Tracking

Includes proxy and conntrack data which both are available in csv or raw format. Exports can be filtered by from_date and to_date. Optional fields are:

  • search_text: Search for websites, connections, IP addresses or MAC addresses.

cURL command to retrieve connection tracking proxy data which contains the string amazon between 01.01.2019 and 31.02.2019:

1
2
3
curl --insecure -o proxy_log.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=connection_tracking&download=proxy&dataformat=csv&from_date=2019.01.0100:00:00
&to_date=2019.01.31 23:59:59&search_text=amazon" https://192.168.1.1/batch.php

Application Log

The Application Log of the WebAdmin menu System / Application log. Can be exported in csv or xls format and filtered by from_date and to_date. Optional fields are:

  • search_text: Filter the logs with a specific search text.

cURL command to export all Application Logs between 01.01.2019 and 31.01.2019 which include the search_text “logon”.

1
2
3
curl --insecure -o application_log.csv --data "username=<USER>&password=<PASSWORD>
&action=application_log&download=logdata&dataformat=csv&from_date=2019.01.0100:00:00
&to_date=2019.01.31 23:59:59&search_text=logon" https://192.168.1.1/batch.php

Application Log Tickets only

Exports only Application Logs which are caused by tickets, e.g. a ticket login or logoff. Can be exported in csv or xls format and filtered by from_date and to_date. Optional fields are:

  • hide_msg: Extended log messages will not be exportet.

  • search_text: Filter the logs with a specific search text.

cURL command to export all Application Logs related to ticket actions between 01.01.2019 and 31.01.2019 which also include the search_text “logon” but without extended log messages.

1
2
3
curl --insecure -o application_log.csv --data "username=<USER>&password=<PASSWORD>
&action=application_log&download=logdata&dataformat=csv&from_date=2019.01.01 00:00:00
&to_date=2019.01.31 23:59:59&hide_msg=1&search_text=logon" https://192.168.1.1/batch.php

System Logs

Exports system or mail logs, selectable by generations, e.g. generation 0 means today and generation 1 means yesterday. Only the last 7 days are available.

Hint

  • The output is a compressed gzip file.

cURL command to export the compressed system logs from today.

1
2
curl --insecure -o system_log.zip --data "username=<USER>&password=<PASSWORD>&action=system_log&
download=system&generation=0" https://192.168.1.1/batch.php

List DataCollector Templates

Returns all available datacollector templates in json format. The returned template id’s can be used to query specific messaging data (see below).

1
2
curl --insecure -o templates.jsn --data "username=<USER>&password=<PASSWORD>
&action=dtc_templates&subaction=get_templates" https://192.168.1.1/batch.php

Messaging Data

Exports Messaging Data which was previously obtained by messaging modules. Can be exported as csv and xls and filtered by from_date and to_date. The following data-types are possible for download:

  • email: Email addresses which were used to create tickets with the Email module.

  • sms: Phone numbers which were used to create ticket with the SMS module.

  • social: Email addresses which were used to create tickets by logging in with the Social module, e.g. Facebook or Google+.

  • tkrq: Email addresses which were used to send a request via the Email ticket request module.

  • dtc: Data which was obtained by using the Data Collector.

  • dtc_template: Datacollector template id that should be queried. Needed if download data-type is dtc.

cURL command to export data which was gathered by the Email ticket request module between 01.01.2019 and 31.01.2019.

1
2
3
curl --insecure -o messaging_data.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=messaging&download=tkrq&dataformat=csv&from_date=2019.01.0100:00:00
&to_date=2019.01.31 23:59:59" https://192.168.1.1/batch.php

cURL command to export data which was gathered by the Data Collector template 912 between 01.01.2019 and 31.01.2019.

1
2
3
curl --insecure -o messaging_data.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=messaging&download=dtc&dtc_template=912&dataformat=csv&from_date=2019.01.0100:00:00
&to_date=2019.01.31 23:59:59" https://192.168.1.1/batch.php

User Info

Returns online and maximum concurrent users in json format.

1
2
curl --insecure -o userinfo.jsn --data "username=<USER>&password=<PASSWORD>&action=json
&want=userinfo "https://192.168.1.1/batch.php

License Info

Returns license data and licensed modules in json format.

1
2
curl --insecure -o licenseinfo.jsn --data "username=<USER>&password=<PASSWORD>&action=json
&want=licenseinfo" https://192.168.1.1/batch.php

System Info

Returns CPU load, memory usage and hdd usage in json format.

1
2
curl --insecure -o systeminfo.jsn --data "username=<USER>&password=<PASSWORD>&action=json
&want=systeminfo" https://192.168.1.1/batch.php

Version

Returns software version, patchlevel and release date of the IACBOX in json format.

1
2
curl --insecure -o version.jsn --data "username=<USER>&password=<PASSWORD>&action=json
&want=version" https://192.168.1.1/batch.php

List Ticket Templates

Returns all available ticket templates in json format.

1
2
curl --insecure -o templates.jsn --data "username=<USER>&password=<PASSWORD>
&action=templates&subaction=get_templates" https://192.168.1.1/batch.php

List Ticket Printers

Returns all available ticket printers in json format with the printer id’s as keys.

1
2
curl --insecure -o templates.jsn --data "username=<USER>&password=<PASSWORD>
&action=printers&subaction=get_printers" https://192.168.1.1/batch.php

Get last GDPR Data Processing Register Report

Returns the last GDPR Data Processing Register Report as .pdf file. If there was no report created yet, create and return a new one. If a new report needs to be created, the settings from the WebAdmin menu Settings / Privacy Toolkit will be used.

Hint

  • In order to use this Batch Access API call, the Privacy Toolkit Module must be licensed.

1
2
curl --insecure -o report.pdf --data "username=<USER>&password=<PASSWORD>
&action=privacy_report" https://192.168.1.1/batch.php

Ticket Data

Returns Ticket Data from the WebAdmin menu Users/Tickets / Overview. The returned data format is .CSV. The format for the time-span can be either YYYY.MM.DD hh:mm:ss or YYYY-MM-DD hh:mm:ss.

1.) cURL command to return all tickets created within a given time-span (from_date - to_date). If no from_date and to_date is provided, all tickets from now until 24 hours back are returned.

1
2
3
curl --insecure -o all_tickets.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=get_ticket_data&ticket_type=all&from_date=2018.07.01 00:00:00
&to_date=2018.07.10 23:59:59" https://192.168.1.1/batch.php

2.) cURL command to return used tickets that are still valid and were created within a given time-span (from_date - to_date). If no from_date and to_date is provided, all tickets from now until 24 hours back are returned.

1
2
3
curl --insecure -o used_tickets.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=get_ticket_data&ticket_type=used&from_date=2018.07.01 00:00:00
&to_date=2018.07.10 23:59:59" https://192.168.1.1/batch.php

3.) cURL command to return unused tickets that are still valid and were created within a given time-span (from_date - to_date). If no from_date and to_date is provided, all tickets from now until 24 hours back are returned.

1
2
3
curl --insecure -o unused_tickets.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=get_ticket_data&ticket_type=unused&from_date=2018.07.01 00:00:00
&to_date=2018.07.10 23:59:59" https://192.168.1.1/batch.php

4.) cURL command to return all tickets that are currently online.

1
2
curl --insecure -o online_tickets.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=get_ticket_data&ticket_type=online" https://192.168.1.1/batch.php

5.) cURL command to return all invalid tickets.

1
2
curl --insecure -o invalid_tickets.csv --data "lang=en_US&username=<USER>&password=<PASSWORD>
&action=get_ticket_data&ticket_type=invalid" https://192.168.1.1/batch.php

Ticket Commands

Ticket Create

Create tickets based on a specified template (by id).

Hint

Ticket Create via Batch Access API is available on IACBOX version 17 or newer.

Required parameter is use_template.

  • use_template - template_id to use for ticket create (see List Ticket Templates)

Optional parameters are:

  • return_userdata (1) - returns username, password and ID of created ticket

  • tk_username - specify a custom username for the new ticket

  • tk_password - specify a custom password for the new ticket (min. length = 4 characters; 7 characters for password only tickets)

  • description - add custom description to created ticket. User specific data fields can also be added like this: “description=name:john;email:mail@example.com;”

  • expiration (Days / > 0) - overwrite template expiration period

  • time_credit (Min. / > 0) - overwrite template time_credit

  • ticket_limit (MB / > 0) - overwrite template ticket_limit

  • session_limit (MB / > 0) - overwrite template session_limit

  • idle_timeout (Min. / > 0) - overwrite template idle_timeout

  • bw_in (Kbit/s / > 64) - overwrite template download_bandwidth

  • bw_out (Kbit/s / > 64) - overwrite template upload_bandwidth

  • set_online (1) - set given device (MAC-Address) online with created ticket

  • device_mac (MAC-Address) - MAC-Address of the device which should be set online on next connect. This is needed for set_online option.

  • printer_id (int) - ticket printer id on which the created ticket will be printerd (see List Ticket Printers on how to obtain the printer id)

Create ticket example

1
2
3
4
curl --insecure --data "username=<USER>&password=<PASSWORD>&action=create&subaction=create_ticket
&use_template=248&return_userdata=1&expiration=15&time_credit=77&ticket_limit=1234&session_limit=123
&idle_timeout=99&bw_in=25000&tk_username=myticket&tk_password=mysecret&set_online=1
&device_mac=AA:BB:CC:11:22:33" https://192.168.1.1/batch.php

Create ticket example with simple custom description

1
2
3
4
5
curl --insecure --data "username=<USER>&password=<PASSWORD>&action=create&subaction=create_ticket
&use_template=248&return_userdata=1&expiration=15&time_credit=77&ticket_limit=1234&session_limit=123
&idle_timeout=99&bw_in=25000&tk_username=myticket&tk_password=mysecret&set_online=1
&device_mac=AA:BB:CC:11:22:33&description=for room number 123"
https://192.168.1.1/batch.php

Create ticket example with custom description used for user data

1
2
3
4
5
curl --insecure --data "username=<USER>&password=<PASSWORD>&action=create&subaction=create_ticket
&use_template=248&return_userdata=1&expiration=15&time_credit=77&ticket_limit=1234&session_limit=123
&idle_timeout=99&bw_in=25000&tk_username=myticket&tk_password=mysecret&set_online=1
&device_mac=AA:BB:CC:11:22:33&description=Name:John;Patient Number:123;Email:mail@test.com"
https://192.168.1.1/batch.php

Ticket Logout

Logout certain tickets based on the ticket id. This also works with multiple ticket ids.

1
2
curl --insecure --data "username=<USER>&password=<PASSWORD>&action=manage_ticket
&subaction=logout&ids=12,22,540,299" https://192.168.1.1/batch.php

Ticket Revoke

Revoke certain tickets based on the ticket id. This also works with multiple ticket ids.

1
2
curl --insecure --data "username=<USER>&password=<PASSWORD>&action=manage_ticket
&subaction=revoke&ids=12,22,540,299" https://192.168.1.1/batch.php

Autologin Devices

Create a new Autologin Device

Add an autologin device as either static or dynamic device. Optional autologin types are:

  • type=static: Adds the autologin device as a static device. Requires parameters mac and ip.

  • type=dyn_mac: Adds the autologin device as a dynamic device identified via MAC address. Requires parameter mac.

  • type=dyn_ip: Adds the autologin device as a dynamic device identified via IP address. Requires parameter ip

  • type=wildcard_mac: Adds a wildcard entry to affect multiple devices at once via MAC address. Requires parameter mac. Valid formats are AA:BB:CC:11:22:33, AA:*:CC:*:22:* and AA:??:CC:??:22:??.

  • type=wildcard_ip: Adds a wildcard entry to affect multiple devices at once via IP address. Requires parameter ip. Valid formats are 172.30.3.54, 172.30.3.* and 172.30.3.??.

Following parameters are available:

  • return_userdata: Can be used when adding a new autologin device. If value is 1, returns the autologin device id.

  • device_id: When removing an autologin device, the device_id must be specified.

  • mac: Used when adding a static device or a wildcard via MAC address device.

  • ip: Used when adding a static device or a wildcard via IP address device.

  • desc: For static autologin devices, this will become the name. For all other types, this is the description.

  • ticket_limit: Ticket limit in MB. Can be used while adding a new autologin device. If the ticket limit is used up, the ticket will be revoked and recreated.

  • session_limit: Session limit in MB. Can be used while adding a new autologin device. If the session limit is used up, the ticket will be logged off. If the device is still in the network, it will automatically be logged in again.

  • idle_timout: Defines the time a ticket will be logged off when the device is completely inactive (turned off or not in the network anymore).

  • bw_in: The download bandwidth in Kbit/s for new autologin entries.

  • bw_out: The upload bandwidth in Kbit/s for new autologin entries.

cURL command to add a new static autologin device with the MAC address AB:12:34:34:56:FF and IP address 172.30.3.54. The added device is called Batch_Test. The ticket limits for this device should be 1234 MB as session limit, 5678 MB as ticket limit and 20.000 Kbit/s as download and upload bandwidth:

1
2
3
4
curl --insecure -o created_autologin_device_id.tmp --data "username=<USER>&password=<PASSWORD>
&action=autologon_devices&subaction=add_device&type=static&mac=AB:12:34:34:56:FF
&ip=172.30.3.54&desc=Batch_Test&ticket_limit=5678&session_limit=1234&bw_in=20000
&bw_out=20000" https://192.168.1.1/batch.php

cURL command to add a single dynamic MAC device with the MAC address AB:12:34:34:56:FF. The device description should be Batch_Test and the idle timout 30 minutes. The ticket limits for this device should be 1234 MB as session limit, 5678 MB as ticket limit and 20.000 Kbit/s as download and upload bandwidth:

1
2
3
4
curl --insecure -o created_autologin_device_id.tmp --data "username=<USER>&password=<PASSWORD>
&action=autologon_devices&subaction=add_device&type=dyn_mac&mac=AB:12:34:34:56:FF
&desc=Batch_Test&ticket_limit=5678&session_limit=1234&idle_timeout=30&bw_in=20000
&bw_out=20000" https://192.168.1.1/batch.php

cURL command to add a single dynamic IP device with the IP address 172.30.3.122. The device description should be Batch_Test and the idle timout 30 minutes. The ticket limits for this device should be 1234 MB as session limit, 5678 MB as ticket limit and 20.000 Kbit/s as download and upload bandwidth:

1
2
3
4
curl --insecure -o created_autologin_device_id.tmp --data "username=<USER>&password=<PASSWORD>
&action=autologon_devices&subaction=add_device&type=dyn_ip&ip=172.30.3.122
&desc=Batch_Test&ticket_limit=5678&session_limit=1234&idle_timeout=30&bw_in=20000
&bw_out=20000" https://192.168.1.1/batch.php

cURL command to add a wildcard MAC entry, so that all devices which apply to the MAC address wildcard AB:12:CD:34:*:F5 will be recognized as an autologin device and get an according ticket. The device description should be Batch_Test and the idle timout 30 minutes. The ticket limits for this entry should be 1234 MB as session limit, 5678 MB as ticket limit and 20.000 Kbit/s as download and upload bandwidth:

1
2
3
4
curl --insecure -o created_autologin_device_id.tmp --data "username=<USER>&password=<PASSWORD>
&action=autologon_devices&subaction=add_device&type=wildcard_mac&mac=AB:12:CD:34:*:F5
&desc=Batch_Test&ticket_limit=5678&session_limit=1234&idle_timeout=30&bw_in=20000
&bw_out=20000" https://192.168.1.1/batch.php

cURL command to add a wildcard IP entry, so that all devices which apply to the IP address wildcard 172.30.3.* will be recognized as an autologin device and get an according ticket. The device description should be Batch_Test and the idle timout 30 minutes. The ticket limits for this entry should be 1234 MB as session limit, 5678 MB as ticket limit and 20.000 Kbit/s as download and upload bandwidth:

1
2
3
4
curl --insecure -o created_autologin_device_id.tmp --data "username=<USER>&password=<PASSWORD>
&action=autologon_devices&subaction=add_device&type=wildcard_ip&ip=172.30.3.*
&desc=Batch_Test&ticket_limit=5678&session_limit=1234&idle_timeout=30&bw_in=20000
&bw_out=20000" https://192.168.1.1/batch.php

cURL command to remove a static autologin device, in this example the id 111.

1
2
curl --insecure -o log.tmp --data "username=<USER>&password=<PASSWORD>&action=autologon_devices
&subaction=remove_device&type=static&device_id=111" https://192.168.1.1/batch.php

cURL command to remove a dynamic autologin device, in this example the id 222. The type dynamic must be used for all according types which includes dyn_mac, dyn_ip, wildcard_mac and wildcard_ip.

1
2
curl --insecure -o log.tmp --data "username=<USER>&password=<PASSWORD>&action=autologon_devices
&subaction=remove_device&type=dynamic&device_id=222" https://192.168.1.1/batch.php

To automatically revoke tickets together with an autologin entry, add the POST parameter del_ticket=1. Note that this does only work for single dynamic autologin entries but not for wildcard entries.

1
2
curl --insecure -o log.tmp --data "username=<USER>&password=<PASSWORD>&action=autologon_devices
&subaction=remove_device&type=dynamic&device_id=222&del_ticket=1" https://192.168.1.1/batch.php

Hint

  • A possibility to upload lists with multiple autologin devices is scheduled for one of the next updates.

System Commands

Reboot System

Supported since 17.0.11166-p11393. Rebooting an IACBOX via Batch Access API by:

1
2
curl --insecure --data "username=<USER>&password=<PASSWORD>
&action=services&subaction=reboot" https://192.168.1.1/batch.php

Poweroff System

Supported since 17.0.11166-p11393. In order to support UPS operation (automatic shutdown of the IACBOX in UPS operation), shutting down IACBOX can be done with this call:

1
2
curl --insecure --data "username=<USER>&password=<PASSWORD>
&action=services&subaction=halt" https://192.168.1.1/batch.php

Export Backup

Exports and returns a system backup.

1
2
curl --insecure -o backup.bkp --data "username=<USER>&password=<PASSWORD>
&backup=1" https://192.168.1.1/download_backup.php

Online Update

Start the online update on the selected IACBOX from outside.

1
2
curl --insecure -o update.tmp --data "username=<USER>&password=<PASSWORD>&action=online_update
&subaction=doupdate" https://192.168.1.1/batch.php

Download Update-Log Lists

Returns a list with all available logfiles from the online update (not the actual logs).

1
2
curl --insecure -o logfiles.tmp --data "username=<USER>&password=<PASSWORD>&action=online_update
&subaction=list_log_files" https://192.168.1.1/batch.php

Export Update Log

Exports a specific update log from all available log files on the IACBOX.

1
2
3
curl --nsecure -o logfiles.tmp --data "username=<USER>&password=<PASSWORD>&action=online_update
&subaction=fetch_log_files&logfiles=onlupdate_20160621132007.log;
onlupdate_20160621043642.log" https://192.168.1.1/batch.php