SysAid REST API Guide

 
Author
Message
SysAid Technical Writer
1001
 

SysAid REST API Guide

 

Table of Contents

 

    Introduction
    Login
    Users
    Filters
    Service Requests
    Assets
    Lists
    Add-ons
    CIs
    Resource Bundle (RB)
    Password Services
    Appendix A: Field Types
    Appendix B: Lists
    Contact us
 

 

 

 

Introduction

 

SysAid is a robust IT management system that was designed to meet all of your needs as an IT department. The SysAid REST API was designed to help you meet two specific needs:

  • Display, store, and process help desk data in a way that is best for your organization
  • Interface SysAid with third party applications

The REST API is supported by SysAid versions 15.4 and up.

 

Definitions

 

There are several definitions that you should be familiar with before you read the rest of this guide.

 

SysAid entity (object)
A SysAid entity is anything in SysAid that has both a list page and a form page. Examples are service records, assets, tasks, projects, and software products. Each SysAid entity is represented by a SysAid object. The API gives you full access to all entities in SysAid. For a full list and description of SysAid entities see Appendix B.
 

 

Endpoint

When you use the API, the endpoint should be appended to your account URL as in the following example:

 

https://www.johndoe.sysaid.com/api/v1/<api_url>

 

Common parameters

The following parameters are available in all or most of the API calls.

 

Offset

If you are retreiving a list of items, you can use the Offset parameter to set where on the list you should begin. For example, if you are retrieving a list of service records and there are 500 that match your criteria, but you are not interested in the first 100, you can set the Offset to 101 so the API returns service records 101 and up.

 

Limit

The maximum number of items to retrieve. For example, if your API call retrieves 1000 assets, you can set the limit to 300 so that only the first 300 assets (beginning from the defined offset, if specified) are retrieved.

 

View

A SysAid view which defines the available fields. Such views can be selected and set for lists in SysAid. You can create or customize views from the SysAid admin web interface.

 

Fields

Define a ist of comma seperated values representing the field names you wan to retrieve. If this parameter is set together with the View parameter, the API call returns both View fields and the fields specified in this parameter.

 

Info

Additional information fields.

 

JSON Samples

Throughout this guide sample JSON Input and Return values are displayed as in white box like the one below:

 

Sample JSON input - set sr status, assigned to, due date and add a note

{

  “info”: [{“key”:”due_date”, ”value”:1391756438000},

            {“key”:”status”, ”value”:2},

            {“key”:”notes”,”value”:[

            {“userName”:”sysaid”,”createDate”:1391756438000,”text”:”Note 123”}

             ]},

             {“responsibility”:66}]

}

 

Login

This Login call is for non-OAuth users.

 

Command Name Command Description More Details
Authenticate a user in SysAid server POST/login Checks both that the user is an administrator, and that he has permission to access the mobile app. More Details

 

Important: Upon a successful login, the API consumer needs to retrieve the JSESSIONID cookie from the Response Header and submit it in all consequent API Request Headers.

 

Users

 

Command Name Command Description More Details
Get Users List GET/users?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} Get list of users in SysAid More Details
Get User GET/users/{id}?view={view_name}&fields={field1,field2...} Get information on the specified user More Details
Get User's Photo GET /users/{id}/photo Downloads the specified user's photo More Details
Upload User's Photo POST/users/{id}/photo uploads the specified user's photo More Details
Get User Permissions GET/users/{id}/permission Get user permissions More Details
Get A User's Permission GET/users/{id}/permission/{permissionId} Check a specific user permission More Details
 

Filters

 

Command Name Command Description More Details
Get Filters List GET/filters?view={view_name}&fields={field1,field2..}&offset={offset}&limit={limit} Get list of available filters and their values. More Details
Get Filter GET/filters/{id}?view={view_name}&offset={offset}&limit={limit} Returns the information and available values for the specified filter More Details

Service Requests

 

Command Name Command Description More Details
Get Service Request List GET/sr?view={view_name}&fields={field1,field2..}&ids={id1,id2..}&type={type}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}...

Returns a list of available service requests (SR).

Number of SRs to return can be controlled by offset, limit & type parameters.

Returned SRs can be filtered by filters (See Filter Service).

Each Service Request, Includes the fields according to view & fields parameters. If none specified, all SR fields are returned.

More Details
Get Service Request GET/sr/{id}?view={view_name}&fields={field1,field2...} Returns the information for the specified service request. More Details
Update Service Request PUT/sr/{id} Update a service request More Details
Close Service Request PUT/sr/{id}/close Close a Service Request. Sets the service request status to the default close status, as defined in the Help Desk settings. More Details
Get Service Request Template GET/sr/template?view={view_name}&fields={field1,field2..}&type={sr_type}&template={template_id} Get a new service request template More Details
Create Service Request POST/sr?view={view_name}&type={sr_type}&template={template_id} Create a new service request and returns the newly created service request. More Details
Delete Service Request DELETE/sr?ids={id1,id2….} Delete one or more service requests More Details
Service Request Links
Add Service Request Link POST /sr/{id}/link Add a link to service request More Details
Delete Service Request Link DELETE /sr/{id}/link Delete a link from service request More Details
Service Request Attachments
Add Service Request Attachment POST /sr/{id}/attachment Add an attachment to service request More Details
Delete Service Request Attachment DELETE /sr/{id}/attachment Delete an attachment from service request More Details
Service Request Activities
Add Service Request Activity POST /sr/{id}/activity Add an activity to service request More Details
Delete Service Request Activity DELETE /sr/{id}/activity Delete an activity from service request More Details
Service Request Messages
Send Message From Service Request POST /sr/{id}/message?method={method} Send a message from a service request More Details
 

Assets

 

Command Name Command Description More Details
Get Assets List GET /asset?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} Get list of assets in SysAid More Details
Get Asset GET /asset/{id}?view={view_name}&fields={field1,field2...} Get information on the specified asset More Details
 

Lists

 

Command Name Command Description More Details
Get All Lists GET/list?entity={entity}&fields={field1,fields2..}&offset={offset}&limit={limit} Get all available lists and their values. More Details
Get List GET/list/{id}?entity={entity}&entityId={entity_id}&entityType={entityType}&fields={field1,fields2..}&offset={offset}&limit={limit}&key={keyField} Returns the values of the specified list. Values may be filtered according to the entity (sr, asset etc) for which you populate the list values. More Details
 

Add-ons

 

Command Name Command Description More Details
List Add-On Application GET /addons Get a list of all available add-ons. More Details
Get Add-On Parameters GET /addons/{addon name} Returns the full information about an add-on with all of its parameters. More Details
Update Add-On Parameters PUT /addon/{addon name} Update an add-on's parameters. More Details
Test Add-On Connection PUT /addon/{addon name}/testConnection Test an add-on's parameters. More Details
Refresh Add-On List GET /addons/refresh Immediately refresh the list of add-ons. More Details
 

CIs

 

Command Name Command Description More Details
Get CI List/Form GET/ci?view={view_name}&fields={field1,field2..}&ids={id1,id2..}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}supportBarcode={true/false}...

Returns a list of CIs that can be filtered by the available filters.

The Number of CIs to return can be controlled by the Offset and Limit parameters.
Returned CIs can be filtered.
Each CI Includes the fields according to the View and Fields parameters. If none are specified, all CI fields are returned.

More Details
Update CI PUT/ci/{id} Update a CI More Details
Get CI Types GET/ci/type?supportBarcode={true/false}

Returns the available CI types.

If the barcode flag is requested, returns only CI types with barcode support (if add-on is available).
More Details
Get CI View GET/ci/view/{ciTypeId}?view={view_name} Returns the fields contained in the specified view. More Details
Get CI Relation Types GET /ci/relationtypes Returns all the valid CI relation types defined in SysAid database and their ID numbers. More Details
Get CI Relation GET /ci/relation An API to retrieve all the destination CIs and their relation types, which are associated to a given Ci Id. More Details
Create CI Relations POST /ci/{ciId}/relation API for creating one or more relations for a given CI ID. More Details
Delete CI Relations DELETE /ci/{ciId}/relation

API for deleting one or more relations for a given Ci ID.

More Details
 

Resource Bundle (RB)

 

Command Name Command Description More Details
Get RB Translated Keys POST /rb Get array of translated keys according to the account location. More Details
Get RB Translated Keys With Given Location POST /rb/{locale} Get array of translated keys according to the given location. More Details
 

Password Services

 

Command Name Command Description More Details
Get LDAP Domains

GET /ps/domain

Get LDAP domains. More Details
Get Password Services Permission GET /ps/permission Get Password Services permissions. More Details
Get Security Question POST ps/{method}/question

Get Security Questions for given user.

The method @pathparam can be: unlock/reset.
More Details
Unlock Account POST ps/unlock/ Unlock user on verifying his answers. More Details
Reset Password POST ps/reset/ Reset user’s password on verifying his answers. More Details
Update Password POST ps/reset/update Update user’s password manual on verifying his token. More Details

Appendix A: Field Types

 

Field Type Description
text

A textual value

numeric A numeric value
boolean Boolean value - can be either 0/1, or true/false
date A date value. Returned as milliseconds in UTC/GMT (since January 1, 1970). The valueCaption is the formatted date representation, according to date display configuration in SysAid.
list A list of values. The full list of values can be retrieved using the /list/{id} api call.
nested The value is an item in a nested list. Currently used for category levels.
object The value is an object with sub values.
custom TBD...

 

 

Appendix B: Lists

 

The available lists are fetched by entity types.

For example, if you want to retreive all available lists in the Service Request form, you can send the following API call:

/list?entity=sr


The available lists are:

 

List Type Description
sr Service Request related lists
asset Asset related lists
user User related lists
ci CI related lists
company Company related lists
action_item Action item related lists
project Service Request Sub Tabs lists
task Task related lists
catalog Catalog related lists
software Software related lists
sr_activity Service request activity related lists
supplier Supplier related lists
task_activity Task activity related lists
user_groups User Group related lists

Contact us

 

SysAid welcomes your questions and suggestions. We can be reached via phone and email:

Toll Free phone center (U.S): 800-686-7047

Tel (U.S): +1 617-231-0124

Fax (U.S): +1 617 507 2559

Tel (Israel): +972 3 533 3675

Fax (Israel): +972 3 761 7205

Email: helpdesk@sysaid.com

SysAid community: http://www.sysaid.com/Sysforums/forums/home.page

You can also view our full support page at http://www.sysaid.com/contact_support.htm.

 

SysAider
2
 
Is this available for SysAid on-premises?

Are there any examples for querying the API with PowerShell?
SysAid Product Manager Community Manager
4979
 
ssouthern wrote:Is this available for SysAid on-premises?

Are there any examples for querying the API with PowerShell?

Hi,

This is indeed available on SysAid On-Premise, starting with version 15.4. Unfortunately I don't have any PowerShell examples to provide, but you can try searching for some on this forum, perhaps other users have conjured something up

Cheers,
Danny

This message was edited 2 times. Last update was at Dec. 01, 2015 04:18 AM

SysAider
6
 
How does one enable the REST API? We're using on premise and currently running v15.2.04 b1.
SysAid Product Manager Community Manager
4979
 
Hi GJAU,

Sorry for the confusion. REST API is only available starting with version 15.4 (Winter 16) and up. It should be available to Cloud customers soon, and to On-Premise customers when the new version is released in January.

You can also join our Winter 16 (v15.4) On-Premise Beta and test it out early, by becoming a SysAid Pathfinder.

Cheers,
Danny

This message was edited 1 time. Last update was at Dec. 01, 2015 07:05 AM

SysAider
6
 
Given it's not documented here am I correct in assuming that the tasks aren't exposed to the REST API at this point?
SysAider
28
 
Could you please give more information about OAuth login?
Other application (es Jira) need some parameters (Consumer Key and Private Key) to intgrate with OAuth standard.
tnx