SimpleHelp Community

SimpleHelp Scripting API


#1

Now coming in 5.2 we have a new addition that will make Tools far more powerful than ever before - the SimpleHelp Scripting API.

Update The Scripting API documentation is now live and available to use with the 5.2 beta: https://simple-help.com/toolbox-guide#SimpleHelp-Scripting-API

In their present state tools and the scripts they run are very useful both for maintenance on remote machines and for more complex or customised monitoring and alerting.

Custom alerts let you use a tool with any script you like to monitor virtually anything and produce an alert trigger based on the return code:

This allows you to use all the functions the scripting language provides you and commands that are present on the target machine.

This is great, but now we have a whole new set of APIs available that communicate directly from your script to the SimpleHelp server, and give you access to wide new range of functions.

These new API functions enable things that a script simply couldn’t do before, like securely transferring files between remote access machines, getting monitoring stats, sending emails or popping up questionnaire forms for the tech or end user.

In this first example, here’s a short Bash script that checks if the ‘root’ user is logged in on Linux (something some Linux admins prefer to prevent):

function checkUser {
	status=0
	for u in $(who | awk '{print $1}' | sort | uniq)
	do
	if [ "$u" == "$1" ]; then
		return 0
	fi
	done
	return 1
}

checkUser root

if [ $? -eq 0 ]; then	

echo "User Logged In"

	exit 0
else
	echo "User Not Logged In"
	exit 1
fi

You can see there is a function checkUser that is used to verify if root is logged in, and if they are we print out “User Logged In” (highlighted above).

With the new APIs, rather than simply printing if root is logged in, we can email a technician. All we need to do is add one line under the “User Logged In” printout:

if [ $? -eq 0 ]; then
	echo "User Logged In"

ServerUtilsSendEmail(@TechsByName(Alice),“Root Login!”,“Warning, someone has logged in as root.”)

	exit 0
else
	echo "User Not Logged In"         
	exit 1
fi

The ServerUtilsSendEmail() line isn’t actually a format that the Bash script would recognise but SimpleHelp automatically converts this into the necessary Bash code to trigger the email being sent to the tech named ‘Alice’.

That’s pretty cool, but if we are concerned about this root login maybe we also want to capture some of the recent login attempts right away and get them off the machine so they can’t be wiped. Again, with the Scripting API this is now super simple:

if [ $? -eq 0 ]; then
	echo "User Logged In"                                              
	
	ServerUtilsSendEmail(@TechsByName(Alice),"Root Login!","Warning, someone has logged in as root to this server in contravention of company policy")

PushFile(@Machine(Alice Desktop),“C:\Users\aem\Desktop”,"/var/log/auth.log")

	exit 0
else
	echo "User Not Logged In"
	exit 1
fi

As before we added just one more line, but now if the root user is logged in we not only send an email to the technician, but we also grab the auth.log file and push it immediately and directly to Alice’s desktop PC. The file transfer will even patch directly through to Alice’s desktop if possible rather than going via the SimpleHelp server to speed up the transfer and reduce bandwidth usage.

We are using Bash script in the example above but nothing about the Scripting APIs is specific to any particular scripting language. You can add the same lines into Powershell scripts, Python, Ruby, Perl, whatever you like to script in. SimpleHelp will take care of converting it into something the scripting language will understand.

For a second example, we can easily build a form to request information from the end user whenever a tool is run. This can be used in exactly the same way to ask the Tech to fill in a form when a tool is run too.

Below are a few lines that will pop up a single form for the end user when the tool is run to gather more information from them. After the form is submitted the API functions are converted to hardcoded strings and numbers within the script, so we can assign them directly into variables within the script and use them:

ServerUtilsAskUser(Please describe your issue, title)
export name=“ServerUtilsAskUser(Name, text)
export problem=“ServerUtilsAskUser(Describe your problem, text)
export severity=“ServerUtilsAskUser(Severity, choice, minor, minor, important, blocking work)

From the scripts’ point of view, this is exactly the same as the following, except the values are captured live from the form:

export name=“Bob
export problem=“My printer is not working
export severity=“blocking work

When the tool is run, SimpleHelp pops up a form to ask the user questions, then substitues their responses into the script before it runs:

This is just a quick example but something like this could allow technicians to not only triage problems that customers are having, but to capture information about the state of the system at the time when the problem actually occurred without having to take time away from other important work.

The possibilities with tools are already wide ranging but the Scripting API allows tools to become much more than just something that runs on a remote machine. They now have the ability to manage, monitor and maintain systems spread across multiple computers - entire software and hardware stacks from end user machines to web caches, proxies and servers right through to backend database systems.

We plan to have full documentation ready for release with 5.2 along with more examples like the above to demonstrate both how to use Scripting APIs and the sorts of things you might want to do with them.

In the meantime though, here’s a quick rundown on the full list of APIs so far that will be in 5.2:

(Executed before the script runs)

  • DownloadFile - download a file from a web URL
  • PrePullFile / PrePushFile - pull or push a file to a remote machine
  • GetCpuUsage / GetMemoryUsage - get the current CPU or memory usage of the local or a remote machine
  • GetWanIP - get the WAN IP of the local or a remote machine
  • GetWifiMbit / GetWifiPercent - get the wifi stats for the local or a remote machine
  • GetRdpSessions - get the Terminal Services / RDP session count for the local or a remote machine
  • AskTech / AskUser - full-featured forms to prompt either the technician or the end user to fill in and substitute data into the script
  • GetMachineProperty - more on this in a future post :wink:

(Executed after the script runs)

  • PullFile / PushFile - pull or push a file to a remote machine
  • Log - log text to the SimpleHelp server log file
  • LogFile - log (append) text to a log file on the local or a remote machine
  • SendEmail - send an email via the SimpleHelp server to one or more email recipients, or one or more technicians
  • NotifyAllTechs - send a notification to all technicians
  • NotifyTechs - send a notification to one or more technicians
  • RunTool - run a tool on the local or a remote machine
  • AlertTrigger / AlertReset - directly trigger or reset a custom alert (rather than using the return code of the script)
  • SetMachineProperty

#2

I’m very much looking forward to this.

One thing that I can see that we’ll want right away will be GroupProperties. For example I have software that needs a deployment code specific to each business I support. If that code is embedded in the computer’s group, I could read the code, download the software, and install it all from a SimpleHelp toolbox.

Cheers.Peet


#3

I 2nd this request!!!


#4

If I use the scripting API, is there a way to push a file back to the SimpleHelp Server so I can view it?

I have a script the generates an HTML file.
I want to push that back to the server so I can review it. A link to the file in the Output data window of the toolbox would be ideal.


#5

Check out https://simple-help.com/toolbox-guide#(Post)-PushFile. You would have to have the agent installed on the server I would think. Then you could use ServerUtilsPushFile(@Machine(SERVER_NAME),@Folder(E:\All Backups),@Path(C:\Users\abc\Documents)) and store the file on the server.

Hope that helps


#6

@Peet_McKinney check out my post at Onboarding Script I’ve starts a topic with how I’m doing this.


#7

I tried that. I also failed at doing that. :stuck_out_tongue:
Not sure what I was doing wrong. I am sure its just some syntax I am screwing up.


#8

Does the folder exist or are you making a new folder on the “SERVER_NAME”. I know there was an issue with creating folders if they did not exist. Might be the answer?