How To

• 1: Alarms
• 2: Manage Devices
• 2.1: Add Linux Device
• 2.2: Add Windows Device
• 2.3: Add Windows Client
• 2.4: Import Devices
• 3: Manage Models
• 4: Manage Users
• 5: Test Telemetry
• 6: Update Agent

1 - Alarms

maiLink uses alarms to help users identify problems with devices in the field. Alarms are set by workflows, and once set, can be see in different places in the user interface.

You team can define different alarms for different purposes. An example might be the following set of four alarms:

Note: Alarms span workflows, meaning that multiple workflows can set the same alarm.
Note: Alarms can also span models, although maiData discourages that.

• Caution: It is strongly recommended that you do not create alarms for use on multiple models.
• Caution: A future release will include further information in the definition of an alarm that will make sharing alarms across models undesireable.

Alarms

Displaying Alarms

Alarms are displayed to users in several places:

1. Click on the Devices selection in the maiLink UI top bar.
   • Any device (row) with an Alarm icon (🔔) has alarms that are currently set.
   • The number of alarms is shown with that icon.
2. Navigate to a Devices > Device page.
   • In the lefthand menu the Alarms side tab selection may show an Alarm icon (🔔).
   • It will be displayed if any alarms are set for this device.
   • The number of alarms currently set is shown with that icon.
3. Navigate to a Devices > Device > Alarms page.
   • The table indicates a history of all the alarms that have been set.
   • Active alarms are shown with the Alarm icon (🔔).
   • The number of alarms since the first alarm, or since the alarms were last cleared is also shown.

Defining Alarms

Alarms are a simple concept. Each has a name and a description. To create Alarms:

1. Navigate to Settings (⚙).
2. Select Alarm Definitions on the lefthand tabs.
3. Click on Create Alarm to add a new alarm. Make sure the name of the alarm is unique.

Setting and Clearing Alarms

Setting Alarms

Alarms are set by workflows. Within a workflow you can add a Set an Alarm workflow step. You will be asked to select the name of the Alarm that you want to set from the list of Alarm Definitions. When the workflow is triggered, when it reaches the Set an Alarm step

1. Navigate to Settings (⚙).
2. Select Alarm Definitions on the lefthand tabs.
3. Click on Create Alarm to add a new alarm. Make sure the name of the alarm is unique.

Clearing Alarms

Clearing alarms is the way that service technicians can indicate that resolution has been acheived. This is not a substitute for your standard service processes for documentation, but it does let clean up the user interface for the next service shift.

1. Navigate to Devices > Device > Alarms.
2. On a row with active alarms, click the Clear button.

Resetting Alarms

Resetting alarms may seem a little odd, but it is meant for the situation where perhaps something was not resolved as well as once thought, so the service technician wants to flag it for the next team.

1. Navigate to Devices > Device > Alarms.
2. On a row with cleared alarms, click the Reset button.

2 - Manage Devices

2.1 - Add Linux Device

Prerequisites

1. You have administrator rights to install software

Step 1: Begin installing Agent software on remote device

1. In a browser, log into your maiLink account at app.maidata.io.
2. Navigate to the Software tab.
3. Locate the proper version, for example 64bit linux, mailink-agent_{version}_linux_amd64.deb, right click and copy the Link/URL.
4. Go to your Terminal window and navigate to your home directory run the following command. Your coppied url will vary.

wget https://github.com/maiData/releases/releases/download/{version}/mailink-agent_{version}_linux_amd64.deb

1. Run the following command (replacing version) in the directory you have transfered the .deb file to.

sudo apt install ./mailink-agent_{version}_linux_amd64.deb

Output

Reading package lists... Done
Building dependency tree
Reading state information... Done
Note, selecting 'mailink' instead of './mailink-agent_22.5.3_linux_amd64.deb'
The following NEW packages will be installed:
  mailink
0 upgraded, 1 newly installed, 0 to remove and 105 not upgraded.
After this operation, 13.8 MB of additional disk space will be used.
Get:1 /home/maidata/Downloads/mailink-agent_22.5.3_linux_amd64.deb mailink amd64 22.5.3 [5,537 kB]
Selecting previously unselected package mailink.
(Reading database ... 108002 files and directories currently installed.)
Preparing to unpack .../mailink-agent_22.5.3_linux_amd64.deb ...
 Please provide the device key:
 :>
Progress: [ 20%] [#####################.....................................................................................]

1. Leave the installer as shown above and proceed to Step 2.

Step 2: Create the Device in the maiLink Cloud.

1. Navigate to the Devices page.
2. Click on Create Device.

   

3. Enter a Device Name and Device ID (Serial Number is recommended).
4. Click + to add tags that help identify the system, such as:
   1. Site Name
   2. Address
   3. IP Address

      

5. Click Create to save the settings and open the Device Info page for the new device.

Step 3: Create a Device Key for the new device.

1. Click on Device Keys side tab.

   

2. Click on Create Key.

   

3. Click on Copy Device Key to save the key to the Clipboard.

   

Step 4: Finish the Agent Installation

1. Return to the Agent installer on the remote device.
2. Paste the content of the clipboard (Right Click or Ctrl + Shift + V) into the Installer screen, and then hit .
3. The installer will complete as follows…

Unpacking mailink-agent (22.9.11) ...
Setting up mailink-agent (22.9.11) ...
 Setting permissions
 Creating logging directory
 Creating linux configuration file
 Creating plugin directory structure
 Setting up service

1. Verify the Agent is running by running this command

sudo systemctl status mailink-agent.service

Output

● mailink-agent.service - maiData maiLink Service
   Loaded: loaded (/etc/systemd/system/mailink-agent.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2022-09-19 20:18:02 UTC; 1min 29s ago
 Main PID: 7713 (mailink-agent)
    Tasks: 13 (limit: 500)
   CGroup: /system.slice/mailink-agent.service
           ├─7713 /usr/bin/mailink-agent run --mailink-home /etc/mailink
           └─7784 /etc/mailink/mailink-agent-plugin serve

Step 5: Verify the Agent is Connected

1. Navigate to the Devices page in the maiLink webpage.
2. Verify that the device is connected to the maiLink SRM Cloud by observing a small solid green dot in the upper left section of the “About Device” page.

Success!

The new device is now connected. If you have the maiLink Client installed on your machine, you will be able to access the new device remotely.

If you have issues, contact your Administrator or email maiData Customer Support at maiData at service@maidata.io.

2.2 - Add Windows Device

Prerequisites

1. You have installed maiLink Client on your computer
2. You have downloaded or transferred the maiLink agent installer
3. You have administrator rights to install software

Step 1: Begin installing Agent software on remote device

1. In a browser, log into your maiLink account at app.maidata.io.
2. Navigate to the Software tab.
3. Select maiLink Agent and Windows.
4. Click on the installer mailink-agent_{version}_windows_amd64.exe for the latest version of the Agent software.
5. Follow the instructions until you arrive at the maiLink Agent Device key screen.

   

6. Leave the installer as shown above and proceed to Step 2.

Step 2: Create the Device in the maiLink Cloud.

1. Navigate to the Devices page.
2. Click on Create Device.

   

3. Enter a Device Name and Device ID (Serial Number is recommended).
4. Click + to add tags that help identify the system, such as:
   1. Site Name
   2. Address
   3. IP Address

      

5. Click Create to save the settings and open the Device Info page for the new device.

Step 3: Create a Device Key for the new device.

1. Click on Device Keys side tab.

   

2. Click on Create Key.

   

3. Click on Copy Device Key to save the key to the Clipboard.

   

Step 4: Finish the Agent Installation

1. Return to the Agent installer on the remote device.
2. Click in the large installer text entry box and paste (Ctrl-V) the Device Key from the clipboard. Click Install.

   

3. Then continue following the instructions until the installer completes.

Step 5: Verify the Agent is Connected

1. Navigate to the Devices page in the maiLink webpage.
2. Verify that the device is connected to the maiLink SRM Cloud by observing a small solid green dot at the left.

Success!

The new device is now connected. If you have the maiLink Client installed on your machine, you will be able to access the new device remotely.

If you have issues, contact your Administrator or email maiData Customer Support at maiData at service@maidata.io.

2.3 - Add Windows Client

Prerequisites

1. You have administrator rights to install software on the desired computer

Begin installing maiLink Client software

1. In a browser, log into your maiLink account at https://app.maidata.io.
2. Navigate to the Software tab.
3. Locate and download the Latest Client Software Version installer, the installer is the executable (.exe) file.
4. The installer will have you register your client as part of the install steps, simply enter the Name you want as a reference for your client (e.g. Work laptop) and add a simple Description (e.g. HP Pavilion).

   

5. complete the installation by returning to the installer window and clicking next and then Finish to complete the installation.

Success!

You can verify local client is registered by observing the green light indicator on the top right of the header!

If you have issues, contact your Administrator or email maiData Customer Support at maiData at service@maidata.io.

2.4 - Import Devices

This document tells you how prepare a CSV file for mass import into maiLink – it’s the quickest way to add a batch of new devices.

Note: The syntax of the CSV file matters, so please follow this guidance carefully.

Note: Once your CSV file is ready, contact support@maidata.io for help. Our team will upload the file for you. We offer this service as a protection for all our customers to prevent accidental SQL injection issues.

Creating a CSV File

Most users will create an Excel file containing the required data and then simply export it into a CSV file. The Excel file will be created by exporting data from some sort of asset manager, CRM system, or other database. Once the data is in Excel, it will be manipulated to meet the CSV Requirements below.

If you think your CSV file is ready, contact support@maidata.io.

CSV Requirements

The CSV file you create should have the following:

1. Values seperated by commas (',').
2. Any values containing commas enclosed in double quotes ('"').
3. One header row.
4. Any number of additional rows, where each row corresponds to one unique device.
5. The following column headers in row 1:

3 - Manage Models

A model is a collection of devices that share most common attributes. Some examples of models are:

• Model 3000 Digital Mammography System
• Model 3000 Digital Breast Tomosynthesis System
• Model 6000 Digital Breast Tomosynthesis System

The first two may share some common features, but have other differentiating features that would make the manufacturer want to keep track of them separately. Please think carefully when defining models to ensure you don’t have to change models going forward.

Add a Model

Note: To add a model you must have the Owner or Fleet Manager role assigned to you.

Adding a model takes a few steps:

1. Create a model.
2. Create a device.
3. Configure telemetry charts.

** Note that you cannot define telemetry charts until you have device defined of that model type.

Create a Model

1. Navigate to Models in the maiLink UI top bar.
2. Click the Create button to begin defining the new model.
   • Enter the Name for the model.
   • Select the Connection Types that the devices of this model will support.
   • Next to the Tags label, click (+) to add a tag. Repeat as necessary.
3. Click Save to store the model.

Note: You can’t define telemetry charts yet. First you must create a device.

Create a Device

Create a device of the model you defined above.

Configure Telemetry Charts

1. Navigate to Models in the maiLink UI top bar.
2. Hover over the model for which you will configure telemetry charts.
3. Click on the Edit button edit the model.
4. Under the Telemetry Charts section, pull down Example Device ID and select a device of this model.
5. Next to Telemetry Charts click (+) to add a new telemetry chart.
   • Click in the New Chart and it will expand.
   • Type in a Name for the new chart.
   • Select the Period.
   • Select the Interval.
   • Click Add Query and:
     • If the device is connected and sending metrics:
       • Select a metric that is to be plotted on the chart, or
       • Type a query by hand into one of the Query boxes.
       • Examples:
         • md_memory_used_percent{device="$device.id"}
         • pump_pressure_mmHg{device="$device.id"}
         • disk_partition_free_bytes{device="$device.id",partition="/dev/sda1"}
     • If the device is not yet sending metrics:
       • Type a query by hand into one of the Query boxes.
   • Click Update.
   • When a dialog box appears, type update into the box and click update.

The charts you configure this way will appear in the About page for each device of this model. If you create a new device, it will inherit the telemetry charts defined for its model.

Edit a Model

1. Navigate to Models in the maiLink UI top bar.
2. Hover over the model for which you will configure telemetry charts.
3. Click on the Edit button edit the model.
4. Make the desired changes.
5. Click Update.
   • When a dialog box appears, type update into the box and click update.

Delete a Model

Note: Deleting a model is a serious business because it will affect ALL devices that are of that model type. If you delete a model, all devices of that model type are set to “default” model type. There is no way to undo that change except for manually changing all those devices back, should you choose to undelete the model later on.

1. Navigate to Models in the maiLink UI top bar.
2. Hover over the model for which you will configure telemetry charts.
3. Click on the Delete button to delete the model.
   • When a dialog box appears, type delete into the box and click delete.

4 - Manage Users

Useful Links

• Add User
• Delete User
• Set User Roles
  • Predefined Roles
  • Role Permissions

Add a User

Note: To add a user you must have the Owner or User Manager role assigned to you.

To add a user, you need to know that user’s full name and email address.

1. Navigate to Settings (Gear) > Users & Access Control.
2. Click on the Invite User button.
3. Enter the person’s First Name, Last Name and Email.
4. Select the Roles to assign to that person. Best practice is to only assign a person the roles they really need to get their work done.
5. Click on the Send Invite button Send Invite is a misnomer today. Think of it instead as Add User.

Then email the following to the user:

- Please go to https://maidata.io.
- Enter your email address.
- Click on Forgot Password?
- Check your email ... there will be one from maidata that has a link for setting your password.
- Click that link.
- In the browser, maiLink will ask you to enter a password twice. Use a complex password:
    - At least 8 characters
    - At least one of !@#$%^&*
    - At least one uppercase and one lowercase character
    - At least one digit 0-9

Delete User

Note: To delete a user you must have the Owner or User Manager role assigned to you.

Note: You cannot delete yourself.

1. Navigate to Settings (Gear) > Users & Access Control.
2. On the row for the user that is to be deleted, click the Delete button.
3. Confirm the action by entering the email of the user you are deleting.
4. Click delete.

Set User Roles

Note: To set user roles you must have the Owner or User Manager role assigned to you. Note: You are not able to modify your own permissions.

You how make or modify the permissions that are assigned to a maiLink user. Permissions are how maiLink controls access to certain data or capabilities in the maiLink Cloud.

Assignment

mailink determines what data to show to a user, or what actions to allow that user to take, based on the roles that have been assigned to that user. The permissions assigned to a user can only be modified by a user with the USERS W permission.

1. Navigate to Settings (Gear) > Users & Access Control.
2. Select a user to modify by clicking Edit on that individual’s row.
3. In the Permissions & Access Control section, pull down Roles.
4. Toggle On / Off any of the roles that you want to add or remove.

Predefined Roles

The following roles are defined in maiLink.

Note: At this time it is not possible for administrators to modify these definitions, though that is being planned for a future release.

Role Permissions

Each permission is a combination of the TYPE of information to be accessed and the ACCESS granted. ACCESS can be R (read) or W (write). The following permissions (first two columns) are granted to each of the roles (latter columns).

5 - Test Telemetry

The maiLink Agent contains a REST API interface to which you can send Telemetry messages. Those messages are in the form of JSON data packets that must be formatted according to the maiLink Agent REST API Specification.

Getting Started

1. Install the maiLink Agent on your computer using these instructions. It’s important that 1) the Agent is installed on the machine that will generate the telemetry, and 2) the Agent is up and running. You can check that everything is OK using the Windows Services tool (press Windows+R and type services.msc then press Enter) and scroll down to verify that maiLink Agent status is running.

2. Open a PowerShell window, running it as administrator.
3. Give yourself permission to run PowerShell scripts by entering the following command:

> Set-ExecutionPolicy unrestricted

4. Create a working directory such as C:\Users\<your_name>\telemetry.

> cd ~
> md telemetry
> cd telemetry

■ Example: Sending Individual Metrics

The first PowerShell script accepts two command line parameters, creates a JSON data object, and pushes it to the Agent REST API.

1. Open a new text file.

> notepad.exe sendMetric.ps1

2. Copy and paste the following code into the editor, then save it.

# sendMetric.ps1 -- a simple Metric sender
#
# Usage: sendMetric [label] [value]

param(
    $label,
    $value
)

$json = "{""type"":""metric"",""label"":""" + $label + """,""value"":" + $value + "}"
$returnvalue = Invoke-RestMethod -Method Post -Uri "http://localhost:5465/mailink/v1/telemetry" -ContentType 'application/json' -Body $json

3. Run the script a number of times, slightly changing the value while keeping the label gateTemp__C the same. This will start to build up data in the maiLink Telemetry Metrics database.

> .\sendMetric gateTemp__C 39.2
> .\sendMetric gateTemp__C 39.3
> .\sendMetric gateTemp__C 39.5
> .\sendMetric gateTemp__C 39.2
> .\sendMetric gateTemp__C 39.1
> .\sendMetric gateTemp__C 39.0
> .\sendMetric gateTemp__C 22.0
> .\sendMetric gateTemp__C 44.0

If your repeat this command a number of times, slightly changing the value while keeping the label gateTemp__C the same, you will start to build up data in the maiLink Telemetry Metrics database. Note that the time when you run the script defines the times associated with each data point – the Agent creates the timestamps for you.

JSON Data Object

The JSON data object for one of the single telemetry messages is simple:

{
    "type": "metric",
    "label": "<label>",
    "value": <value>
}

■ Example: Sending Batch Metrics

1. Open a new text file.

> notepad.exe generateBatchMetrics.ps1

2. Copy and paste the following code into generateMetrics.ps1 and save it.

# generateBatchMetrics.ps1 -- a maiLink Telemetry data generator
#
# Use this script to generate a number of geometric waveforms that are sent to the cloud, with a batch
# sent for each time point. The waveforms are:
#
#    Waveform  Description
#    --------  ---------
#    cos       Cosine
#    coshalf   Half-wave cosine
#    sin       Sine
#    sinhalf   Half-wave sine
#    tan       Tangent (clipped to +/- 100)


# Put all the functions requested into an array.
$functions = $("cos", "coshalf", "sin", "sinhalf", "tan")

$pi = [math]::PI
$delta = $pi / 72.   # For 10 cycles per hour (1 cycle every 360 seconds) need 72 samples at 5 second rate).
For ($t=0.0; $t -lt 10*$pi; $t+=$delta) {

    $json = "{""items"":["
    For ($l=0; $l -lt $functions.Length; $l++) {
        $label = $functions[$l]
        switch ($label) {
            "cos" {$value = [math]::cos($t)}
            "coshalf" {$value = [math]::abs([math]::cos($t))}
            "sin" {$value = [math]::sin($t)}
            "sinhalf" {$value = [math]::abs([math]::sin($t))}
            "tan" {$value = [math]::min([math]::max([math]::tan($t),-100.),100.)}
        }
        
        # Here is the content from sendMetric.ps1
        $json += "{""type"":""metric"",""label"":""" + $label + """,""value"":" + $value + "},"
    }
    $json = $json.Substring(0,$json.Length-1)
    $json += "]}"
    $returnvalue = Invoke-RestMethod -Method Post -Uri "http://localhost:5465/mailink/v1/telemetry/batch" -ContentType 'application/json' -Body $json

    Write-Host "." -NoNewline 
    Start-Sleep -Seconds 5.0
}

3. Run the script. It generates a series of batch JSON data objects and sends one to the Cloud every 5 seconds. You only have to run it once … it will continue running for about an hour.

> .\sendBatchMetrics

You can visualize as many as four of the metrics at once. Just change the Query strings to any of these:

JSON Data Object

The JSON data object for one of the batch telemetry messages looks like:

{
    "items": [
        {
            "type": "metric",
            "label": "cos",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "coshalf",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "sin",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "sinhalf",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "tan",
            "value": <value>
        }
    ]
}

Cleaning Up

At present there is no way to delete experimental telemetry data that you may have sent to the Cloud using the instructions above. Be aware that after 90 days all telemetry data ages out of the Cloud database and is thus lost. This includes both variable names and data points (if a variable name has not been transmitted to the Cloud with telemetry data in the last 90 days, it too is removed).

6 - Update Agent

The following methods are used to update the maiLink Agent on Devices without having to establish a connection and log in.

Single Device

To update the Agent version on a Device:

1. Open the maiLink web app.
2. Navigate to Devices > DeviceID.
3. Select Update Device from the left hand tab bar.

Locate the Update Agent section, which shows the current Agent version.

4. Click in the Versions pull-down and select one of the available versions.
5. Click Apply to upgrade the Device to the selected version.

Note that the same controls can be used to revert to earlier versions of the Agent as well. Simply select an older version from the Available Versions drop-down and Apply. maiLink will not allow you to revert to versions of the Agent that were released prior to the release of Agent single-click upgrade because of software architecture incompatability.

Selected Devices

Future Enhancement

Device Type

Future Enhancement