Objective

To demonstrate the ability of a Fiorano REST application to interact with an end user by exposing a secured REST service which accepts HTTP POST requests at a URL and responds with a count of new records inserted into a database successfully.

Prerequisites

• Start Fiorano Enterprise Server (FES) and Fiorano Peer Server (FPS)
• Login to eStudio application
  • Understand the basic menus and perspectives (panels) in eStudio application
• Add DB jars (ojdbc.jar) to System Library by following the steps mentioned in Add Resources to a Microservice. This is for the DB component to work seamlessly.

Scenario

• Configure RESTStub component to receive HTTP POST requests from RESTConsumer and process it as query configured in a DB component; bind DB schema to RESTStub and transform the routes between RESTStub and DB.
• Configure RESTConsumer component to send HTTP POST requests triggered using a Feeder component which adapts RESTConsumer schema.
• Use security settings (Basic HTTP Authentication / SSL security) for Peer Server Jetty profile, RESTStub and RESTConsumer in sequence.

How it Works

The REST service gets deployed in the jetty server running inside the peer server and whenever a rest client sends a request to the service, the request is available on the output port and the response can be routed back by connecting a route to the input port.

Components used

• RESTStub
• RESTConsumer
• DB
• Feeder
• Display

Setting up the Example

Configuring Peer Server Profile for Security

Stub component would be running in the FPS server. As SSL support and HTTP Authentication are provided for Jetty, configure the corresponding parameters (SSL configuration or Basic Authentication as per requirement) for Jetty in the FPS server profile.

For Basic Authentication settings as well as SSL security settings, changes are done in Properties of Jetty in FPS Profile. To navigate to this panel,

Open Profile Manager in eStudio and load the respective FPS profile 

 Navigate to Fiorano > Esb > Jetty > Jetty

In the Properties of Jetty section on the right side, under ComponentInstanceConfiguration section, enable the BasicAuthSupported property or SSLEnabled as the case may be. Below sections explain both of these configurations.

Basic Authentication

To configure the Jetty properties for Basic Authentication in the FPS server, enable the BasicAuthSupported property and provide location where RealmProperties file is saved.

SSL Configuration

To configure the Jetty properties for SSL Security in the FPS server, refer the Manage Jetty Security section to enable the SSLEnabled property and provide Keystore and Trustore values.

Configuring Server Event Process

Create an Event Process with name 'REST-POST_Server' to configure a server application with a DB component to raise query. 

Configuring DB component

Use the DB component to store data and return result upon Insert Query Statement.

To configure DB component, perform the following actions in the REST-POST_Server event process:

1. Under DB category in the Microservice Palette, drag the DB component to the Fiorano Orchestrator.
   
    
   
   

2. Double-click the component to open the Configuration Property Sheet (CPS). 

3. In the Managed Connection Factory panel, click Database Configuration ellipsis button to configure DB Connection. Provide the credentials for the respective DB from which the table needs needs to be accessed.

   Icon

   Refer  Database Configuration section to know about the properties that needs to be configured.

   
    
    

4. Click OK and click the Test button present in the Managed Connection Factory panel to confirm successful connection. Click Next to move to the Interaction Configurations panel.
   
   

   Icon

   Ensure that DB jars are added to the System Library as instructed in the Prerequisites section in the beginning, else there may be issues with the connection.

5. In the Interaction Configurations panel, click SQL Configuration ellipsis button to configure Insert SQL statement; provide Query Name: insert.

   Icon

   Refer Simple Insert Statement section to know how to insert values to a table.

   
   
   
   

6. Click Finish to complete SQL Configuration.
   
   
   
   

7. Click Finish in the Interaction Configurations panel  to complete the DB Configuration.

Configuring RESTStub component

RESTStub component exposes Restful services in Fiorano environemnt. To configure RESTstub component, perform the following actions in eStudio application:

1. In the REST-POST_Server event process, drag the RESTStub component from the Web category in Microservice palette to the Fiorano Orchestrator.
   
   
    

2. Double-click the component to open the Configuration Property Sheet (CPS).

   Icon

   Notice that the RESTStub component does not have any ports attached to it; ports appear only after configuration.

3. First screen in the CPS, that is, wizard (1 of 3) is used to define the service using a user interface for WADL. User can create a WADL manually by defining different aspects of the service or can load an existing WADL and edit the configurations.
   Provide Service Name as 'Sample' with which the event process functionality is exposed as RESTful service.
4. Under Create/Edit WADL section, perform the following actions:
   
   

   1. Bind DB input port and output port schemas to RESTStub

      1. Click Schemas under Configuration tab.

         Icon

         Port Schemas appear only if the DB component is configured correctly.

      2. In the Schemas Configuration section, click Add  button and click Load from Port Schemas option

      3. In the Select Port dialog box that pops-up, select 'IN_PORT'.
         
         
         
         

      4. Similarly, select OUT_PORT also and click OK; both schemas get added under Schemas section.
         
         

   2. Add POST method

      1. Right-click GET node and select Remove Method option to remove the default method.
         
         
         
         

      2. Right-click resource under Resources node, go to Add Method and select POST option to add Post method.
         
         
          

   3. Rename resource path to give a logical meaning to the scenario

      1. Click resource node. 

      2. Under Resource Configuration tab, replace the default value of Path 'resourcePath' with 'insertData'.
         

         
         
         

   4. Add request SQL element to Post node

      1. Click the POST node.

      2. Click the Add  button under Request Configuration tab.

      3. Click the ellipsis  button under Representation tab.

      4. In the Select Element pop-up, select "SQL_CFG_1" under Request element and click OK.
         
         

   5. Add response SQL element to Post node

      1. Right-click the POST node and click the Add Response option; Response node appears.

      2. Click the Response node

      3. Click the Add  button under Response Configuration tab.

      4. Click the ellipsis  button under Representation tab.

      5. In the Select Element pop-up, select "SQL_CFG_1" under Response element and click OK.
         
         

Security Configuration in RESTStub

Click Next to navigate to the second screen: wizard(2 of 3). Here, SSL Configuration, HTTP Authentication Configuration and Additional Configuration can be done.

In this example, SSL Configuration and Basic Authentication under HTTP Authentication is being done one after the other. Do either of these two and move forward accordingly.

SSL Configuration

In SSL Configuration section, enable SSL by selecting the Use SSL option and provide.

Basic Authentication Configuration

In HTTP Authentication Configuration, enable HTTP authentication by selecting Use HTTP Authentication option. Provide the credentials as below:

• Type: Basic
• Username and Password: as provided in FPS Jetty profile.

Click Next and then Finish in the third screen, that is, wizard (3 of 3) to close the CPS and to save the configuration. The input and output ports gets generated.

Configuring Transformation

Connecting Ports Creating Routes

Connect the ports of the RESTStub and DB components in the following manner:

• Output Port of RESTStub component to the Input Port of DB component.
• Output Port of DB component to the Input Port of RESTStub component.

Route Transformation

To configure transformation between input and output ports of RESTStub and DB, perform the following actions in the Fiorano Orchestrator:

1. Right-click route1, point to Configure Transformation and select Mapper Project to open Fiorano Mapper editor.
   
   
    
2. In the Mapper Project, connect the values with the same names present in panels: Input Structures and Output Structures:
   1. Name
   2. ID
   3. Designation
      
      
   
    
3. Click Save icon (or File > Save) to save the transformation configuration and close the Mapper Project editor.
4. Similarly, go to the Mapper Project window for route2 as well and connect the following values:
   1. id
   2. UpdateCount
       
   

5. Save the mapping configuration as explained previously.

   Icon

   Now the dotted lines in the route would be transformed to bold lines implying that route transformation has been done.

   

Launching the Server Event Process

WADL URL has to be copied from RESTStub component to use in RESTConsumer component that gets added in further steps; perform the following actions in the Fiorano Orchestrator:

1. Click Check Resource and Connectivity (CRC)  icon (or press ALT+SHIFT+C) to check resource and connectivity.

   Icon

   Ensure that the security configurations completed in Profile Management and RESTStub are in sync, that is, the corresponding configurations for SSL Security or Basic Authentication as the case may be. Errors may occur while CRC if these are not configured correctly.
2. Click Run Event Process  icon (ALT+SHIFT+R) to run the event process.

3. Right-click the RESTStub component and click Copy WADL URL option to copy the WADL URL.
   
   

Configuring Client Event Process

Create another Event Process with name REST-POST_Client to configure a client event application with a Feeder and Display.

Configuring RESTConsumer

RESTConsumer component serves as a client to access exposed services in Fiorano Environment. To configure RESTConsumer component and hence communicate with RESTStub which has exposed RESTservice, perform the following actions in the REST-POST_Client application:

1. Add the RESTConsumer component from Web category in Microservice Palatte to the Fiorano Orchestrator.
   
   
    
2. Double-click the component to open the Configuration Property Sheet (CPS).
   
   
   
   
3. Perform the following actions in the wizard (1 of 3) panel:
   1. Enable Load WADL option; the From URL option below gets active/editable.
   2. Select From URL option and paste the WADL URL copied from RESTStub (previous section).

   3. Click the Load WADL button to apply the RESTStub schemas. Schemas get populated in the below section in the panel.
       

   

Security Configuration in RESTConsumer

Click Next to navigate to the second screen: wizard(2 of 3). Here, SSL Configuration, HTTP Authentication Configuration and Additional Configuration can be done.

In this example, SSL Configuration and Basic Authentication under HTTP Authentication is being done one after the other. Do either of these two and move forward accordingly.

SSL Configuration

In SSL Configuration section, enable SSL by selecting the Use SSL option and provide the values as used in RESTStub SSL Configuration.

 

Basic Authentication Configuration

In HTTP Authentication Configuration, enable HTTP authentication by selecting Use HTTP Authentication option.

Provide the credentials as provided in RESTStub.

Click Next and then Finish in the third screen, that is, wizard (3 of 3) to close the CPS and to save the configuration. The input and output ports gets generated.

Configuring Feeder

1. Add Feeder and Display components from the Util category in Microservice Palette into the REST-POST_Client orchestrator.
2. Connect the ports of the RESTConsumer to the two components in the following manner:
   1. Output Port of Feeder component to the Input Port of RESTConsumer component.
   2. Output Port of RESTConsumer component to the Input Port of Display component.
       
   
   
   
3. Double-click the Feeder component and click the Connected Port Schemas button in the Message Type Configuration panel. Select the last child node ('resource_POST_Request' in this example) in Connected ports pop-up to import RESTConsumer schema into the feeder and click OK.
   
   
   
   
4. The Select Root Element text box gets populated and schema editor also gets populated with the RESTConsumer schema. Click Next.
   
   
   
   
5. In Message Details Configuration panel, click Generate Sample to open XSD Sample Generation Dialog. Enter '1' in max text field under No. of Repeatable elements to be generated to reduce the number of samples generated to just one, and click OK.
   
   
   
   
6. Click the Finish or Save and Close button to complete the Feeder configuration.
   
   

Running the Example

To see the REST-POST_Client Event Process running in conjunction with REST-POST_Server Event Process, perform the following actions in the REST-POST_Client Event Process:

1. Click Check Resource and Connectivity  icon (or press ALT+SHIFT+C) to check resource and connectivity.
2. Click Run Event Process  icon (ALT+SHIFT+R) to run the event process; Feeder and Display windows get opened.
3. Provide the required column values (in this example, DEPTNO: 144, DNAME: KEN and LOC: US) in Feeder window and click Send.
   
   
    
4. If the Insert query is successful, 'UpdateCount' appears as '1' in the Display window.
   
    

Reference

• Download REST POST Client and Server Example event processes and import it to the Event Process Repository in the Server Explorer in eStudio to understand the configuration used in this example and to execute the working sample.
• Please note that the component options used in this example are minimum, which helps you to get an overview of the application. To explore other options present in the RESTStub and RESTConsumer components, refer sections: RESTStub and RESTConsumer.