Objective

To create a Rest Service that receives images, store it into a predefined location and then return the file location in JSON format.

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

Scenario

1. Configure RESTStub component to receive binary data from RESTConsumer and forward the data to FileWriter component to be uploaded to a predefined location. Provide Content Type as "application/octet-stream" for RESTStub.
2. Configure RESTConsumer component to send the binary data (received from FileReader) to RESTStub and receive the uploaded file path as JSON message. For response message, provide Content Type as "apllication/json"

How it Works

The Event Process, as per scenario, works in the following manner:

1. Binary file is read by FileReader and content is forwarded to RESTConsumer
2. RESTConsumer sends the binary content to RESTStub and then to FileWriter
3. FileWriter uploads the binary content to the predefined location
4. RESTConsumer receives the JSON output message with file path of uploaded file

Components used

• FileReader
• FileWriter
• RESTStub
• RESTConsumer

Setting up the Example

Configuring RESTStub component

This component is used to expose an Event Process or a part of Event Process as a RESTful web service deployed in the Peer Server. To configure RESTStub component, perform the following actions:

1. Add a new Event Process with name 'REST_Service_Example'.
2. Drag the RESTStub component from Web category in the Micro Service Palette to the Fiorano Orchestrator.
   
   
   Figure 1: Adding RESTStub component to REST_Service_Example orchestrator
    
3. Double-click the RESTStub component to open Configuration Property Sheet (CPS).
4. In the Configuration dialog box, perform the following actions:
   
   1. Add Service Name: 'restdemo', right-click resource under Resources and click Remove Resource to remove default resource.
      
      
      Figure 2: Removing default resource from RESTStub
       
   2. Under Create/Edit WADL section, Right-click Resources and click Add Resource to add new resource.
      
      
      Figure 3: Adding new resource
       
   3. Type 'upload' in ID and path fields that appear under Resources Configuration tab. New resource with name 'upload' gets added under Resources.
      
      
      Figure 4: Providing resource name 'upload'
       
   4. Right-click upload, point to Add Method and click POST.
      
      
      Figure 5: Adding Method 'POST'
       
   5. Click POST option that appears under upload resource and click Add icon under Representations section present in the Request Configuration tab.
   6. Under Representation tab, select 'application/octet-stream' from the Media Type drop-down.
      
      
      Figure 6: Adding Representation with Media Type as application/octet-stream
       
   7. Right-click POST node, select Add Response and select 'application/json' from Media Type drop-down
      
      
      Figure 7: Adding Representation for RESPONSE - 'application/json'
       
5. Click Next twice to skip security-related configuration (SSl Configuration) and Connection Configuration, and click Finish to save RESTStub configuration.

Configuring FileWriter component

The FileWriter component writes the received data from its input port to the specified output file. To configure RESTStub component, perform the following actions in REST_Service_Example event process:

1. Add the FileWriter component from File category in the Micro Service Palette to the Fiorano Orchestrator.
   
   
   Figure 8: Adding FileWriter component in REST_Service_Example event process
    
2. Double-click the FileWriter component to open Configuration Property Sheet (CPS).
3. In the Interaction Configuration dialog box, click the Attributes tab to configure the attributes.
4. Select the Is input Binary ? checkbox to write the data as bytes and click the FileWriter Configuration Ellipsis button.
   
   
   Figure 9: Selecting Binary Input
    
5. In the FileWriterConfig dialog box, provide the following values and click OK:
   1. File Name: The name of the file to which the input data has to be written. If the file with this name does not exist, a new file is created
   2. Target Directory: Provide the location to save the file.
   3. Working Directory: Location to save the file during intermediate processing.
   4. Error Directory: Location to save the file in case the processing does not get successful.
      
      
      Figure 10: Providing File Name and storage locations
       
6. Click Next, clear the Enable Scheduling option and click Finish to save the FileWriter configuration.

Connecting FileWriter and RESTStub

In the REST_Service_Example event process, perform the following actions:

1. Connect the FileWriter with RESTStub in the following manner:
   1. RESTStub output port to FileWriter input port.
   2. FileWriter output port to RESTStub input port.
      
      
      Figure 11: Connecting RESTStub with FileWriter
       
2. Replace the names of 'route1' and 'route2' with 'UploadRequest' and 'UploadResponse' respectively to match the scenario. After clicking on the respective route, do any of the following to change the name:
   
   1. Press F2, change the name and click OK.
      
      
      Figure 12: Renaming using Keyboard action 'F2'
       
   2. Go to Name property under General tab in Properties, change the name and press ENTER
      
      
      Figure 13: Renaming using General Properties
       
3. The routes show up with the changed names
   
   
   Figure 14: Connection with route names changed 

Configuring Transformation between FileWriter and RESTStub

To manage Route Transformation between FileWriter output port and RESTStub input port, perform the following actions in the REST_Service_Example event process:

1. Right-click UploadResponse, point to Configure Transformation and select Mapper Project to open Fiorano Mapper editor.
   
   
   Figure 15: Navigating to Mapper Project for Route Transformation
    
2. In the Output Structures panel, click Status under Response. 'Status' appears in Funclet View panel.
   
   
   Figure 16: Working on Funclet View
    
3. In the Funclet View panel, drag the function element Constant to the Funclet easel. Double-click it, edit the name as '200' and click OK.
   
   
   Figure 17: Adding Constant from String Functions
    
4. Connect the source node of the constant '200' to the destination node of Status.
   
   
   Figure 18: Connecting Constant with new name '200' to the Status element
    
5. Similarly, connect source node of the constant 'application/json' to the destination node of MediaType (select from Representation under Output Structures panel).
   
   
   Figure 19: application/json constant connected to Media Type element
   
   
6. Add the following elements to the Funclet easel in the following manner:
   1. Click ANY present under Element in Output Structures panel
   2. Drag FullName present under FileInfo in Input Structures panel.
   3. Add two Constant functions from String Functions and change their name as below:
      
      • { "FilePath" : "
      • " }
   4. Add Concat from String Functions.
      
      
      Figure 20: Adding Constant functions, FullName from FileInfo, Concat and ANY
       
7. Connect the elements added in Step#6 in the following order:
   1. Source node of { "FilePath" : " to the destination node '1' of Concat.
   2. Source node of FullName to the destination node '2' of Concat. Destination node '3' appears after this conncetion.
   3. Source node of " } to the destination node '3' of Concat.
   4. Source node of Concat to the destination node of ANY.
   Adding the elements in the above order helps to generate Display output in the following format:
   { "FilePath" : "<TARGET_FILE_PATH>" }:
   
   
   Figure 21: Functions and elements connected to generate Display output
    
8. Click Save icon (or File ??Save) to save the transformation configuration and close the Mapper Project editor.

Launching the Event Process

To launch the event process, perform the following actions:

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.
   
   
   Figure 22: Running REST_Service_Example event process 

Configuring RESTConsumer component

This component is used to expose an Event Process or a part of Event Process as a RESTful web service deployed in the Peer Server. To configure RESTConsumer component, perform the following actions:

1. Add a new Event Process with name 'REST_Client_Example'.
2. Add the RESTConsumer component from Web category in the Micro Service Palette to the Fiorano Orchestrator.
   
   
   Figure 23: Adding RESTConsumer component to REST_Client_example orchestrator
    
3. Switch to REST_Server_Example event process, right-click RESTStub component which is running, and click Copy WADL URL to copy the WADL URL.
   
   
   Figure 24: Copying WADL URL
    
4. Switch back to REST_Client_Example event process and double-click RESTConsumer component to open the CPS.
5. In the Configuration dialog box, perform the following actions:
   1. Select the Load WADL checkbox
   2. Select the From URL option.
   3. Paste the copied WADL URL copied in Step#2.
   4. Click the Load WADL button.
   
   Figure 25: Pasting and loading WADL URL
    
6. In the Configuration tab under Create/Edit WADL section, values as configured in RESTStub component gets populated.
   
   
   Figure 26: Resources populated after configuration
    
7. Click Next twice to skip SSL and Connection configurations as done in RESTStub component, and click Finish to save RESTConsumer configuration.

Configuring FileReader component

The FileReader component reads files from the file system and sends their contents to the output port. To configure FileReader, perform the following actions in REST_Client_example event process:

1. Add the FileReader component from File category in the Micro Service Palette to the Fiorano Orchestrator.
   
   
   Figure 27: Adding FileReader component to REST_Client_Example event process
    
2. Double-click the FileReader component to open Configuration Property Sheet (CPS).
3. In the Interaction Configuration dialog box, select the 'Is input Binary ?' checkbox to write the data as bytes and click the FileReader Configuration Ellipsis button.
   
   
   Figure 28: Selecting Binary File
    
4. In the FileReaderConfig dialog box, provide the following values and click OK:
   1. File Name: The name of the file to be read. A pattern of file names can also be provided using wildcard character * (asterisk symbol).
      Example: *.* includes all the files and *.jpg includes the files with .jpg extension.

   2. Source Directory: The directory which holds the file(s) to be read. All the files in this directory whose names match the pattern specified for the File name property will be processed.

      Icon

      Working Directory and Error Directory are optional. Select the Use Working Directory check box to use working directory.

      
      

   3. Figure 29: Providing File Name and storage location
       

5. Click Next and clear Enable Scheduling check box to allow Feeder component to provide input.
   
   
   Figure 30: Disabling Scheduler Configurations
    
6. Click Finish to save the FileReader configuration.

Connecting FileReader and RESTConsumer

In the REST_Client_Example event process, perform the following actions:

1. Connect the FileReader output port to RESTConsumer input port.
2. Rename the ruote as 'PushFile'.
   
   
   Figure 31: FileReader and RESTConsumer connected and route name changed 

Configuring Transformation between FileReader and RESTConsumer

To manage Route Transformation between FileReader output port and RESTConsumer input port, perform the following actions in REST_Client_Example event process:

1. Right-click PushFile, point to Configure Transformation and select Mapper Project to open Fiorano Mapper editor.
   
   
2. In Output Structures panel, right-click upload and click User XSL to edit User XSL.
   
   
   Figure 33: Adding User XSL to 'upload' resource
    
3. In the User XSL for upload dialog box, insert the text "upload" within a tag, and then click OK. The text is being added for the component to identify the resource being invoked.
   
   
   Figure 34: Adding XSL for 'upload' element
    
4. In Output Structures panel, right-click Request and click User XSL to edit User XSL.
   
   
   Figure 35: Adding User XSL to 'Request' resource
   
   
5. Comment the Resource parameters as shown in the image below.
   
   
   Figure 36: Commenting the Resource parameters
   
   
6. Click Save icon (or File ??Save) to save the transformation configuration and close the Mapper Project editor.

Compose the Event Process

Add more components and compose the REST_Client_Example event process as mentioned below:

1. Add Feeder and Display components from Micro Service Palette under Util category to Fiorano Orchestrator.
2. Connect the components in the following manner:
   1. Feeder output port to FileReader input port. Rename the route to 'ScanFiles'
   2. RESTConsumer output port to Display input port. Rename the route to 'ExtractJSON'.
      
      
   
   Figure 37: Connecting Feeder and Display to FileReader and RESTConsumer respectively

Configuring Transformation between RESTConsumer and Display

To get the output in JSON format, Route Transformation between FileWriter output port and RESTStub input port is required.

To configure transformation, perform the following actions in REST_Client_Example event process:

 

1. Right-click ExtractJSON route, point to Configure Transformation and select Mapper Project to open Fiorano Mapper editor.
2. In the Mapper Project, perform the following actions in Output Structures panel:
   
   1. Click the Add icon on the upper-right part of the page and select XML option.
   2. In the Load Output XML Structure dialog box, add the following text in XML Content editor:<output>output</output>
   3. Click DTD icon to generate DTD element. The message appears in Generated DTD section. Click Finish.
   
   Figure 38: Configuring to generate JSON message
    
3. Connect ANY element present in Input Structures panel to output element that appears in Output Structures panel.
   
   
   Figure 39: Connecting ANY element to output
    
4. In the Menu, go to Tools and select XSLT Properties. In XSLT Properties dialog box, select 'text' from Output Method drop-down.
   
   
   Figure 40: Configuring XSLT Properties 
5. Click Save icon (or File >Save) to save the transformation configuration and close the Mapper Project editor

Running the Example

To run the REST_Attachments example, perform the following actions:

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. Two components: Feeder and Display appear.
3. In the Feeder component, click the Send button.
   
   
   Figure 41: Sending message from Feeder
    
4. Confirmation message appears in the following format in Display1: { "FilePath" : "<TARGET_FILE_PATH>" }
   
   
   Figure 42: Receiving message in Display

Reference

• Download the event processes  REST_Service_Example and REST_Client_Example 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 the other options present in the RESTStub, RESTConsumer, FileReader, and FileWriter components, refer RESTStub, RESTConsumer, FileReader and FileWriter sections.