Tutorial Part 3: Create Application

This step walks through the creation of an OpenDXL application that exposes a single DXL service to the DXL fabric. The DXL service will allow for DXL clients to query Geolocation information for IP addresses and host names.

NOTE: The MessageUtils class which is included in the OpenDXL Bootstrap library is used throughout the code presented in this portion of the tutorial. MessageUtils provides several convenience methods for setting and retrieving the payload on DXL messages (Python dictionary to JSON payload, etc.).

For complete details of the MessageUtils class please refer to the Message Utilities Class Documentation.

Create Workspace Directory

The first step is to create a directory that will be used as a workspace throughout the rest of this tutorial.

mkdir opendxl-geolocation

Change to the newly created directory:

cd opendxl-geolocation

Generate Application

In this step the application will be generated by using the OpenDXL Bootstrap application template (application-template).

The Bootstrap application requires a configuration file that defines the properties of the application that is going to be generated. The properties for the application generated in this tutorial are shown below.

[Application]
name=geolocationservice
fullName=Geolocation Service
appClassName=GeolocationService
copyright=Copyright 2018
services=geolocation_service
installRequires=requests

[geolocation_service]
serviceType=/mycompany/service/geolocation
requestHandlers=geolocation_service_hostlookup

[geolocation_service_hostlookup]
topic=/mycompany/service/geolocation/host_lookup
className=GeolocationHostLookupRequestCallback

For complete details about the application-template configuration file and its related properties refer to this page.

In this particular case, a single DXL service (geolocation_service) is defined with a single request handler (geolocation_service_hostlookup). The topic associated with the request handler is defined as /mycompany/service/geolocation/host_lookup. The callback class, GeolocationHostLookupRequestCallback will be invoked each time an incoming DXL request is received by the service on the host lookup topic.

It is also worth noting that the installRequires property has been defined to have a value of requests. This indicates that this application has a dependency on the Requests Python library (as part of the generation process this dependency will be listed in setup.py). The Requests library is used to make calls to the Geolocation web service (via HTTP).

Create application template configuration file

Create a file in the opendxl-geolocation directory named application-template.config. Paste the contents of the configuration listed above into this file and save it.

At this point the contents of the opendxl-geolocation directory should appear as follows:

opendxl-geolocation\
    application-template.config

Run Bootstrap

At this point the OpenDXL Bootstrap application will be executed resulting in the Geolocation application being created.

To generate the application, execute the following command from the opendxl-geolocation directory.

python -m dxlbootstrap application-template application-template.config app

The command above creates a project using the application-template with the properties in the configuration file created previously (application-template.config). The output of the generation is placed in the app output directory. For complete details about the Bootstrap application command line and its related arguments refer to this page.

If the generation is successful, the message Generation succeeded will be displayed. The contents of the opendxl-geolocation directory should now appear as follows:

opendxl-geolocation\
    app\
    application-template.config

Modify Application

In this step the Geolocation functionality will be integrated into the generated application.

Change to the application directory

At this point change to the generated application directory:

cd app

The contents of the application directory should appear as follows:

opendxl-geolocation\
    app\
        config\
        dist.py
        doc\
        Dockerfile
        geolocationservice\
        LICENSE
        MANIFEST.in
        README
        README.md
        sample\
        setup.py

The geolocationservice directory contains the Python code for the generated application.

Modify Request Handler callback

In this step the request handler callback (GeolocationHostLookupRequestCallback) will be modified to delegate requests to the Geolocation web service.

Edit request handlers Python file

Open the requesthandler.py file within the geolocationservice directory for editing. This file contains all of the request handlers that were generated for the application. In this particular case there is only one request handler (GeolocationHostLookupRequestCallback).

Import requests library

Add an import of the requests library to the top of the request handlers file as shown below:

import logging
# Requests library
import requests

from dxlclient.callbacks import RequestCallback
...

Invoke Geolocation web service

Change the following code in the on_request handler method from:

# Set payload
MessageUtils.encode_payload(res, "geolocation_service_hostlookup response payload")

To the following:

# Read DXL request payload into dictionary
request_dict = MessageUtils.json_payload_to_dict(request)

# Invoke Geolocation web service
http_res = requests.get("http://geoloc.opendxl.io/{0}/{1}".format(
    request_dict["format"], request_dict["host"]))

# Add web service response to DXL response payload
MessageUtils.encode_payload(res, http_res.content)

The changes above achieve the following:

• The payload of the DXL request (which is expected to be in JSON format) is parsed and converted to a Python dictionary (dict).

• The web service hosted at geoloc.opendxl.io is invoked with two parameters that are retrieved from the Python dictionary (from the request).

  The parameters are as follows:

  • host : A host name or IP address for which to retrieve Geolocation information.
  • format : A format for the response. Supported values are: json, csv, and xml.

• Place the response from the web service into the DXL response message's payload.

Run Application

In this step, the Geolocation application will be started. Once started, the application will run forever, waiting for incoming Geolocation lookup requests via the DXL fabric.

Populate DXL client configuration file

Prior to running the application, the dxlclient.config file located in the config directory of the application must be modified to include the information necessary to connect to the DXL fabric.

The steps to populate this configuration file are the same as those documented in the OpenDXL Python SDK, see the OpenDXL Python SDK Samples Configuration page for more information.

Install Requests library

Since the application requires the Requests library, it must be installed. Run the following command to ensure the Requests library is available.

pip install requests

Start application

To start the application, execute the following command from within the application directory (opendxl-geolocation\app):

python -m geolocationservice config

The output should appear similar to the following:

Running application ...
On 'run' callback.
On 'load configuration' callback.
Incoming message configuration: queueSize=1000, threadCount=10
Message callback configuration: queueSize=1000, threadCount=10
Attempting to connect to DXL fabric ...
Connected to DXL fabric.
Registering service: geolocation_service
Registering request callback: geolocation_service_hostlookup
On 'DXL connect' callback.

Modify Sample

In this step the Geolocation functionality will be integrated into the basic sample that is included with the generated application.

Edit Basic Sample file

Open the basic_sample.py file within the sample\basic directory for editing.

Change the following code in the sample from:

MessageUtils.encode_payload(req, "geolocation_service_hostlookup request payload")

To the following:

# Create dictionary with host to lookup and response format 
req_dict = {"format": "json", "host": "mcafee.com"}

# Convert dictionary to JSON and set as DXL request payload
MessageUtils.dict_to_json_payload(req, req_dict)

The changes above achieve the following:

• A Python dictionary (dict) is created that contains the information to include in the DXL request message.

  The parameters are as follows:

  • host : The host name to retrieve Geolocation information for (mcafee.com)
  • format : The format for the response (json)

• The dictionary is converted to JSON and placed in the DXL request message's payload.

Run Sample

In this step, the Geolocation application basic sample will be executed.

Ensure the application that exposes the Geolocation service is still running (see "Run Application", above).

A new command prompt/shell will need to be opened for executing the sample.

Populate DXL client configuration file for samples

Prior to running the sample, the dxlclient.config file located in the sample directory of the application must be modified to include the information necessary to connect to the DXL fabric.

The steps to populate this configuration file are the same as those documented in the OpenDXL Python SDK, see the OpenDXL Python SDK Samples Configuration page for more information.

Run basic sample

To run the basic sample, execute the following command from within the application directory (opendxl-geolocation\app):

python sample\basic\basic_sample.py

The output should appear similar to the following:

Response for geolocation_service_hostlookup: '{"ip":"161.69.29.243","country_code":"US","country_name":"United States",
"region_code":"CA","region_name":"California","city":"Santa Clara","zip_code":"95054","time_zone":"America/Los_Angeles",
"latitude":37.3961,"longitude":-121.9617,"metro_code":807}'

As shown above, the response is received in JSON format and includes the Geolocation information for mcafee.com.

Continue to next step, Creating the client wrapper