Setting Up Custom Management Features

The ITmanager.net API will be composed of 2 separate systems, the Management API and the Monitoring API.

Management API

 

The purpose of the management API is to allow customers to integrate their own custom management features into the ITmanager.net product.  Many features are too small for us to integrate ourselves and could be developed either by a customer themselves, or by a 3rd party who wants to enable remote management of their products using the ITmanager.net app.  Eventually we could have an app store of 3rd party integrations.

 

Adding a custom API

 

Customers will add a custom API by selecting the “Add” button in the Services tab of ITmanager.net.  Then they will select “Custom”, if the customer does not subscribe to the proper plan they will get an error “You must subscribe to the Enterprise Plan to use this feature”.

 

The add screen will have the following fields:

  • Display Name
  • API URL  (required)
  • Authentication
  • Private Network

 

GET URL Requests

 

The app will perform a GET on the API URL, the API will then return a json object representing the screen to be displayed, the format of the of json object is this.

 

{

“title”: ”the title, only required field”,

“subtitle”: “optional subtitle”,

“icon”: “url of icon 88x88”,

“url”: “url to load this object”,

“search”:true,

“moreurl”:”?start=100”

“fields”: [

{

“name”: ”the name of the field”,

“datatype”: “int,string,email,url,checkbox,list”

“value”: “textvalue”, int, bool

“items”: [“item1”, “item2”],

“editable”: true,

“secure”: false,

“required”: false,

“refresh”:true,

“hint”: “description”,

“regex”:””,

“regexerror”:”You must enter a valid email address”

}

],

“items”: [

// array of objects to show in a list

{

“title”:”the item title”,

“icon”:”the icon of the item”

}

],

“actions”:[

{

“name”:”name of the action”,

“url”:”url the action be sent to”,

“method”: “post,get or delete”,

“status”: “Saving...”,

“confirm”:”Are you sure?”,

“type”:”default,submit,input,password”

“input”:”Please enter a new name:”

}

],

“itemactions”:[

{

“name”:”Delete item”.

“confirm”:”Are you sure you want to delete <title>?”,

“params”:”delete=true”

}

]

}

 

Authentication

 

A user can choose to add saved authentication to a custom API, then all requests will include an Authorization headers with credentials in the Basic format.   If a user enters “Ask everytime”, then the API may choose to send back a 401 http code to prompt the user.

 

URL Formats

 

The following url formats are allowed:

  1. Absolute URL’s  (http:// , https://)
  2. Relative URL’s
  3. telnet://  , ssh://, rdp://, vnc://

 

Form Submissions

 

When an action has the value “type”:””submit” , then clicking this action will cause the app to submit all the editable fields to the server using the specified URL.  The fields will be URL Encoded in the POST body as content-type = “application/x-www-form-urlencoded”. If the method of the action is “GET” then the form is sent as query parameters.

 

Action HTTP Responses

 

If an action responds with a 200, then the action was successful, the object is refreshed, and if a previous list contains the object then the object in the list is also refreshed.  If an action returns an error code, then the HTTP status message is shown to the user.

 

The Action Post (as well as Form Submission) can return a document like this as well:

{

“message”: “A confirmation message to show to the user.”,

“refresh”: true,

“close”: true

}

Monitoring API

 

We want to allow users to create their own monitoring data sources, beyond the currently supported SNMP apis.   We will do this using an HTTP api.

 

Users will add a custom monitoring API, using the Monitoring tab and clicking the “Add” menu, then selecting “Custom”, if the user is not an Enterprise Tier subscriber he will receive an error.

 

The Add Custom monitor screen will have the following fields:

  • Display Name
  • URL
  • Private Network

 

The monitoring system will then perform a GET on the URL every 60 seconds.   The URL will return the following json format:

 

{

“success”: true,

“value”: 200,

“error”:”message”

}