A Simple RFM Services client application in ASP.NET

◂ Prev Next ▸

The basic steps of connecting to and consuming RFM Web Services in a client application are:

1. Choose your client framework for communicating with the RFM Web Services.
2. Configure the application's Web Services client interface so it can connect to the RFM Web Services server.
3. Connect to the RFM Web Services using your client framework; Authenticate, and create a new session.
4. Call RFM Web Services operations as required by your application.

You can use any platform that supports HTTP Web Services to consume RFM Web Services. In the example we create here, we will use a simple ASP.NET application, but almost everything that is not specifically targeted at the browser (i.e HTML, javascript, etc.) is equally applicable in any .NET target environment (console applications, services, Windows Forms, WPF). To create the application:

Start Visual Studio Go to the menu option File → New → Project and select it. Select "ASP.NET Web Application" in the New Project dialog. We will call the new project "Rate". Build and run the new project to ensure it was created and builds correctly.

Visual Studio 2010 new ASP.NET Project

Visual Studio 2017 new ASP.NET Project

The first task is to give your new application the means by which it can communicate with the Web Services server. That is, to add a client framework that provides the link between the application and the RFM Web Services server. There are several ways to go about this, depending on whether you choose to communicate with the RFM Web Services server via the SOAP 1.1 or via the REST interface (see a short review of SOAP vs REST).

REST Interface
REST-based service calls rely heavily on the pre-existing elements of the HTTP protocol. As such, client support for them requires only the ability to make HTTP requests, and receive the results. .NET provides a variety of classes capable of doing this, for example HttpClient in .NET 4.6 and later, or HttpWebRequest for earlier versions of .NET. Note that all RFM Web Services REST calls use the HTTP POST method, and encode the message body using JSON.

SOAP 1.1 Interface
SOAP calls are more complicated than REST as they require that the HTTP request body include XML that satisfies a particular schema. Most languages and the IDEs that support them provide automation facilities so the programmer does not need to be exposed to this XML in any way. .NET and Visual Studio are no different in this regard. Visual Studio allows applications to consume SOAP services by creating a Service Reference. When a Service Reference is first created, the IDE reads the WSDL presented by the Web Service and uses it to create a wrapper class that exposes one method for each operation of tmakes the remote service calls as easy to invoke as calling a method on a local .NET object. Note that the WSDL for the demonstration RFM Web Services server can be read from: http://rfmdemoserver.azurewebsites.net/RFMWebService.svc?wsdl.

RFM Web Services Client
RFM has encapsulated both SOAP and REST-based client access to RFM Web Services in the RFM Web Services Client. Including this DLL in your project:

• Automatically includes the infrastructure necessary to connect to the RFM Web Services server.
• Provides a single class (RFMWebServiceClient that encapsulates both the REST or SOAP interfaces, and hides which one is being used to actually communicate with the server. Using this class, RFM Web Service operations can be called in client code simply by invoking a method in the RFMWebServiceClient class and setting a parameter to indicate whether the call will be made as REST or SOAP.
• Provides an AJAX handler that automatically routes AJAX requests from the browser to the appropriate operations in the RFM Web Service library.
• Provides session management so that persistent objects retain their value bewtween HTTP page requests.

In this example, we'll use the RFMWebServiceClient since it does much of the background work required to interface our small application to RFM Web Services and manage the connection as the applications runs.

To utilize the RFM Web Services client in the app we are building:

1. Copy all the DLLs supplied in the bin folder of RFM Web Services (shown right) into the project's bin folder (you can download the project, including the required DLLs, here).
2. Add the file RFMWebServceClient.dll as a reference to the project.
3. Build the project again to make sure there are no errors.

Once the client interface has been determined and installed, it must be configured so that it can find the RFM Web Services server. You will need to know the URL, of the RFM Web Services host you are connecting to. If you are connecting to the public RFM Web Service demonstration server, you can use the URL: http://rfmdemoserver.azurewebsites.net/

The way you configure this URL in the software depends on the client you are using. If you are using your own REST client, you can specify the URL each time you create a new request object. If you are using the SOAP client or the RFM Web Services Client, you should specify the RFM Web Services host URL in the applications configuration file, usually web.config for web-based applications.

1. Open the web.config file for editing.
2. Make sure the following sections (appSettings and system.serviceModel, and the settings within them, are included (use your host URL as appropriate):
   <appSettings> <add key="DefaultClientProtocol" value="REST"/> </appSettings> <system.serviceModel> <client> <endpoint name="RFMRestService" address="http://rfmdemoserver.azurewebsites.net/RFMWebServices/" binding="webHttpBinding" contract="RFMRESTService"/> <endpoint address="http://rfmdemoserver.azurewebsites.net/RFMWebServices/RFMWebService.svc" binding="basicHttpBinding" contract="SOAP.IRFMWebService" name="BasicHttpBinding_IRFMWebService" /> </client> </system.serviceModel>

   Note:

   • The DefaultClientProtocol setting tells the RFM Web Services Client which protocol you prefer that it uses. This setting is not required if you are not using the RFM Web Services Client.
   • The <endoint> named "RFMRestService" is read by the RFM Services Client and is used to establish the URL to which the REST requests will be sent.
   • The <endoint> named "BasicHttpBinding_IRFMWebService" is also used by the RFM Services Client, which embeds a wrapper around a Service Reference that will attempt to connect to the RFM Web Services services at the address specified in this endpoint.
3. Make changes to aspx.cs "Code Behind" file" to support AJAX message handling.
   The RFM Web Services Client has been architected to use AJAX as the preferred method of providing web-server support for events generated in the browser. For example when the user clicks a button, an AJAX request is sent to the server, which handles the event as appropriate, and asynchronously returns a stream of data to the browser. The asynchrounous response is itself an event which can be handled in the browser with its own "handler" javascript function.

   This entire sequence events can be largely automated using the framework provided in the RFM Web Services Client. To enable this, the following line should be added to the Page_Load() handler in the "code behind" .cs file associated with your .aspx page.

   using RFM.WebServices.Client; public partial class RFMTestPage : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { RFMAjaxHandler.Handle(); // <--- Add this line. } }

   The Handle() method filters the HTTP Request parameters searching for one named "RFMAjaxMessage". If this exists in the request, Handler() invokes the appropriate Web Service, and marshalls the return result.

4. Build the application again to ensure there are no errors.

The high level architecture of the various RFM elements and the components that host them is shown in the diagram below.

Note that the RRM Web Services Client and the RFM Javascript Library provide functions that hide much of the plumbing needed to wire up communications between the various tiers, manage session information, authentication, etc. However, they are not necessary to consume RFM Web Services, as you can create your own custom interfaces between the tiers. More information on the interfaces between the tiers, and how to build your own client layer, is provided here.

In this step, we add our first web page to the application and create a login panel that the user can use to enter their username and password. We then make an Ajax call to the web server, which is relayed to the RFM Web Services to create a new session, authenticated by the user and password.

Note: We make extensie use of AJAX in this example since this usually provides for a more fluid, interactive user expereience by reducing the number of complete page refreshes required.

1. Create a new .aspx page in the application. We will call it RFMTestPage.aspx
2. Add the following HTML code to the <body> section of the code to produce the panel shown (for clarity, styling code has been omitted. Feel free to add any desired styling to the elements, or refer to the source code for this example for styling.):

   <div id="LoginPanel"> <div > <table style="width:100%"> <tr> <td>User</td> <td><input id="UserName" class="InputField"/></td> </tr> <tr><td colspan="2"> </td></tr> <tr> <td>Password</td> <td><input type="password" id="Password" /></td> </tr> <tr> <td colspan="2" style="text-align:center"><br /><br /> <input type="button" value="Login" onclick="Login()"/> </td> </tr> </table> </div> <div id="LoginError" style="color:Red;margin-top:2em;"></div> </div>

3. Notice that the onclick event of the Login button is handled by the function Login. The next step is to add the code that defines the Login function to a <script> block in the <head> block of the page. The javascript file rfm_lib.js defines an RFM object that provides a number of utility routines that make it easier to work with RFM objects in the web browser. Before doing anything else, this script file should be included in the head of the HTML code for the page.
   <script type="text/javascript" src="rfm_lib.js"></script>
   We now add the Javascript for handling the login event. Since this is implemented as an AJAX request, we define it in two parts. The first (the Login() function) collects data from the elements in the on-screen form and dispatches them as an AJAX request, and the second (HandleLoginResponse()) handles the asynchronous response received when the AJAX call returns. (we will fill in what happens if the login is successful in the next step. If it fails, we just write the failure message).
   <script type="text/javascript"> // // Handle click of the Login button // function Login() { var login_info = new FormData(); login_info.append("RFMAjaxMessage", "login"); login_info.append("username", UserName.value); login_info.append("password", Password.value); // // Call the login request. // The asynchronous response is handled by HandleLoginResponse. // RFM.ajaxRequest(document.URL, login_info, HandleLoginResponse); } function HandleLoginResponse(httpResponse) { var response_obj = JSON.parse(httpResponse); if (response_obj.result == "Success") { // Do this in the next step } else LoginError.innerHTML = response_obj.message; } </script>

sets If the authentication process was successful in step 3, above, we want to dismiss the login panel and replace it with a form that contains the fields we need to display to gather the data necessary to perform a credit rating. How do we know what those fields are, and what they should contain? The answer is that we do not need to. We can just ask RFM to serve the HTML that contains all the fields, embedded attributes, event handlers etc, that are needed to capture the required data. All we need to do is provide some screen real-estate into which RFM can render the required panels. Let us add the code that does this now, by replacing the comment // Do this in the next step with the code shown below.

Note the use of the function RFM.getPanelHTML(). This makes an AJAX call which the RFM Web Services Client Handler method passes to the RFM Web Services server. The server responds by looking up the model, and automatically generating the HTML necessary to render the request panels. These are RatingFinancialsPanel, which renders the financial parameters input panel shown left (below), and RatingQualitativePanel which renders the questionnaire to the right.

Note that no HTML was ever hand written to create the panels shown above. They were all automatically computed by the getPanelHTML functions.

Once the form fields have all been filled, clicking the Rate button will send the information to RFM Web Services's Rate() operation. This accepts a model identifier and group of parameters, and returns the calculated probability of default (PD). To enable this using the RFM Javascript library, we need only add the following javascript in our .aspx file to handle the onclick event from the Rate button:

Again, note that the rating event is handled in two parts. First, DoRating() collects the data from the on-screen forms and calls the RFM Javascript library function RFM.rate(). Internally, this makes an AJAX call, which must be handled when it returns. This second part of the process is impelemented by HandleRatingResult().

Also note the use of the RFM Javascript library function RFM.getAjaxFormData(). This locates the DOM element in the current HTML document whose id is passed as function's first argument, and finds all the data-bearing elements it contains, either directly or indirectly. For example, it will search for all <input>, <select>, <textarea>, and certain <div> elements and build a JSON object that records each identified data value as a property:value pair. This object (whose variable name is data in the example above) can then be used to send data to an RFM AJAX call.

This is illustrated below, where the form values on the left result in a JSON object passed to RFM.DoRating() as shown on the right. The questionnaire values are not shown but the JSON object is still populated with their results, (specifically, the 0-based index of the selected item).

{ _wm_entity_fqn : "Rating", WorkingCapital : 1000, TTA : 200, InterestExpense : 100, EBIT : 500, TotalLiabilities : 50, CurrentAssets : 2000, CurrentLiabilities : 200, Sales : 3000, SalesPrevYear : 2500, LengthCustomer : 0, ManagementExperience : 0, ManagementReputation : 0, IndustryMaturity : 0, Planning : 0, Sustainability : 0, CustomerConcentration : 0, SupplierConcentration : 0, _wm_attributes : "WorkingCapital,TTA,InterestExpense,EBIT,TotalLiabilities,CurrentAssets,CurrentLiabilities,Sales,SalesPrevYear,LengthCustomer,ManagementExperience,ManagementReputation,IndustryMaturity,Planning,Sustainability,CustomerConcentration,SupplierConcentration" }