One of the major benefits of developing under ARS is the quick and easy of its integrations using web services. Select a form, select some fields and done. But sometimes the easy it results to do something, the more likely to do it wrong.
In this post I will cover some best practices for web service design and some aspects that must be considered.
Creating a web service is not all about consuming and providing the information
When planning an integration, the different parts normally focus on the information that must be shared between systems and how this information will be transferred. But a lot of aspects must be taken in consideration like security, auditability, error control, debug capabilities, etc.
Security is an important part. Normally in Remedy, web services security is based on user security. That means that any user with access to the information is able to use the web service. You must consider restrictions on which users can or can’t access the information through the web service. Also security is about your system. Denial of Service is not impossible. A uncontrolled loop on the other side of the integration can start a madness of uncountable web service calls that affect the ARS servers and database engine.
Auditability and log debugging are very important. You must check your needs and see what auditability level do you need. In this direction you must check if only editing actions must be audited, or also reading actions need to be tracked. In this direction, maybe you may want to track all editing failures, that is, some editing or submitting action that provoked an error.
Finally, you must create an error communication channel with the other part, to control the result of the action.
The presentation layer for web services
If we review the three layers concept for Remedy, we can state that filters are designed to provide a business logic layer and active links to provide a presentation layer. But active links can’t be used for web services. In fact the active link concept is non-sense for web services. So, there is no presentation layer for web services. Well, this is not correct, we can program the presentation layer code with filters. But, Isn’t it messing both layers? No, if we create an interface form or a buffer form.
The interface form
The first option is to create a join form to act as an interface with the web service. Do not create web services directly connected to the main regular form, but an special form specifically designed to host the web services. For ease of reading let’s define some concepts. Let’s call “main form” as the original form that holds the information. Let’s call “interface form” to the join form create to host the web service.
The interface form is a join form with the main form as the two parts of the join. That is, it is only a “view” of the original form (not to be confused with a “view form” that is a completely different concept).
Having an interface form has a lot of benefits. But the most important of them is the segregation of layers. All filters of the web service presentation layer will be associated with the interface form, and all filters of the business logic layer will be associated with the main form.
The buffer form
The buffer form option can be applied to request creation web services. It consist of a regular form that reproduces some fields of the main form. When a request is created form the web service, this request is reproduced at the main form using workflow.
The workflow that creates the request can be done with filters or with escalation. Review the abuse of escalations post, for information about this practice. Our election must be always filters, except when the processing time is so high that there is a high risk of obtaining a timeout in the web service connection. At those cases, the escalation is the best option. Review the post about how to schedule actions.
The buffer form is more complex to create than the interface form, but has some advantages. The first is that the exact information provided for the creation is stored at the form, so we obtain an exact audit of the web service calls, no matter is it ends with an error at the main form request creation. The second advantage is that it allows the use of escalations to process the request creation offline.
Presentation layer options
Well, we have created a presentation layer for our web service, but, what can we do with this layer. Let’s review some options.
You can create a new field (display only for interface forms and optional for buffer forms) to store a message that reports the result of the action. Your presentation layer will store the result of the received action at this field. This field can be published by the web service at the output.
If you have restrictions to some fields, you can control them at the presentation layer and provide a better error that will reduce the integration effort.
You can create a new form to store an audit of reads. Using workflow rules, you can create a request each time the web service is consumed. This workflow must be executed only for web services, so it will be placed at the interface form. So user reads will not fire this audit. Depending on your audit needs you can store each call or the details of the call (like the used qualification).
You can store at another form the last time a web service was called by some user. If it is called again by the user you can reject the call, notify, register or any action you consider.
Localization and translations
Selection fields are only localized at views. Web services can’t localize the value. You can create display only fields at the interface form to hold a translated version of the field. This idea can be extended to any translation you need to integrate both systems.