Chapter 14. Administration

Consider the following hardware requirements for your AmmonitOR installation. Better hardware means more performance while using AmmonitOR. Recommendations are:

For the administration of an AmmonitOR server, you need to be familiar with the following tasks:

For remote installation of AmmonitOR by Ammonit, you have to provide:

In the user administration site users and access rights can be managed. AmmonitOR displays to which projects the user has been invited to and the permissions related to the project. Usernames and passwords can be changed. New users can be added by clicking on add user on the top right. Optionally, full name, company and telephone number can be entered.

Users can be selected via the search box on the site users page. To perform an action, select an users by activating the checkbox in the first column and choose the action from the dropdown list above the user list. Click on Go to perform the selected action.

In the edit mode of a project five attribute fields are available: username, password, personal info, permissions, important dates and project memberships. Additional project memberships per user can be added; three permission types can be selected.

	Important
	By deselecting the active checkbox on the site user edit page, the selected user can be temporarily locked out from AmmonitOR. This feature can be useful in case of spam attacks.

Figure 14.4. Site user administration page

The project administration page provides an overview over all relevant project details: project name, project key, data loggers, project users (members) and available reports.

In order to perform an action, e.g., delete a project or regenerate reports, select one or more projects by activating the checkbox(es) in the first column and choose an action from the dropdown list above. Click on Go to perform the action.

Click on Add project on the top right of the page to set up further projects. The project edit page displays all project details including user memberships. Superusers (see Section 14.2.1, “User administration”) can assign read and write permission to site users. Additionally, users can be added to projects. The Project state indicates whether a project is active or finished.

Figure 14.5. Projects administration page

The data logger administration page lists all available data loggers with serial number, data logger type, name, import email address, firmware version and related projects.

To perform an action, e.g., delete a data logger or reimport missing data files, select one ore more data loggers by activating the checkbox(es) in the first column and choose an action from the dropdown list above. Click on Go to perfom the action.

Click on a data logger serial number to edit data logger details. On the data logger edit page AmmonitOR displays all settings of the data logger, e.g., related projects, serial number, name, import email address (Meteo-32), data logger type and firmware version.

	Important
	Ignore database table names and database model names. Do not edit the fields!

Figure 14.6. Data logger administration page

To setup a custom header logo stated in the left upper corner of the screen you have to add your own logo in three different formats to a folder named logo/active/.

	Important
	The logo section can be found under /usr/share/ammonit-ammonitor/static/css/img/logo/ Apply strictly the naming rules shown in logo/examples/ folder. All icons have to have the correct size!

You can use the examples as template, if you like. Logo customisation affects not only header logo but also the logo used in Emails sent by AmmonitOR or default logo of the reports. Report logos can be customised via UI individually anyways.

	Important
	You have to be logged in on the server's bash and have to have the needed permissions to edit this folders.

Follow this steps to enable the logos:

	Important
	Please be careful and make sure the owner and permissions of these files are correctly set!

Ammonit Measurement GmbH can't be responsible for your customised web page with AmmonitOR instance, so you have to customise the imprint section and when needed also the about page as well as adding legal notes according to your company policies.

	Important
	To edit Imprint and legal notes you need to have permissions to edit the related file directly on the server. The files can be found under /usr/lib/python3/dist-packages/ammonitor/jinja2/info/ There is also a example folder to be found. Place the files directly into this folder. Please be careful and make sure the owner and permissions of these files are correctly set!

The files are standard .txt files, where you can write in HTML and also Jinja2 syntax.

Files to edit are:

To allow Meteo devices sending e-mails to AmmonitOR, the SSH key of the data logger has to be added in AmmonitOR. The SSH key can be downloaded in the Communication → AmmonitOR or the Communication → Online menu of the data logger web interface. Add the SSH key in the Base → SSH keys menu of AmmonitOR. Click on Add ssh key on the top right of the page.

Figure 14.7. SSH key administration page

Copy and past the key into the Public key field. Insert the data logger serial number and save the action. This task has to be done once for each data logger.

Figure 14.8. Add SSH key for a data logger

The raw data file overview page displays a list of raw data files of all available data loggers. AmmonitOR lists all files imported or not yet imported.

Not yet imported raw data files can be imported by choosing the Reimport data option from the dropdown list above. Click on Go to perform the action. The reimport may take few seconds.

It is not possible to make any changes on the data file edit page. However, the page displays further details about the file, e.g., import method, which is called Email Message-ID or username. AmmonitOR displays, which method has been used to import the raw data file, i.e. SCP (Meteo-40, Meteo-40 Plus and Meteo-42), email (Meteo-32) or manual upload. The related configuation file numbers are listed under Config. In the File field the file name in the database is displayed.

Figure 14.9. Raw data file page

The general concept behind the connection of third party applications is usage of http GET request to connect to particular AmmonitOR addresses (urls) to get data and information. The data is returned as response in JSON format, which can be read by the application. It is simmilar to requesting the standard url, but done internally between AmmonitOR and application.

Figure 14.10. User interface to interact with the applications management.

AmmonitOR offers a range of responses for third party applications. The user input parameters to the url are:

List of avaliable requests/responses:

If your application requires more data, information, views or simply you would want to ask us questions about connecting your application to AmmonitOR, feel free to contact us. We are opened for providing more options in our API.

        #!/usr/bin/python3

# Example client for the AmmonitOR REST API
# Copyright 2017 Ammonit Measurement GmbH

import argparse
import json
import sys

import requests

SSL = {
    "disable": False,
    "enable": True
}


def get_options():
    parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter)
    parser.add_argument(
        "-a",
        "--app",
        help="Provide the application name",
        default="Ammonit API example client",
    )
    parser.add_argument("-d", "--device", help="Device serial, e.g. 'D123456'")
    parser.add_argument(
        "-D",
        "--date",
        help="Specify date to get completeness " "e.g. 2017-01-01T00:00:00",
    )
    parser.add_argument("-e", "--export", help="Export ID e.g. 123")
    parser.add_argument(
        "-f",
        "--file",
        help="Device original filename, " "e.g. 'D123456_20160808.csv'",
    )
    parser.add_argument(
        "-F",
        "--date_from",
        help="Specify date from, " "e.g. 2017-01-01T00:00:00",
    )
    parser.add_argument(
        "-i",
        "--filetype",
        help="\n".join(["Specify the type of file:"] + FILE_TYPES),
    )
    parser.add_argument(
        "-p",
        "--project",
        help="AmmonitOR project key, e.g. 'ABCD'",
        required=True,
    )
    parser.add_argument(
        "-s",
        "--server-url",
        help="Server URL to use, e.g. https://or.ammonit.com",
        default="https://or.ammonit.com",
    )
    parser.add_argument(
        "-t",
        "--token",
        help="Token to communicate with AmmonitOR, "
        "coming from requesting the permission view",
    )
    parser.add_argument(
        "-T", "--date_to", help="Specify date to, " ".e.g. 2017-12-31T00:00:00"
    )
    parser.add_argument(
        "-u",
        "--username",
        help="Valid AmmonitOR user, e.g. bach@example.com",
        required=True,
    )
    parser.add_argument(
        "-v",
        "--view",
        help="\n".join(
            ["Avaliable views:"]
            + sorted(
                [
                    "%-12s - %s" % (k, v.__doc__ or "(undocumented)")
                    for k, v in REQUESTABLES.items()
                ]
            )
        ),
        required=True,
    )
    parser.add_argument(
        "-n",
        "--no-ssl",
        help="If no ssl is provided, use this flag to make it work",
        required=False,
        default=False,
    )
    return parser.parse_args()


def format_output(output):
    return json.dumps(json.loads(output.decode("utf-8")), indent=4, sort_keys=True)


def get_token(options, header, no_ssl):
    "make a enquiry for a new app in AmmonitOR"
    url = options.server_url + "/api/auth-token/"
    data = {
        "username": options.username,
        "project_key": options.project,
        "app_id": options.app,
    }
    r = requests.post(url, data, verify=no_ssl)
    print(format_output(r.content))


def list_devices(options, header, no_ssl):
    "list AmmonitOR devices in project"
    if options.project:
        url = options.server_url + "/api/%s/loggers-list/" % (options.project)
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print("Please provide the project key!")


def get_device_data(options, header, no_ssl):
    "get the device metadata"
    if options.project and options.device:
        url = options.server_url + "/api/%s/%s/" % (
            options.project,
            options.device,
        )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print("Please provide the project key and device serial!")


def list_files(options, header, no_ssl):
    "list data files for a device"
    if options.project and options.device and options.filetype:
        url = options.server_url + "/api/%s/%s/files/%s/" % (
            options.project,
            options.device,
            options.filetype,
        )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print("Please provide the project key and device serial!")


def get_download(options, header, no_ssl):
    "download data files of given project and device"
    if options.project and options.device and options.file and options.filetype:
        url = options.server_url + "/api/%s/%s/files/%s/%s/" % (
            options.project,
            options.device,
            options.filetype,
            options.file,
        )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print(
            "Please provide the project key, device serial, "
            " and name of file to be downloaded!"
        )


def list_exports(options, header, no_ssl):
    if options.project and options.device:
        url = options.server_url + "/api/%s/%s/export-list/" % (
            options.project,
            options.device,
        )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print("Please provide the project key and device serial!")


def get_export_download(options, header, no_ssl):
    if options.project and options.device and options.export and options.date_from:
        url = options.server_url + "/api/%s/%s/export/%s/?date_from=%s&date_to=%s" % (
            options.project,
            options.device,
            options.export,
            options.date_from,
            options.date_to,
        )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print(
            "Please provide the project key, device serial, export id and" " date from!"
        )


def get_export_direct_download(options, header, no_ssl):
    if options.project and options.device and options.export and options.date_from:
        url = options.server_url + "/api/%s/%s/export/%s/direct/?date_from=%s&date_to=%s" % (
            options.project,
            options.device,
            options.export,
            options.date_from,
            options.date_to,
        )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print(
            "Please provide the project key, device serial, export id and" " date from!"
        )


def get_completeness_values(options, header, no_ssl):
    if options.project and options.device:
        if options.date_from and options.date_to:
            url = (
                options.server_url
                + "/api/%s/%s/completeness/?date_from=%s&date_to=%s"
                % (
                    options.project,
                    options.device,
                    options.date_from,
                    options.date_to,
                )
            )
        else:
            url = options.server_url + "/api/%s/%s/completeness/" % (
                options.project,
                options.device,
            )
        r = requests.get(url, headers=header, verify=no_ssl)
        print(format_output(r.content))
    else:
        print(
            "Please provide the project key, device serial and optionally"
            " both date from and date_to!"
        )


def get_completeness_day(options, header, no_ssl):
    if options.project and options.device:
        if options.date:
            url = options.server_url + "/api/%s/%s/completeness/day/?date=%s" % (
                options.project,
                options.device,
                options.date,
            )
            r = requests.get(url, headers=header, verify=no_ssl)
            print(format_output(r.content))
        else:
            print("Please provide the date!")
    else:
        print("Please provide the project key and device serial")


def get_connections(options, header, no_ssl):
    if options.project and options.device:
        if options.date_from and options.date_to:
            url = (
                options.server_url
                + "/api/%s/%s/connections/?date_from=%s&date_to=%s"
                % (
                    options.project,
                    options.device,
                    options.date_from,
                    options.date_to,
                )
            )
            r = requests.get(url, headers=header, verify=no_ssl)
            print(format_output(r.content))
        else:
            print("Please provide the date from and to!")
    else:
        print("Please provide the project key and device serial")


REQUESTABLES = {
    "device": get_device_data,
    "download": get_download,
    "export_file": get_export_download,
    "export_file_direct": get_export_direct_download,
    "exports": list_exports,
    "files": list_files,
    "devices": list_devices,
    "permission": get_token,
    "completeness": get_completeness_values,
    "day_completeness": get_completeness_day,
}


FILE_TYPES = ["primary", "secondary", "tertiary", "config", "gust", "logbook"]


if __name__ == "__main__":
    options = get_options()

    header = None
    no_ssl = SSL["enable"]
    if options.no_ssl:
        no_ssl = SSL["disable"]

    if options.view != "permission":
        if options.token:
            header = {"Authorization": "Token " + options.token}
        else:
            print("Please provide the token for authentication!")
            sys.exit(1)

    if options.view in REQUESTABLES.keys():
        REQUESTABLES[options.view](options, header, no_ssl)
    else:
        print("Unknow view '%s'" % options.view)
        print("Use one of " + ", ".join(sorted(REQUESTABLES.keys())))