BMC Track-It! Web. Web Services API Guide. Version 11.3

(1)

Web Services API Guide

(2)

Numara Software and BMC Software Confidential. i

Legal Notices

BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners.

Track-It! is the property of Numara Software, Inc. is registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other Numara Software trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners.

The information included in this documentation is the confidential information of BMC Software, Inc., its affiliates, or licensors. Your use of this information is subject to the terms and conditions of the applicable End User License agreement for the product and to the proprietary and restricted rights notices included in the product documentation.

Numara Software, Inc.

2101 CityWest Blvd, Houston TX 77042-2827, USA 713 918 8800

(3)

Numara Software and BMC Software Confidential. ii

Web Services API

Web Services API Overview

The Web Services API feature enables software developers to integrate Track-It! and other applications or custom utilities in your organization. The API can be used to perform various actions for Work Orders and assets such as creating Work Orders and searching for Work Orders created through other

interfaces, and getting an asset by asset name or number. An XML JSON RESTful Web Service interface to BMC Track-It! is available for all platforms for integration with other applications. It supports .NET 4.0. Functions are available for creating Issues, updating Issues and querying the database for Work Orders.

Note: For Web Services API, a new virtual directory is automatically created by the Track-It! installer. For details, see the following section in the Track-It! 11.3 installation guide: Step 12: Install Track-It! Web (Optional) and Web Services API.

The Track-It! Web API log is available in the following directory: C:\windows\temp.

The Track-It! Web Service API supports the following actions. Click each link for API call details and examples:

• Login—Authenticate the user and generate the access token

Help Desk: Work Orders

• WorkOrder/Get—Get a Work Order • WorkOrder/Update—Update a Work order • WorkOrder/Create—Create a Work Order

• WorkOrder/ChangeStatus—Change a Work Order’s Status • WorkOrder/Close—Close a Work Order (Quick Close) • WorkOrder/AddNote—Add a Note to a Work Order

Inventory: Assets

• Asset/Audit—Audit Assets via Web API • Asset/Create—Create an Asset

• Asset/Get—Get Assets by Asset Number • Asset/GetByID—Get Assets by Asset ID • Asset/GetByName—Get Assets by Asset Name • Asset/GetByFilters—Get Assets by Filters • Asset/Update—Update an Asset by Asset ID • Asset/Update—Update an Asset by Asset Number

Limitations:

• Event Policies and related notifications, as well as Skill Routing Policies are not applied when creating Work Orders via Web API.

• Windows authentication login is not supported. The Technician user name and password is the same as the Technician Client.

• Work Order fields will not be automatically populated, for example, an asset associated with a requestor or a callback number.

• Validation will not be applied for values in integer fields, for example, Hours and Charges in the billing information for a Work Order.

• Validation for character lengths for text fields will not be applied, for example, the Subject field in a Work Order.

See also: Web Services API Data Transfer Object Definitions and Web Services API Error Codes

Authenticate and Generate Access Token

(5)

Numara Software and BMC Software Confidential. 2 • Type of call: GET

• Request Header: <none> • Request body: <none> • Request Parameters:

1. Username: Specify a Track-It! Technician's login ID.

2. Pwd: Specify the Track-It! Technician's password in plain text. • Request returns value:

o JSON object containing the encrypted token in apikey. For details refer to Return-token definitions.

o This token value is required to be passed as a Request header in all subsequent API calls.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/login?username=ben&pwd=

Note:

• This is a mandatory first call that authenticates the user and gets the access token. All of the calls described in the following topics are to pass the token returned by this call in the Request

header.

• The token validity can vary between 1 minute and 8 hours and is controlled by the

“TrackItAPIKeyValidity” configuration in the Track-It! Web web.config file. Default validity is 60 minutes.

• All of the following API calls expect the apikey to be sent as a Request Header.

Web Services API Data Transfer Object Definitions

Return-token Definitions

Name Value

Success true / false

Apikey String value

Work Order DTO fields that can be set through the Create/Update API

Name Value

Id Numeric value

AssetName Asset name - string value

AssignedTechnician Technician Name - string value

Category String value

Location String value

Department String value

Hours Numeric value

Charge Numeric value

Priority Numeric value

RequestorName Requestor Name - string value

StatusName Status - string value

SubType String value

Summary String value

Type String value

UdfText1 String value

(6)

UdfDate1 Date & time

UdfNumeric Numeric value

UdfInt Numeric value

UdfLookup1 String value

ParentIncidentId Numeric value

NotificationBccAddress Email address – string value NotificationCcAddress Email address – string value

RequestorPhoneNumber String value

Work Order DTO fields that are returned by the Get Work Order API

Name Value

Id Numeric value

AssetName Asset name - string value

AssignedTechnician Technician Name - string value TechnicianEmailAddress Email address

TechnicianSmsEmailAddress Email address

Category String value

ResponseDate Date & time

RespondedDate Date & time

RespondedBy String value

AssignedDate Date & time

RequestorEnteredDate Date & time EnteredCompletionDate Date & time ExpectedCompletionDate Date & time HasSkillRoutingExecuted true / false

Location String value

Department String value

Hours Numeric value

Charge Numeric value

IsClosed true / false

(7)

RequestorName Requestor Name - string value

StatusName Status - string value

SubType String value

Summary String value

Type String value

UdfNumeric Numeric value

UdfInt Numeric value

AttachmentCount Numeric value

AssignmentCount Numeric value

IsAssignment true / false

IsIncident true / false

IsIncidentTemplate true / false

IsAssignmentTemplate true / false

ParentIncidentId Numeric value

WasLocked true / false

IsReadOnly true / false

IsClockStopped true / false

Notes List of <Note Object>. For details, see Note Object Definitions, below.

NotificationBccAddress Email address – string value NotificationCcAddress Email address – string value

(8)

Note Object Definitions

Name Value Can be set through

AddNote API?(Yes/No)

CreatedBy String value No

CreatedDate Date & time No

IsPrivate true / false Yes

FullText String value Yes

WorkOrderNoteTypeId String value No

IsTextMessage true / false No

RecipientType String value No

WorkEfforts Numeric value No

IsNoteTruncated true / false No

MessageType String value No

Inventory / Asset DTO API Fields

NOTE: In a Create/Update asset call, the sequence where multiple fields are specified in the Request Body will decide the values in the final asset record created/updated.

Name Value

Can be set through Create/Update Asset Web API?(Yes/No)

Additional Information

ID Numeric No

 The Asset Number is automatically generated and can be viewed from the grid by adding Asset Number.  The maximum

number of

characters for this field is 40.

 If the ID and Name show the same values on

the Inventory Grid the GetByName API call may not return that asset if the Assets Detail > Hardware > Name is blank and the ID value is in Name column.

Identifier String

value Yes

This is the ID field on the Asset form.

Name String

value Yes

 If present, the Asset Name on the Inventory Home grid is obtained from the Hardware tab on the Asset form. This will only

(9)

Numara Software and BMC Software Confidential. 6 be updated with an Update call if the Asset Type is either a non-audited Computer or a non-Computer.  It is not allowed to change an Asset Name with an Update API call if the Asset Type is computer and already audited.

TypeName String

value Yes

Note - This cannot be done for an Update call.

UserName String

value Yes

If the user record has Location ad department specified, the department, department number, location values will be populated in the created/updated asset Location String value Yes Department String value Yes Department and

Department Number are linked fields so it is possible to run

Create/Update calls with only one of these

fields. The Location field may be changed

depending on the order of the inputs in an Update call.

DepartmentNumber Numeric Yes See the information given in the Department field.

UdfText1 String value Yes UdfText2 String value Yes UdfText3 String value Yes UdfText4 String value Yes UdfText5 String value Yes UdfText6 String value Yes ModemNumber String value Yes

(10)

Numara Software and BMC Software Confidential. 7 ModemExtension String value Yes Network String value Yes Description String value Yes CompanyAssetUniqueId String value No

CompanyAssetUniqueIdScanDate Date &

Time No

IsComputer true \ false No

IsRetired true \ false No

State Numeric No

A return value of 0 means the Asset is Active, but a return value of 1 means to Asset is Retired.

Web Services API Error Codes

Error Code Error String Scenario when this error is returned Web.Lifecycle.005 Login failed for user '<UserName>' If the login name and/or password

provided for generating the token is invalid.

Web.Lifecycle.003 You are not authorized to consume this API without a valid Track-It! Web Services API token. Please contact your administrator for further details.

When Web API calls are made without a valid TrackIAPIKey

Web.Lifecycle.004 Your session is no longer valid. Please obtain a new Track-It! Web Services API token again by sending a login request.

When the TrackItAPIKey is no longer valid. The token has to be regenerated in this case.

Web.Lifecycle.006 Origin or Method is not allowed. When a CORS call is invoked and the Origin from where the call is generated is not specified in the list of allowed origins for CORS in web.config. Or, the requested Method (e.g. GET/POST) is not in the allowed method list in web.config.

Help Desk / Work Orders

Business.HelpDesk.028 WorkOrder could not be

locked. Locked by <USERNAME>.

When trying to update a work order through the

AddNote/Update/ChangeStatus/Close API calls, if the work order is locked

Business.HelpDesk.046 Work Order <WorkOrderId> could not be found.

When trying to update a work order through the

AddNote/Update/ChangeStatus/Close API calls, if the wrong work order ID is

provided

Web.HelpDesk.008 Error changing Work Order status. When there is an error changing the status through the ChangeStatus API,

(11)

Numara Software and BMC Software Confidential. 8 when the status name provided in the request body is invalid

Web.HelpDesk.062 Work Order could not be created. Please provide a value for Summary.

When trying to create a Work Order with no value provided for “Summary” Web.HelpDesk.064 User lacks permission to create Work

Order

When the user trying to create a Work Order through the API does not have rights to create a Work Order

Web.HelpDesk.065 User lacks permission to modify Work Order

When the user trying to update a Work Order through the

Close/ChangeStatus/Update/AddNote APIs does not have rights to modify a Work Order

Web.HelpDesk.066 User lacks permission to view the Work Order

When the user trying to retrieve a Work Order through Get API does not have rights to view a Work Order

Web.HelpDesk.067 Value provided for field <FieldName> is in incorrect format. Work Order could not be created or updated

When a call is made to the

Update/Create/AddNote APIs, this error will be retuned if the data for a field is not in the correct format. For example, if an alphanumeric string value if provided for a integer field like ”ParentIncidentId” Web.HelpDesk.068 The operation failed. It might be due

to any one of the following reasons. Please check the request and try again.

1. Field name(s) provided for the current operation is not valid 2. Content-type specified is not 'text/JSON' or 'application/JSON' 3. Request body is either not present or is invalid

When either no data is provided or the data is wrongly formatted in the

Create/AddNote/Update/ChangeStatus Web API calls

Web.HelpDesk.069 Note could not be added to the Work Order. Please provide a value for FullText

When trying to add a note to a work Order, if no data is provided for the “FullText” field. FullText is mandatory when adding a note through web service API

Inventory/Assets

Web.Inventory.058 Insufficient permission to create an Asset.

When the user trying to update an Asset through Update API does not have rights to update an Asset

Web.Inventory.060 Insufficient permission to view an Asset.

When the user trying to view an Asset through Get API does not have rights to view an Asset

Web.Inventory.061 The operation failed because the Asset ID was not provided.

When the user trying to view an Asset through Get API does not provide any Asset ID in the request

Web.Inventory.062 The operation failed because the Asset ID provided matches multiple records.

When the user trying to update Asset through Update API by providing Asset ID and that Asset ID has multiple matching records in the system

(12)

Numara Software and BMC Software Confidential. 9 <AssetID> provided. found for different API calls (e.g. Get,

Update, Audit etc.) by supplying an Asset ID

Web.Inventory.064 This action cannot be performed because the Asset is retired.

When the user trying to update an Asset by Asset ID through Update API but the Asset is retired in the system

Web.Inventory.065 Asset could not be locked. Locked by <USERNAME>.

When the user trying to update an Asset by Asset ID through Update API but the Asset is locked by some user in the system

Web.Inventory.066 The operation failed. This might be due to any one of the following reasons. Please check the request and try again.

1. The field name(s) provided for the current operation is not valid.

2. The content type specified is not ""text/JSON"" or

""application/JSON"".

3. The request body is either not present or is invalid.

When either no data is provided or the data is wrongly formatted in the Audit/GetByFilters Web API calls

Web.Inventory.067 No matching records found for provided filters.

When there are no matching records found for GetByFilters API call Web.Inventory.068 Following non-Computer type Assets:

[ <Asset IDs> ] are not queued for Audit.

When the user trying to invoke audit for non-computer type assets

Web.Inventory.069 Asset could not be created. Provide a value for the Type and ID.

When the user trying to create an asset without supplying mandatory field values in Create Web API call

Web.Inventory.070 Value provided for field <FIELDNAME> is incorrectly formatted. The Asset could not be created or updated.

When the user trying to create/update an asset with improperly formatted field data through Create/Update Web API call Web.Inventory.071 Asset could not be created. The

value provided for AssetType: <AssetType> is not matching any Asset Type or matches multiple Asset Types." +

"To resolve this, you can provide the Asset Type in the following format: Parent_Type > Sub_Type > Sub_Type

When the user trying to create an asset with improperly formatted Asset Type through Create Web API call

Web.Inventory.072 The number of assets for auditing exceeded the limit of 500 per API call.

When the user trying to audit more than 500 Asset IDs in a single Audit Web API call

CORS (Cross Origin Resource Sharing) Support for Web APIs Overview

CORS (Cross Origin Resource Sharing) support is added for Track-It! Web API calls if any browser based application (which is not hosted on the same server as Track-It! web server) is trying to invoke Track-It! Web API from within XMLHttpRequest/AJAX request.

The following keys are added in Web.config for supporting CORS in Track-It!: 1. AllowOriginsForCORS

(13)

Numara Software and BMC Software Confidential. 10 Comma separated string to represent allowed origins for allowing CORS (examples

http://myapplication.com or http://mysite.com) 2. AllowMethodsForCORS

Comma separated string to represent methods allowed for CORS (examples GET or POST) If you want to test CORS Support, see this Knowledge Base

article: http://support.numarasoftware.com/support/articles.asp?ID=7420&mode=detail

APIs for Help Desk: Work Orders

Get Work Order via Web API

API: workorder/get • Type of call: GET

• Request Header: TrackItAPIKey: apiKey received through the Login API call. • Request body: <none>

• Request Parameters:

o WO#: Specify Work Order ID

• Request returns value: Work Order object in JSON format. For details refer to

Work_Order_DTO_fields_that_are_returned_by_the_Get_Work_Order_API. • URL: http(s)://<machine_name>/TrackitWebAPI/api/workorder/Get/<wo#>

Important: If the WO# is passed as value ‘0’, then the API will return an empty JSON object representing the entire WO object and all available fields. This JSON object can then be used for consecutive call as appropriate.

Example

http(s)://<machine_name>/TrackitWebAPI/api/workorder/Get/341

This will return the work order object with the list of fields and their corresponding values for work order 341. Request-header: TrackItAPIKey "ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYafl cIjj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up" Request-return: {"success":"true","data":{"AssignedTechnician":"Larry

Daniels","Id":"3411",","IsClosed":"False","Priority":"3-Medium","StatusName":"Open”,"Summary":"Microsoft Office Outlook Test Message",….}}

Update a Work Order via Web API

Note: The Hours and Charge fields will not get updated through an Update call in Web Service API if the work order timer is enabled.

API: workorder/Update • Type of call: POST • Request Header:

o TrackItAPIKey: apiKey received through the Login API call. o Content-Type: text/json

• Request body: Name value pairs of fields and field value. • Request Parameters:

o WO#: Specify Work Order ID

• Request returns value: Work Order object in JSON format. For details refer to Work Order DTO fields that can be set through the Create/Update API.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/workorder/Update/<wo#> Example

(14)

Numara Software and BMC Software Confidential. 11 Request-header: TrackItAPIKey ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body:

{ "StatusName":"Open","Summary":"Work Order created by Web API ","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":19000, …}

Request-return:

{"success":"true","data":{"message":"Work Order 4850 updated successfully","data":{“ID”:”4850”, "Status":"Open","Summary":"Issues With Exchange Server","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":350, …}}}

Create a Work Order via Web API

Note: The Hours and Charge fields will not get updated through an Update call in Web Service API if the work order timer is enabled.

API: workorder/Create • Type of call: POST • Request Header:

o TrackItAPIKey: apiKey received through the Login API call. o Content-Type: text/json

• Request body: Name value pairs of fields and respective values. • Request Parameters: <none>

• Request returns value: Work Oder object in JSON format. For details refer to Work Order DTO fields that can be set through the Create/Update API.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/workorder/Create

Important: A value for the Summary field is mandatory when trying to create a Work Order through the Web Service API.

Example http(s)://<machine_name>/TrackitWebAPI/api/workorder/Create Request-header: TrackItAPIKey : ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body:

{ "StatusName":"Open","Summary":"Work Order created by Web API ","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":19000, …}

Request-return:

{"success":"true","data":{"message":"Successfully created new Work Order with Id 19888","","data":{“ID”:”19888”, "Status":"Open","Summary":"Issues With Exchange Server","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":19000, …}}}

Change the Status of a Work Order via Web API

API: workorder/ChangeStatus • Type of call: POST • Request Header:

o TrackItAPIKey: apiKey received through the Login API call o Content-Type: text/json

• Request body: Name of the status in double quotes • Request Parameters:

(15)

Numara Software and BMC Software Confidential. 12 • Request returns value: Work Order object in JSON format. For details refer to Work Order DTO

fields that can be set through the Create/Update API.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/workorder/ChangeStatus/<wo#> Example http(s)://<machine_name>/TrackitWebAPI/api/workorder/ChangeStatus/345 Request-header: TrackItAPIKey : ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body: "Escalated" Request-return:

{"success":"true","data":{"message":"Work Order 345 updated successfully","data":{“ID”:”345”, "Status":"Escalated","Summary":"Issues With Exchange Server","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":350, …}}}

Close a Work Order (Quick Close) via Web API

API: workorder/Close • Type of call: POST • Request Header:

• Request body: resolution note text (optional) • Request Parameters:

• Request returns value: Work Order object in JSON format. For details refer to Work Order DTO fields that can be set through the Create/Update API.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/workorder/Close/<wo#> Example http(s)://<machine_name>/TrackitWebAPI/api/workorder/Close/65988 Request-header: TrackItAPIKey : ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body:

“Closing the Work Order – resolved by applying the latest patch” Request-return:

{"success":"true","data":{"message":"Work Order 65988 updated successfully","data":{“ID”:” 65988”, "Status":"Closed","Summary":"Issues With Exchange Server","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":350, …}}}

Add a Note to a Work Order via Web API

API: workorder/AddNote • Type of call: POST • Request Header:

(16)

Numara Software and BMC Software Confidential. 13 o Note: Only two fields are recognized: ‘IsPrivate’ and ‘Fulltext’. NoteType is defaulted to

‘Technician Note’ and Activity Code is set to blank. • Request Parameters:

• Request returns value: Work Order object in JSON format along with request status code. For details refer to Work Order DTO fields that can be set through the Create/Update API.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/workorder/AddNote/<wo#>

Important: A value for the “FullText” field is mandatory when trying to add a note to a Work Order through Web Service API.

Example http(s)://<machine_name>/TrackitWebAPI/api/workorder/AddNote/455 Request-header: TrackItAPIKey : ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body:

{“IsPrivate”: “true”, “FullText”: “This seems to be an issue with the installer, investigation is on.”} Request-return:

{"success":"true","data":{"message":"Work Order 455 updated successfully","data":{“ID”:” 455”, "Status":"Open","Summary":"Issues With Exchange Server","UdfDate2":"9/18/2013 6:20:03 PM", "AssignedTechnician":"Larry Daniels", "ParentIncidentId":350, …}}}

APIs for Inventory: Assets

Audit Assets via Web API

API: asset/audit

• Type of call: POST • Request Header:

• TrackItAPIKey: apiKey received through the Login API call • Content-Type: text/json

• Request body: Comma separated list of Asset IDs • Request Parameters:

• None

• Request returns value: A success message is returned if an Asset is queued for Auditing, and a failure message is returned in case of failure.

Note: If the requested list includes non-computer/retired asset types, then a message with list of Assets which are not queued for auditing is returned.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/audit Example http(s)://<machine_name>/TrackitWebAPI/api/asset/audit Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up • Content-Type: text/json Request-body: “101, 102, 103” Request-return:

(17)

Numara Software and BMC Software Confidential. 14 {"success":"true","data":{"message":"Assets successfully queued for Auditing."}}

Create an Asset via Web API

API: asset/create

• Request body: { "Identifier": “”, "Name": “”, "TypeName": “”, "UserName": “”, "Location": “”, "Department": “”, "DepartmentNumber": “”, "UdfText1": “”, "UdfText2": “”, "UdfText3": “”, "UdfText4": “”, "UdfText5": “”, "UdfText6": “”, "ModemNumber": “”, "ModemExtension": “”, "Network": “”, "Description": “”}

• Request Parameters: o None

• Request returns value: A success message is returned with all the fields of an Asset record including any fields that were ignored because of incorrect values. A failure message is returned in case of failure. • URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/create Example http(s)://<machine_name>/TrackitWebAPI/api/asset/create Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up • Content-Type: text/json

Request-body: {"Description": "Company Laptop 01","Username":"Ashlee Owens", "Department": "Information Technology ", "Location": "Tampa", “UdfText1”: “Category_1”}

Request-return:

{"success":"true","data":{"message":"Asset cpthook101 created successfully." ,"ignoredFields":"None", "reasonForIgnoringFieldValues":"Some fields were ignored due to any one of the following reasons:\r\n1. These fields contained invalid data OR \r\n2. The asset was audited and these fields cannot be updated on an audited asset.\r\n\r\nTo know the list of ignored fields, please refer to the \"ignoredFields\" in the response data.",

"data{"Id":"101","Identifier":"cpthook101","Name":"cpthook","TypeName":"Computer","Location":"Tampa"," Department":"Information

Technology","DepartmentNumber":"500","UdfText1":"Category_1","UdfText2":"","UdfText3":"","UdfText4": "","UdfText5":"","UdfText6":"","ModemNumber":"","ModemExtension":"","Network":"","Description":"CptHo ok was first discovered via an IP Scan. It was then transferred to Inventory. Next, the Product Number and Serial Number were scanned from the side of the unit. This was synchronized into the Barcode assets window. Lastly, Match to Inventory was selected and the cpthook from the IP scan was selected. After Apply was clicked, the barcode info was added to the cpthook record in Inventory. ","CompanyAssetUniqueId":"DS123S#ABA","CompanyAssetUniqueIdScanDate":"7/10/2006 10:38:09 AM","IsComputer":"True","State":"0","IsRetired":"False","UserName":"Gloria Wright"}}}

Get Assets by Asset number via Web API

API: asset/get/<assetNumber> • Type of call: GET • Request Header:

• Request body: • None

• Request Parameters: • None

(18)

Numara Software and BMC Software Confidential. 15 • Request returns value: A success message with asset information found by the asset number is

returned, and a failure message is returned in case of failure.

Note: If the Asset Number provided is zero, a dummy asset is returned to use as reference to get keys to be used in Create and Update Web API calls.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/get/<assetnumber> Example http(s)://<machine_name>/TrackitWebAPI/api/asset/get/0 Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body: Request-return: {"success":"true","data":{"Id":"0","Identifier":"","Name":"","TypeName":"","Location":"","Department":"","Dep artmentNumber":"","UdfText1":"","UdfText2":"","UdfText3":"","UdfText4":"","UdfText5":"","UdfText6":"","Mo demNumber":"","ModemExtension":"","Network":"","Description":"","CompanyAssetUniqueId":"","Compan yAssetUniqueIdScanDate":"","IsComputer":"False","State":"0","IsRetired":"False","UserName":""}}

Get Assets by Asset ID via Web API

API: asset/getbyID/<assetID> • Type of call: GET • Request Header:

• Request body: • None

• Request returns value: A success message with list of assets found by the asset id is returned, and a failure message is returned in case of failure.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/getbyID/<assetid> Example http(s)://<machine_name>/TrackitWebAPI/api/asset/getbyid/101 Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body: Request-return: {"success":"true","data":{"Assets":{"Asset1":{"Id":"101","Identifier":"101","Name":"cpthook","TypeName":"C omputer","Location":"Tampa","Department":"Information Technology","DepartmentNumber":"500","UdfText1":"","UdfText2":"","UdfText3":"","UdfText4":"","UdfText5 ":"","UdfText6":"","ModemNumber":"","ModemExtension":"","Network":"","Description":"CptHook was first discovered via an IP Scan. It was then transfered to Inventory. Next, the Product Number and Serial Number were scanned from the side of the unit. This was synchronized into the Barcode assets window. Lastly, Match to Inventory was selected and the cpthook from the IP scan was selected. After Apply was clicked, the barcode info was added to the cpthook record in Inventory.

","CompanyAssetUniqueId":"DS123S#ABA","CompanyAssetUniqueIdScanDate":"7/10/2006 10:38:09 AM","IsComputer":"True","State":"0","IsRetired":"False","UserName":"Gloria Wright"}}}}

Get Assets by Asset Name via Web API

(19)

Numara Software and BMC Software Confidential. 16 • Type of call: GET

• Request Header:

• Request body: • None

• Request returns value: A success message with list of assets found by the asset name is returned, and a failure message is returned in case of failure.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/getbyname/<assetname> Example http(s)://<machine_name>/TrackitWebAPI/api/asset/getbyname/101 Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json Request-body: Request-return: {"success":"true","data":{"Assets":{"Asset1":{"Id":"101","Identifier":"101","Name":"cpthook","TypeName":"C omputer","Location":"Tampa","Department":"Information Technology","DepartmentNumber":"500","UdfText1":"","UdfText2":"","UdfText3":"","UdfText4":"","UdfText5 ":"","UdfText6":"","ModemNumber":"","ModemExtension":"","Network":"","Description":"CptHook was first discovered via an IP Scan. It was then transfered to Inventory. Next, the Product Number and Serial Number were scanned from the side of the unit. This was synchronized into the Barcode assets window. Lastly, Match to Inventory was selected and the cpthook from the IP scan was selected. After Apply was clicked, the barcode info was added to the cpthook record in Inventory.

Get Assets by filters via Web API

API: asset/getbyFilters • Type of call: POST • Request Header:

• Request

body: {"ModemNumber":"","ModemExtension":"","Name":"","Identifier":"","Id":"","CompanyAsset UniqueId":"","UdfText1":"", "UdfText2":"", “UdfText3":"","UdfText4":"",

"UdfText5":"","UdfText6":""} • Request Parameters:

• None

• Request returns value: A success message with list of assets found by the provided filters is returned, and a failure message is returned in case of failure.

Note: In order to obtain more accurate results, you can provide more filters with appropriate values. • URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/getbyFilters Example http(s)://<machine_name>/TrackitWebAPI/api/asset/getbyFilters Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up

(20)

Numara Software and BMC Software Confidential. 17 Content-Type: text/json Request-body: {"Name":"cpthook"} Request-return: {"success":"true","data":{"Assets":{"Asset1":{"Id":"101","Identifier":"101","Name":"cpthook","TypeName":"C omputer","Location":"Tampa","Department":"Information Technology","DepartmentNumber":"500","UdfText1":"","UdfText2":"","UdfText3":"","UdfText4":"","UdfText5 ":"","UdfText6":"","ModemNumber":"","ModemExtension":"","Network":"","Description":"CptHook was first discovered via an IP Scan. It was then transfered to Inventory. Next, the Product Number and Serial Number were scanned from the side of the unit. This was synchronized into the Barcode assets window. Lastly, Match to Inventory was selected and the cpthook from the IP scan was selected. After Apply was clicked, the barcode info was added to the cpthook record in Inventory.

Update an Asset by Asset ID via Web API

API: asset/update

• Request Parameters: • Asset Identifier

• Request returns value: A success message is returned with all the fields of an Asset record including any fields that were ignored because of incorrect values. A failure message is returned in case of failure.

• URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/update?assetIdentifier=<assetID> Note: If an Asset ID matches multiple records, the update call will quit and return:

{"success":"false","data":{"Code":"Web.Inventory.062","Message":"The operation failed because the Asset ID provided matches multiple records."}}

Example http(s)://<machine_name>/TrackitWebAPI/api/asset/update?assetIdentifier=cpthook101 Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json

Request-return:

{"success":"true","data":{"message":"Asset cpthook101 updated successfully." ,"ignoredFields":"None", "reasonForIgnoringFieldValues":"Some fields were ignored due to any one of the following reasons:\r\n1. These fields contained invalid data OR \r\n2. The asset was audited and these fields cannot be updated on an audited asset.\r\n\r\nTo know the list of ignored fields, please refer to the \"ignoredFields\" in the response data.",

Technology","DepartmentNumber":"500","UdfText1":"Category_1","UdfText2":"","UdfText3":"","UdfText4": "","UdfText5":"","UdfText6":"","ModemNumber":"","ModemExtension":"","Network":"","Description":"CptHo ok was first discovered via an IP Scan. It was then transferred to Inventory. Next, the Product Number and Serial Number were scanned from the side of the unit. This was synchronized into the Barcode assets window. Lastly, Match to Inventory was selected and the cpthook from the IP scan was

(21)

Numara Software and BMC Software Confidential. 18 selected. After Apply was clicked, the barcode info was added to the cpthook record in Inventory.

","CompanyAssetUniqueId":"DS123S#ABA","CompanyAssetUniqueIdScanDate":"7/10/2006 10:38:09 AM","IsComputer":"True","State":"0","IsRetired":"False","UserName":"Gloria Wright"}}}

Update an Asset by Asset Number via Web API

API: asset/update

• Request Parameters: • Asset Number

• Request returns value: A success message is returned with all the fields of an Asset record including any fields that were ignored because of incorrect values. A failure message is returned in case of failure. • URL: http(s)://<machine_name>/TrackitWebAPI/api/asset/update/<assetNumber> Example http(s)://<machine_name>/TrackitWebAPI/api/asset/update/101 Request-header: TrackItAPIKey: ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflc Ijj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up Content-Type: text/json

Request-return:

{"success":"true","data":{"message":"Asset cpthook101 updated successfully." ,"ignoredFields":"None", "reasonForIgnoringFieldValues":"Some fields were ignored due to any one of the following reasons:\r\n1. These fields contained invalid data OR \r\n2. The asset was audited and these fields cannot be updated on an audited asset.\r\n\r\nTo know the list of ignored fields, please refer to the \"ignoredFields\" in the response data.",

Technology","DepartmentNumber":"500","UdfText1":"Category_1","UdfText2":"","UdfText3":"","UdfText4": "","UdfText5":"","UdfText6":"","ModemNumber":"","ModemExtension":"","Network":"","Description":"CptHo ok was first discovered via an IP Scan. It was then transferred to Inventory. Next, the Product Number and Serial Number were scanned from the side of the unit. This was synchronized into the Barcode assets window. Lastly, Match to Inventory was selected and the cpthook from the IP scan was selected. After Apply was clicked, the barcode info was added to the cpthook record in Inventory. ","CompanyAssetUniqueId":"DS123S#ABA","CompanyAssetUniqueIdScanDate":"7/10/2006 10:38:09 AM","IsComputer":"True","State":"0","IsRetired":"False","UserName":"Gloria Wright"}}}

BMC Track-It! Web. Web Services API Guide. Version 11.3

Web Services API Guide

Table of Contents

Web Services API

Web Services API Overview

Help Desk: Work Orders

Inventory: Assets

Authenticate and Generate Access Token

Web Services API Data Transfer Object Definitions

Return-token Definitions

Work Order DTO fields that can be set through the Create/Update API

Work Order DTO fields that are returned by the Get Work Order API

Note Object Definitions

Inventory / Asset DTO API Fields

Web Services API Error Codes

Help Desk / Work Orders

Inventory/Assets

CORS (Cross Origin Resource Sharing) Support for Web APIs Overview

APIs for Help Desk: Work Orders

Get Work Order via Web API

Update a Work Order via Web API

Create a Work Order via Web API

Change the Status of a Work Order via Web API

Close a Work Order (Quick Close) via Web API

Add a Note to a Work Order via Web API

APIs for Inventory: Assets

Audit Assets via Web API

Create an Asset via Web API

Get Assets by Asset number via Web API

Get Assets by Asset ID via Web API

Get Assets by Asset Name via Web API

Get Assets by filters via Web API

Update an Asset by Asset ID via Web API

Update an Asset by Asset Number via Web API