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 = "";
/*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*/
/*Next we get the severity value from the SR. Be sure to replace "CustomColumn5sr" with the correct custom column number that you recorded earlier.*/
/*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.*/
/*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.*/ |
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. 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(); /*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) {
/*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.*/ /*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.*/
|
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.
- 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).
- Create a new class.
- 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(); - 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. - 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); - Change the SR's title:
sr.setTitle("My new title"); - Now save the service record using the service object created in step 3:
service.save(sessionId,sr); - 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:
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.