Say you’ve taken the wise decision to have your corporate cloud data be backed up by the Keepit cloud solution: you’ve selected one of our many data centers, configured relevant connectors, and are now seeing how snapshots are blissfully parading into eternal archive as you log in to the Keepit web user interface. But perhaps you want a bit more assurance and perhaps you are not keen on logging into a separate web application several times a day to get that assurance.
Many of our customers have their own monitoring solutions and communication systems that they wish to enrich with information from their Keepit account. Luckily, we have a very elaborate API (Application Programming Interface) to allow for all sorts of queries on the state and history of your backups; while we do publish the full API documentation, some might find a small appetizer easier to comprehend.
If you’re already a Keepit customer and if you have an account and working connectors, then this blog post will guide you through creating a PowerShell API agent that prints the timestamp of the last completed backup on your screen. It is very simple: it will not integrate into any monitoring or alerting system, it will not print fancy messages in any messaging platforms, nor will it draw graphs on its own – but it is a small building block that you can extend and transform into whatever you might need.
Getting Access to the API
In order to make calls to the API, your script needs to have the proper credentials and those are obtained through the web user interface. So, log in with a user that has at least ‘Job Monitor’ privileges and create an API token by doing: Users -> Your user – Edit User (the grey cog wheel) -> Security -> Add API token. Give the token a name and decide when it should expire; the API token cannot outlive the user it is associated with. Click ‘Create’ – confirm your password and you will get an API token username and password. Those you need to store in a secure place.
You are now ready to make API calls. For this example, we will be using PowerShell, and the first API call to be made is the call to obtain your account GUID. Now, the account GUID is also available in the web user interface, but obtaining this via the API is a nice, small exercise to verify that the API token and your script is working.
Launch your favorite text editor – it can be Notepad, Notepad++, VSCode, Vim, or whatever you fancy the most, create the file accountguid.ps1 and paste this code into it:
try {
$username = '<API Token username>'
$password = '<API Token password>'
$basicauth = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes('${username}:${password}'))
$headers = @{
'User-Agent' = 'PowerShell-Keepit-API-Agent-1.0/jakob-dalsgaard'
'Authorization' = 'Basic $basicauth'
}
$response = Invoke-WebRequest -UseBasicParsing `
-Uri 'https://de-fr.keepit.com/users' `
-Method:Get -Headers $headers -ErrorAction:Stop -TimeoutSec 10
$userlist = [xml]$response.Content
$id = $userlist.user.id
Write-Host $id
}
catch {
$line = $_.InvocationInfo.ScriptLineNumber
Write-Host 'Cannot query Keepit API due to: $_'
Write-Host 'at line $line'
}Make sure to get the backticks and single and double quotes correct – computers can be very pedantic. In this file, you need to put in the API Token username and API Token password where specified. On line 11, this example reads ‘de-fr.keepit.com’ – thus valid for a Keepit account on our German data center – please change this hostname to the hostname of the data center for your account (i.e., ‘dk-co’, ‘uk-ld’, ‘us-dc’, ‘ca-tr’ or ‘au-sy’). Then, in a command terminal, you execute the script by typing:
Powershell .\accountguid.ps1
Depending on your security setup, you might need to confirm that you really want to execute a script, but please do – and you should see the script print out your 20-character account GUID. This GUID can then be used, along with the API Token, to obtain the list of connectors available in your account.
Save the following code block as devices.ps1:
try {
$username = '<API Token username>'
$password = '<API Token password>'
$userguid = '<Account GUID>'
$basicauth = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes('${username}:${password}'))
$headers = @{
'User-Agent' = 'PowerShell-Keepit-API-Agent-1.0/jakob-dalsgaard'
'Authorization' = 'Basic $basicauth'
}
$response = Invoke-WebRequest -UseBasicParsing `
-Uri 'https://de-fr.keepit.com/users/${userguid}/devices' `
-Method:Get -Headers $headers -ErrorAction:Stop -TimeoutSec 10
$devicelist = [xml]$response.Content
foreach ($system in $devicelist.devices.cloud) {
$name = $system.name
$guid = $system.guid
Write-Host 'Name: $name'
Write-Host 'Guid: $guid'
Write-Host
}
}
catch {
$line = $_.InvocationInfo.ScriptLineNumber
Write-Host 'Cannot query Keepit API due to: $_'
Write-Host 'at line $line'
}Again, put in API Token username and password, the Account GUID, and correct the hostname. Then execute as:
Powershell .\devices.ps1
Your terminal will then be filled with a list of connector names and GUIDs, and among those you will have to select one that can be used in the final script that will be called latest.ps1– this script will print out the timestamp of the latest backup performed by one specific connector:
try {
$username = '<API Token username>'
$password = '<API Token password>'
$userguid = '<Account GUID>'
$connectorguid = '<Connector GUID>'
$basicauth = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes('${username}:${password}'))
$headers = @{
'User-Agent' = 'PowerShell-Keepit-API-Agent-1.0/jakob-dalsgaard'
'Authorization' = 'Basic $basicauth'
}
$response = Invoke-WebRequest -UseBasicParsing `
-Uri 'https://de-fr2.keepit.com/users/${userguid}/devices/${connectorguid}/history/latest' `
-Method:Get -Headers $headers -ErrorAction:Stop -TimeoutSec 10
$history = [xml]$response.Content
$tstamp = $history.history.backup.tstamp
if ($tstamp) {
Write-Host $tstamp
}
else {
Write-Host 'Backup not completed yet'
}
exit 0
}
catch {
$line = $_.InvocationInfo.ScriptLineNumber
Write-Host 'Cannot query Keepit API due to: $_'
Write-Host 'at line $line'
exit 1
}Again, put in API Token username and password, account GUID, connector GUID, correct hostname, and then execute as:
Powershell .\latest.ps1
If your selected connector has completed a backup, you should now, in your terminal, see the timestamp of completion of the latest backup for this connector. It might look something like:
2022-12-24T18:30:00Z
This would say that the latest backup completed on Dec 24, 2022, at 18:30 UTC. The timestamp is given in the ISO8601 format with the Z designator for UTC.
Further Integration
While such a neat PowerShell script is nice to have on the command line, it will bring much more value as part of a monitoring platform or other reoccurring automatic execution. For your business, it might make sense to execute this script once per hour and alert if no backup has been completed for 24 hours. You might want to explore our public API for more information and status.
About Version 2 Digital
Version 2 Digital is one of the most dynamic IT companies in Asia. The company distributes a wide range of IT products across various areas including cyber security, cloud, data protection, end points, infrastructures, system monitoring, storage, networking, business productivity and communication products.
Through an extensive network of channels, point of sales, resellers, and partnership companies, Version 2 offers quality products and services which are highly acclaimed in the market. Its customers cover a wide spectrum which include Global 1000 enterprises, regional listed companies, different vertical industries, public utilities, Government, a vast number of successful SMEs, and consumers in various Asian cities.
About Keepit
At Keepit, we believe in a digital future where all software is delivered as a service. Keepit’s mission is to protect data in the cloud Keepit is a software company specializing in Cloud-to-Cloud data backup and recovery. Deriving from +20 year experience in building best-in-class data protection and hosting services, Keepit is pioneering the way to secure and protect cloud data at scale.
The Keepit Approach to the Five Quality Components of Usability
One prominent aspect of Keepit’s cloud backup and recovery solution that customers rave about most is its simplicity and ease of use. Where other similar solutions often require weeks of training, the Keepit solution is plug and play, capable of being implemented and fully operational within minutes – and by everyone on the team. No extensive courses and diplomas are required.
The intuitive ease with which Keepit locates and restores files also means our customers are actively incorporating it into their day-to-day internal support operations, rather than just using it for finding and recovering files that have simply gone astray. The ease of use comes from a dedicated design process, which puts usability up front and users in the driver’s seat.
There are many different opinions on what the word usability means, so here at Keepit — as with many other things — we are inspired by what we observe in the workplace and then have our take on it that fits our product.
The Keepit Design Hierarchy
Creating and following a design hierarchy goes to the heart of how we build and continue to improve Keepit’s backup solution.
For every design and feature we implement, Keepit follows a clear usability vision that strongly focuses on following a design code.
The hierarchy in which we make design and usability decisions is built around Principles, Pillars, and Patterns.
Starting with our Design Principles, everything we do is based on these principles: They are abstractions of how we design our products and help designers make the right decisions.
Design Pillars are more focused on how we implement designs and how the user should experience the Keepit solution. Pillar example: “The right functionality, at the right time, to the right person.” This Pillar is used rigorously for each feature we create throughout the entire user flow.
Is this the right functionality being presented to the user?
Is this the right time to show this functionality?
Will it work for the person who is going to use it?
Finally, we have Patterns.
Design Patterns are specific implementations of functionality. This could be how we implement breadcrumbs, how we handle truncation, checkboxes, dropdowns, and wizards, just to name a few.
Defining Usability
Usability is a quality attribute that assesses how easy user interfaces are to use. The word ‘usability’ also refers to methods for improving ease of use during the design process.
The most popular definition of Usability has five components, as explained by the
Learnability: How easy is it for users to accomplish basic tasks the first time they encounter the design?
Efficiency: Once users have learned the design, how quickly can they perform tasks?
Memorability: When users return to the design after a period of not using it, how easily can they re-establish proficiency?
Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors?
Satisfaction: How enjoyable is it to use the design?
There are many other important quality attributes, one of which is utility, which refers to the design’s functionality. In other words, does it do what users need?
How Keepit Measures Usability
Learnability in Keepit:
Let us look at the first item: Learnability. The nature of a backup application is not something our users check in to merely to “get a dopamine kick” from watching cool facts about their running backups. Instead, backup is more “set it and forget it,” and usually, our users come to the platform for one of two reasons. One, is to make sure that everything is running as it should. Two, is to restore data that was lost.
For many of our users, the fact that the application is so easy to learn and understand saves them much time, money, and the frustration of being unable to find the data that needs to be restored.
Memorability in Keepit:
Our approach is not just that things should be easy to learn but also that they must be easy to get back into after being away for a period of time. We do this with a consistent system: most things work in a predictable, similar way, following the same ideas. This increases the chance that something is memorable and easy to re-learn. There are, of course, many things we do to improve the memorability of Keepit, with consistency and recognizability of the applications they are backing up being just some of them.
Efficiency in Keepit:
All of this leads to Keepit’s Efficiency. We like to look at efficiency from the point of view that you should “take the time to look before you jump.” This means we do not consider “few clicks” a success criterion in itself, but rather, we consider “carefully placed” clicks as a step in the right direction – i.e., solving the problem with just the right number of clicks.
Errors in Keepit:
Naturally, we do everything within our power to ensure the number of mistakes made in relation to the task being solved is at a minimum and that a tight correlation exists between the number of errors the user is making and the solution’s efficiency. Every time the user makes an error, it sends them back into the flow, and they will have to redo actions, which again leads to an ineffective solution. Learnability and memorability directly impact the user’s errors, so everything is connected, as you can see.
Satisfaction in Keepit:
Finally, there is one more thing to address: satisfaction. Satisfaction is a tricky topic to discuss when talking about a solution that’s practical in nature and does not contain any real incentive to be a pleasurable experience. In the Keepit design, we have gone to great lengths to fight against the tendency of “functional design” that flourishes in the world of IT management tools. Instead, we have moved toward the concept of “emotional design” because IT administrators also deserve good tools.
In functional design, where the idea that showing everything all at once means more control and empowered admins, Keepit believes showing the right thing, at the right time, to the right person offers the ultimate degree of control and empowerment. We also believe that creating a pleasurable and satisfying experience with administration tools like Keepit, where everything “just works,” frees up administrators to focus on other priorities.
Final Thoughts
Despite our mission to create the perfect solution that requires no previous knowledge to recover data, we are painfully aware that achieving perfect usability is a goal yet to be reached. But we strive every day to get there.
That said, we recommend that our users regularly make sure they understand the flows and the emergency training so that in the case of an emergency, they know exactly what to do and when to do it, which we’ll save for a future blog post.
At Keepit, we put a lot of effort into ensuring that the design leaves little room for mistakes and is easy to pick up again after a long vacation – even for an inexperienced administrator.
Help The Keepit Design Team
We are always looking for people who would like to provide feedback on our solution and help us create the best design in the world. Please if you are interested in becoming part of the user feedback forum. 