Restful API Plugin


 

APLRestfulARDBC is a plugin that allows Remedy to consume Restful API Web Services through Vendor forms

This plugin extends the capabilities of Remedy to consume the same Restful services that Remedy 9.x can publish, but does not require a 9.x Remedy server to utilize.  This plugin is provide as an open source project to allow users to take the framework that I have built and extend it to cover additional scenarios that I haven’t thought of or things that are specific to your system.

Installation and configuration instructions are available in the download.

If you think of a feature that you feel this plugin should have that you think everyone should have available to them that you developed, or if you don’t have the skill and want me to develop it, either way, contact me and I can look into incorporating it into the source available for everyone.

Enjoy

Version History
4.0 – August 11, 2018
– Upgrade Requirements: This release updates both the JAR and the form definitions, so you’ll want to re-import the def file ensuring to remove fields that don’t exist in the def as I have removed at least one field. Additionally I’ve changed JSON libraries so you will need to ensure that your pluginsvr_config.xml is updated properly with the new library being put in place on the server as well
– CHANGE: A major change in this release was a complete rewrite of the JSON Parser using a new library. This rewrite allows for greater flexibility in handling of the JSON and increased capabilities, additionally, the size of the JSON library I’m using is significantly smaller than the original one, this requires reconfiguration of the plugin to utilize the new library, all of the sample files have been updated appropriately
– ENHANCEMENT: I’ve modified the tool to automatically detect XML/JSON responses, so no longer have a field requesting this information from you, that’s one less thing you need to configure for your services
– ENHANCEMENT: Added the ability to specify a record indicator level instead of an element name, this provides greater flexibility in defining your records
– ENHANCEMENT: Added ability to ‘ignore’ certain levels of the returned results. See Appendix B for more details
3.10 – July 29, 2018
– Upgrade Requirements: This release updates both the JAR and the form definitions, so you’ll want to re-import the def file
– CHANGE: In an effort to make the setup and configuration easier and to utilize information already available to the plugin, I’ve removed a few settings: BackupUserName, BackupUserPass, BackupRASHash, and RemedyServerPort. The ‘Backup’ values are unneeded because of access that the plugin already has to the RASHash in the ar.cfg file, asking you to provide it for the plugin was not necessary and I’ve coded the plugin to just simply use that information automatically instead of forcing you to provide it, similarly, the port that Remedy is running on is also available and un-needed. Despite having access to the ar.cfg settings I’ve decided to leave the RemedyServerName setting because it might be necessary for flexibility
– ENHANCEMENT: In version 2.7 I added the ability for the plugin to use a Proxy server, but with that setting I made it an all or nothing setting, either the plugin was using it or not, not accounting for the fact that the plugin might need to use it for some but not all services being called, this update adds a new checkbox on the Table record allowing you to ‘opt out’ of using proxy on select services if a proxy server is configured
– ENHANCEMENT: I had a user contact me regarding the ability to get a value out of a response header instead of the body, it takes a slightly different nomenclature in the format of the field, but it works
3.9 – July 13, 2018
– Upgrade Requirements: This release updates both the JAR and the form definitions, so you’ll want to re-import the def file
– BUG: The enhancement I added in 3.7 didn’t work properly, I’ve done a bit more rigorous testing of it and it seems to be working better, thank you for the report
– ENHANCEMENT: I’ve modified the ‘Cache’ form to no longer store Status History. I did some analysis of the performance of the caching function and the status history function was not needed and caused unnecessary DB interaction, disabling this feature should enhance the performance of the plugin by a non-insubstantial amount
3.8 – June 22, 2018
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– CHANGE: Previously, the EntryID of any given cache record was the epoch timestamp + the request id. This works fine in most circumstances, It was however recently discovered that when using Vendor forms in Joins, that the vendor form must produce a 15 character entry id for all records. This is a minor change in the code, but important for functioning of the vendor form in question within Joins, so I needed to make this change for a specific user.
– CHANGE: While doing some checking today I found that I wasn’t using the Jackson Annotations library anymore, so I’ve removed it from the download and removed it from the templates. This will NOT impact your system if you continue to have it on your server but it’s no longer necessary
3.7 – June 20, 2018
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– ENHANCEMENT: Prior to this release, it was incumbent upon you to ensure the values that you were sending out were compliant with the formatting requirements of the format you were using, so if you had quotes or < characters or something along those lines in your data, the plugin did nothing to help you out, I have enhanced the template portion of the process to replace ‘special’ characters that would normally screw up the transaction with their relevant escaped/converted values for you
– ENHANCEMENT: Updated the JSON Parser code to attempt to detect the character encoding of the response JSON. According to specification this should always be in UTF-8 encoding, but apparently sometimes people don’t follow standards and it messes with other people assumptions, this is an attempt to accommodate those systems
– CHANGE: Within a given record, if the record contained an array with named values in it, you had a few options, you could specify which field/value pair you wanted, or the plugin would simply give you the last one. I’ve had a request to provide the capability to store all of the field/value pairs for all elements in the array, so what I have done is changed the behavior from just giving you the last one, to appending each of them sequentially in the element separated by a comma, this should allow you to collect all of the data and parse it out manually once the data is retrieved
3.6 – April 7, 2018
– Upgrade Requirements: This release updates the jar and some of the Remedy code. So, replacing the jar and import the def file replacing all of the objects.
– BUG: When you are sending a Date/Time field from the vendor form outside to another system I wasn’t making provision to convert that back from a Remedy value to a human readable value, I’ve added that provision. It uses format 2018-04-07T14:02:00
– BUG: There were times when a field wasn’t being used, and it was marked optional, but the field was still showing up in the body of the message being sent over, causing issues, this has been corrected
– CHANGE: The former default behavior from the beginning was to bypass any/all ssl issues with the certificate on the remote end, then in 3.0 I had a handshake error when using part of it, likely related to the fact that I was not doing any ssl validation, so I commented out part of the ssl all accepting code, which caused issues for others where the ssl cert was not valid for the host in question, so I have now added a check box on the table form that allows you to bypass all SSL cert checks…it’s defaulted to NOT checked, which means that all existing configurations will now validate the SSL configuration instead of the default before of NOT validating them, so if your SSL in question has ‘issues’, you can check the box and it won’t do any validation, otherwise you will do normal, proper validation.
3.5 – March 22, 2018
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: The web connection setup process was not setting the method properly if the remote server was a Remedy server
3.4 – February 19, 2018
– The only change in this release is the change of the license from GPL 3.0 to Apache 2.0
3.2 – December 8, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced, but because of some minor changes in the supporting def, you can re-import that if you care to
– BUG: Slight issue in the template pluginsvr_config.xml, missing a / where one was needed, corrected
– BUG: When making Rest calls to other Remedy servers it was incorrectly trying to open the connection to the remote server twice
– BUG: Made a slight modification to the RemedyUser sample Table entry, you may want to remove and re-import that arx file if you are using/testing that example
– BUG: ProcessEntry function wasn’t verifying that the entry in question wasn’t null causing nullPointerException
– CHANGE: I added default response codes to the Table form, this doesn’t change the defaults that the plugin uses, it just sets them in new records created by default
3.1 – November 5, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: Because of some refactoring I needed to do for the Attachment work I messed up some of the code for header replacement and Remedy authentication
3.0 – October 28, 2017
– Upgrade Requirements: This release updates the jar and some of the Remedy code. So, replacing the jar and import the def file replacing all of the objects. There are also a number of new config file parameters that can be utilized, so look at the template and see if any of them are relevant to your needs
– CHANGE: In version 2.4 when I upgraded Jackson from version 2.5.4 to 2.8.5, they apparently upgraded their java requirement from 6 to 7, which effectively upgraded mine as well, but I didn’t change the requirement at the package level…so the plugin would still load, but when it tried to use the Jackson libraries it would fail version check…so, since 2.4 you needed Java 7, but now the plugin requires it too
– BUG: My use of the ‘all trusting ssl’ code was causing an SSL Handshake error. After analyzing the effort it was related to the HostnameVerifier section, commenting that out allowed the connection to succeed, and verifying a remote system’s hostname isn’t a bad thing in general, so I left it commented out
– BUG: Added Error checking around custom headers to prevent index out of bounds errors
– BUG: Some of the workflow associated with automatic field generation was pointing to the wrong fields, I’ve fixed this
– BUG: Local Filtering was allowing values that were ‘null’ to show up when filtering on a specific value
– ENHANCEMENT: Added support for Attachment fields, see the rest of the documentation on how to build/manage/use an attachment field
– ENHANCEMENT: Converted the connection so that it properly recognizes http vs https for connection types enabling better handling of SSL specific capabilities
– ENHANCEMENT: Added the ability to set a keystore. The purpose of this keystore is to allow the client to provide a client certificate for authentication, templates updated and documentation updated to reference new xml parameter options
– ENHANCEMENT: The ‘Custom Header’ is now dynamic, it follows the same rules as the template bodies, you now have the ability to specify a field value in the headers and have that value replaced by the actual value at run-time
– ENHANCEMENT: Rest cache was previously stored in memory, which meant that if you were using this in a server group, each server would have it’s own cache of the values. I have converted the plugin to store the cache in a new cache form which will provide more stable caching across server group situations
2.9 – May 8, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: Issue identified in some JSON cases one ‘record’ was not logged into the recordList properly
2.8.1 – May 1, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: In version 2.5 I replaced the SSL Trust Manager with the ‘Extended’ trust manager in an attempt to fix something with the Remedy authentication, that ended up not being the issue, but I didn’t revert the change…this change had the unintended consequence of requiring an upgrade to Java 7.  I have reverted to the old trusted store code which restores Java 6 compatibility.
2.8 – April 27, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: Corrected an ‘Already Connected’ error when the body was being used
2.7 – April 14, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: If you had ‘Remedy Server’ checked, but your URL didn’t have a port specified, the URL wasn’t built properly and didn’t work
– ENHANCEMENT: Had the first server that needed a proxy server, added the config and code to handle it
– ENHANCEMENT: Added config parameters allowing the Table and Field form names to be able to be specified, allowing the user to rename the APL forms on their servers as they feel appropriate without causing the plugin to fail
– ENHANCEMENT: Added config parameter AlwaysLogDetails, if set to true, all activity is logged without the need to set the debug flag on a particular call, it’s still logged at ‘INFO’ level
2.6 – March 23, 2017
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: Fixed problem when passing ‘null’ values into fields
– BUG: Corrected RequestID value when the ‘create’ was not successful
– ENHANCEMENT: Added code to Template processing to remove all ‘non processed’ template values and replace it with blank strings
– ENHANCEMENT: Modified the code to provide a ‘Content-Length’ header in all situations, not just when a body template is provided
2.5 – December 15, 2016
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– BUG: When the Rest service in question was Remedy, I was hard coding the ‘Content-Type’ header and not telling you about it. This was needed only back before I allowed custom headers to be define, and the one I was defining for query was fine, but not for create or set, so it was causing issues. I have removed this hard-coded header, and added notification of the addition of the Authentication header that was also always being set
– ENHANCEMENT: Updated the Remedy Sample form that gives examples of Create/Set body templates and finished fully fleshing out the field list, so if you are using this sample form, you will want to re-import the def and re-import the Table and Field data records as well.
2.4 – November 20, 2016
– Upgrade Requirements: There are several supporting JAR replacements, all of the jar’s need to be copied to the server and the references updated/added in the pluginsvr_config.xml file appropriately. The templates have been updated for reference.
– BUG: Local Filtering was causing a results list with more entries than there were entries…or in other words, the entries were filtered, but not the results list 
– BUG: Local Filtering was causing filtering, but at the wrong level. If the query said give me 1 record (a setfield action) then it was grabbing only the first record of the total resultset, then, if that didn’t match the local filter, it returned 0 records. I needed to move the filtering of local before the max return portion of the code
– BUG: Added Try/Catch in the CacheCleanup method to prevent that process from preventing processing properly if there are errors in it
– ENHANCEMENT: Added ‘method used’ to the debug output just for completeness of detail
– ENHANCEMENT: Added body (template) format validation before making the call
– Added Jackson databind library (used for JSON validation)
– Added Jackson annotations library (used as part of overall Jackson upgrade
– Updated Jackson core library from version 2.5.4 to 2.8.5
2.3 – February 25, 2016
– Upgrade Requirements: This release is only updating the code in the plugin itself, so only the Jar is needing to be replaced
– ENHANCEMENT: The limitations of the 2.2 release on local filtering were too restrictive for my own needs, so I needed to build out full query capabilities including NOT, >, <, AND, and OR capabilities
– ENHANCEMENT: The query that returns records previously returned all rows and all fields for the record, this was potentially resource intensive on the network/client depending on how many columns are involved. This enhancement makes it so that the fields returned are only those being requested. This will speed up set-field actions as well as table queries by transferring less data between the plugin and the client
– ENHANCEMENT: Previously, the ‘control fields’ that are controlled by the plugin (Debug, BypassCache, and OutputUnusedElements) were not previously being returned with your search results. Recently I found that when using Vendor forms in Joins, that this caused the records not to display properly., so I changed this process to populate the control fields as well
– BUG: Apparently 9.x changes the way that escalations sends information to the plugin so I needed to move the code around a bit to make the ‘Backup’ process function properly
2.2 – February 18, 2016
– Upgrade Requirements: There was new workflow and new fields added, so this update requires a re-import of the Remedy code as well as replacement of .jar file
– ENHANCEMENT: Local Filtering, I came across a requirement where the web service I was calling didn’t have the ability to give me only the results I wanted (no ability to query on the value), so, in my example they were providing me 50 records, when I actually only wanted to display 10 of them. This lead me to this feature of ‘Local Filtering’. The feature is an attribute of the field definition. Read the documentation inline to learn all the details
– ENHANCEMENT: Added the ability to auto-generate fields. After a ‘Table’ record has been created you can now click the ‘Auto Generate Field Records’, provide proper sample data and the plugin goes through the request and adds any elements in the resulting call to the Fields list for that table
– ENHANCEMENT: Added the ability to get a Request ID back from the service on a Create function by specifying the element name in ‘Create Request ID Element’ field
– BUG: When using Cached results, the plugin wasn’t storing the results in the resultsMap, so, it was throwing an error when trying to get those results back
– BUG: While the plugin was properly maintaining when to use the previously cached results, and when to get new results, the cache was never being cleaned out, as a consequence, the size of the cache object just kept growing over time taking more memory. I added a mechanism to go through the cache object and clean out expired cache objects
– BUG: It turns out the ‘optional’ feature I added to templates with 2.1 never actually worked properly (sorry Tony), so, I got that working at this point
2.1 – February 8, 2016
– Upgrade Requirements: To apply this upgrade you will need to import the APL:RestfulVendorForms:Table form to get the new fields, and replace the .jar file on your server
– ENHANCEMENT: With the new template feature, I added the ability to now mark a field as optional in a template. If the field is part of the template, and the field is null, it’ll remove the field, and all tags on the line
– ENHANCEMENT: With the addition of CRUD, I hard coded the expected response codes. This is causing issues for some people, so I’ve made them variables that can be defined as needed
– BUG: I was not checking to ensure that the methods for CRUD were populated, so it’s possible that I was going to pass a blank value. I have defaulted the values if nothing is specified in the Table record. CRUD defaults to POST/GET/PUT/DELETE respectively
2.0 – February 2, 2016
– Upgrade Requirements: To upgrade the plugin, you will need the new Jar file as well as importing all of the Remedy Code. This will give you all of the forms/workflow necessary to utilize everything.  All of the existing records will continue to work without issue after the import.  Additionally, if you want to take advantage of the new Backup RAS Hash feature, that value will need to be added to your pluginsvr_config.xml file.
– ENHANCEMENT: Added the ability to do more than search on a form. With this release you now have the ability to Create, Update, and Delete ‘records’ on this vendor form.
– ENHANCEMENT: This plugin now supports not just putting things in the URL, but, now also in the body of the request. This is handled through the new ‘template’ fields defined on the Table form.  By providing a mix of hard coded values and field names encased in | values the body will be able to be dynamic based on the contents of the fields.  Check out the Template fields above for details about how the field value replacement works
– ENHANCEMENT: Added the ability to add your Remedy Application Service ‘hash’ from your ar.cfg file instead of a username/password for ‘backup’ purposes, when the plugin needs to log on and it’s the Escalator that’s executing the plugin. This feature allows you to store a hashed password without the need to have the ID/PW actually in the config file.
– ENHANCEMENT: On the ‘Table’ form, there is now a button to show you the current contents of the Cache
– ENHANCEMENT: When an error occurs, the error message now provides not just the Error code and URL, but also the Message associated with the error, for better troubleshooting help
-BUG: When a query was issued and 0 results were returned, the plugin still generated 1 entry, essentially an empty entry. If the query returns 0 records, but is still a valid call, then 0 entries will be returned now
– BUG: ‘Field’ = “Value” worked, but “Value” = ‘Field’ did not work…I made the assumption that everyone was making their qualifications the same way, this is obviously not true…so, both nomenclatures now work properly
1.9 – January 4, 2016
– ENHANCEMENT: Prior to this release, the connection you made to the remote service didn’t have a timeout value, which can cause a timeout when making calls to it because Remedy will timeout waiting for a response. So, I have modified the plugin to have a default plugin value of 90 seconds, and allow you to specify the plugin default within the pluginsvr_config.xml file, as well as a new parameter per table, which will require you to re-import the APL:RestfulVendorForms:Table table to get the new field.  If you choose to do none of these things, the new default of 90 still applies, you just don’t have ability to override it.
– BUG: There are apparently two types of ‘Basic’ authentication. One that requires authentication to connect to the web host, and a second that utilizes the Authorization header information to not provide authentication to the web server, but instead, to the app in question.  This plugin was previously only doing web server authorization, but not doing header authorization.  This has now been added to allow for this to function properly
– CHANGE: Removed the ‘username’ from the result set name. Originally, was planning on storing the results per user that issued a query, but never implemented…so…the username being stored as part of the result set name was confusing and not needed…doesn’t affect any functionality, just an internal structure change
1.8 – November 20, 2015
– ENHANCEMENT: A user come to me yesterday with a web service they were trying to consume that used a query parameter of ‘request_id#en=’. The problem they were having is that my plugin was not encoding the #, and causing them issues.  This confused me because I’m doing proper encoding.  After looking into it, the use of # in a URL is an ‘invalid’ practice and shouldn’t be done.  The # actually creates what is known as a fragmented url.  Everything past the # is supposed to be interpreted by a browser to indicate ‘where on a page to load’, and isn’t supposed to be sent to the server.  Because of this, my code was assuming that everything after the # was a reference to a location on the page, and wasn’t encoding it.  Well, being the vendor is xMatters, a ‘known quantity’ in the Remedy world, instead of making it so that my plugin won’t work with their tool, I decided to ignore the ‘standards’ of how it’s all done, and encode everything properly…but, truly….they shouldn’t be using them in their restful api J
– BUG: It was discovered by me that if you build everything properly on your Dev server, and then move your Vendor form to your test environment without moving the ‘Table’ and ‘Field’ records, that the plugin wasn’t handling that situation properly. I corrected the code to provide a nice and informative error message when this situation occurs.
1.7 – November 2, 2015
– ENHANCEMENT: Added a new field value mapping capability to the JSON interpreter. If you have an array with multiple ‘records’ in it with named values, the existing functionality gives you the ‘last’ entry in the array as your field values. This change allows you to specify a value in the array and map the field that matches it in the same record…details are above in the field documentation section.
1.6 – October 9, 2015
CHANGE: A User provided me with a sample XML where the value that would be provided for ‘Record Indicator’ wasn’t unique in the XML, in fact, that element name was duplicated within the element itself, which made it not unique which was causing an improper closing of the record when the child element closed. Because of this, I have modified the code so that the record indicator is fully qualified, so instead of just using ‘songs’, it’s now ‘ROOT:songs’.  This change will break existing records that are setup, but only requires a simple modification to the ‘Record Indicator’ field to be fully qualified instead of only the element name
– BUG: In the XML Parser, the element value wasn’t being cleared properly on end element, causing extra elements being populated that weren’t populated in the source XML
1.5 – September 21, 2015
– ENHANCEMENT: Added the ability to define ‘custom headers’ for each call, allowing you to control the headers being sent. This in vital/needed for both Jira and Service Now, without it a 400 ‘Malformed Request’ error is returned.
– ENHANCEMENT: I have now included a sample Service Now configuration that a user was kind enough to give me access to in order to troubleshoot his issue
– ENHANCEMENT: Added the ability for each ‘table’ to have its own cache setting that overrides the default cache size set in the plugin config
– BUG: Fixed a small bug with the caching that was causing it to no longer use a cache after the initial cache for a url expired
– BUG: Fixed a bug in the JSON parser that was causing rows inside of arrays to not be processed as new rows. I’m sure I did this on purpose at some point during development, but can’t recall it, didn’t make note of it, so, I’m reversing it…the code is now functioning properly with Service Now calls
– BUG: Fixed some references in some of the Sample code that was preventing it from being imported on some older Remedy servers
1.4 – September 4, 2015
– Initial ‘publicly available’ download
– ENHANCEMENT: Determined that upon ‘Error’ of one kind or another, the workflow needed to be able to determine that via workflow. To accomplish this, there is a new ‘Default’ field available on all Vendor forms (created by this plugin) named ‘ErrorOutput’ that can be added. If the plugin generates an error, then this field will be populated with the contents of that error. Further, if an error is encountered during calling the service, that cached entry will not be used, and a fresh call to the web service will be utilized
– ENHANCEMENT: This plugin utilizes the currently logged in user to log back into Remedy to get information. When an Escalation performs the execution, it doesn’t pass valid credentials to the plugin server to be able to log back in and get the information needed. Because of this, Escalations were throwing errors. I have included 2 new plugin parameters ‘BackupUserName’ and ‘BackupUserPass’ in the pluginsvr_config.xml file. These parameters are needed only if an Escalation has the possibility of causing a search against a vendor form.
– BUG: Fixed a problem with the caching mechanism, where every time a cache was used, the cache timestamp updated to the time it was used, causing a cached item to stay cached significantly longer than expected depending on use
1.3 – August 25, 2015
– ENHANCEMENT Modified all ‘System.out’ calls to be log messages allowing for proper logging as configured for the plugins
1.2 – August 21, 2015
– ENHANCEMENT: Updated some of the documentation based on user feedback
– ENHANCEMENT: Updated some of the definitions, you should re-import the ‘Remedy Code’ Def file to get the updates
– ENHANCEMENT: Updated the OpenWeather sample to include a Console allowing you to consume both services, seeing the difference between the two, and giving an example of how the results can be used
– BUG: Notified about a defect on the ‘getEntry’ call which was preventing the results from being displayed, corrected
1.1 – August 13, 2015
– ENHANCEMENT: Added ability to consume Remedy 9.x web services, need to re-import ‘Remedy Code’ def files
1.0 – August 10, 2015
– Initial public pre-release made available for download