Access Synology API data via Alfred workflow

I don’t really know PHP, but I like to tinker. When I came across a PHP library for utilising the Synology APIs by Nicolas Cerveaux (zzarbi) on GitHub I thought it would be a challenge to see if I could get it working as an Alfred workflow (the add-on Powerpack is required to run PHP scripts). I began by attempting to get my DiskStation to tell me its model designation, installed RAM, serial number, temperature, uptime and DSM version: a step-by-step follows.

Obtain the API library

Head over to zzarbi’s project page on GitHub and download a ZIP file of the API library:

Zip

De-compress this download, and note that the resulting synology-master folder contains a folder called ‘library’; we’ll need this shortly.

Create the workflow

From the Workflows tab in Alfred, click on the plus button to create a new workflow. Populate the fields with your custom content as shown:

Alfred Preferences

Add a workflow input

From the ‘Add’ icon in the top right, add an Input of the type ‘Keyword’:

Keyword

Populate this as shown (I chose to use ‘syno’ as the root keyword, and in this case ‘info’ to display a subset of data):

Alfred Preferences 2

Add a workflow action

From the ‘Add’ icon in the top right, add an Action to ‘Run Script’:

Run script

Change the script language to PHP as shown:

Language

Click on the ‘Open workflow folder’ button at the bottom right of the script window, and drag the API library folder from within synology-master that you downloaded earlier into the user.workflow.xxx folder that will open on your OS X desktop:

Library

Back in Alfred, we can know begin writing the required PHP code into the Script window.

PHP coding

Paste the following code blocks sequentially into the Script field within the Run Script Action. The first thing we need to do is include the library folder that we just placed inside the workflow folder:

//Load the API library
set_include_path(dirname(__FILE__).'/library'.PATH_SEPARATOR.get_include_path());
function __autoload($class_name) {
	$path = str_replace('_', DIRECTORY_SEPARATOR, $class_name);

	include $path . '.php';

}

Next, we need to establish a connection to our DiskStation. Replace the paramaters in Synology_DSM_Api() with your LAN IP address and DSM port, and in $synology->connect() with user DSM username and password:

//Connect to DiskStation
$synology = new Synology_DSM_Api('IP_ADDRESS', DSM_PORT, 'http', 1);
//$synology->activateDebug();
$synology->connect('DSM_USER', 'DSM_PASSWORD');

Uncomment $synology->activateDebug(); to check that you are successfully connecting (you’ll need to add a workflow output first; see below).

Now to the good stuff. It took me ages to figure out how to get the values of keys contained within a stdClass Object: in the end it was simple. Because the value for the uptime key was an integer (number of seconds) I wanted to output this in a more human-readable form, and learned how to do so via this example. The API zzarbi wrote uses $synology->getInfo() to hold key and value pairs within an array; we need to get the values from their respective keys. Here is the code we want to display information about our DiskStation:

//Get values from stdClass Object
//print_r($synology->getInfo());
//var_dump($synology->getInfo());
echo 'Synology DiskStation Information:' . "\r\n";
echo 'Model: ' . $synology->getInfo()->model . "\r\n";
echo 'RAM: ' . $synology->getInfo()->ram . "\r\n";
echo 'Serial no: ' . $synology->getInfo()->serial . "\r\n";
echo 'Temperature: ' . $synology->getInfo()->temperature . "\r\n";
echo 'DSM version: ' . $synology->getInfo()->version_string . "\r\n";

function secondsToWords($seconds)
{
    $ret = "";

    /*** get the days ***/
    $days = intval(intval($seconds) / (3600*24));
    if($days> 0)
    {
        $ret .= "$days days ";
    }

    /*** get the hours ***/
    $hours = (intval($seconds) / 3600) % 24;
    if($hours > 0)
    {
        $ret .= "$hours hours ";
    }

    /*** get the minutes ***/
    $minutes = (intval($seconds) / 60) % 60;
    if($minutes > 0)
    {
        $ret .= "$minutes minutes ";
    }

    /*** get the seconds ***/
    $seconds = intval($seconds) % 60;
    if ($seconds > 0) {
        $ret .= "$seconds seconds";
    }

    return $ret;
}

echo 'Uptime: ' . secondsToWords($synology->getInfo()->uptime);

Uncomment the print_r or var_dump line to examine the keys and values within the array (you’ll need to add a workflow output first; see below).

With the code blocks inserted, now click Save to close the Action:

Alfred Preferences 3

Add a workflow output

Finally, we need to display the information we have extracted from the DiskStation. Because there is too much text to be contained within an OS X Notification Centre type of output, I chose Large Type:

Screen Shot 2014 01 07 at 04 43 30

Because I thought it might be handy to have the output as plain text as well, not merely displayed on screen, I also added a Copy to Clipboard type of output.

Large Type isn’t configurable, however, in the Copy to Clipboard output field you need to type {query}.

The finished workflow

Hover over the right margin of the Input and you should see a bud; drag this across to link with Run Script:

Screen Shot 2014 01 07 at 04 50 22

Now link Run Script to both Large Type and Copy to Clipboard in the same way; you should end up with this workflow design:

Screen Shot 2014 01 07 at 04 52 46

The workflow in use

Hit Alt-Space to bring up Alfred and type ‘syno’ followed by ‘info’ (or just ‘i’ will likely be enough):

Syno

Following a slight pause you should see the DiskStation’s details displayed in large type on your screen:

Output

Hitting the Escape key will clear the display from your screen. You can also hit Command-V to paste this information into any application as plain text.

More workflows to build

If you wanted to report information about volume status and storage, you could create a ‘syno volume’ workflow using this code as the third block within the Script (code example found here):

foreach ($synology->getObjects('Volume')->volumes as $value) {
   echo $value->id . ' status is ' . $value->status . "\r\n";
   echo 'Used ' . round($value->used/$value->total * 100) . '% (' . round($value->used) . ' of ' . round($value->total) . ')';
}

Connection log

Display connections by activity, address, time, type and user:

//Set date.timezone to select timezone and avoid warning
if( ! ini_get('date.timezone') )
{
   date_default_timezone_set('GMT');
}

foreach ($synology->getObjects('Connection')->connections as $value) {
   echo $value->user . ' accessed ' . $value->activity . ' via ' . $value->type . ' from ' . $value->address . ' (' . date('D g:i A', $value->timestamp) . ')' . "\r\n";
}

Example output:

admin accessed web via afp from 192.168.1.111 (Thu 6:59 AM)

Package installations

Display installed packages by enabled status, name, version, maintainer and description:

foreach ($synology->getObjects('Package')->packages as $value) {
   echo str_replace("1","[On] ", $value->enabled) . $value->name . ' (' . $value->version . ') ' . 'by ' . $value->maintainer . ': ' . $value->description . "\r\n\r\n";}

Example output:

Piwik (1.10.1-0005) by The Piwik Team: Piwik is an easy-to-use real time web analytics software. It provides you with detailed reports on your website visitors, the search engines and keywords they used, the language they speak and your popular pages. The data is stored in your own database and you can get all of your statistics using the Piwik Analytics API.

[On] PhotoStation (6.0-2626) by Synology Inc.: Photo Station is an online photo album integrated with a blog for you to easily share photos, videos, and blog over the Internet. Moreover, you can also browse photos and watch videos saved on your DiskStation with your iPhone, iPad and Android mobiles on the go.

Service status

Display built-in services by enabled status and service name:

foreach ($synology->getObjects('Service')->services as $value) {
   echo str_replace("1","[On] ", $value->enabled) . $value->name . "\r\n";
}

Example output:

[On] AFP
BonjourPrinter

Applications list

Display built-in applications by application name:

foreach ($synology->getObjects('Application')->applications as $value) {
   echo $value->name . "\r\n";
}

Example output:

File Station

Share list

Display user-accessible shares on DiskStation volume:

foreach ($synology->getObjects('Share')->shares as $value) {
   echo $value->name . ' (' . $value->description . ')' . "\r\n";
}

Example output:

backup (Time Machine backups)
homes (user home)

User list

Display a list of DiskStation user names and descriptions:

foreach ($synology->getObjects('User')->users as $value) {
   echo $value->name . ' (' . $value->description . ')' . "\r\n";
}

Example output:

admin (System default user)

Unfortunately this doesn’t report user status e.g. ‘Disabled’, which would be useful.

Block list

Display a list of blocked IP addresses with date of blocking:

//Set date.timezone to select timezone and avoid warning
if( ! ini_get('date.timezone') )
{
   date_default_timezone_set('GMT');
}

foreach ($synology->getObjects('AutoBlock')->addresses as $value) {
   echo $value->address . ' (' . date('d M y', $value->timestamp) . ')' . "\r\n";
}

Example output:

XXX.XXX.XXX.XXX (09 Dec 13)

More to do!

Looking over zzarbi’s code and the lists here and here, the following additional workflows should be possible (at the least) ; some will require further development of zzarbi’s API library: