Download Lab Guide v1.0 - The Exchange Network

Virtual Exchange Service
Lab Guide
9/15/2013
This document is a step by step tutorial on how to use the Virtual Exchange Service Administrator (VESA)
Virtual Exchange Service Lab Guide
Revision History
Change Record
Version
Number
1.0.00
Description of Change
Initial Draft
ii
Change
Effective Date
Change
Entered By
September 16,
2013
Dr. Yunhao
Zhang
Virtual Exchange Service Lab Guide
Page 3 of 15
Table of Contents
1
Introduction .................................................................................................. 4
2
The Virtual Exchange Service Administrator (VESA) ............................... 4
3
Create a Network Node................................................................................ 5
4
Create a Dataflow ......................................................................................... 6
5
Add a Data Source ....................................................................................... 7
6
Data Publishing ............................................................................................ 8
6.1
Create a Query Service ........................................................................ 8
6.2
Test Query Services ........................................................................... 10
7
Data Submission ........................................................................................ 12
7.1
Create Submit Service........................................................................ 12
7.2
Test Submit Services ......................................................................... 13
8
View Transactions ..................................................................................... 14
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 4 of 15
1 Introduction
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.
2 The 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:
https://vnaptest.epacdxnode.net
https://vnap.cloudapp.net
An administrator should login to the TEST VESA using their test NAAS ID and in
to the PRODUCTION VESA 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.
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 5 of 15
3 Create a Network Node
Click the “Create a Node” link on the left panel to bring you to the New Node
creation page:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 6 of 15
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.
4 Create a Dataflow
A dataflow is a logical collection of similar information exchange s(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:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 7 of 15
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 contain spaces .
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.
5 Add a Data Source
A Data Source for defining a database connection for each database to plan on
accessing via services on your network node. In the 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).
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 8 of 15
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.
6 Data Publishing
6.1
Create a Query Service
A query service is used for real time data publishing. There are three key
elements in the data publishing process:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 9 of 15
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.
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 10 of 15
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.2
Test 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 VESA very easily by
simply clicking on a service in the Service List page, the service detail page will
be shown:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 11 of 15
At the bottom of the page, click on the TEST button. The Service Test Tool will
then be displayed:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 12 of 15
On the test page, enter the CustomerId parameter and click the Submit button to
run the service.
7 Data Submission
7.1
Create 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:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 13 of 15
The form is really simple:
1.
2.
3.
4.
7.2
Enter a Service Name and a brief description.
Select Submit as the method type.
Choose GenericWorkflow as the Workflow.
Click on the SAVE button to store the service.
Test 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:
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 14 of 15
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.
8 View Transactions
VESA offers a transaction search utility for searching and viewing transaction
activities.
Doc Ref # & Location
5/15/2017
Virtual Exchange Service Lab Guide
Page 15 of 15
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 # & Location
5/15/2017