GoToAssist Monitoring API

The GoToAssist Application Programming Interface (API) supports requests from computer programs, from both GoToAssist and other third parties. You can write small scripts and programs that submit data to the GoToAssist API. The API makes it easy to submit PQL queries against your GoToAssist database and to add documents to it.

Services

All calls to the GoToAssist API use the HTTP POST command to post data to the following URL:

https://api.GoToAssist.com/api/

The GoToAssist API includes the following services:

• paglo.ping — Tests whether you can reach the GoToAssist API, and validates your data key or API key.
• paglo.query — Submits a PQL statement to your GoToAssist Search Index and gets results.
• paglo.submit — Submits data into your GoToAssist Search Index beyond what your Crawler collected, which makes that data searchable.

There is also a facility for generating chart images suitable for use in other portals.

paglo.ping

The paglo.ping performs a basic ping test to verify that you can reach the GoToAssist API and that your data key or API key is valid.

Example 1

This example pings the company's GoToAssist database using the paglo_api.rb.

#!/usr/bin/env ruby
#
require 'paglo_api'
p = Paglo::Session.new("your data key or api key goes here")
resp = p.ping
puts "Response: #{resp}"

Result 1

The result of the ping looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<ping_response xmlns="http://GoToAssist.com/xml/1.0/">
  <pong></pong>
  <arg>
    <name>v</name>
    <value>1.0</value>
  </arg>
  <arg>
    <name>api_key</name>
    <value>your data key or api key</value>
  </arg>
  <arg>
    <name>action</name>
    <value>index</value>
  </arg>
  <arg>
    <name>method</name>
    <value>paglo.ping</value>
  </arg>
  <arg>
    <name>controller</name>
    <value>api</value>
  </arg>
</ping_response>

Example 2

This example pings your company's GoToAssist database using net/http, net/https, and cgi.

#!/usr/bin/env ruby
require 'net/http'
require 'net/https'
require 'cgi'

h = Net::HTTP.new("app.GoToAssist.com", 443)
h.use_ssl = true
resp,body = h.post("/api",
                   "method=paglo.ping" +
                   "&api_key=" + CGI.escape("your data key or api key"))
puts "Code:    #{resp.code}" 
puts "Message: #{resp.message}" 
puts "Body:    #{body.to_s}" 

Result 2

This example produces the same result as in Example 1.

paglo.query

Use the paglo.query to submit a PQL statement to your company's GoToAssist database, such as SELECT or DELETE. (To make a PQL MERGE, INSERT, or UPDATE statement, use paglo.submit.)

This is very useful if you want to develop applications that extend the use and functionality of GoToAssist.

Example 1

This example submits a simple query to find everything about Node #2886.

#!/usr/bin/env ruby
#
require 'paglo_api'
p = Paglo::Session.new("your api key or data key goes here.")
resp = p.query(:query => "select interface from 2886")
puts "Response: #{resp}"
 

Result 1

Of course, the result of this example query depends on whether your database contains a node with an identical number of 2886 or not. Still, it is useful to examine a sample result. In the following sample, standard parameters are returned as arg nodes, as well as several row nodes, one row for each item that matches the PQL statement.

This is most useful for SELECT statements. PQL INSERT, MERGE, UPDATE, and DELETE have a <response></response> node, but are empty. For MERGE statements, the paglo.submit API is more appropriate than paglo.query.

<?xml version="1.0" encoding="UTF-8"?>
<query_response xmlns="http://GoToAssist.com/xml/1.0/">
  <response>
<row>
  <value name="interface/interface/inet/ip_address">10.10.10.10</value>
  <value name="interface/interface/mac_address">00:01:02:03:04:05</value>
</row>
  </response>
  <arg>
    <name>v</name>
    <value>1.0</value>
  </arg>
  <arg>
    <name>api_key</name>
    <value>the api key or data key you used appears here</value>
  </arg>
  <arg>
    <name>action</name>
    <value>index</value>
  </arg>
  <arg>
    <name>method</name>
    <value>paglo.query</value>
  </arg>
  <arg>
    <name>controller</name>
    <value>api</value>
  </arg>
  <arg>
    <name>query</name>
    <value>select interface from 2886</value>
  </arg>
</query_response>

Example 2

Example 1 returns its results in the form of a table. This example returns the same results in tree format:

SELECT interface 
  FROM /network/device 
    WHERE system/name='smith-desktop' 

Result 2

Here are the results in the form of a tree:

<?xml version="1.0" encoding="UTF-8"?>
<query_response xmlns="http://GoToAssist.com/xml/1.0/">
 <response>
  <tree name="row">
   <tree name="interface">
    <value name="mac_address">
     00:01:02:03:04:05
    </value>
    <value name="name">
     eth0
    </value>
    <value name="type">
     6
    </value>
    <value name="speed">
     10000000
    </value>
    <value name="out_errors">
     0
    </value>
    <value name="in_errors">
     0
    </value>
    <value name="mtu">
     1500
    </value>
    <value name="out_octets">
     1157447151
    </value>
    <value name="in_octets">
     214365650
    </value>
    <value name="descr">
     eth0
    </value>
    <tree name="inet">
     <value name="ip_address">
      10.10.10.10
     </value>
     <value name="netmask">
      255.255.255.255
     </value>
    </tree>
    <value name="oper_status">
     1
    </value>
    <value name="admin_status">
     1
    </value>
   </tree>
  </tree>
 </response>
 <arg>
  <name>
   v
  </name>
  <value>
   1.0
  </value>
 </arg>
 <arg>
  <name>
   api_key
  </name>
  <value>
   your api key appears here
  </value>
 </arg>
 <arg>
  <name>
   action
  </name>
  <value>
   index
  </value>
 </arg>
 <arg>
  <name>
   method
  </name>
  <value>
   paglo.query
  </value>
 </arg>
 <arg>
  <name>
   controller
  </name>
  <value>
   api
  </value>
 </arg>
 <arg>
  <name>
   query
  </name>
  <value>
   select interface from /network/device 
   where system/name='smith-desktop'
  </value>
 </arg>
</query_response>

paglo.submit

The paglo.submit adds, merges, or updates the data in your GoToAssist account. This API is the equivalent of sending a PQL INSERT, MERGE, or UPDATE statement.

This is especially useful if you want the ability to search some type of data that the GoToAssist Crawler does not currently gather. You have the option of writing a Crawler plugin to extend the Crawler, of course. But you may already have a data-gathering system such as mrtg or an rrdtool-based system. If so, you can enable your legacy system to communicate with GoToAssist by writing small scripts and programs that submit data to the GoToAssist API. Then, with a few lines of code and the paglo.submit, you can send that data to GoToAssist to index it, where you can search it.

Example 1

Note that the data that you submit via paglo.submit must be URL-encoded, and it must be valid for the VALUES clause of a PQL MERGE statement. For example, if you submit {a[b='2'] => {b => '3'}} as your data, GoToAssist inserts this data into a PQL MERGE statement like this: MERGE INTO / VALUES {a[b='2'] => {b => '3'}}. If this does not form a syntactically correct PQL statement, an error is returned.

This example submits data to the company's GoToAssist database with a simple ruby script using net/http, net/https, and cgi.

#!/usr/bin/env ruby
require 'net/http'
require 'net/https'
require 'cgi'
h = Net::HTTP.new("api.GoToAssist.com", 443)
h.use_ssl = true
resp,body = h.post("/api",
                   "method=paglo.submit&v=1.0&api_key=" +
                   CGI.escape("your api or data key goes here") +
                   "&data=" + CGI.escape("{a[b='2'] => {b => '3'}}"))
puts "Code:    #{resp.code}" 
puts "Message: #{resp.message}" 
puts "Body:    #{body.to_s}" 

Result

Unlike the other GoToAssist APIs, the result of a successful paglo.submit is short. GoToAssist does not repeat your entire submission in the response, unless the submission fails (see Error messages). The following result indicates a successful submission:

Example 2

This example submits data to the company's GoToAssist database using paglo_api.

#!/usr/bin/env ruby
#
require 'paglo_api'
p = Paglo::Session.new("your api or data key goes here")
resp = p.submit(:data => "{a[b='2'] => {b => '3'}}")
puts "Response: #{resp}" 

Result

This example produces the same result as in Example 1.

Error messages

GoToAssist does not repeat your entire submission in the response, unless the submission fails. If the submission fails, GoToAssist returns the submission and indicates where the failure occurred. The paglo.submit can result in one of two possible return codes:

Example

The following example shows a paglo.submit call that returns Code 200, but contains an error code indicating an invalid API key:

<?xml version="1.0" encoding="UTF-8"?>
<error_response xmlns="http://GoToAssist.com/xml/1.0/">
  <error_code>2</error_code>
  <error_message>API key is not valid</error_message>
  <arg>
    <name>v</name>
    <value>1.0</value>
  </arg>
  <arg>
    <name>api_key</name>
    <value>thisisnotavalidkey</value>
  </arg>
  <arg>
    <name>action</name>
    <value>index</value>
  </arg>
  <arg>
    <name>method</name>
    <value>paglo.submit</value>
  </arg>
  <arg>
    <name>controller</name>
    <value>api</value>
  </arg>
  <arg>
    <name>data</name>
    <value>{a[b='2'] => {b => '3'}}</value>
  </arg>
</error_response> 

chart

You can generate a chart using the URL https://app.GoToAssist.com/chart.

This URL supports a number of parameters:

• q – the search query to display in the chart
• options[style] – the type of chart, one of bar, line, pi, area, uptime
• options[width] – the width of the chart in pixels
• options[height] – the height of the chart in pixels
• options[colors] – color palette specification of the form 0x00ff00,0xff0000,...
• options[x_title] – X axis title
• options[y_title] – Y axis title
• options[legend] – pass none to suppress the legend
• options[orientation] – orientation of bar charts, either horizontal or vertical
• options[line_type] – type of line drawing in line charts, one of simple, step, spline
• options[pie_3d] – whether a pie chart should be 3-d. Either yes or no
• options[area_type] – type of area chart, either simple or stacked
• options[stack_type] – whether stacked charts should be stack or percentage

The response from the URL is be a PNG image. Here is an example:

https://app.GoToAssist.com/chart?options[style]=bar&options[width]=300&q=select+systemname||'+'||name,+size,+freespace+%0Afrom+/network/device/wmi/win32_logicaldisk+%0Awhere+drivetype+%3D+3%0Aorder+by+freespace+asc%0Alimit+10

Related topics

• GoToAssist APIs
• Developing applications
• Writing crawler plugins
• For developers
• Developer sandbox
• Developer tools
• Learn about GoToAssist Query Language

| Views: 2987 | Last Updated: Thu, May 09 2013 2:28 PM

Is this article helpful?