Example: Using the Discovery Resource

Download this manual as a PDF file

Discovery is the process by which SL1 retrieves data from the devices in a network and then adds and configures those devices. SL1 runs discovery to perform the initial discovery of your network and then nightly to collect and update information about your network. You can also manually initiate discovery, for a single device or for a range of devices, at any time.

To start discovery, you must provide the discovery tool with one or more IP addresses and other information about how you want SL1 to perform the discovery. You save the list of IP addresses and other information about how you want SL1 to perform the discovery in a discovery session. When you execute the discovery session, SL1 then finds all the devices and components in the range. For each discovered device or component, SL1 gathers detailed data. This data is used throughout SL1.

The following sections will show you how to use the API to perform some basic tasks for managing discovery sessions.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all of the menu options, click the Advanced menu icon ().

Requirements

  • This section assumes that you have a working version of cURL installed and can run cURL from a command prompt. For information on cURL, see http://curl.haxx.se/.
  • To connect to the API, you must use HTTPS. If you have not installed or configured a security certificate or if your appliance uses a self-signed certificate, you must use include the "-k" option each time your execute cURL. The "-k" option tells cURL to perform the HTTPS connection without checking the security certificate.
  • Through the API, you can perform only actions for which you have permission in the system. To perform the tasks in this section, you must connect to the API using an account (username and password). The account must have Access Keys that grant the following:
  • Access the Discovery page
  • Schedule or execute a discovery session

Getting Started

  • In the examples in this section, we will connect to the example Administration Portal with the IP address of 192.168.10.205. To run these examples on your system, you should replace this IP address with the base URI of the API on the appliance you are using.
  • In the examples in this section, we will connect using the default account "em7admin", with the default password "em7admin". To run these examples on your system, you should replace this username and password with a valid username and password for your system.
  • In the examples in this section, we will execute each request at a shell prompt or command prompt. However, you can include these requests in a script or program.

The examples in this section use the custom-header option "X-em7-beautify-response:1".This header tells the API to include white-space in a response, to make it easier to read. However, this header can greatly increase the amount of time required to process a request. ScienceLogic recommends you use this header only when testing requests. ScienceLogic strongly discourages you from using this header in integration code.

Connecting to the API

To connect to the API and view the root directory (with an HTTP GET request), enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api"

  • curl -v. Executes the cURL request. The -v option tells cURL to use verbose mode (displays all header information and all status and error messages). In the response, lines that start with ">" include header data returned by cURL. Lines that start with "<" include header data received by cURL.
  • -H 'X-em7-beautify-response:1'. The -H option tells cURL to include an additional header in the request. In this case, we're including a ScienceLogic custom header that tells the API to include white-space in the response.
  • -u 'em7admin:em7admin'. The -u option tells cURL to authenticate as a specified user. In our example, we authenticated as the user "em7admin" with the password "em7admin".
  • "https://192.168.10.205/api". Connect to the specified URL. In our example, we connected to the API at 192.168.10.205.

The response will look like this (however, we've added line numbers for reference):

1) * About to connect() to 192.168.10.205 port 443 (#0)

2) * Trying 192.168.10.205... connected

3) * Connected to 192.168.10.205 (192.168.10.205) port 443 (#0)

4) * Server auth using Basic with user 'em7admin'

5) GET / HTTP/1.1

6) Authorization: Basic ZW03YWRtaW46ZW03YWRtaW4=

7) User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3

8) Host: 192.168.10.205

9) Accept: */*

10) X-em7-beautify-response:1

11) >

12) < HTTP/1.1 200 OK

13) < Date: Wed, 20 Jan 2010 23:03:46 GMT

14) < Server: Apache/2.2.9 (Unix) mod_ssl/2.2.9 OpenSSL/0.9.8e-fips-rhel5

15) < X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

16) < Content-Length: 703

17) < Content-Type: application/json

18) <

19) {

20) "data":{

21) "account":{

22) "URI":"\/account",

23) "description":"Get\/Update\/Add\/Delete User Accounts"

24) },

25) "device":{

26) "URI":"\/device?limit=100",

27) "description":"Get\/Update\/Add\/Delete Devices and Get Collected Data"

28) },

29) "discovery_session":{

30) "URI":"\/discovery_session\/",

31) "description":"Get\/Update\/Add\/Delete Device Discovery Sessions"

32) },

33) "dynamic_app":{

34) "URI":"\/dynamic_app\/",

35) "description":"Get Dynamic Application Resources"

36) },

37) "organization":{

38) "URI":"\/organization",

39) "description":"Get\/Update\/Add\/Delete Organizations"

40) },

41) "ticket":{

42) "URI":"\/ticket?limit=100",

43) "description":"Get\/Update\/Add\/Delete Tickets"

44) },

45) "ticket_queue":{

46) "URI":"\/ticket_queue",

47) "description":"Get Ticket Queues"

48) }

49) }

50) }

51) Connection #0 to host 192.168.10.205 left intact

52) Closing connection #0

  • Lines 1-4 show cURL trying to connect to and authenticate with the API.
  • Lines 5-11 show the HTTP GET request we sent. The initial request performs a GET on the root directory of the API.
  • accept: */*. Specifies that we will use the default accept header. The accept header tells the API how to format the response. The API can respond in XML or JSON. Because we didn't specify an accept header, the API will use the default format, which is JSON. If you want to view the response in XML, you can include the header option "
    -H 'Accept:application/xml" in the cURL command.
  • X-em7-beautify-response:1. Tells the API to include white-space in the response, for easier reading.
  • Line 12 shows the HTTP version and the HTTP status code for the response.
  • Lines 12-18 show the header information for the response.
  • Lines 19-52 display the response to the HTTP GET request on the root directory of the API.

The response for the HTTP GET request displays a list of resources. A resource is a functional area in SL1 that you can access through the API.

You can interact with the following entities through the API:

  • Accounts
  • Account Lockouts
  • Alerts
  • Appliances
  • Assets
  • Collector Groups
  • CBQoS Objects
  • Collection Labels
  • Credentials
  • Custom Attributes
  • Dashboards
  • Devices
  • Device Categories
  • Device Classes
  • Device Interfaces
  • Device Groups
  • Device Relationships
  • Device Templates
  • Discovery Sessions
  • Dynamic Applications
  • Events
  • Event Categories
  • External Contacts
  • File Uploads
  • Interfaces
  • Monitoring Policies
  • Organizations
  • Performance Data
  • PowerPacks
  • Product SKUs
  • Schedules
  • System Patches
  • System Settings
  • Tasks
  • System Thresholds
  • Themes
  • Thresholds
  • Tickets
  • Ticket Categories
  • Ticket Chargeback
  • Ticket Logs
  • Ticket Notes
  • Ticket Queues
  • Ticket States
  • User Policies
  • Vendors

For each resource, the response displays the associated URI for accessing the resource and a description that lists the actions you can perform on the resource.

For our example, we'll be looking at the discovery_session resource. The entry for the discovery_session resource includes the URI of the discovery_session resource and includes the following description:


29) "discovery_session":{

30) "URI":"\/discovery_session\/",

31) "description":"Get\/Update\/Add\/Delete Device Discovery Sessions"

32) },

Viewing a List of Discovery Sessions

In the previous section, we used an HTTP GET request to retrieve information about the root directory of the API. Our response included a list of resources. We learned that we can request information about discovery sessions.

To access a resource, like discovery_session, we can use an HTTP GET and append a discovery session's URI to the URI of the root directory. To access the resource discovery_session, we could enter the following at the command line.

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session"

The response looks like this:

...[REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]

< HTTP/1.1 302 Found

< Date: Wed, 27 Jan 2010 16:32:05 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< Location: /discovery_session?limit=100

< X-EM7-status-message: discovery_session index requires a limit

< X-EM7-status-code: FOUND

< Content-Length: 977

< Content-Type: application/json

<

{

"searchspec":{

"fields":{

"data":[

"dgid",

"date_edit",

"date_run",

"scan_ports",

"organization",

"collector_id",

"edited_by",

"discover_non_snmp"

]

},

"options":{

"extended_fetch":{

"type":"boolean",

"description":"Fetch entire resource if 1 (true), or resource link only if 0 (false)",

"default":"0"

},

"hide_filterinfo":{

"type":"boolean",

"description":"Suppress filterspec and current filter info if 1 (true)",

"default":"0"

},

"limit":{

"type":"int",

"description":"Number of records to retrieve",

"default":"100"

},

"offset":{

"type":"int",

"description":"Specifies the index of the first returned resource within the entire result set",

"default":"0"

}

}

},

"total_matched":"14",

"total_returned":0,

"result_set":[

]

}

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

The response does not contain the results we wanted, that is, information about the discovery sessions in SL1. Instead, the response contains:

  • HTTP/1.1 302 Found. This status code indicates that discovery_session resources were found, but our request was missing required filtering and options.
  • Location: /discovery_session?limit=100. This is a redirect header. Most browsers would automatically redirect our request to this URI. However, cURL requires an additional option to use redirects.
  • "X-EM7-status-message: discovery_session index requires a limit" and "X-EM7-status-code: FOUND". Human-readable status messages provided by the API. These messages indicate that our API does include discovery_session resources and that our HTTP request was missing the "limit" option.
  • "searchspec". The response include a list of searchspec options. These options allow use to filter content contained in the response.
  • "total_matched":"14", "total_returned":"0, "result_set":[]. This line indicates that the default "limit" option would have returned 14 discovery sessions, but that our request returned zero discovery sessions.

Let's run the command again with the correct URI that contains the required option. To do this, enter the following at the command line:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session?limit=100"

The response looks like this:

...[REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY] 

< HTTP/1.1 200 OK

< Date: Wed, 27 Jan 2010 16:36:20 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< Content-Length: 2530

< Content-Type: application/json

<

{

"searchspec":{

"fields":{

"data":[

"dgid",

"date_edit",

"date_run",

"scan_ports",

"organization",

"collector_id",

"edited_by",

"discover_non_snmp"

]

},

"options":{

"extended_fetch":{

"type":"boolean",

"description":"Fetch entire resource if 1 (true), or resource link only if 0 (false)",

"default":"0"

},

"hide_filterinfo":{

"type":"boolean",

"description":"Suppress filterspec and current filter info if 1 (true)",

"default":"0"

},

"limit":{

"type":"int",

"description":"Number of records to retrieve",

"default":"100"

},

"offset":{

"type":"int",

"description":"Specifies the index of the first returned resource within the entire result set",

"default":"0"

}

}

},

"total_matched":"14",

"total_returned":14,

"result_set":[

{

"":{

"URI":"\/discovery_session\/1",

"description":"SNMP:1:2"

}

},

{

"":{

"URI":"\/discovery_session\/2",

"description":"21:22:23:25:80"

}

},

[...REMOVED SESSONS 3-13 FROM RESPONSE, FOR BREVITY]

{

"":{

"URI":"\/discovery_session\/14",

"description":"21:22:23:25:80"

}

},

{

"":{

"URI":"\/discovery_session\/15",

"description":"21:22:23:25:80"

}

}

]

}

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

Notice that the response includes:

  • HTTP/1.1 200 OK. Status code that indicates that our HTTP request was successful.
  • An entry for all of the discovery sessions found. The response includes basic information about 14 discovery sessions, because only 14 sessions exist on our example system. Because we set the limit option to "100", the response could contain information about the first 100 discovery sessions. For each found discovery session, the response includes:

  • URI of the discovery session.
  • Our response is in JSON format. Notice that the URI for the discovery session includes escaped forward slash characters ("\/").

  • Description of the discovery method. A list of values that were selected in the Detection Method & Port field (in the  System > Manage > Classic Discovery page). The possible values are described in the following section, in the description of the scan_ports field.
  • To request all information about all discovery sessions, you can use the extended_fetch option. This is described in the following section.

Viewing Details about All Discovery Sessions

We can use the HTTP GET request and the extended_fetch option to request all information about each returned discovery session. If we append "&extended_fetch=1" to our URI, we can request all information about the first 100 discovery sessions. To do so, we enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session?limit=100&extended_fetch=1"

The response will return a list of the first 100 discovery sessions, with the following information for each session:

  • Discovery Session ID. The unique numeric identifier, assigned to this session by SL1.
  • The Discovery Session ID and the numbered list in the Session Register pane in the System > Manage > Classic Discovery page may not match. The Session Register pane in the System > Manage > Classic Discovery page is sorted by date and changes when a discovery session is edited.

  • dgid. ID of the Device Group associated with this discovery session. If no device group is associated with this discovery session, this field will contain the value "NULL".
  • date_edit. Date and time the discovery session was last edited.
  • date_run. Date and time the discovery session was last executed.
  • scan_ports. A list of values that were selected in the Detection Method & Port field (in the  System > Manage > Classic Discovery page).
  • If in the Detection Method & Port field, a user selected the "Default" method, this list includes the default TCP ports that are used during discovery (21, 22, 23, 25, and 80).
  • If in the Detection Method & Port field, a user selected one or more TCP ports, the list includes those ports.
  • If in the Detection Method & Port field, a user selected "UDP 161", the list includes the string "SNMP".
  • ip_list. The start IP and end IP for each IP range included in the discovery session.
  • credentials. One or more credentials selected for this discovery session.
  • organization. Link to the organization resource associated with the discovery session.
  • collector_id. The appliance ID of the Data Collector associated with the discovery session.
  • edited_by. Link to the account resource for the user who last edited this discovery session.
  • discover_non_snmp. Specifies whether this session will discover devices that don't support SNMP. These devices are called "pingables" in SL1. "0" (zero) means do not include pingables; "1" (one) means include pingables.
  • logs. Link to the logs sub-resource for this discovery session.

NOTE: Our response is in JSON format. Notice that the URIs for other resources include escaped forward slash characters ("\/").

Filtering the List of Discovery Sessions

We can use the fields listed in searchspec to filter the list of discovery sessions that will appear in the response. For the discovery_session resource, the searchspec includes:

  • dgid. Selected Device Group.
  • date_edit. Date and time the session was last edited.
  • date_run. Date and time the session was last run.
  • scan_ports. Value selected in the Detection Method & Ports field.
  • organization. Organization associated with the discovery session.
  • collector_id. Appliance ID of a single Data Collector (not a collector group). Currently, there is no way to query Appliance information through the API.
  • edited_by. The user account that last edited the discovery session.
  • discover_non_snmp. Specifies whether this session will discover devices that don't support SNMP. These devices are called "pingables" in SL1. "0" (zero) means do not include pingables; "1" (one) means include pingables.

If we wanted to view details about only discovery sessions that do not include pingables, we could enter the following at the command line:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session?limit=100&extended_fetch=1&filter.discover_non_snmp=0"

The response would display full details about the first 100 discovery sessions that do not discover pingables.

We can also use the following operators in the searchspec:

  • .not (not equal to)
  • .min (greater than or equal to)
  • .max (less than or equal to)
  • .contains (string comparison)
  • .in (is in a list)

For example, if we wanted to view full details about the first 100 discovery sessions that are not associated with the Data Collector with the ID of 3, we could enter the following at the command line:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session?limit=100&extended_fetch=1&filter.collector_id.not=3"

Retrieving Information about a Specific Discovery Session

We can use the HTTP GET method and the URI for a specific discovery session to request information about that specific discovery session.

When you include the URI for a specific discovery session, the response automatically includes all the information for the session. If you include the URI for a specific discovery session, you do not need to include "extended_fetch=1"

For example, if we wanted to request information about discovery session ID "1", we could enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session/1”

The response would look like this:

...[REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY] 

< HTTP/1.1 200 OK

< Date: Wed, 27 Jan 2010 19:16:49 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< X-EM7-status-message: discovery_session seq:1 loaded successfully

< X-EM7-status-code: OK

< Content-Length: 625

< Content-Type: application/json

<

{

"dgid":null,

"date_edit":"1264540686",

"date_run":"1264544101",

"scan_ports":[

"SNMP",

"1",

"2"

],

"ip_lists":[

{

"start_ip":"192.168.9.1",

"end_ip":"192.168.9.100"

},

{

"start_ip":"192.168.10.200",

"end_ip":"192.168.10.203"

}

],

"credentials":[

"\/api\/credential\/snmp\/1",

"\/api\/credential\/snmp\/2",

"\/api\/credential\/db\/10"

],

"organization":"\/api\/organization\/0",

"collector_id":"3",

"edited_by":"\/api\/account\/28",

"discover_non_snmp":"0",

"logs":{

"URI":"\/api\/discovery_session\/1\/log",

"description":"Discovery Session Logs"

}

}

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

 

  • Notice the HTTP status message and the ScienceLogic status messages.
  • The response includes all the details about the specified discovery session
  • If the discovery session did not exist (for example, if we supplied an incorrect ID), the response would include:

HTTP/1.1 404 Not Found

X-EM7-status-message: Unable to find discovery_session w/ id of '401'

X-EM7-info-message: Use /discovery_session search to find valid discovery_session resources

 

Starting a Discovery Session

After the initial discovery, SL1 automatically polls monitored devices and applications to retrieve new and updated data. SL1 performs these updates at regular intervals. However, you can manually execute a discovery session at any time.

You can use the API to manually execute an existing discovery session. To do this, we use the URI of the existing discovery session, the HTTP POST method, and an additional resource called discovery_session_active.

The discovery_session_active resource allows you to execute a discovery session, view a list of currently active discovery sessions, and stop a currently active discovery session.

In our example, we'll POST the URI for a discovery session to the discovery_session_active resource. We'll use discovery session ID 1 as the discovery session.

To execute discovery session 1, enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active" -H 'content-type:application/em7-resource-uri' --data-binary "/api/discovery_session/1"

  • "https://192.168.10.205/api/discovery_session_active". Notice that the address for the HTTP Post includes the discovery_session_active resource in the URI.
  • 'content-type:application/em7-resource-uri'. Tells the API that the incoming data is a resource URI.
  • --data-binary "/api/discovery_session/1". Specifies that HTTP POST should transmit use the URI exactly as is, with no extra processing. The URI of the discovery session must be surrounded by double-quotes.

The response looks like this:

[...REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]

< HTTP/1.1 202 Accepted

< Date: Wed, 27 Jan 2010 19:36:44 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< X-EM7-status-message: Discovery session queued for discovery

< X-EM7-status-code: ACCEPTED

< Content-Length: 1

< Content-Type: application/json

<

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

 

  • The HTTP status code is 202, because the action did not complete within the HTTP response time. This is because the discovery session is still running when the API generates the response.
  • Notice the ScienceLogic status messages, which specify that the session has been queued for execution.
  • If the discovery session is already running or is already queued, the response includes:

HTTP/1.1 400 Bad Request

X-EM7-status-message: /discovery_session/1 is already active

X-EM7-status-code: BAD_REQ

Viewing a List of All Active Discovery Sessions

You can use HTTP GET and the discovery_session_active resource index to request a list of all currently active discovery sessions.

To view a list of all currently active discovery sessions, enter the cURL command from the previous section, to start a discovery session:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active" -H 'content-type:application/em7-resource-uri' --data-binary "/api/discovery_session/1"

Then immediately enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active?limit=100"

The response looks like this:

* About to connect() to 192.168.10.205 port 443 (#0)

* Trying 192.168.10.205... connected

* Connected to 192.168.10.205 (192.168.10.205) port 443 (#0)

* Server auth using Basic with user 'em7admin'

> GET /discovery_session_active?limit=100 HTTP/1.1

> Authorization: Basic ZW03YWRtaW46ZW03YWRtaW4=

> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3

> Host: 192.168.10.205

> Accept: */*

> X-em7-beautify-response:1

>

< HTTP/1.1 200 OK

< Date: Wed, 27 Jan 2010 19:42:51 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< Content-Length: 1087

< Content-Type: application/json

<

[.... REMOVED SEARCHSPEC INFORMATION FROM response, FOR BREVITY]

"total_matched":"1",

"total_returned":1,

"result_set":[

{

"":{

"URI":"\/api\/discovery_session_active\/1",

"description":"SNMP:1:2"

}

}

]

}

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

  • We receive the HTTP status code and a ScienceLogic status message.
  • We found one active discovery session.
  • The ID for the active discovery session is "1", with a URI of /api/discovery_session_active/1.

Our response is in JSON format. Notice that the URI for the discovery session includes escaped forward slash characters ("\/").

Retrieving Information about a Specific Active Discovery-Session

We can request information about a specific, active discovery session using the HTTP GET method with the URI for a specific discovery_session_active resource.

To request details about an active discovery session, perform the following:

First, start a discovery session. Enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active" -H 'content-type:application/em7-resource-uri' --data-binary "/api/discovery_session/1"

Before the discovery session completes, enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active/1

HTTP/1.1 303 See Other

X-EM7-status-message: The requested discovery_session is not currently active.

X-EM7-status-code: FOUND

 

and will also include a redirect to the discovery_session resource for the discovery session.

Viewing Logs for a Discovery Session

When you request information about a discovery session, the returned data includes a sub-resource: logs. Sub-resources are always associated with their parent resource. Sub-resources have their own URI, appended to that of their parent resource. In our example, logs is a sub-resource of a discovery_session resource.

If we look at the response from an HTTP GET of discovery session 1, the logs sub-resource looks like this:

"logs":{

"URI":"\/api\/discovery_session\/1\/log",

"description":"Discovery Session Logs"

}

Each discovery session has only a single log. Each time the discovery session is executed, the previous log is overwritten with information from the current session.

To view the log for a discovery session, enter the following HTTP GET command at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session/1/log?limit=100

Note that we appended the URI of the log to the URI of the discovery session, as referenced in the HTTP GET of discovery session 1.

The response looks like this:

[...REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY] 

< HTTP/1.1 200 OK

< Date: Wed, 27 Jan 2010 20:07:34 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< Transfer-Encoding: chunked

< Content-Type: application/json

<

[.... REMOVED SEARCHSPEC INFORMATION FROM response, FOR BREVITY]

"total_matched":null,

"total_returned":71,

"result_set":[

{

"log_tstamp":"1264621963",

"msg_id":"124",

"msg_txt":"Beginning auto-discovery session"

},

{

"did":"\/device\/113",

"ip":"192.168.9.71",

"log_tstamp":"1264621979",

"msg_id":"500",

"msg_txt":"Discovered and modeled existing device"

},

{

"did":"\/device\/114",

"ip":"192.168.9.70",

"log_tstamp":"1264621979",

"msg_id":"500",

"msg_txt":"Discovered and modeled existing device"

},

{

"did":"\/device\/115",

"ip":"192.168.9.72",

"log_tstamp":"1264621979",

"msg_id":"500",

"msg_txt":"Discovered and modeled existing device"

},

{

"ip":"192.168.9.12",

"log_tstamp":"1264621994",

"msg_id":"504",

"msg_txt":"Discovered, not modeled, pingable device"

},

[...REMOVED REMAINING 66 DEVICE ENTRIES, FOR BREVITY]

{

"log_tstamp":"1264622228",

"msg_id":"125",

"msg_txt":"Auto-discovery session completed"

}

]

}

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

  • We receive the HTTP status code and a ScienceLogic status message.
  • The log includes an entry for each discovered device, including device IP, device name for SNMP devices, date and time device was discovered, and a description of what was performed on the device.

Stopping a Currently Running Discovery-Session

We can perform an HTTP DELETE method on a discovery_session_active resource to stop a currently running discovery session.

Let's first start discovery session 1 again. To do this, enter the following at the command prompt:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active" -H 'content-type:application/em7-resource-uri' --data-binary "/api/discovery_session/1"

Before the discovery session completes, enter the following at the command prompt to stop the discovery session:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session_active/1" –X DELETE

  • /api/discovery_session_active/1. We used the URI of the currently active discovery session.
  • –X DELETE. We simply appended "-X DELETE" to our HTTP statement to use the DELETE method.

The response looks like this:

* About to connect() to 192.168.10.205 port 443 (#0)

* Trying 192.168.10.205... connected

* Connected to 192.168.10.205 (192.168.10.205) port 443 (#0)

* Server auth using Basic with user 'em7admin'

> DELETE /discovery_session_active/1 HTTP/1.1

> Authorization: Basic ZW03YWRtaW46ZW03YWRtaW4=

> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3

> Host: 192.168.10.205

> Accept: */*

> X-em7-beautify-response:1

>

< HTTP/1.1 202 Accepted

< Date: Wed, 27 Jan 2010 20:49:59 GMT

< Server: Apache

< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow

< X-EM7-status-message: Collector signaled to stop Discovery Session

< X-EM7-status-code: ACCEPTED

< Content-Length: 1

< Content-Type: application/json

<

* Connection #0 to host 192.168.10.205 left intact

* Closing connection #0

  • Notice that the ScienceLogic status message indicates that the discovery session will be stopped.
  • If the discovery session was not currently running, the response would include the following:

HTTP/1.1 400 Bad Request

X-EM7-status-message: The requested discovery_session is not currently active.

X-EM7-status-code: BAD_REQ

Deleting a Discovery Session

You can use the HTTP DELETE method on a discovery_session resource to remove a discovery session from SL1. When you remove a discovery session from SL1, the entry is removed from the Session Register in the System > Manage > Classic Discovery page, and users can no longer execute this discovery session.

To delete a discovery session from SL1, enter the following at the command line:

curl -v -k -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/discovery_session/1" –X DELETE

  • discovery_session/1. We used the URI of the discovery session we want to delete.
  • –X DELETE. We simply appended "-X DELETE" to our HTTP statement, to specify that this is a DELETE method.