Alloy Navigator API - Alloy...

P r o d u c t V e r s i o n : 7 . 0

D o c u m e n t R e v i s i o n : 1 . 0D a t e : N o v e m b e r 3 0 , 2 0 1 5

Alloy Software Incorporated88 Park Avenue, Unit 2B, Nutley, NJ 07110

phone: +1 (973) 661-9700fax: +1 (973) 661-9777e-mail: [email protected]: www.alloy-software.com

Alloy Navigator APIIntegration with External Systems

U S E R ’ S G U I D E

Copyright © 2015 Alloy Software, Inc. All rights reserved. Alloy Software, Alloy Navigator, Alloy Navigator Express, Alloy Discovery, and Alloy Discovery Express logos are registered trademarks owned by Alloy Software, Inc. All other trademarks and brand names are the property of their respective owners. This manual, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Alloy Software, Inc. Alloy Software, Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in this book. This manual is protected by United States and foreign copyright. This manual shall not be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior permission of Alloy Software, Inc.

Alloy Navigator API User’s Guide

Table of Contents i

Table of Contents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Introducing the Alloy Navigator API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Document Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Default URL to Access the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2HTTP Request Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Response Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Date and Time Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Obtaining an API Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Obtaining Information About an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Creating an Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Updating an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Obtaining a List of Objects (GET) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Obtaining a List of Objects (POST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Checking Task Action Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Supported Alloy Navigator Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Software for Testing the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24


Chapter 1. Introduction 1

CHAPTER 1. Introduction

Introducing the Alloy Navigator API

The Alloy Navigator API enables you to integrate Alloy Navigator with external applications. Using the API, you can work with Alloy Navigator database objects over the Internet or a local network.

The Alloy Navigator API offers the following functionality:

Authenticating the user

Obtaining information about objects

Creating objects

Updating objects

Listing objects

Checking Task Action availability

For the list of supported objects, see “Supported Alloy Navigator Object Classes” on page 22.

Document Audience

The Alloy Navigator API User’s guide targets system administrators and software engineers who will configure third-party applications to interact with Alloy Navigator.

This guide assumes that you are familiar with other Alloy Navigator product documentation and have a basic understanding of Web technologies, including the HTTP protocol, JSON, and XML.


Chapter 2. Getting Started 2

CHAPTER 2. Getting Started

Default URL to Access the API

It is further assumed that the API handler application is installed in a virtual directory named api. Example:

http://www.example.com/api/

HTTP Request Methods

Alloy Navigator API calls utilize two HTTP request methods: GET and POST.

URL Encoding

All URL elements and parameters must be URL-encoded. For more information on URL encoding, see https://en.wikipedia.org/wiki/Query_string#URL_encoding. Below are examples of a URL with non-encoded and encoded parameters.

Initial URL (non-encoded parameters):

http://www.example.com/api/v1/Incidents?Assignee=John Doe&par_sort_desc=Created_Date&par_fields=Ticket,Due_Date, Summary&par_offset=50&par_limit=20

URL with encoded parameters:

http://www.example.com/api/v1/Incidents?Assignee=John%20Doe&par_sort_desc=Created_Date&par_fields=Ticket%2CDue_Date%2CSummary&par_offset=50&par_limit=20

Response Format

The default response format is JSON. The API also supports the XML format. If you want to receive responses in the XML format, specify it in the request header:

Accept: application/xml orAccept: text/xml

You can specify the XML response format for all API requests except an initial request for obtaining an API access token. An API access token is always received in the JSON format.

Date and Time Format

The API uses the following date and time format:

https://en.wikipedia.org/wiki/Query_string#URL_encoding

https://en.wikipedia.org/wiki/Query_string#URL_encoding



Complete date:

YYYY-MM-DD (eg 1997-07-16)

Complete date plus hours, minutes, and seconds:

YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)

When sending requests to the API, you must specify date and time values in this format.

The format includes information about the user’s timezone. The API also has its own timezone, which you specify when configuring the API. When the user’s timezone is different from the API’s timezone, the user’s time is converted to the API’s time.

Obtaining an API Access Token

To start using the Alloy Navigator API module, you first need to authenticate the user and obtain an API access token.

To obtain an access token, send a POST request to the API URL.

HTTP method

POST

API URL

http://www.example.com/api/token

POST parameters

A token is valid for 8 hours.

Once you have obtained a token, you will be able to specify it in the Authorization Header section when sending requests to the API. Note that you must prefix the token with “bearer”, for example:

Authorization: bearer <token>

Parameter Description

grant_type This parameter must be set to password.

username Credentials for an Alloy Navigator technician or SSP customer account.

A password must be specified for accounts not only with Standard authentication, but also with Windows authentication.password



Note that the user authenticated to the API is in the same security context as when logged in to other Alloy Navigator modules. For example, technicians can access through the API the same objects and actions as in the Main Console and the Web Portal.

Example

Here is an example of a correct request.

POST parameters:

grant_type: passwordusername: <correct username> password: <correct password>

Response:

{ "access_token": "m_egolZq...your_token...zkw", "token_type": "bearer", "expires_in": 28799}

Error Handling

This method may return errors when the user cannot be authenticated.

Example

The following request is incorrect because of an invalid grant_type.

POST parameters:

grant_type: <bad string>username: <correct username>password: <correct password>

Response:

{ "error": "unsupported_grant_type"}

Example

The following request is incorrect because of bad username and password.

POST parameters:

grant_type: passwordusername: <bad username> password: <bad password>



Response:

{ "error": "invalid_grant"}


Chapter 3. Obtaining Information About an Object 6

CHAPTER 3. Obtaining Information About an Object

The API module provides the ability to obtain information about objects: Tickets, Computers, Persons, etc. For the list of supported objects, see “Supported Alloy Navigator Object Classes” on page 22.

HTTP method

GET

API URL

http://www.example.com/api/v1/object/<oid>

URL parameters

Example


(GET) http://www.example.com/api/v1/object/T000002/HeadersAuthorization: bearer <your access token>

Response:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Items": [{ "name": "Ticket", "caption": "Ticket", "value": "T000002" }, { "name": "Description", "caption": "Description", "value": "Ever since I received this computer earlier today it's been really slow. In fact it's slower than my old computer. Everything from browsing to using Microsoft Word seems to drag and all I get is the hourglass." }, ................. { "name": "Impact",


oid Object identifier.

Example:

T000001


Chapter 3. Obtaining Information About an Object 7

"caption": "Impact", "value": "Single Person" }] }}

Example

The following request is incorrect because it does not contain a token.

(GET) http://www.example.com/api/v1/object/T000002

Response:

{ "Message": "Authorization has been denied for this request."}

Example

The following request is incorrect because of a bad object identifier.

(GET) http://www.example.com/api/v1/object/incorrectOIDHeadersAuthorization: bearer <your access token>

Response:

{ "success": false, "errorCode": 101, "errorText": "$$$MSG_OBJECT_ID_NOT_FOUND,incorrectOID", "responseObject": null}


Chapter 4. Creating an Object 8

CHAPTER 4. Creating an Object

The API provides the ability to add new objects via Create Actions.

HTTP method

POST

Values should be passed in the body of the POST request. To send data in the HTML Form format, set the header’s Content-Type field to application/x-www-form-urlencoded. For JSON, set Content-Type to application/json.

API URL

http://www.example.com/api/v1

POST request

Request Headers: Authorization: bearer <your access token> Content-Type: application/jsonPOST body: {ActionId: <actionId>,Fields: {<fieldName1>: '<fieldValue1>',<fieldName2>: '<fieldValue2>'...}}



POST parameters

Example


(POST) http://www.example.com/api/v1Request Headers:Authorization: bearer <your access token>Content-Type: application/jsonPOST Body{ActionId: 231,Fields: {Summary: 'Exchange server down',Description: 'Exchange server is reported to be down. Needs to be fixed ASAP'}}

Response:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Succeed": true, "ObjectID": "b4554178-df1f-4ccb-823d-57f785a6ea5c",


ActionId Create Action ID.

Fields Fields on the Create Action form.

<fieldName1>

<fieldName2>

...

Field names

• For virtual fields, you must specify the name of the field.

• For object fields and activity fields, you can specify either the name of the field or the field’s caption.

Field values

• For reference fields, you must specify the ID of the referenced object (example: ‘T000015’) or its name (example: ‘Alyssa Royal’).

• For classification fields (e.g. Priority or Impact), you must specify a string containing the element’s display value (example: ‘Immediate’ or ‘Multiple People’).

• For boolean fields, you must specify true/false or 1/0.



"ObjectOID": "T000052" }}

Example

Here is an example of a request with an incorrect ActionId.

(POST) http://www.example.com/api/v1/Content-Type: application/jsonPOST Body{ActionId: 99999,Fields: {}}

Response:

{ "success": false, "errorCode": 101, "errorText": "Requested action is not available.", "responseObject": null}


Chapter 5. Updating an Object 11

CHAPTER 5. Updating an Object

The API provides the ability to update objects through Task Actions.

HTTP method

POST

Values should be passed in the body of the POST request. To send data in the HTML Form format, set the header’s Content-Type field to application/x-www-form-urlencoded. For JSON, set Content-Type to application/json.

API URL

http://www.example.com/api/v1/object/<oid>/action/<actionId>

URL parameters

POST request

Request Headers: Authorization: bearer <your access token> Content-Type: application/jsonPOST Body: {<fieldName1>: '<fieldValue1>',<fieldName2>: '<fieldValue2>'...}


oid ID of the object on which you want to execute a Task Action.

Example:

T000001

actionId ID of a Task Action.

Example:

250


Chapter 5. Updating an Object 12

POST parameters

Example


(POST) http://www.example.com/api/v1/object/T000052/action/247Request Headers: Authorization: bearer <your access token> Content-Type: application/jsonPOST Body:{Resulution: 'Fixed. Exchange is up and running again'

}

Response:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Succeed": true, "ObjectID": "b4554178-df1f-4ccb-823d-57f785a6ea5c", "ObjectOID": "T000052" }}


<fieldName1>

<fieldName2>

...

Fields on the Task Action form.

Field names

• For virtual fields, you must specify the name of the field.

• For object fields and activity fields, you can specify either the name of the field or the field’s caption.

Field values

• For reference fields, you must specify the ID of the referenced object (example: ‘T000015’) or its name (example: ‘Alyssa Royal’).

• For classification fields (e.g. Priority or Impact), you must specify a string containing the element’s display value (example: ‘Immediate’ or ‘Multiple People’).

• For boolean fields, you must specify true/false or 1/0.


Chapter 6. Obtaining a List of Objects (GET) 13

CHAPTER 6. Obtaining a List of Objects (GET)

The API offers the ability to obtain a list of objects via a GET request with parameters specified in the query string.

HTTP method

GET

API URL

http://www.example.com/api/v1/<objectClass>

URL parameters

GET parameters (query string)

You specify parameters of a GET request in the URL query string:

?param1=value&param2=value...

Parameter/value pairs must be separated by an ampersand (&).


objectClass Alloy Navigator object class.

Examples:

IncidentsComputersKnowledge Base Articles

For the correct spelling of Alloy Navigator object classess, see “Supported Alloy Navigator Object Classes” on page 22.


par_sort_desc Fields by which to sort the result in descending order. Fields must be separated by a comma. This is an optional parameter.

par_sort_asc Fields by which to sort the result in ascending order. Fields must be separated by a comma. This is an optional parameter.

par_fields Fields to show in the result, separated by a comma. This is a required parameter.

A list of fields for a particular object class can be found in the Administrative Setting console: Business Logic Configuration > [Object Class] > Fields.

par_offset A number of records to skip. This is a required parameter.



Example

Here is an example of a correct request for obtaining a list of Incidents.

(GET) http://www.example.com/api/v1/Incidents?par_fields=Summary%2CAssignee%2CDescription&par_limit=10

Response:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Fields": [{ "Name": "Summary", "DataType": "string" }, { "Name": "Assignee", "DataType": "string" }, { "Name": "Description", "DataType": "memo" }], "Data": [{ "Cells": ["New computer slowness", "Arturo Greco", "Ever since I received this computer earlier today it's been really slow. In fact it's slower than my old computer. Everything from browsing to using Microsoft Word seems to drag and all I get is the hourglass."] }, { "Cells": ["Machine slowness again!", "Arturo Greco", "This morning someone was here, and the machine seemed ok, but after lunch the machine has started to act up again, can someone please come by again? I've rebooted several times."] }, ............... { "Cells": ["Can't access Intranet", "Lynch Stevens", "Customer is unable to access the company intranet. Determined he is also unable to access network shares or email"] }] }

par_limit A number of records to show in the result. This is an optional parameter.

<fieldName1>

<fieldName2>

...

Field values to filter the result by.

Example:

Priority=High

This is an optional parameter.




}

Example

Here is an example of a request for obtaining a list of Incidents filtered by Assignee.

(GET) http://www.example.com/api/v1/Incidents?par_fields=Summary%2CAssignee%2CDescription&par_limit=10&Assignee=Arturo%20Greco

Response:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Fields": [{ "Name": "Summary", "DataType": "string" }, { "Name": "Assignee", "DataType": "string" }, { "Name": "Description", "DataType": "memo" }], "Data": [{ "Cells": ["New computer slowness", "Arturo Greco", "Ever since I received this computer earlier today it's been really slow. In fact it's slower than my old computer. Everything from browsing to using Microsoft Word seems to drag and all I get is the hourglass."] }, { "Cells": ["Machine slowness again!", "Arturo Greco", "This morning someone was here, and the machine seemed ok, but after lunch the machine has started to act up again, can someone please come by again? I've rebooted several times."] }, ....................... { "Cells": ["Desktop crashes with BSoD", "Arturo Greco", "My desktop frequently crashes since last week. Today it already crashed two times. See the attached screen capture."] }] }}


Chapter 7. Obtaining a List of Objects (POST) 16

CHAPTER 7. Obtaining a List of Objects (POST)

The API offers the ability to obtain a list of objects via a POST request with parameters specified in the request body.

HTTP method

POST

API URL

http://www.example.com/api/v1/<objectClass>

URL parameters

POST request

Request Headers:Authorization: bearer <your access token>Content-Type: application/jsonPOST Body: { filters:[ { name: '<filterName>', value: '<filterValue>', operation: <filterOperationId> }, ... ], sort: [ { property:'<sortProperty>', direction: '<sortDirection>' }, ... ], fields: ['<field1>', '<field2>',...], offset: <offset>, limit: <limit>


objectClass Alloy Navigator object class.

Examples:

IncidentsComputersKnowledge Base Articles

For the correct spelling of Alloy Navigator object classess, see “Supported Alloy Navigator Object Classes” on page 22.



}

POST parameters

Below are examples of correct requests for obtaining a list of Incidents with different parameters.

Example

Request:

(POST) http://www.example.com/api/v1/IncidentsRequest Headers: Authorization: bearer <your access token> Content-Type: application/jsonPOST Body: { sort: [ { property:'Due_Date', direction: 'desc' }, { property:'Ticket', direction: 'asc'


filters A collection of filters. Each filter must contain a field name, value, and a filtering operation identifier:

• name – a field to filter the data records by

• operation – a numeric value specifying the filtering operation: 0 (equal), 1 (not equal)

• value – a value to use in the filtering operation


sort A collection of field and direction pairs for sorting:

• property – a field to sort by

• direction – sorting order: ascending (asc) or descending (desc).


fields Fields to show in the result. This is a required parameter.

offset A number of records to skip. This is a required parameter.

limit A number of records to show in the result. This is an optional parameter.



} ], fields: ['Ticket', 'Due_Date', 'Summary'], offset: 0, limit: 1000}

Response:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Fields": [{ "Name": "Ticket", "DataType": "string" }, { "Name": "Due_Date", "DataType": "datetime" }, { "Name": "Summary", "DataType": "string" }], "Data": [{ ["T000025", "20150818 14:55:00", "Unable to print"] }, { ["T000022", "20150817 12:06:00", "Unable to boot up a computer"] }, ......................... { ["T000002", "20140620 16:33:38", "New computer slowness"] }] }}

Example

Request:

(POST) http://www.example.com/api/v1/IncidentsRequest Headers: Authorization: bearer <your access token> Content-Type: application/json

POST Body:{ filters:[ { name: 'Ticket', value: 'T000007', operation: 0 }



], fields: ['Ticket', 'Due_Date', 'Summary'], offset: 0, limit: 3}

Response:

{ "success": true,* "errorCode": 0, "errorText": "", "responseObject": { "Fields": [{ "Name": "Ticket", "DataType": "string" }, { "Name": "Due_Date", "DataType": "datetime" }, { "Name": "Summary", "DataType": "string" }], "Data": [{ ["T000007", "20140801 11:06:00", "Unable to access the Internet"] }] }}


Chapter 8. Checking Task Action Availability 20

CHAPTER 8. Checking Task Action Availability

The API enables you to check the availability of a Task Action for a particular object. The availability of Actions depends on object types, object statuses, security roles, and possibly other criteria.

HTTP method

GET

API URL

http://www.example.com/api/v1/object/<oid>/action/<actionId>/check

URL parameters

Example

In this example Task Action 253 for object T000002 is available (the result is true).

(GET) http://www.example.com/api/v1/object/T000002/action/253/checkRequest Headers: Authorization: bearer <your access token>

Responce:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Result": true }}

Example

In this example Task Action 247 for object T000002 is unavailable (the result is false).

(GET) http://www.example.com/api/v1/object/T000002/action/247/check


oid Object identifier.

Example:

T000001

actionId ID of a Task Action.

Example:

250


Chapter 8. Checking Task Action Availability 21

Request Headers: Authorization: bearer <your access token>

Responce:

{ "success": true, "errorCode": 0, "errorText": "", "responseObject": { "Result": false }}


Chapter 9. Supported Alloy Navigator Object Classes 22

CHAPTER 9. Supported Alloy Navigator Object Classes

The API module allows you to work with the majority of Alloy Navigator object classes. Supported object classes are listed below.

Refer to this table for the correct spelling of object class names. You can also use an alternative spelling with no spaces. If needed, you can use table names instead of object class names.

Correct Spelling Alternative Spelling Table Name

All CIs AllCIs CI_List

All Tickets Ticket_List

Announcements Announcements

Approval Requests ApprovalRequests Approval_Requests

Approval Stages ApprovalStages Approval_Stages

Assets Assets

Change Requests ChangeRequests Change_Requests

Computers Computers

Configurations Configurations

Consumables Consumables

Contracts Contracts

Documents Documents

Groups User_Groups

Hardware Hardware

Incidents Incidents

Knowledge Base Articles KnowledgeBaseArticles KB_Articles

Library Items LibraryItems Library

Locations Locations

My Tickets MyTickets My_Requests


Chapter 9. Supported Alloy Navigator Object Classes 23

Networks Networks

Organizations Organizational_Units

Persons Persons

Problems Problems

Products Products

Projects Projects

Purchase Order Items PurchaseOrderItems PO_Items

Purchase Orders PurchaseOrders PO

Reservations Reservations

Service Catalog Items ServiceCatalogItems Service_Catalog_Items

Service Level Agreements ServiceLevelAgreements SLA

Service Requests ServiceRequests Service_Requests

Services Services

Software Catalog SoftwareCatalog Soft_Products

Software Licenses SoftwareLicenses Software_Licenses

Stock Rooms StockRooms Stock_Rooms

Stock Rules StockRules Stock_Rules

Tracked Software TrackedSoftware Tracked_Software

Vendor Products VendorProducts Vendor_Products

Vendors Vendors

Work Orders WorkOrders Work_Orders

Correct Spelling Alternative Spelling Table Name


Chapter 10. Software for Testing the API 24

CHAPTER 10. Software for Testing the API

To test the Alloy Navigator API, you can use any software capable of sending HTTP requests and receiving HTTP responses, for example:

• Chrome REST Console (https://chrome.google.com/webstore/detail/rest-console/cokgbflfommojglbmbpenpphppikmonn)

• Fiddler (http://www.telerik.com/fiddler)

You can also use scripting languages, such as PHP, Python, Ruby, etc.

https://chrome.google.com/webstore/detail/rest-console/cokgbflfommojglbmbpenpphppikmonn

https://chrome.google.com/webstore/detail/rest-console/cokgbflfommojglbmbpenpphppikmonn

http://www.telerik.com/fiddler

Date post:	25-Apr-2018
Category:	Documents
Upload:	phamnga
View:	221 times
Download:	2 times