In SL1, a ticket is a request for work. This request can be in response to a problem that needs to be fixed, for routine maintenance, or for any type of work required by your enterprise. A ticket can be assigned to a specific user, to inform and remind that user of requests for work.
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
-
- 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 you 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 SL1. To perform the tasks in this
- View tickets and ticket details
- View Ticket Queues
- Edit a ticket
- Create a ticket
- Assign a ticket to a user
- Add a new note to a ticket
Getting Started
- In the examples in this
- In the examples in this
- In the examples in this
The examples in this
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:examplepassword' "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:examplepassword'. The -u option tells cURL to authenticate as a specified user. In our example, we authenticated as the user "em7admin" with the password "examplepassword".
- "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, 25 Aug 2010 15:47:40 GMT
14) < Server: Apache
15) < X-EM7-Implemented-methods: GET
16) < X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
17) < Content-Length: 1451
18) < Content-Type: application/json
19) <
20) [
21) {
22) "URI":"\/account",
23) "description":"Get\/Update\/Add\/Delete User Accounts"
24) },
25) {
26) "URI":"\/alert",
27) "description":"Create Alerts"
28) },
29) {
30) "URI":"\/credential",
31) "description":"View Credentials"
32) },
33) {
34) "URI":"\/device?limit=100",
35) "description":"Get\/Update\/Add\/Delete Devices and Get Collected Data"
36) },
37) {
38) "URI":"\/device_group?limit=100",
39) "description":"Get\/Update\/Add\/Delete Device Groups"
40) },
41) {
42) "URI":"\/device_template?limit=100",
43) "description":"Get\/Update\/Add\/Delete Device Templates"
44) },
45) {
46) "URI":"\/discovery_session?limit=100",
47) "description":"Get\/Update\/Add\/Delete Device Discovery Sessions"
48) },
49) {
50) "URI":"\/discovery_session_active?limit=100\/",
51) "description":"View\/Start\/Stop Active Device Discovery Sessions"
52) },
53) {
54) "URI":"\/dynamic_app\/",
55) "description":"Get Dynamic Application Resources"
56) },
57) {
58) "URI":"\/event",
59) "description":"View\/Update\/Clear Events"
60) },
61) {
62) "URI":"\/monitor",
63) "description":"Get\/Update\/Add\/Delete Monitor Policies"
64) },
65) {
66) "URI":"\/organization",
67) "description":"Get\/Update\/Add\/Delete Organizations"
68) },
69) {
70) "URI":"\/ticket?limit=100",
71) "description":"Get\/Update\/Add\/Delete Tickets"
72) },
73) {
74) "URI":"\/ticket_queue",
75) "description":"Get Ticket Queues"
76) }
77) {
78) "URI":"\/ticket_state?limit=100",
79) "description":"Get\/Update\/Add\/Delete Custom Ticket States"
80) },
81) ]
82) Connection #0 to host 192.168.10.205 left intact
83) 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-19 show the header information for the response.
- Lines 20-81 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 ticket resource. The ticket resource uses the following URI and includes the following description:
69) {
70) "URI":"\/ticket?limit=100",
71) "description":"Get\/Update\/Add\/Delete Tickets"
72) }
NOTE: The response is in JSON format. Notice that the URI for the ticket includes escaped forward slash characters ("\/").
Viewing a List of Tickets
In the previous section, we used an HTTP GET request to retrieve information about the root directory of the API. The response included a list of resources. From the previous response, we learned that we can retrieve information about tickets.
To access a resource, like ticket, we can append its URI to the URI of the root directory. So to access the resource ticket, we could enter the following at the command line.
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket"
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 /ticket 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: */*
> em7-beautify-response:1
>
< HTTP/1.1 302 Found
< Date: Wed, 25 Aug 2010 15:48:40 GMT
< Server: Apache
< X-EM7-Implemented-methods: GET,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< Location: /api/ticket?limit=100
< X-EM7-status-message: ticket index requires a limit
< X-EM7-status-code: FOUND
< Content-Length: 833
< Content-Type: application/json
<
{"searchspec":
{"fields":
{"data":["class","severity","status","source","date_create","date_update","assigned_to","resolution","cause","escalation","chargeback","date_close","auto_close","organization","description","opened_by","updated_by","closed_by","ticket_queue","parent_ticket"]},
"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":"102","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 tickets in SL1. Instead, the response contains:
- HTTP/1.1 302 Found. This status code indicates that ticket resources were found, but our request was missing required filtering and options.
- Location: /ticket?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: ticket 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 ticket resources and that our HTTP request was missing the "limit" option.
- "searchspec". The response includes a list of searchspec options. These options allow us to filter the items (in this case, tickets) that are included in a response.
- "total_matched":"102", "total_returned":"0, "result_set":[]. This line indicates that the request could have returned 102 tickets, but that our request returned zero tickets.
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:examplepassword' "https://192.168.10.205/api/ticket?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 /api/ticket?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, 25 Aug 2010 15:49:40 GMT
< Server: Apache
< X-EM7-Implemented-methods: GET,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< Transfer-Encoding: chunked
< Content-Type: application/json
<
{
"searchspec":{
"fields":{
"data":[
"class",
"severity",
"status",
"source",
"date_create",
"date_update",
"assigned_to",
"resolution",
"cause",
"escalation",
"chargeback",
"date_close",
"auto_close",
"organization",
"description",
"opened_by",
"updated_by",
"closed_by",
"ticket_queue",
"parent_ticket"
]
},
"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":"102",
"total_returned":100,
"result_set":[
{
"URI":"\/api\/ticket\/1",
"description":"TICKET FOR ORGANIZATION: Device not responding to critical ping "
},
{
"URI":"\/api\/ticket\/2",
"description":"TICKET FOR ORGANIZATION: Connection refused to port: Timeout while requesting http:\/\/www.google.com"
},
[.... REMOVED TICKETS 3-98 FROM response, FOR BREVITY]
{
"URI":"\/api\/ticket\/99",
"description":"Rollback Configuration on Device CustB_2821-1.cisco.com"
},
{
"URI":"\/api\/ticket\/100",
"description":"Physical Memory usage has exceeded threshold: (80%) currently (99%)"
}
]
}
* 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 each of the first 100 tickets found. The response includes basic information about the first 100 tickets found (as specified in the "limit" option). For each found ticket, The response includes:
- URI of the ticket, which includes the ticket ID.
NOTE: Our response is in JSON format. Notice that the URI for the ticket includes escaped forward slash characters ("\/").
- Description text from the ticket.
- To retrieve all information about a ticket, you can use the extended_fetch option. This is described in the following section.
Viewing a List of Tickets and Ticket Details
We can use the HTTP GET method and the extended_fetch option to retrieve all information about each returned ticket. If we append "&extended_fetch=1" to our URI, we can retrieve all information about the specified tickets. To do so, we enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket?limit=100&extended_fetch=1"
For each returned ticket, The response will include something like the following structure:
{
"class":"1",
"severity":"2",
"status":"0",
"source":"43",
"date_create":"2010-01-18 20:12:06",
"date_update":"2010-01-18 20:12:06",
"assigned_to":"\/api\/account\/0",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0000-00-00 00:00:00",
"auto_close":"0",
"custom_fields":{
},
"organization":"\/api\/organization\/0",
"description":"Rollback Configuration On Device CustB_2821-1.cisco.com",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/1",
"ticket_queue":"\/api\/ticket_queue\/8",
"parent_ticket":"\/api\/ticket\/0",
"aligned_resource":null,
"notes":{
"URI":"\/api\/ticket\/99\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
}
Notice that the response now includes information about all the ticketing fields.
Also notice that some fields, like organization, include URIs. The URI is a link to a different resource (for example, an organization resource).
NOTE: Our response is in JSON format. Notice that these URIs include escaped forward slash characters ("\/").
Filtering a List of Tickets
We can use the fields listed in searchspec to filter the list of tickets that will appear in the response. For the ticket resource, the searchspec includes:
- class
- severity
- status
- source
- date_create
- date_update
- assigned_to
- resolution
- cause
- escalation
- chargeback
- date_close
- auto_close
- organization
- description
- opened_by
- updated_by
- closed_by
- ticket_queue
- parent_ticket
In our example, we'll filter the list of tickets by severity.
- If we wanted to request only tickets with a severity of "major", we would append "&filter.severity=3" to the URI for our request. To view tickets of a specific severity, use the format:
- "&filter.severity=number_of_severity"
- If we wanted to view all tickets with a severity of major or higher, we would append "&filter.severity.min=3" to the URI for our request. You can use the following operators in a filter clause:
- .not (not equal to)
- .min (greater than or equal to)
- .max (less than or equal to)
- .contains (string comparison)
- .in (is in a list)
To request all tickets with a severity of "major", enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket?limit=100&extended_fetch=1&filter.severity=3"
The response contains all ticket information for all tickets with a severity of "major".
To request all tickets with a severity equal to or greater than major (major and critical), enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket?limit=100&extended_fetch=1&filter.severity.min=3"
The response contains all ticket information for all tickets with a severity of "major" or "critical".
Retrieving Information about a Specific Ticket
We can use the HTTP GET method and the URI for a specific ticket to request information about only that specific ticket.
When you include the URI for a specific ticket, the results automatically include all the information for the ticket. If you include the URI for a specific ticket, you do not need to include "&extended_fetch=1"
For example, if we wanted to request information about ticket 99, we could enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/99”
The response would look 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 /ticket/99 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, 25 Aug 2010 15:51:40 GMT
< Server: Apache
< X-EM7-Implemented-methods: GET,PUT,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< X-EM7-status-message: Ticket tid:99 loaded successfully
< X-EM7-status-code: OK
< Content-Length: 812
< Content-Type: application/json
<
{
"class":"1",
"severity":"2",
"status":"0",
"source":"43",
"date_create":"1263845526",
"date_update":"1263845526",
"assigned_to":"\/api\/account\/0",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0",
"auto_close":"0",
"organization":"\/api\/organization\/0",
"description":"Rollback Configuration On Device CustB_2821-1.cisco.com",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/1",
"ticket_queue":"\/api\/ticket_queue\/8",
"parent_ticket":"\/api\/ticket\/0",
"aligned_resource":null,
"custom_fields":{
},
"notes":{
"URI":"\/api\/ticket\/99\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
}
* 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 ticket.
Updating a Ticket
The easiest way to update a ticket is to:
- Use an HTTP GET request to capture the ticket's current values and store them in a file.
- Edit that captured file.
- Use an HTTP POST method to update the ticket with the contents of the edited file.
In this section, we'll update some values for ticket 99.
Capture Ticket Information in a File
To update a ticket, first we will capture the information from ticket 99 and store it in a file. To do this, enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/99" > ticket99.json
We have now captured the information from ticket 99 and stored it in the file ticket99.json. The file looks like this:
{
"class":"1",
"severity":"2",
"status":"0",
"source":"43",
"date_create":"1263845526",
"date_update":"1263845526",
"assigned_to":"\/api\/account\/0",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0",
"auto_close":"0",
"organization":"\/api\/organization\/0",
"description":"Rollback Configuration On Device CustB_2821-1.cisco.com",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/1",
"ticket_queue":"\/api\/ticket_queue\/8",
"parent_ticket":"\/api\/ticket\/0",
"aligned_resource":null,
"custom_fields":{
},
"notes":{
"URI":"\/api\/ticket\/99\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
}
Edit the Captured File
To update the ticket, we'll edit one or more values in the file ticket99.json. Let's change the severity (from "2" (minor) to "4" (critical)) and status (from "0" (open) to "1" (working)) of the ticket and then save our changes to the file.
NOTE: Do not make changes to the value for notes. This is a sub-resource, which are explained later in this example.
{
"class":"1",
"severity":"4",
"status":"1",
"source":"43",
"date_create":"1263845526",
"date_update":"1263845526",
"assigned_to":"\/api\/account\/0",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0",
"auto_close":"0",
"organization":"\/api\/organization\/0",
"description":"Rollback Configuration On Device CustB_2821-1.cisco.com",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/1",
"ticket_queue":"\/api\/ticket_queue\/8",
"parent_ticket":"\/api\/ticket\/0",
"aligned_resource":null,
"custom_fields":{
},
"notes":{
"URI":"\/api\/ticket\/99\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
}
Use HTTP POST to Update the Ticket with the Edited File
We'll now use an HTTP POST method to update the ticket with the contents of the file ticket99.json. To do this, enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/99" -H 'content-type:application/json' --data-binary @ticket99.json
In addition to the optional "beautify response" header and the URI for the ticket, you must specify:
- 'content-type:application/json'. So the API knows that the incoming data is in JSON format.
- --data-binary @file_name.json. Specifies that HTTP POST should transmit the data exactly as is, with no extra processing. The @ symbol tells cURL that the data is stored in a file.
The response should look like the following:
* 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'
> POST /ticket/99 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
> content-type:application/json
> Content-Length: 722
>
< HTTP/1.1 200 OK
< Date: Wed, 25 Aug 2010 15:53:40 GMT
< Server: Apache
< X-EM7-Implemented-methods: GET,PUT,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< X-EM7-status-message: Ticket tid:99 updated.
< X-EM7-status-code: OK
< Content-Length: 812
< Content-Type: application/json
<
{
"class":"1",
"severity":"4",
"status":"1",
"source":"43",
"date_create":"1263845526",
"date_update":"1263845526",
"assigned_to":"\/api\/account\/0",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0",
"auto_close":"0",
"organization":"\/api\/organization\/0",
"description":"Rollback Configuration On Device CustB_2821-1.cisco.com",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/1",
"ticket_queue":"\/api\/ticket_queue\/8",
"parent_ticket":"\/api\/ticket\/0",
"aligned_resource":null,
"custom_fields":{
},
"notes":{
"URI":"\/api\/ticket\/99\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
- Notice that the status codes and status messages specify that the ticket was updated and also specify the ticket ID. The response contains the ticket with the edits applied, so an additional GET request on the /api/ticket/99 URI is not necessary to see the changes.
- If our file ticket99.json had included bad syntax, we would get:
HTTP/1.1 400 Bad Request
< X-EM7-status-message: Unable to decode JSON string.
< X-EM7-status-code: BAD_REQ
Sending Only Changes in the ticket99.json File
Our ticket99.json file included all the ticket information. However, we could have edited our file ticket99.json to include only changes to the ticket. That is, our file could contain only:
{
"severity":"4",
"status":"1"
}
We could have sent this shortened file with an HTTP POST method and had the same result.
Creating a New Ticket
We can use the HTTP POST method to create a new ticket. To create a ticket, we must perform the following steps:
- Capture an existing ticket and store the information in a file. We will use this file as our template for creating a new ticket.
- Determine the URI for a user account. This is the user that will appear in the opened_by, assigned_to, and updated_by fields.
- Edit the captured file to create the new ticket.
- Perform an HTTP POST method to create a new ticket from the edited file.
The following sections explain each step.
Capturing an Existing Ticket and Storing the Information in a File
First, we will request all the information from an existing ticket and store that information in a file. We will then use the file as a template for creating a new ticket.
To do this, enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/1" > new_ticket.json
We will use the file new_ticket.json as our template.
Determining the URI for a User Account
The fields opened_by, assigned_to, and updated_by require a reference to a user account. Because account is another resource in the API, the reference for each of these fields is a URI for a specific account.
First, let's request the index for the account resource. To do this, enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/account"
The response looks like this:
[REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]
< HTTP/1.1 302 Found
< Date: Wed, 25 Aug 2010 15:54:52 GMT
< Server: Apache
< X-Implemented-methods: GET,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< Location: /account?limit=100
< X-EM7-status-message: account index requires a limit
< X-EM7-status-code: FOUND
< Content-Length: 1828
< Content-Type: application/json
<
{
"searchspec":{
"fields":{
"data":[
"default_map_type",
"user",
"email",
"state",
"restrict_ip",
"admin",
"active",
"create_date",
"edit_date",
"timezone",
"default_map",
"refresh",
"barred",
"page_results",
"event_severity",
"ldap",
"console_height",
"date_format",
"iflabel_pref",
"all_orgs",
"contact_fname",
"contact_lname",
"title",
"dept",
"phone",
"fax",
"cell",
"pager",
"email_2",
"address",
"office",
"city",
"zip",
"country",
"billing_id",
"crm_id",
"tollfree",
"email_3",
"im",
"im_type",
"role",
"critical",
"notes",
"verification_question",
"verification_answer",
"organization",
"theme",
"created_by",
"updated_by",
"user_policy"
]
},
"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":"26",
"total_returned":0,
"result_set":[
]
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
The response tells us that:
- The account URI requires the limit option (like the previous example for the ticket resource).
- We can filter accounts by user-name.
We can now try to find the URI for our current user ID, em7admin. To do this, enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/account?limit=100&filter.user=em7admin"
The response will look like this:
[...REMOVED CONNECTION INFORMATION, HEADER INFORMATION, and SEARCHSPEC INFORMATION FOR BREVITY]
},
"total_matched":"1",
"total_returned":1,
"result_set":[
{
"URI":"\/api\/account\/1",
"description":"em7admin"
}
]
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
- We now know that the URI for the user "em7admin" is "/api/account/1".
NOTE: Our response is in JSON format. Notice that the URI for the account includes escaped forward slash characters ("\/").
Editing the Captured File
We'll edit our captured file like this:
{
"class":"1",
"severity":"3",
"status":"1",
"source":"43",
"assigned_to":"\/api\/account\/1",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0",
"auto_close":"0",
"organization":"\/api\/organization\/0",
"description":"TICKET FOR ORGANIZATION: System | ID: 0",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/0",
"ticket_queue":"\/api\/ticket_queue\/7",
"parent_ticket":"\/ticket\/0",
"aligned_resource":null,
"custom_fields":{
},
"notes":{
"URI":"\/api\/ticket\/1\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
},
"logs":{
"URI":"\/api\/ticket\/1\/log\/?hide_filterinfo=1&limit=1000",
"description":"Logs"
}
}
- We changed the assigned_to, opened_by, and updated_by field to the URI for the user "em7admin". Because the file is in JSON format, we must escape the forward slash characters (/). Notice that we did so when specifying the account URI.
- We removed the entire line that contains "date_create". The API will automatically insert the current date and time in the new ticket.
- We removed the entire line that contains "date_update". The API will automatically insert the current date and time in the new ticket.
- We set the organization field to reference the System organization (URI is "/api/organization/0").
- We accepted the previous ticket's values for all other fields. However, you can edit these fields as you want. To determine a URI value for a field, do an HTTP GET request for the referenced resource (account, organization, ticket, ticket_queue).
- We left the entries for "notes" and "logs" sub-resources. The API ignores these fields and replaces them with empty fields that reference the new ticket's URI.
Using the Edited File to Create a New Ticket
To use the file new_ticket.json to create a new ticket, enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/ticket" -H 'content-type:application/json' --data-binary @new_ticket.json
- Notice that unlike when we updated the ticket, in this example we POST to the URI for the general index for the ticket resource instead of POSTing to a URI for a ticket ID. This is because we do not yet have a ticket ID.
- Like when we updated a ticket, we include the following in the POST:
- 'content-type:application/json'. So the API knows that the incoming data is in JSON format.
- --data-binary @file_name.json. Specifies that HTTP POST should transmit the data exactly as is, with no extra processing. The @ symbol tells cURL that the data is stored in a file.
You should get a response that looks something like this:
[...REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]]
< HTTP/1.1 201 Created
< Date: Wed, 25 Aug 2010 15:54:52 GMT
< Server: Apache
< X-Implemented-methods: GET,PUT,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< Location: /ticket/279
< X-EM7-status-message: Ticket tid:279 added successfully
< X-EM7-status-code: CREATED
< Content-Length: 788
< Content-Type: application/json
<
{
"class":"1",
"severity":"3",
"status":"1",
"source":"43",
"date_create":"1260402605",
"date_update":"1260402605",
"assigned_to":"\/account\/1",
"resolution":"0",
"cause":"0",
"escalation":"0",
"chargeback":"0",
"date_close":"0",
"auto_close":"0",
"organization":"\/api\/organization\/0",
"description":"TICKET FOR ORGANIZATION: System | ID: 0",
"opened_by":"\/api\/account\/1",
"updated_by":"\/api\/account\/1",
"closed_by":"\/api\/account\/0",
"ticket_queue":"\/api\/ticket_queue\/7",
"parent_ticket":"\/api\/ticket\/0",
"aligned_resource":null,
"custom_fields":{
},
"notes":{
"URI":"\/api\/ticket\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
- Notice that the status codes and status messages specify that the ticket was created successfully and also specify the ticket ID.
- If our file new_ticket.json had included bad syntax, we would get:
- Notice that the API automatically inserted the current time (in UNIX timestamp format) for the "date_created" and "date_updated" fields.
- Notice that the API automatically inserted an appropriate URI for the "notes" sub-resource.
HTTP/1.1 400 Bad Request
< X-EM7-status-message: Unable to decode JSON string.
< X-EM7-status-code: BAD_REQ
...
Viewing Notes for a Ticket
When you request information about a ticket, the response includes a sub-resource: notes. Sub-resources are always associated with their parent resource. Sub-resources have their own URI, appended to that of their parent resource. In our examples, notes is a sub-resource of a ticket resource.
We could look at the response from the ticket we just created (ticket 279). In the response, the reference to the notes a sub-resource looks like this:
"notes":{
"URI":"\/ticket\/note\/?hide_filterinfo=1&limit=1000",
"description":"Notes"
}
To view all the notes for the ticket we just created (ticket 279), enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/279/note"
Because we have not yet added a note to this ticket, the response looks like this:
[.... REMOVED CONNECTION INFORMATION, HEADER INFORMATION, AND SEARCHSPEC INFORMATION FROM response, FOR BREVITY]
"total_matched":"0",
"total_returned":0,
"result_set":[
]
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
Suppose we know that ticket ID 97 includes two notes. Let's request all the notes in this ticket. To do this, enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' "https://192.168.10.205/api/ticket/97/note"
The response would look like this:
[.... REMOVED CONNECTION INFORMATION, HEADER INFORMATION, AND SEARCHSPEC INFORMATION FROM response, FOR BREVITY]
"total_matched":"2",
"total_returned":2,
"result_set":[
{
"URI":"\/api\/ticket\/97\/note\/96",
"description":"Someone or some event altered the configuration on this device. Roll back configuration to last-known-good.<br \/>\r\n<br \/>\r\nEvent occured on device CustB_2821-1.cisco.com.<br \/>\r\n<br \/>\r\nSee detail of event at http:\/\/ap.server.url\/\/em7\/index.em7?exec=events&q_type=aid&q_arg=17710&q_sev=1&q_sort=0&q_oper=0.<br \/>\r\n<br \/>\r\n<br \/>\r\n<br \/>\r\n<br \/>"
},
{
"URI":"\/api\/ticket\/97\/note\/270",
"description":"For security, immediately performed rollback.<br \/>\r\n<br \/>\r\nCurrently analyzing logs to determine where change came from.<br \/>\r\n<br \/>"
}
]
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
In the response:
- We see that there are two notes in ticket 97: note 96 and note 270.
- We can view the text included in each note.
Now let's request a specific note. Using ticket 97 and our results above, we can request information about note 96 in ticket 97. To do this, enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/97/note/96"
The response would look like this:
About to connect() to 192.168.10.205 port 443 (#0)
[.... REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]
< HTTP/1.1 200 OK
< Date: Wed, 25 Aug 2010 15:59:52 GMT
< Server: Apache
< X-Implemented-methods: GET,PUT,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< X-EM7-status-message: Note id:96 loaded successfully
< X-EM7-status-code: OK
< Content-Length: 475
< Content-Type: application/json
<
{
"note_text":"Someone or some event altered the configuration on this device. Roll back configuration to last-known-good.<br \/>\r\n<br \/>\r\nEvent occured on device CustB_2821-1.cisco.com.<br \/>\r\n<br \/>\r\nSee detail of event at http:\/\/ap.server.url\/\/em7\/index.em7?exec=events&q_type=aid&q_arg=17710&q_sev=1&q_sort=0&q_oper=0.<br \/>\r\n<br \/>\r\n<br \/>\r\n<br \/>\r\n<br \/>",
"edited_by":"\/api\/account\/1",
"date_edit":"1263845526",
"ip":"192.168.10.206"
"hidden":"0",
"mime_type":"text\/html",
"media": {
"URI": "\/api\/ticket\/97\/note\/96\/media",
"description": "Associated Note Media"
}
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
The response contains the following:
- HTTP code 200 OK. The API was able to successfully find note 96 within ticket 97. If note 96 did not exist, we would see the following:
HTTP/1.1 404 Not Found
X-EM7-status-message: Note id:96 is not a valid note for ticket tid:97
X-EM7-status-code: NOT_FOUND
- Our note contains the following fields:
- note_text
- edited_by
- date_edit
- ip
- hidden
- mime_type
Adding a Note to a Ticket
Now let's try adding a note to an existing ticket. To do this:
We can use the HTTP POST method to add a note to an existing ticket. We will add a note to the ticket we created earlier, ticket 279. To add a note to a ticket, we must perform the following steps:
- Request an existing note and store the information in a file. We will use this file as our template for creating a new note.
- Edit the captured file.
- Execute an HTTP POST method to create a new note from the edited file.
The following sections explain each step.
Capturing an Existing Note and Storing the Information in a File
To add a note to a ticket, first we will request the information from note 96 in ticket ID 97 and store it in a file. We will then use this file as a template. To do this, enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/97/note/96" > new_note.json
The information from the note will be stored in the file new_ note.json. We will use this file as our template.
Editing the Captured File
We'll edit our file new_note.json like this:
{
"hidden":"0",
"note_text":"This is a test note from the API",
"mime_type":"text\/html",
"edited_by":"\/api\/account\/1"
}
- We removed the lines that contain "date_edit" and "ip". The API will automatically insert the current date and time and the source IP of the request in the new note.
- We removed the "media" section.
- In the mime_type field, we accepted the value from the previous ticket (text/html).
- In the hidden field, we accepted the value from the previous ticket ("0", zero).
- When "hidden" is set to "0" (zero), the note is not cloaked.
- When "hidden" is set to "1" (one), the note is cloaked.
- We changed the value of the note_text field to "This is a test note from the API".
- We changed the edited_by field to the URI for the user "em7admin" (/api/account/1). Because the file is in JSON format, we must escape the forward slash characters (/). Notice that we did so when specifying the account URI.
Creating a New Note Using the Edited File
To use the file new_note.json to create a new note in ticket 279, enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/279/note" -H 'content-type:application/json' --data-binary @new_note.json
- Notice that we POST to the URI for the index for the note sub-resource for this ticket, instead of to a specific note ID. This is because we do not yet have a note ID.
- We include the following in the POST:
- 'content-type:application/json'. So the API knows that the incoming data is in JSON format.
- --data-binary @file_name.json. Specifies that HTTP POST should transmit the data exactly as is, with no extra processing. The @ symbol tells cURL that the data is stored in a file.
The response should look like the following:
[.... REMOVED CONNECTION INFORMATION and SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]
< HTTP/1.1 201 Created
< Date: Wed, 25 Aug 2010 16:01:49 GMT
< Server: Apache
< X-Implemented-methods: GET,PUT,POST
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< Location: /api/ticket/279/note/273
< X-EM7-status-message: Note /ticket/279/note/273 added.
< X-EM7-status-code: CREATED
< Content-Length: 142
< Content-Type: application/json
<
{
"date_edit":"1264525835",
"hidden":"0",
"note_text":"This is a test note from the API",
"edited_by":"\/api\/account\/1"
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
- Notice that the status codes and status messages specify that the note was created successfully and also specify the note ID (note 273).
- If our file new_ticket.json had included bad syntax, we would get:
HTTP/1.1 400 Bad Request
< X-EM7-status-message: Unable to decode JSON string.
< X-EM7-status-code: BAD_REQ
...
- Notice that the API automatically inserted the current date and time (in UNIX timestamp format) in the date_edited field.
Viewing the Attachments for a Ticket
In a ticket, each note can include one or more attachments. Each ticket note has a /media sub-resource that can be used to search and view the attachments associated with that ticket note.
For example, to view the attachments for ticket 2058, at note 11, we could enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/2058/note/11/media?limit=100"
The response would look like this:
[.... REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]
< HTTP/1.1 200 OK
< Date: Wed, 25 Aug 2010 16:03:11 GMT
< Server: Apache
< X-Implemented-methods: GET
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< X-EM7-status-message: Fileindex found with 1 resources.
< X-EM7-status-code: OK
< Content-Disposition: inline; filename="test_attachment.rtf"
< Content-Length: 357
< Content-Type: application/rtf
<
{
"searchspec": {
"fields": [
"creation_date",
"file_length",
"is_attachment",
"is_complete",
"mime_type",
"modified_date",
"total_size",
"user_owner"
],
"options": {
"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"
},
"extended_fetch": {
"type": "boolean",
"description": "Fetch entire resource if 1 (true), or resource link only if 0 (false)",
"default": "0"
},
"link_disp_field": {
"type": "enum",
"description": "When not using extended_fetch, this determines which field is used for the \"description\" of the resource link",
"default": "mime_type",
"values": [
"is_attachment",
"mime_type",
"is_complete",
"user_owner",
"total_size",
"file_length",
"creation_date",
"modified_date"
]
}
}
},
"total_matched": 1,
"total_returned": 1,
"result_set": [
{
"URI": "\/api\/ticket\/2058\/note\/11\/media\/Penguins.jpg\/info",
"description": "image\/jpeg"
}
]
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
In the response, notice that:
- The status codes and messages specify that one attachment was found.
- If no attachments were found, the response would include:
X-EM7-status-message: Fileindex found with 0 resources.
- The result set includes an entry for each attachment.
- The entry for each attachment includes the URI that can be used to request detailed information about the attachment.
Now let's request a specific attachment. Using ticket 2058, note 11 and our results above, we can request information about the "Penguins.jpg" attachment. To do this, enter the following at the command line:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/2058/note/11/media/Penguins.jpg/info"
The response would look like this:
About to connect() to 192.168.10.205 port 443 (#0)
[.... REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]
< HTTP/1.1 200 OK
< Date: Wed, 25 Aug 2010 15:59:52 GMT
< Server: Apache
< X-Implemented-methods: GET,POST,PUT,DELETE
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< X-EM7-status-message: /ticket/2058/note/11/media/Penguins.jpg loaded successfully
< X-EM7-status-code: OK
< Content-Length: 475
< Content-Type: application/json
<
{
"mime_type": "image\/jpeg",
"is_complete": "1",
"user_owner": "\/api\/account\/0",
"total_size": 777835,
"file_length": 777835,
"creation_date": "1445379816",
"modified_date": "1445379816",
"is_attachment": "1",
"chunks": [
{
"offset": 0,
"length": 777835,
"md5": "9d377b10ce778c4938b3c7e2c63a229a"
}
],
"data": {
"URI": "\/api\/ticket\/2058\/note\/11\/media\/Penguins.jpg",
"description": "File Contents"
}
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
The response contains the following:
- HTTP code 200 OK. The API was able to successfully find the Penguins.jpg attachment.
- The URI field in the data section specifies the download link for the file.
NOTE: For FIPS-compliant systems, the response will include a SHA hash, not an MD5 hash.
Adding an Attachment to a Ticket Note
You can add an attachment to an existing ticket note. To do this, we must use the HTTP PUT method instead of the HTTP POST method. The HTTP PUT method is used for explicitly adding or replacing (where HTTP POST is used for creating or updating).
The API will not allow you to add an attachment with an HTTP POST method. If you try, the response will look like this:
[.... REMOVED CONNECTION INFORMATION AND SOME HEADER INFORMATION FROM RESPONSE, FOR BREVITY]
< HTTP/1.1 405 Method Not Allowed
< Date: Wed, 25 Aug 2010 16:04:25 GMT
< Server: Apache
< X-Implemented-methods: GET,PUT,DELETE
< X-Powered-By: ScienceLogic,LLC - EM7 API/SL1 PowerFlow
< X-EM7-status-message: POST not allowed for note media. PUT an explicitly named new attachment or image
< X-EM7-status-code: BAD_METHOD
< Content-Length: 214
< Content-Type: application/json
<
{
"errors":[
{
"errorcode":"BAD_METHOD",
"message":"POST not allowed for ticket attachments. PUT an explicitly named new attachment or image"
}
],
"messages":[
],
"resource_body":null
}
* Connection #0 to host 192.168.10.205 left intact
* Closing connection #0
To use HTTP PUT, we must include the "-T" option with the cURL command.
Suppose we want to add the image file "spidey.png" to ticket 97, note 96. We could enter the following at the command prompt:
curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:examplepassword' "https://192.168.10.205/api/ticket/97/note/96/media/spidey.png" -H "content-type:image/png" -T ./spidey.png
- attachment/spidey.png. Tells the API the filename to use when saving the attachment in the system.
- -H "content-type:image/png". Tells the API that the attachment will be an image file of type png.
- -T. Tells cURL to perform an HTTP PUT.
- ./spidey.png. Full pathname of the file to attach. "./" means "current directory".
- Notice that unlike HTTP POST, the HTTP PUT method does not require the "--data-binary option" or the "@" characters before the filename.
If an attachment has been prohibited in the Ticket Attachment Blacklist page (Registry . Ticketing > Attachment Blacklist), the API will not attach the file to the ticket note. The API will not allow you to attach files with a file extension that matches a blacklist entry.