Virtual Exchange ServiceLab Guide

Virtual Exchange ServiceLab Guide
9/15/2013
This document isa step by step tutorial on how to use the Virtual Exchange Service Administrator (VESA)

Revision History

Change Record
Version Number / Description of Change / Change
Effective Date / Change
Entered By
1.0.00 / Initial Draft / September 16, 2013 / Dr.Yunhao Zhang

1

Virtual Exchange ServiceLab GuidePage 1 of 15

Table of Contents

1Introduction

2The Virtual Exchange Service Administrator (VESA)

3Create a Network Node

4Create a Dataflow

5Add a Data Source

6Data Publishing

6.1Create a Query Service

6.2Test Query Services

7Data Submission

7.1Create Submit Service

7.2Test Submit Services

8View Transactions

1Introduction

This document walks you through a series of steps of creating a Network Node, a dataflow, two services for data publishing and data submission. At the end of the session, you should have a fully functioning node that actively publishes information from a relational database and is able to accept any type of data submissions in to the node.

There are no prerequisites for the training session, except using a web browser. Background knowledge in the Exchange Network would be helpful.

2The Virtual Exchange Service Administrator (VESA)

VESA is a web application for administrators to manage, control and configure network nodes, node services and scheduled tasks. There are two VESA endpoints:

TEST:

PRODUCTION:

An administrator should login to the TEST VESA using their test NAAS ID and in to the PRODUCTIONVESA using production NAAS ID.

After login, the Node Dashboard will be displayed. The left panel contains two groups of tools (see screenshot below):

  • Action: The group contains node object management tools.
  • Utility: The group contains addition tools for security and other administrative functions.

3Create a Network Node

Click the “Create a Node” link on the left panel to bring you to the New Node creation page:

All information on the page is required except the Supervisor Phone. There is one crucial item, Node ID, which must be unique and there should be no white spaces in the identifier. (E.g. CaliforniaWaterboardNode)

When the “REQUEST NODE CREATION” button is clicked, a new node will be created, but it will be marked as “Pending” approval. An email will be sent to Virtual Exchange Service (VES) approvers for review / approval.

4Create a Dataflow

A dataflow is a logical collection of similar information exchanges(e.g. WQX,AirEmissions). According to the Node Functional Specifications, a service must belong to one and only one dataflow. So, a dataflow must be created before adding services.

Click on the “Dataflow” link in the left panel, the Dataflow list will be displayed as shown in the screenshot below.

The “Add New” link will lead to the Create Dataflow page:

The form is very basic and easy to fill out. The only important item is the Dataflow Name, which should be relatively short and should not containspaces .

Syndications is selected if you would like an RSS feed to be created for viewing the data that is submitted to the dataflow.

Click the Save button when done.

5Add a Data Source

A Data Source for defining a database connection for each database to plan on accessing via services on your network node. Inthe virtual exchange service, a data source is required in order to publish information such as web services. A data source may also be needed when accepting data submissions.

On the left panel, click on the Data Sources link and then select “Add New” on the page to create a new data source. The following screen shows a data source hosted on an SQL Server (vndata.cloudapp.net).

In order to try this datasource out for yourself on your virtual exchange service, be sure to enter the information exactly as it appears here in order to make a successful connection to the our sample database server.

  • Data Source Name: This should be a unique name without white spaces.
  • Database Type: select SQLServer.
  • Host Name: vndata.cloudapp.net (This is our hosted database server in Microsoft Azure Cloud).
  • Port: 56789
  • Database Name: Enter SampleData
  • User Name: cdx
  • Password: test

Please click the SAVE button to create the data source. An error will be displayed if verification of the database connection failed. The error message usually contains detailed reason for the failure.

6Data Publishing

6.1Create a Query Service

A query service is used for real time data publishing. There are three key elements in the data publishing process:

  1. Database Connection: It is necessary to establish network connectivity from the Virtual Exchange Service to a database server. This is accomplished through Data Sources.
  2. SQL Statement: An SQL statement is needed in order to retrieve and filter data from a database server.
  3. Data Mapping and Transformation: A process to map data fields to XML elements and perform necessary transformation. The Virtual Exchange Service supplies a default mapping using a generic Data Set schema or a user supplied schema, if required.

A service can be created by clicking the Services link on the left menu panel, and then select the Add New on the service list page. The service creation page will be displayed as shown below.

On this page, a Query service named GetCustomers is defined, which retrieves a list of customers based on the supplied partial customer ID. You should copy the SQL Statement:

SELECT * FROM Customer WHERE CustID LIKE ‘{$CustomerId}%’

to the SQL Statement box. There is nothing special about the SQL statement except that it has a parameter, {$CustomerId}, which will be replaced by the value supplied by a user of the service.

The service parameter, CustomerId, is created by entering the name and then clicking the Add button on the right side of the parameter line.

Click the Save button to store the service. VESA will now display a Service List with the new service in it.

6.2Test Query Services

As soon as the service is created, it is made available to consumers if it is configured as Enabled. You can test the service in the VESAvery easily by simply clicking on a service in the Service List page, the service detail page will be shown:

At the bottom of the page, click on the TEST button. The Service Test Tool will then be displayed:

On the test page, enter the CustomerId parameter and click the Submit button to run the service.

7Data Submission

7.1Create Submit Service

A Submit service is a service for accepting document submissions. The Virtual Exchange Service uses Windows Workflow Foundation as the business processing framework for all incoming flows.

Click on the Services link on the left panel and then the Add New button to create a new service as shown below:

The form is really simple:

  1. Enter a Service Name and a brief description.
  2. Select Submit as the method type.
  3. Choose GenericWorkflow as the Workflow.
  4. Click on the SAVE button to store the service.

7.2Test Submit Services

You can test a Submit service inside VESA to verify its operation. Click on the Services link on the left panel and then the service to be tested. The service detail page will display a TEST button on bottom of the page. A screen similar to the following should be displayed:

To run the service:

  1. Click on the Browse button, and choose any XML or ZIP document from your computer.
  2. Select a File Type that matches to the file.
  3. Click on the Submit button.

8View Transactions

VESA offers a transaction search utility for searching and viewing transaction activities.

All entries on the search page are optional except the Node. You can further limit the search scope by date, status and users. Transactions met the selected criteria will be displayed in the lower part of the page.

Note:

This LAB Guide is a work in progress. Please give me your feedback on how we could make it even easier to get up to speed on the basics of using a virtual exchange service.

Doc Ref # & Location10/17/2018