Advanced Search
  2. Forum Index
  3. Online Help
  4. SysAid API Guide

SysAid API Guide

Post Reply
 
Author
Message
David Cohen
SysAid Technical Writer
580
 
SysAid API Guide
Dec. 20, 2011 01:50 PM

SysAid API Guide

 

Important

The SysAid API is intended for use by IT professionals who are familiar with Java and JavaScript and who have access to an IDE (for working with the wsdl file). If you are not a trained programmer, you are advised not to make changes using the API, as you could prevent various elements of SysAid from functioning properly.

 

The SOAP API is disabled by default and there are plans to remove support for it in the near future. To enable the API for your account, please contact your account manager. For information about our REST API, see the SysAid REST API guide.

 

 

Table of Contents

 

    Introduction
    Advanced display options for customfields
    Performing server-side and client-side validation on custom fields
    Creating entity triggers
    Using the API wsdl file
    API resources
    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 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

 

 

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.
API object
When you use the SysAid API, you must convert a SysAid object to its corresponding API object. An example of an API object would be ApiServiceRequest. Each API object includes a list of methods. An example of a method for the ApiServiceRequest object would be setPriority.

A full list of API objects and their methods can be found in the Resources section, below.
Custom field
Some of the API options are available only for custom fields you've added to your SysAid. A custom field is any field you've added under Settings > Customize > Entities. The SysAid entities that support custom fields are: Asset, Service Record, Task, Project, CI, User, Company, and Action Item. You can read more about custom fields here.
DB Field Name
All SysAid fields have a unique name in the database. For custom fields that you've added to your SysAid, you can view the DB Field Name under Settings > Customize > Fields Customization by viewing an individual custom field. Please make sure to select a DB Field Name that describes the field you're adding, as the DB Field Name can be used later in the creation of custom reports.

 DB Field Name

 

Display, store, and process data

 

SysAid provides you with several capabilities that allow you to control how your data is displayed, stored, and processed:

 

Display in List and Display in Form
Allows you to change how any custom field appears in the appropriate list or form. An example of a change to the form would be marking a field as a password field, so that any data entered would be shown to the user as ****. Can be used on any field that you add to SysAid under Settings > Customize >Fields Customization.
Server-Side Validation and Client-Side Validation
Server-Side validation allows you to verify and update custom fields in SysAid after those fields are saved. Client-Side validation allows you to ensure that data entered into a field on one of your forms is in the correct format (e.g. Employee ID field contains exactly 5 digits). Can be used on any field that you add to SysAid under Settings > Customize > Fields Customization.
On Load, Before Save, and After Save triggers
Triggers allow you to take specific, conditional actions every time a form is loaded or saved. An example of a trigger for the Service Record entity could check to see if the SR due date has passed and create a popup notifying the administrator if this is the case.

 

 

Interface SysAid with third party applications

 

SysAid allows you to connect your various in-house and third party applications to SysAid using the web services described in the SysAid wsdl file. By interfacing your applications with SysAid, you can create, modify, and delete entities in SysAid, as well as sending emails.

 

 

Using the SysAid API

 

Each of the sections below explains how to use a specific component of the SysAid API. Each section includes an overview of the API feature, instructions for using it, and an example.

 

The API resources section includes a list of all API services and objects and a description of each.

 

 

 

Advanced display options for custom fields

 

SysAid allows you to control how your custom fields are displayed in the following places:

  • Forms
  • Lists
  • The SysAid Mobile App (SR fields only)

 

You may access advanced display options from Settings > Customize > Fields Customization > (Select an entity type) > (Select a custom field) > Advanced (tab).

 

 Editing the display options for custom fields

 

Display in List

 

Display in List allows you to control how SysAid displays the value of your custom field in the appropriate SysAid list (e.g. SR list). For example, you might want a field value to be displayed in Red if the field contains a certain value. This would make that value stand out when you're looking at the list. The example below shows you how you can do this.

 

Example

The following example continues the Severity example shown for After Save triggers, below. In this example, the Display in List field has been used to give the severity a different font color depending upon the severity.

 

Changing the font color of the Severity field -- Display in List

/*We first need to get the severity value. You must use the DB Field Name for the severity field.*/

String severity = rs.getString("sr_cust_severity") == null ? "" : rs.getString("sr_cust_severity");

 

/*Here we use an if/else to display a different color for each severity. SysAid defaults to black if a font color is not detected.*/

String fontColor = "";


if (severity.equals("Highest")){
fontColor = "#FF1121";
} else if (severity.equals("High")) {
fontColor = "#FF5E07";
} else if (severity.equals("Medium")) {
fontColor = "#17A50D";
} else if (severity.equals("Low")) {
fontColor = "#3898FF";
} else if (severity.equals("Lowest")) {
fontColor = "#A530FF";
}

 

/*Finally, we display the severity value in the list using the chosen color.*/

return ("<span style = \"width=300px; color:" + fontColor + "; font-weight:900;\" class = \"Form_Ctrl_Label\">"+severity+"</span>");

 

 

Display in Form

 

Display in Form allows you to control how SysAid displays the value of your custom field in the appropriate SysAid form (e.g. SR form). For example, you might want a field value to be displayed in Red if the field contains a certain value. This would make that value stand out when you're looking at the form. The example below shows you how you can do this.

 

Example

The following example continues the Severity example shown immediately above. Whereas above we changed the color of the severity field in the SR list, here we're changing the color in the SR form.

 

Changing the font color of the Severity field -- Display in Form

/*Before you start editing this field, look at the default contents. You should see a line that looks like this:

String value = com.ilient.server.Helper.escapeTextArea((String)obj.getAddonFieldValue("CustomColumn5sr"), loginBean.getCharset());

Be sure to save the custom column number that appears (in this case "CustomColumn5sr"). You'll need it later.*/

 

/*We start by getting the SR object*/
com.ilient.server.ServiceRequest sr = (com.ilient.server.ServiceRequest)obj;

 

/*Next we get the severity value from the SR. Be sure to replace "CustomColumn5sr" with the correct custom column number that you recorded earlier.*/
String severity = sr.getAddonFieldValue("CustomColumn5sr") == null ? "" : sr.getAddonFieldValue("CustomColumn5sr");

 

/*Here we use an if/else to display a different color for each severity. SysAid defaults to black if a font color is not detected.*/
String fontColor = "";


if (severity.equals("Highest")){
fontColor = "#FF1121";
} else if (severity.equals("High")) {
fontColor = "#FF5E07";
} else if (severity.equals("Medium")) {
fontColor = "#17A50D";
} else if (severity.equals("Low")) {
fontColor = "#3898FF";
} else if (severity.equals("Lowest")) {
fontColor = "#A530FF";
}

 

/*Finally, we display the severity value in the form using the chosen color. Note that we use <span> instead of <input> so that this field is read only.*/
out.append("<span style = \"width=300px; color:" + fontColor + "; font-weight:900;\" class = \"Form_Ctrl_Label\">"+severity+"</span>");

 

 

Display in Mobile Form

 

This controls how the field is displayed in the Mobile App on your mobile phone. Currently, only custom SR entities are supported in the Mobile App.

 

This field may be edited the same as Display in Form, with one addition:

To ensure that the field displays properly on a mobile device, please make sure to limit the output width/height of the field.

 

 

 

Performing server-side and client-side validation on custom fields

 

SysAid allows you to validate data entered into your custom fields.

 

You may access validation options from Settings > Customize > Entities > (Select an entity type) > (Select a custom field) > Advanced (tab).

 

 Adding validation for custom fields

 

Server-Side Validation

 

This field directs SysAid to relate to specific data in the form in order to perform actions on this data. For example you may want SysAid to automatically change the due date for a service record if the your custom field contains a certain value.

 

Example coming soon!

 

Client-Side Validation

 

This allows you to customize validation conditions for the field and edit the corresponding validation failure/success notifications texts. For example, you might be using an integer field to hold a value that's always 6 digits long. If somebody saved a value that was less than or greater than 6 digits long, you could return an error message.

 

Example coming soon!

 

 

 

Creating entity triggers

 

Triggers are related to the form for a particular entity (e.g. SR form, asset form, etc.). Therefore, they are connected to all fields for an entity, not just custom fields.

 

There are three types of entity triggers:

  • On Load
  • Before Save
  • After Save

 

You may access entity triggers from Settings > Customize > Fields Customization > (Select an entity type) > Triggers (tab).

 

 There are three types of custom triggers for each entity

 

Following is an explanation of what each trigger is used for and an example that shows you how to use that trigger.

 

On Load

 

These triggers will run the moment you load the form, and should be written in Java/JavaScript. As an example, a trigger for the service record entity could check to see if the SR due date has passed and create a popup notifying the administrator if this is the case.

 

Example coming soon!

 

Before Save

 

These triggers will run after you hit OK/Apply, but before the data is saved to the database. No data is sent from the client (web browser) to the server until after these triggers are run. Use JavaScript for these triggers. Before Save triggers are useful for data validation, but can also be used to modify data that's been entered in the form before it's saved to the database. An example trigger of this type could look at integer fields and remove any commas that a user has entered into the number so that it will be saved correctly in the database (i.e. 2,000 would become 2000).

 

Example coming soon!

 

After Save

 

After Save triggers should be written in Java, and perform an action after the form data has already been saved in the database. After Save triggers are typically use for one of three things:

  • To manipulate the data of the object that's just been saved (calculate the value for a field based upon other fields on the form)
  • To affect other entities in SysAid
  • To interact with a 3rd party application. For example, you could tell one of your other systems that a new SR has been opened and then forward the SR ID

 

Example

Here is an example of an After Save trigger that takes the priority and urgency of a service record and then calculates the value of a new field, Severity. In this example, Severity is a string.

 

Calculating Severity -- After Save Trigger

/*Importing all of the SysAid API objects.*/

import com.ilient.api.sysaidObjects.*;

 

/*In an after save trigger, the entity you've just saved (e.g. SR, CI, etc.) is referenced by obj. The first thing you need to do is to cast obj to the appropriate object type.

If you are working with an entity type other than SR, consult the resources section below for the name and location of the appropriate object type.*/

com.ilient.server.ServiceRequest sr = (com.ilient.server.ServiceRequest)obj;

 

/*Next, you must declare the service object. This object allows you to perform all required actions in the future such as editing or deleting the object.
This statement is always the same.*/

com.ilient.api.SysaidApiService service = new com.ilient.api.SysaidApiService();

 

/*You now need to build the API object from the service record you just saved. This allows you to invoke methods on that individual SR.*/

ApiServiceRequest srApi = service.getApiSysAidObjectFromSysAidObject(sr);

 

/*Note: If you have just saved the form for a different entity type, such as the task form, you must use the appropriate API object name. For tasks, this is ApiTask. Please see the list of API Objects in the resources section below for a list of object names.*/

 

/*You're now ready to start performing actions on the service record. The following code gets the SR Priority and SR Urgency and then calculates severity.*/

int priority = srApi.getPriority();
int urgency = srApi.getUrgency();
int severity = priority*urgency;

/*A full list of available methods for each object can be found by clicking the More info links in the objects table in the Resources section, below.*/

 

/*The following line adds the severity into the SysAid log for ease of debugging. The log is found at: ..\SysAid Server\root\WEB-INF\logs\sysaid.log*/

com.ilient.server.IlientConf.logger.info("Calculated severity is: " + severity);

 

try {

 

/*The following line sets a default value for Severity.*/

String severityStr = "Medium";

 

/*The If statement translates the integer severity value into a string value.*/

if (severity == 1)
severityStr = "Highest";
else if (severity <=4)
severityStr = "High";
else if (severity <=9)
severityStr = "Medium";
else if (severity <=16)
severityStr = "Low";
else if (severity <=25)
severityStr = "Lowest";

 

/*Now that you have a value for severity, you must save this value to the database. Create a custom text field for the SR entity under Customize > Entities to hold the severity. Enter severity as the DB Field Name. After saving the new custom field, you'll see that the full DB Field Name is sr_cust_severity.*/

 

/*In order to reach the severity field, you must get a map of all custom fields for the current object type (SR).*/

java.util.HashMap customFields = srApi.getCustomFields();


/*Avoid a null pointer exception in your code.*/

if (customFields == null) {
customFields = new java.util.HashMap();
}

 

/*Now that you have a map of all SR custom fields, you can save the SR severity into the appropriate field. Make sure to use the DB Field Name for the severity field.*/

customFields.put("sr_cust_severity" , severityStr);

 

/*Set the custom columns inside the API object.*/
srApi.setCustomFields(customFields);

/*Finally, save the service record again.*/

service.save(loginBean,srApi);

/*The next time you open this SR, you will see the severity that you've calculated.*/


}
catch (Exception e){
com.ilient.server.IlientConf.logger.error("General Error for Severity After Save Trigger",e);
}

 

 

 

Using the API wsdl file

 

The SysAid wsdl file provides a set of web services that allows you to connect third party programs and code to your SysAid. This can be used to insert data into your SysAid or to pull information for use in other applications.

 

Sample uses for the SysAid API include:

  • Interfacing SysAid with another database, such as the supplier DB used in your purchasing department
  • The creation of service records by 3rd party software
  • Updating non Active Directory/LDAP users from a separate CRM software

 

You may download the wsdl file from Settings > Integration > SysAid API.

 

Example using the wsdl file

 

The following example provides steps for using the SysAid API to change the title of a service record.

 

  1. To get started using the SysAid API, open your development environment of choice, create a new project, and generate objects from our WSDL file (the same as with any other web service you've handled before).
  2. Create a new class.
  3. Create our service object that allows you to communicate with the SysAid server. In our Java environment it looks like this:
    SysaidApiService service = new SysaidApiServiceService().getSysaidApiServicePort();
  4. Log in to the SysAid Server (for authentication reasons) and receive a session ID that will serve you in future API operations (replace the details with you own credentials):
    long sessionId = service.login("ACCOUNT_ID","USER_NAME","PASSWORD");
    Note that the SysAid user you log in with needs SysAid Administrator privileges.
  5. Now load an existing Service Record, such as SR# 5. In the code below, service.loadByID receives the session ID from step 4, the new object that will be filled with the SR's details, and the service record number:
    ApiServiceRequest sr = (ApiServiceRequest)service.loadById(sessionId,new ApiServiceRequest(),5);
  6. Change the SR's title:
    sr.setTitle("My new title");
  7. Now save the service record using the service object created in step 3:
    service.save(sessionId,sr);
  8. Once finished, log out in order to free resources:
    service.logout(sessionId);

 

Other operations are available as detailed in the Resources section, below. This includes creating new entities, deleting entities, etc....

 

Please contact support if you have any additional questions about using the wsdl file.

 

Updating the API

 

If you've added custom fields to your SysAid under Settings > Customize > Fields Customization, you must update the API before you can access these fields. Please go here for instructions for updating the API.

 

 

 

API resources

 

SysAid objects

 

Following is a table of the different SysAid objects and their locations. Refer to this table when casting to the appropriate SysAid object.

 

SysAid Object Object Location
Service Record

com.ilient.server.ServiceRequest
Asset

com.ilient.server.Computer
Project

com.ilient.task.Project
Task

com.ilient.task.Task
CI

com.ilient.server.CI
User (Administrator + End User)

com.ilient.server.SysAidUser
Company

com.ilient.server.Company

 

 

API objects and their methods

 

The SysAid API includes the following API objects, which allow you to interact with the corresponding SysAid entities. All API objects are located at com.ilient.api.sysaidObjects.*

 

Click More info for a list of all methods available for a particular object:

 

API Object SysAid Entity More info
ApiCatalogItem Catalog Items
ApiCI CIs
ApiCIRelationType CI Relation Types
ApiCIType CI Types
ApiCompany Companies
ApiComputer Assets
ApiComputerItem Subset of Asset-- gives access to individual services, processes, software items, and network adapters on a computer
ApiComputerItemList Subset of Asset-- contains a list of services, processes, software items, and network adapters for a computer
ApiProject Projects
ApiServiceRequest Service Records
ApiServiceRequestActivity Service Record Activities
ApiSoftware Software Products
ApiSupplier Suppliers
ApiSysAidUser Administrators and End Users
ApiTask Tasks

 

 

The API service

 

The SysAid API service provides you with a full range of services that can be run on objects. The SysAid API Service is located at com.ilient.api.SysaidApiService

 

Click here for the full list of available services.

 

 

 

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.

 

This message was edited 1 time. Last update was at Sep. 12, 2012 09:44 AM
BobM
SysAider
16
 
Re:SysAid API Guide
Feb. 25, 2013 07:46 PM
First sentence "The SysAid API was intended for use by IT professionals..."
Should read "The SysAid API is intended for use by IT professionals..."
ChadR
SysAider
2
 
Re: SysAid API Guide
May. 18, 2015 04:00 PM
Hi - Is there an updated version of this guide that you can post for the public, please?

This is very outdated, a lot of the methods don't exist in the latest SysAid version. For example, you don't get or set the Notes field via the getNotes or setNotes method which is in this guide, rather you simply use Notes and set that to what you want added to the Notes field.

Thanks,

Chad

This message was edited 1 time. Last update was at May. 18, 2015 04:01 PM
Oded M
SysAid VP Product
1175
 
Re: SysAid API Guide
May. 31, 2015 03:52 PM
Hi,
We are finalizing a new RESTful API that will soon be available.
You will find the RESTful API much easier to work with and it will offer extended capabilities

FASSET
SysAider
9
 
Re: SysAid API Guide
Jul. 30, 2015 03:48 AM
I have sussed how to create new service records and how to pull individual service records from the SysAid API, but is it possible to pull an Array of Service Records based upon criteria such as username or location? I'm looking to implement our cloud based SysAid into our existing intranet portal as a lot of our users are not going to use the End User Portal as its 'just another system' to them.
Danny Tashiev
SysAid Product Manager Community Manager
5276
 
Re: SysAid API Guide
Aug. 03, 2015 06:49 AM
FASSET wrote:I have sussed how to create new service records and how to pull individual service records from the SysAid API, but is it possible to pull an Array of Service Records based upon criteria such as username or location? I'm looking to implement our cloud based SysAid into our existing intranet portal as a lot of our users are not going to use the End User Portal as its 'just another system' to them.

Hi,

This is the response I got after consulting with the R&D team:

You should do something like this:
List<String> srIds=binding.executeSelectQuery(sessionId, new ApiServiceRequest(), "<sql where part>'");
and replace the <sql where part> with the any valid sql where part for example:
"request_user='<sysaid_user_id>" - find every SR where the request user id=<sysaid_user_id>
"responsibility='sysaid' and status=1" - find all SR assigned to user "sysaid" with status=1 (status 1 is NEW)

The result will be a list of SR ids.

Cheers,
Danny
FASSET
SysAider
9
 
Re: SysAid API Guide
Aug. 06, 2015 04:00 AM
Brilliant, i will give that a go.

Many Thanks
josh.yim
SysAider
29
 
Re: SysAid API Guide
Apr. 06, 2016 07:48 AM
Hello.
I would like to see com.ilient.combobox API. Where can I find it?
And is there a Text Area API?
And is there an example on how to get the query result and send it to the text area in the 'Display in Form'?

Best Regards,
Joshua
Danny Tashiev
SysAid Product Manager Community Manager
5276
 
Re: SysAid API Guide
Apr. 18, 2016 09:34 AM
Hi Joshua,

From my understanding, the combobox/text area is not part of the SysAidObjects that are supported. Perhaps our Professional Services team may be able to help you with what you're trying to achieve by a different method or a special project. I suggest contacting your account manager for more information.

Cheers,
Danny
josh.yim
SysAider
29
 
Re: SysAid API Guide
May. 16, 2016 09:39 PM
Hello.

When I create a web client in Eclipse using "http://novacentrix.sysaidit.com/services/SysaidApiService?wsdl",
I got below error message.

"The input type com.ilient.api.ApiSysaidObject is a non-instantiable type and will be omitted from the sample JSP. Continue with sample JSP generation?"

I ignored it and proceeded.
Then, after create the client, when I invoke the method getSysaidApiService() (other methods are the same), I got below error.

org.apache.catalina.core.StandardWrapperValve invoke
: Servlet.service() for servlet [jsp] in context with path [/webtest] threw exception [An exception occurred processing JSP page /sampleSysaidApiServiceProxy/Result.jsp at line 10

I hope somebody help me with this.

Best Regards,
Joshua

This message was edited 1 time. Last update was at May. 16, 2016 09:40 PM
Danny Tashiev
SysAid Product Manager Community Manager
5276
 
Re: SysAid API Guide
May. 19, 2016 06:14 AM
Hi Josh,

I'm checking this with the team and will get back to you once I have an answer

Cheers,
Danny
josh.yim
SysAider
29
 
Re: SysAid API Guide
May. 25, 2016 06:51 AM
Hello.
Can I see the 'display in form' code for the ready-made fields (other than custom fields) like Request time, Category, History etc.?
Best Regards,
Joshua

This message was edited 1 time. Last update was at May. 25, 2016 06:51 AM
Danny Tashiev
SysAid Product Manager Community Manager
5276
 
Re: SysAid API Guide
May. 25, 2016 08:36 AM
Hi Joshua,

If you're referring to Service Requests, this information is present in this very guide, under API resources -> API objects and their methods -> ApiServiceRequest.

Let me know if this is what you're looking for.

Cheers,
Danny
josh.yim
SysAider
29
 
Re: SysAid API Guide
May. 25, 2016 07:31 PM
Hi Danny,
Thank you for your quick reply.
But what I wanted to see was display option code, not API.
Something like above "Advanced display options for custom fields" on the SysAid ready-made fields.
i.e. "Advanced display options for SysAid made fields" if there is.
josh.yim
SysAider
29
 
Triggers text fields are not editable
May. 26, 2016 02:02 AM
Hello.
In Settings > Customize > Fields Customization > (Select an entity type) > Triggers (tab).
•On Load, •Before Save, •After Save
Text fields are not editable.
What is wrong with me?

Best Regards,
Joshua
Post Reply
 
  2. Forum Index
  3. Online Help
  4. SysAid API Guide