SysAid WebAPI and my user system request project

 
Author
Message
SysAider
33
 
When we were converting over to SysAid I wanted to recreate, and improve, a system we used before for monitoring system access requests. In my mind all I wanted was a simple web form users could use to submit a request ticket that the admins could then work on, and if possible I would also like an easy way for users to be able to see what requests they had already made.

I knew I was going to have to work somewhat outside of SysAid for this, and most likely would need to use the Web API to submit the request, and do the lookup. After a lot of web searches, souring the forums, a few emails and phone calls with SysAid, I was told it was impossible.

Impossible only means it hasn’t been done yet.

So here is how I did it, and I decided to document the process for anybody else who wants to do the same thing.

First, a bit of foundation work. I am in a primarily Windows environment, all my users should be using Windows desktops, and I am using Active Directory which I integrated with SysAid. Because I have quite a bit of experience with VB.NET, I decided I was going to write this in ASP.NET using VB. This would work well on a separate Windows server running IIS on my internal network, allowing me to query Active Directory.

My SysAid environment is in the cloud, not on site. So this tutorial is going to be written with my experience on the Cloud, version 9.1.10 b15, on and around December 2013. My onsite web server was running on Windows Server 2008 R2, using IIS 7, with .NET features enabled. I wrote all my pages using Microsoft’s free Visual Studio Web Developer 2008 Express.

I want to add here that what information I did find did not always match up with what I experienced. I don’t know why, or how often it changes. But as I said this was working as of my posting.

To prepare in SysAid I created a new user called “webapi”, and promoted it to Administrator, then in the permissions I made it a “SysAid administrator”. I could possibly have used an existing account (and spared the administrator seat) but for security, and other reasons I wanted a local user separate from all other functions.

Under my ‘Categories’ I created a category called ‘System Request’, and with Sub-categories for each system the user could request access to. You can use a different name, but just take note of what you make, as I use this to create a filter later for ‘existing requests’. The categories were set to not be visible to end user, and just usable in ‘Requests’ and ‘Change’ since I was going to use Workflows later to process them.

I also needed to gather some information, so I went to the SysAid “Integration” configuration, and under “SysAid API” I copied the “wsdl” link. While you’re here also click on the “Network Discovery” configuration, then in “Downloads”, and take a note of your “Account Name”.
SysAider
33
 
This work is not going to cover how to use Web Developer, write VB.NET, or anything of that nature. It’s beyond the scope of this effort. However I will say that once you had created a new website, under ‘Solution Explorer’ on the right I right-clicked on the project (in bold) and selected “Add Web Reference…”. A new window will pop up, and ask for the URL, this is where you put the WSDL link, and click “Go”. After a few seconds it should show the description for “SysaidApiServiceService”. On the right change the “Web reference name” to “SysAid”, then click “Add Reference”.

See attached image for a quick example of what you should see when adding the web reference in 2008.

Now at the top of your project type “Imports SysAid”, and this should now give you access to the SysAid API.

To use the API you need to create a reference to the service, then login (keep track of your session ID), and then use the service to query, retrieve, and save data.

To create the service simply use the line:

Dim saService As SysaidApiServiceService = New SysaidApiServiceService

Next use the login information for your SysAid. This needs the account name (from the ‘Downloads’ section), the webapi user name and password. Remember you need to save the session ID you get from the login.



Now you should be in, but for error checking sake always make sure. If said is 0 then the login failed.


SysAider
33
 
Now that you are connected to your Web API, there are a couple of things you can do. In order to figure out how to submit tickets I first learnt what the existing tickets were saved as. To do this I had to load a ticket. This is done by using the service, pointing to our login session ID, passing a new SR object, and requesting a specific ID number. In this example I am going to request ticket 123, and confirm I got the SR.



Now I can display information about the SR. I added several text boxes to my webpage, and just assigned it values from the SR.



Since the description can be very long it might cause an error on a normal TextBox, so this is using a TextArea instead and setting the innerText value.

Now that I could load an SR, I could find out what the “srType” and “srSubType” should be for a request; that was all that I really needed in order to submit a Request rather than an incident.
SysAider
33
 
Next I needed to save tickets as requests. It is very similar to loading, just a little backwards. Logging in, and creating a session ID is exactly the same. However this time I wanted to start with an empty SR after doing the login.



Now I fill in the same fields with the information I wanted. Here is where I used a web form to gather the information. This example allows you to use the same form for testing saving that you used above in loading.



Now you basically just tell your SysAid service, using your login session ID, to save this new SR. It will return the new SR’s ticket number.



In reality for saving I would make some changes rather than just using a textbox for the information…

Rather than use text boxes from the Type/SubType I will hard code them to the values I know are needed for the type of request I want to make. I will also set the ‘Category’ value to the ‘System Request’ category I made in SysAid, and the SubCategory the system name.

I am also using a rather complicated web form, and other code validated the data in the forms (making sure all fields are filled out, etc.), and then merged it into one large ‘description’.

Depending on the system being requested (Email, Finance, Etc) I can assign it to different admin groups from here, who will take care of processing the requests. I also used the system name in the title of the ticket and the action desired (“New email”, “Modified Finance”, “Terminated user”).

Status should be “New” (1) all the time, again the code above was just for testing. If you want a specific status code to show it is from the web, you can go to the “Customize” section of your SysAid setup, select “Lists”, and from the drop down select “Status”. This will show you the existing names, and their corresponding values which is what you actually send SysAid.

Other options you may want to set are ‘requestUser’ and/or ‘submitUser’. For the ‘submitUser’ I used the person doing the form, to get this automatically I used this line



The request user could be the same, or allow the person filling out the form to submit a request for somebody else. I used a drop down of users from my ActiveDirectory.
SysAider
33
 
The final thing I wanted to do was have an easy way to show users their past and current requests. This depended a little more on my environment being Windows based, and was a little more complicated. However to be complete I wanted to include it here.

On the page I created a “p” paragraph to hold the information, so basically just needed to create some HTML from the query and use the innerHTML to fill and display it to the user. I used a table to format that content as well, as I wanted to display who submitted the request, the system (subCategory) requested, the time of the request, current status, and a link back to SysAid for the request to get more details.

The first thing was to identify the current user, using the same method as the submitUser above.



One thing to note is that this gives you a name like ‘DOMAIN\user’ when everything is working correctly. However for our query to SysAid that backslash needs to be escaped (\\), so I created a second ID from it as I would need both the original (idFull) for the webpage, and the escaped version (idEFull) for the query.



Now I use the same login process as above, with the same session ID, but this time I execute a select query. This command only returns a list of SR numbers, and only allows you to modify the “where” or condition portion of the request.

What I wanted was anything where the requesting user was the same as the current user (idEFull), and the category was the ‘System Request’ master category I created. So I created the condition:



If you are familiar with SQL this shouldn’t be familiar to you. You can create any condition statement you want really, and you can use the database guide here to know the field names :

https://www.sysaid.com/Sysforums/posts/list/5737.page

Next we run the query, and as I mentioned it should return an array of strings. You should check to make sure it returned something, or else nothing matched your query.



With our string array I then looped through them all, passing them to a function to load each one.



The ‘getDetails’ routine is basically the same as the load above, just once it retrieved the data it formatted it in HTML, which would then be placed in the ‘p’ tag



The first column is the user who submitted the request; not always you, as somebody else may have made the request for you. The second column was the sub category, which as I mentioned was the system name (Email, Finance, Etc.). Third column shows the time of the last update to the service record. The fourth column is the status; this is retrieved as an ID number (read about the status list above), and the ‘statusToString’ just converts that ID number to a human string. The final column is simply a link back to the SysAid website where the user can see the entire ticket through SysAid.

This message was edited 1 time. Last update was at Dec. 31, 2013 04:01 PM

SysAider
33
 
In summary, the WebAPI is actually pretty good. However there is virtually NO good documentation or tutorials on how to use it out there. I assume this was partially because SysAid would like use to use the professional services, but since I was told that submitting a request was impossible (yet I can do it) I had to figure this out myself.

As for the results; overall the website is very simple, users basically go to the intranet site where they can see the list of tickets where they were the requesting user, and the category was ‘System Request’. This way they can quickly see what they should have, and information about it.

From this page they can also request new access, and depending on the system request wanted they get a different form requesting different information. For a new email it asks which domain to use for the user from a drop down, but on the finance system asks dollar limits, and things like that. The forms are more to make sure that the user enters all the information the administrator is going to need. However these elements are not kept separate in the submission, they are baked together into a large text description.

This is later translated into a change ticket, so it can go through an approval process, and the various groups can all get tasks off it. Three is a change management video here from SysAid which talks about this portion of it : https://www.youtube.com/watch?v=MGsur17QUjA

Hopefully you find this information useful, and it saves you some time. Hopefully it will also help other people who are trying to get started with the Web API, and working on their own integration efforts.
SysAider
47
 
Stewart Willis wrote:When we were converting over to SysAid I wanted to recreate, and improve, a system we used before for monitoring system access requests. In my mind all I wanted was a simple web form users could use to submit a request ticket that the admins could then work on, and if possible I would also like an easy way for users to be able to see what requests they had already made.


Out of curiosity, why didn't the Web Form and End User Portal fit your needs?
SysAider
33
 
MyITGuy wrote:Out of curiosity, why didn't the Web Form and End User Portal fit your needs?


Hi MrITGuy,

I had tried a number of different options for this, and each seemed to have a different set of challenges. Doing my own custom web API allowed me to best control the process. While the user actually used a “Simple web form” to make the request, getting them that form, validating it, and getting it worked on was the challenge.

Not sure how in-depth you wanted, but here is the full explanation…

My first requirement was to be able to submit a SR as a request; something which other methods did not support and in fact I was told was impossible. Web Forms, and the XML API, can only submit incidents. While I appreciate that the ability to switch between incident/request is available/coming it is one extra step that needs to be performed (or forgotten). Because we are trying to follow ITIL as much as possible, and for the sake of reporting, the difference between an incident and a request is significant enough that I didn’t want somebody forgetting it.

The second was that I wanted to be able to route it directly to a specific admin group by letting me assign it at submission. Every time I submit an e-mail request for example I want the “Collaboration” admin group to get that ticket. Now in theory since I did use a category/sub-category for each request I could have used the built-in routing tools to do this. But since I have ‘catch-alls’ for specific companies this would have meant literally hundreds of rules to get them routed correctly.

Right now I have 10 companies in our SysAid, and should something not get routed to a specific group I wanted it to go to the local support team who could then route it accordingly. So in my routing rules I have rules that “Company 1” with “All categories” goes to “Support group 1”. I have a rule like this for all 10 companies, so local people are supported by the local support staff.

For these system requests, especially on centralized systems, I would have liked to have a rule that says “Any company” with category “System Request” and sub-category “Email” goes to the “Collaboration” admin group for example. Unfortunately since you cannot control the order rules are applied, and SysAid has the company take priority, my rules where a company is selected are applied first. So regardless of the fact it was a “System Request” for “Email”, since the user is from “Company 1” that takes priority over company “Any”, so it ends up going to “Support group 1” regardless.

There were two “solutions” to this, the first was to allow the local support people get them and then re-route them; thanks, but if I wanted to manually move everything around I would use paper tickets. The second is to make company based rules for each of them. So anybody from “Company 1” with category “System Request/Email” goes to “Collaboration”, then anybody from “Company 2” with category “System Request/Email” goes to “Collaboration”, and on and on. So for each system request I would have to make 10 rules. Far too much work for something that should be simple, and a huge pain to maintain! Also I am expecting to add more companies as we expand this to other sites, so it would just compound my problems to no end.

My third problem was trying to get all the fields and data validation correct. SysAid does have the option to create custom fields, which could be placed on custom forms. However this didn’t seem like a good use of resources for me. I would have needed dozens of fields for all the different systems requests elements that I needed to have. Adding all these extra fields into the DB would have been a lot of overhead for little value, since they have no value beyond the actual data gathering and submission.

In other words I would never need to run a report on what was entered as the choice for “needs new chair” in the form when setting up a workstation; but I did want the user to make the selection when submitting the form. Because of this I only wanted it to exist on the form, and not add to the SysAid environment by making it a custom field. Also as system requests change I didn’t want to have to keep an old custom field for a system we no longer support in the future.

Also SysAid had no way of validating some of the entries, which could only be done through an API to other systems. This also allowed me to make my forms dynamic, so I wouldn’t have to keep updating them. For example if I wanted to give the user the option of selecting which delivery routes should be available by a drop down or check box list SysAid had no way of querying to know what routes were available. I would have had to go in and update the web forms every time the route list changed, or made it a free form field which degrades the quality of the data due to user entry errors. Placing this as a separate portal allowed me to make this interlink between systems as well.

So, hope I didn’t bore you to death with my explanation of why I did what I did. There were a couple of other reasons, but these were the major aspects which made doing my own customized portal the best option.
SysAid VP Customer Success
601
 
MyITGuy wrote:Out of curiosity, why didn't the Web Form and End User Portal fit your needs?


It sounds like the Web Form feature would allow submitting incidents and not requests. Assuming the terminology used by Stewart Willis was accurate, he wanted requests.
This is, however, not such a big problem - because you can then use escalation rules to convert the incidents created from web forms to requests.

The bigger problem is that web forms won't allow you to view the past requests. You would have to login to view the past requests.


Steve,
How did you implement that second part (allowing to view the requests)? Did you implement a form that gets the SR# from the user and returns the details? If so, did you consider the security impact (anyone can guess the request number and get its details)?

Thanks,
Joseph.
SysAider
33
 
Joseph Zargari wrote:How did you implement that second part (allowing to view the requests)? Did you implement a form that gets the SR# from the user and returns the details? If so, did you consider the security impact (anyone can guess the request number and get its details)?


Hi Joseph,

I am working on the second part, but the programming is all there.

First let me address your second concern, about the security aspect. My portal only gives the most basic information; who submitted it, the subcategory (which will be the system), the updateTime, and status. Nothing that is vitally critical or sensitive in itself. However it then adds a link back to our SysAid environment for the details of the request, using this format:



From a security standpoint, with this URL alone, anybody with the SR# can lookup the details of any SR, depending on how the end user portal is configured and locked down. In reality without my portal I could type in the URL on any web browser:

https://<yourwebsite>/EndUserSRView.jsp?id=<SR#>&EndUserLink=YES

So my portal is not the security concern here. If we ever decide to lock down this ability on SysAid the link can be removed as it is not critical, just a nice to have as it takes the user to the full details. It wouldn’t limit the ability to check the status of current requests.

So the details on how I did the actual list of past requests is above. But basically it boils down to using the Web API to do an ‘executeSelectQuery’, searching for any SRs for the current user, with the category ‘System Request’. This returns a list of SR#’s for the user, and I then load each one, pull the elements mentioned above, and make a table of the output.

Just noticed my example above excluded the ‘System Request’ portion on the query, so I updated it.
SysAid VP Customer Success
601
 
Hi Stewart,

That's very impressive work! Not all IT Professionals have such programming skills.

As a side note, let me state that end users cannot use the URL as you suggested. They will only be able to view the data if logged-on and if they are the request user on that record.

Joseph.

This message was edited 1 time. Last update was at Jan. 01, 2014 10:19 AM

SysAider
33
 
Hi Joseph,

Joseph Zargari wrote:That's very impressive work! Not all IT Professionals have such programming skills.


Thank you. I know not everybody has these skills, but this information should be enough for anybody with experience in .NET to get started, or point a web developer down the right path. While doing my own research in this area I always felt that the first steps to getting started with the Web API were missing, and a lot of the information is outdated/wrong.

For example on this page https://www.sysaid.com/Sysforums/posts/list/7655.page#wsdl

It says to create the service you use this code :



However the 'getSysaidApiServicePort' is not a part of the Web API / WSDL interface, so this code wouldn't work. Perhaps it was valid back in 2011 (when the post was made), but this is (now) 2014!

(( HAPPY NEW YEARS EVERYBODY! ))

Joseph Zargari wrote:As a side note, let me state that end users cannot use the URL as you suggested. They will only be able to view the data if logged-on and if they are the request user on that record.


This is perfect for me, and matches the security I would like to have. I don't expect or want people to be able to see any records, just their own. Remember, the intent of the website is for people to see their own system requests and check up on them.

SysAider
33
 
Rather than leaving everybody with a spread out documentation I have put all of this together into a single ASP/VB.NET web-form that can demonstrate loading, saving, updating, and querying SysAid using the web API. These are the actual files I have been using while learning the Web API.

The attached files were made with, and can be loaded into Visual Studio Web Developer 2008 Express, which is available for free from here : https://www.asp.net/downloads/essential or by a google search for 'Visual Studio Web Developer 2008 Express' if that site changes.

The Web API I was using was based on the cloud version v9.1.10 b15, and was tested as working during the end of December 2013. Things can, and often do, change over time; which is part of the reason for this post.

This will allow you to work on the form, explore the code, and run the pages as well. However you will need to link your WSDL file to make it work, by getting your WSDL link, and adding a web reference to it and calling the reference ‘SysAid’. Instructions on how to do that is above (look for the other screenshot).

Please note that this is a development / proof of concept type of work. I do very minimal validation of data, and there is little safety nets in place to make sure you don’t do anything crazy.

Use at your own risk!

I have no way of knowing (or desire to find out) what might happen if you tried to save a ticket with very invalid information (like a word for the ID instead of a number). Hopefully the folks at SysAid are also making sure what is coming in is good, but don’t count on it.

Just remember the saying “make something foolproof, and somebody will make a better fool”.

This message was edited 3 times. Last update was at Jan. 01, 2014 09:47 PM

SysAider
33
 
Was unable to add two attachments to a single post; it automatically submitted the post. Here is a second post with the actual source code.
SysAidAPI.zip
SysAider
33
 
The final part to this series of posts to explain the almost end results of my user portal. Technically everything is working, which is what I will explain and cover here. Visually I am very utilitarian, and I expect my pages will be given to somebody with some sense of style to make them look a little more appealing. Also the various departments and groups can use this framework to then add more requests web request forms. I do expect things to change, but the underlying system is what I really wanted, and what the purpose of all this was.

As I mentioned my sites are primarily Windows systems, with an Active Directory managing users and computers. For this reason I decided to run the user portal on a Windows 2008 R2 server, using IIS 7. The pages I created were made with Microsoft Visual Studio Web Developer 2008 Express. Once created the pages were moved to my web server, the folder converted to an “Application” and I was up and running.

The users go to the intranet site (only accessible internally), and get to the site by Single-Sign on or a web-prompt so they log on to the website. It’s not an open website, it requires you to log on with your domain credentials so that the webpage knows your identity; or at least the identity of the person who logged on to the website.

This first page uses information from the users login to gather information from Active Directory (the top part of the page) and uses the SysAid query and loads to look for the user with the same login in SysAid, with any requests that are in the category ‘System Request’.

With the Active Directory integration I determine if they are part of HR or IT; if so they get the ‘search box’ at the top, otherwise they do not.

Next is a couple of simple details pulled from Active Directory about the user, their title, department, manager, etc. The blurs are old data from our previous owners which we are cleaning out. If the person themselves is a manager then they will see a drop down listing all the people who report to them. You can see from the attached example I have 9 people reporting to me. If I use the drop down to select one of these people I will go to their system access page, and see their requests.

For security you can only see another person’s page if you are in HR/IT (like the search) or if you are above them in the organizational chart; their manager, or the managers manager, etc. Otherwise it defaults back to the credentials of the logged in user.

Under the AD section is the actual systems request. This I separated into three areas, “Current Systems”, which is a list of systems where I was requesting access. Next was “Submitted requests”, which is for situations where I submitted the request, but for another user; for example a new hire, or one of my reports. This section is usually hidden, and only shows up if you have submitted requests on behalf of other users. The last section is the “New Requests”; which I will talk about later.

Using the AD credentials (since I have LDAP integration with SysAid) I then use the account to query SysAid for all tickets where the submit user or request user matched the credentials of the users page, and the SR category is ‘System Request’. If the SR request user matches my account, then the ticket was listed under the ‘Current Systems’ list. If the submit user only matched, then it went under the ‘Submitted requests’ tab. Both look almost the same, except on the current systems the first column is “Submitter” and on the other it is “Request for”.

With the tickets I also queried SysAid for the full name of the user, and the e-mail address on file. This was used as a mailto link on the first column. I did not query Active Directory for this for a few reasons, the user could have been a local sysaid account, and old user no longer in Active Directory (but still in SysAid), or later on we may be adding more end user from another LDAP source, or possibly non LDAP users like vendors/contractors/etc.

The ‘System’ column is really the sub-category, which we use to match the system names. The time is the update time on the ticket, and the status matches the status of the ticket. The link column is a link back to SysAid. As Joseph pointed out, the user needs to login to SysAid to get the full details of the ticket, and needs to be the requestor of the ticket, which is exactly what this list is so it should match up just fine.