PopMedNet
Model Plugin Design
Revision 0.3
February 9, 2016
275 Grove Street
Newton, MA 02466
v: 617 848 1502
f: 928 569 6504
1
Table of Contents
Introduction .......................................................................................................................................... 5
1.1
Executive Summary ....................................................................................................................... 5
1.2
PMN Architecture ......................................................................................................................... 5
1.2.1
PMN Portal Web Site ............................................................................................................ 5
1.2.2
PMN DataMarts .................................................................................................................... 6
1.2.3
PMN Deployment .................................................................................................................. 6
1.3
PMN Network Topology ................................................................................................................ 7
1.4
Request/Response Tunnel Abstraction......................................................................................... 8
1.5
Model Abstraction ........................................................................................................................ 9
1.6
PM Software Technology Platform ............................................................................................. 10
2
Plugin Requirements ........................................................................................................................... 10
3
Model Plugin Use Case Scenarios ....................................................................................................... 11
3.1
3.1.1
Developing A Plugin ............................................................................................................ 11
3.1.2
Registering Model Plugin .................................................................................................... 12
3.1.3
Creating a Request .............................................................................................................. 12
3.1.4
Processing a Request .......................................................................................................... 13
3.1.5
Viewing a Response ............................................................................................................ 13
3.1.6
Aggregating a Response ...................................................................................................... 14
3.2
User Experience using Plugins .................................................................................................... 14
3.2.1
Creating a Request .............................................................................................................. 14
3.2.2
Retrieving a Response ......................................................................................................... 14
3.3
4
Plugin Perspective ....................................................................................................................... 11
PMN perspective ......................................................................................................................... 15
3.3.1
Registering a new Plugin with PMN .................................................................................... 15
3.3.2
Creating a request ............................................................................................................... 15
3.3.3
Retrieving a response.......................................................................................................... 15
Module Plugin Design ......................................................................................................................... 16
4.1
Overview ..................................................................................................................................... 16
4.2
Model Registration ..................................................................................................................... 17
4.2.1
2/9/2016
Sample Registration File...................................................................................................... 17
Company Confidential
Page 2 | 30
4.2.2
4.3
Plugin Web Service...................................................................................................................... 18
4.3.1
Overview ............................................................................................................................. 18
4.3.2
Plugin Web Service API ....................................................................................................... 18
4.4
5
Model Registration File Elements ....................................................................................... 17
Model Request Processor ........................................................................................................... 24
4.4.1
Overview ............................................................................................................................. 24
4.4.2
Model Processor Interface .................................................................................................. 24
4.4.3
Model Processor Settings ................................................................................................... 30
Open Items .......................................................................................................................................... 30
2/9/2016
Company Confidential
Page 3 | 30
Document History
The following table is a revision history for this document.
Revision
0.1
0.2
0.3
Author(s)
Bruce Swan
Fyodor Soikin
Daniel Dee
Bruce Swan
Date
12/21/2011
12/22/2011
Description
Created
Revised
1/11/2012
Revised with latest interfaces
Table 1 – Document Revision History
2/9/2016
Company Confidential
Page 4 | 30
1
Introduction
1.1 Executive Summary
The Office of the National Coordinator for Health Information Technology (ONC) through the Standards
and Interoperability (S&I) Framework is developing Use Cases that define the interoperability
requirements for high priority health care data exchange to maximize efficiency, encourage rapid
learning and protect patients’ privacy in an interoperable environment. The Query Health Initiative and
the subsequent Query Health Use Cases have been selected for inclusion within the S&I Framework to
illustrate distributed health data querying approaches. The PopMedNet™ (PMN) software platform and
architecture has been selected as one of the proposed frameworks for the Use Case model for the ONC
Query Health Initiative pilot.
One of the design goals in using the PMN framework is to integrate complementary query engines and
their user interfaces to achieve optimal solutions when applied to a specific problem domain, such as a
health surveillance program or research study. This document presents a design to allow third party
applications to be “plugged into” a PMN network that governs workflow processes, governance
policies, and data. A high level presentation of the PMN architecture is presented followed by a
technical description of the interfaces required to support PMN plugins.
1.2 PMN Architecture
PMN is a distributed network application comprised of two sub-applications, the Portal and the
DataMart.
1.2.1
PMN Portal Web Site
The Portal is a secure website responsible for the creation and management of the network and its
endpoints, called DataMarts, as well all requests that travel over the network, security, and governance
policies. The DataMarts are remote endpoints who process requests through a desktop DataMart client
application.
PMN users are assigned roles that grant them rights to features and functions within the application.
There are a set of built-in roles, such as System Administrator, Investigator, DataMart Administrator,
Observer, Query Administrator, etc. The Portal handles user settings (e.g., passwords, email notification
settings), the creation and distribution of requests to data partners and corresponding responses.
Additionally, the Portal enables creation and management of DataMarts, and enforces permission
settings (i.e., who can submit queries and what they can submit), notification settings, and audit
reporting.
The Portal manages the lifecycle of a query through a set of workflow processes that are configured by
administrators so as to be specific to the institution. Key events within the application create
notifications that are sent to the user. Users control the sensitivity and frequency of the notifications.
2/9/2016
Company Confidential
Page 5 | 30
The portal is built using the Microsoft ASP.Net platform along with components arranged in a serviceoriented architecture (SOA). Communications with DataMarts are over secure web services using SOAP.
The portal database uses SQL Server (2008).
1.2.2
PMN DataMarts
Data partners operate DataMarts responsible for processing requests. Note that DataMarts process
requests, and that a query is one type of request. Examples of other types of requests include files
(which may contain instructions or requests) and programs (for example a SAS program). Data partners
install the DataMart Client application used to retrieve requests, process them, and upload responses.
The DataMart Client application allows the DataMart Administrator to view requests distributed to the
DataMart, execute requests, and review and upload the results to the portal. The DataMart Client is a
.NET/C# Windows desktop application that is installed locally on an Administrator’s desktop. All
communications between the DataMart Client application and the Portal use HTTP/SSL connections to
securely transfer queries and results between the application and the Portal. The application uses ODBC
connections to the local DataMart databases used to process queries and generate results.
1.2.3
PMN Deployment
To deploy a PMN network, a branded instance of the portal is installed at a web server visible to both
users of the network and DataMarts participating in the network. Once installed, a System
Administrator configures the network to support one or more Groups of member Organizations that
have one or more users who participate in network activities.
Part of the network configuration is establishing DataMarts that participate in the network. DataMarts
are supported by Data Partners who provide the underlying data used to process requests as well as
operators who administer them. There is exactly one Portal in the network and each network data
partner can have one or more DataMarts connected to the network.
To participate in a network, data partners must:




Install and configure the DataMart client on one or more local computers or servers.
Assign one or more staff members as the DataMart Administrator(s) responsible for interacting with
the system (via the DataMart Client and the Portal) on behalf of the data partner.
Create data in a format required for the queries and make it available for incoming requests.
Set DataMart preferences to establish settings, such as what data can be queried and who can
submit queries to the DataMart.
Once the network is configured, Investigators may begin constructing queries that are submitted and
routed to appropriate DataMarts who process the query and return a response.
2/9/2016
Company Confidential
Page 6 | 30
1.3 PMN Network Topology
The figure below represents a high level illustration of the PMN network topology.
Figure 1 – PMN Network Topology
2/9/2016
Company Confidential
Page 7 | 30
1.4 Request/Response Tunnel Abstraction
The current implementation of the PMN architecture defines and implements each request that travels
over the network and has knowledge of the internal request / response formats as well as code required
to process the request. Additionally, the requests must be developed as part of the PMN solution. As a
result, introducing new requests requires knowledge and modification of the core code within the
platform as well as the ability to “build” the solution. This constrains the ability to extend the PMN
network to introduce new request types, data sources, and processing required to support the requests,
particularly developing new requests outside the PMN core solution using technology that varies from
PMN (.NET).
To improve PMN’s scalability and extensibility, PMN is undergoing an upgrade that abstracts the request
implementation from the network platform into something called a “Model Plugin” (see Model
Abstraction section below) to allow a more extensible and scalable architecture that separates the
concerns of the network from the details of the requests that travel through it. The result is a network
that forms a tunnel through which requests and responses travel. The PMN workflow processes will be
modified to manage the steps a request and response take without knowledge of the internal request
and response protocols and formats. Where needed, the PMN workflow processes will “call out” to
extension components registered with the network to perform functions against the request along the
request/response pipeline.
The following figure illustrates the architecture of the Request / Response Tunnel:
Figure 2 – PMN Request / Response Tunnel
The requests and responses expose interfaces that allow the network components to manage them as
abstract objects. Each Request and Response contains a common header that is defined by the network
containing identification and routing information. One or more binary documents provided by the
model plugin are associated with the request and response. These documents are created and operated
on by the model plugin component code. Instances where the request or response details need to be
displayed or presented to the user are provided in by the plugin in one of the associated documents.
2/9/2016
Company Confidential
Page 8 | 30
Note that the request tunnel illustration above shows model plugin web server component as a loosely
coupled component that may reside on a server other than the Portal, potentially outside the PMN
hosting network. In fact there will be several plugin frameworks developed:


A loosely coupled plugin that exists as Web pages outside the browser PMN Web server that
provides an easy technology agnostic approach to integrating existing functionality and implements
requests at the expense of a less than optimal user experience, and
A tightly coupled plugin implemented as a .NET MVC component that exists on the PMN web server
host that renders partial views into content area of PMN pages providing a seamless user
experience.
Note this approach allows ONC Query Health Partners to quickly integrate existing technology into PMN
while the tightly coupled plugin architecture is being developed. PMN native models will use the tightly
coupled MVC approach to implement new models. For the remainder of this document, only the loosely
coupled plugin approach is assumed and discussed.
1.5 Model Abstraction
As mentioned in the previous section, the concept of requests, responses, data schemas, metadata, and
the processes required to construct and process a request are being factored into a component called a
“Model” that may be “plugged into” the PMN network.
PMN defines a Model to be the requests, responses, and related structures and processes that form a
particular Request / Response Tunnel. Models always come as a Request Tool / Tunnel Format / Data
Source triplet. For example a Model that binds the i2B2 request tool to EHR data, and moves that data
back and forth along the Request Response Tunnel in HQMF / QRDA format is called an i2b2 / HQMF /
EHR Model. At a more detailed level, models have the following traits:







Domain specific – targeted at a particular area of study, such as a healthcare research study or a
surveillance program.
Collection of Requests – a model contains one or more requests.
Request / Response pattern – each Request generates a Response, however both the Request and
Response may include zero, one, or more documents.
Request / Response visual tools – contains tools to present user views requests and their responses.
Data Model – Each model may define a Data Model required to process requests within the model.
Metadata – Zero or one of the requests may be designated as a “Metadata Request” used to
generate a response containing information about the data available at a given DataMart. This is
used to filter DataMarts in/out of a new Request submittal.
Relationship to network / platform – There may be one or more Models in a single network
instance, and a DataMart may support one or more Models.
2/9/2016
Company Confidential
Page 9 | 30
1.6 PMN Software Technology Platform
The following figure presents the PMN technology platform.
OS/Application/Component
Portal Operating System
DataMart Client Application Operating
System
Website Manager
DataMart Web Services
Portal Database Engine
Plugin Web Services
DataMart Model Processor Framework
Description
Windows Server 2008 R2
XP, Vista, Windows 7
IIS 7
WCF (REST or SOAP)
MS SQL Server 2008 R2
WCF (REST or SOAP)
Microsoft .NET 4
Figure 3 – PMN Technology Platform
2
Plugin Requirements
This PMN Model Plugin Design document presents a design to extend PopMedNet through a set of
interfaces that allow third parties to develop a Model as a plugin that may be introduced and processed
through the PMN request pipeline architecture. A PMN Model consists of the following components:




One or more Request Types that may present a web based user interface to allow the user to
construct requests to be submitted to DataMarts supporting the Model.
A Data Schema required to process the Request Types.
One of the Requests Types may be designated as a “metadata” request used to obtain information
on the model data available at participating DataMarts.
A set of document types that may be pass along with the Request and Responses that contain both
the serialized requests and content that may be viewed by users who interact with the request and
its response along the PMN request workflow process.
The following are the design goals and requirements for PMN Model Plugins:





Allow models to be developed outside the PMN solution, including the current set of PMN native
request types.
Allow models to be registered and used by the PMN network without requiring changes to the code
base of PMN core platform.
The PMN core network must support multiple Models.
The PMN DataMarts may support one or more Models.
Allow requests and responses to be serialized into any format while being passed through the PMN
pipeline.
2/9/2016
Company Confidential
Page 10 | 30




3
PMN Request/Response workflows and features should work as well with plugins as it does with its
native model implementations.
Allow Model Plugins to filter DataMarts by model metadata.
Allow Model Plugins to aggregate responses from one or more DataMarts per requests as
determined by the permissions and workflows established in the network.
Where possible provide a technology agnostic approach to developing model plugins that allows
existing applications developed in varying technologies to be factored into a PMN plugin.
Model Plugin Use Case Scenarios
The following sections present a set of use cases on how model plugins work from the user’s perspective
as well the PMN Network perspective and plugin itself.
3.1 Plugin Perspective
This use case presents the process required to develop and deploy a plugin within the PMN network.
3.1.1
Developing A Plugin
A plugin consists of two components, a set of web pages that allow the user to build a request, and a
.NET component dynamically invoked by the DataMart client that processes requests once they arrive at
the DataMart.
3.1.1.1 Develop Website Components
1.
2.
3.
4.
5.
6.
Compose web pages that encapsulate the query building process.
Add logic to decrypt PMN authentication tokens.
Subscribe and implement PMN plugin web service API.
Optionally add logic to filter DataMarts based on metadata.
Optionally add logic to aggregate DataMart responses.
Format plugin registration XML.
3.1.1.2 Develop DataMart Component
1. Create a .NET project that produces a DLL using .NET 4.
2. Implement the IModelProcessor (see section 4.4 Model Request Processor) interface used to
process requests and return responses.
3. Optionally create a response document that be used to display the response to the user (DataMart
Administrators, Investigators, Group Administrators, etc.).
4. Create a deployment project to install the model processor at DataMarts.
2/9/2016
Company Confidential
Page 11 | 30
3.1.2 Registering Model Plugin
Models are introduced into PMN through a registration file that is uploaded to PMN through an
administrative function on the PMN portal.
3.1.2.1 Register Web Server Plugin
Create a plugin registration XML file containing the following items (see section 4.2 Model Registration).
1. A set of Request Types, each entry contains the following items:
A. User-friendly request type name displayed in PMN menus and controls.
B. Identifier that is unique within the model.
C. “Create Request” URL that contains a substitution parameter to be inserted for the PMN
Request Token.
D. “Retrieve Response” URL that contains a substitution parameter to be inserted for the PMN
Response Token.
E. Public key of your asymmetric cryptographic public/private key pair (the private key remains at
the plugin’s site).
F. Optionally designate one of the request types as a metadata request used to filter DataMarts.
2. Model metadata containing the following items:
A. Model name.
B. Identifier formatted as a GUID.
C. Description that is displayed in PMN UI controls.
Copy Plugin Registration file containing the following items into the PMN server Model Plugin folder.
3.1.2.2 Register the DataMart Model Processor
1. Configure the DataMarts that support the plugin’s model via the PMN DataMart Administrator page.
2. Distribute and install the DataMart plugin model processor at each participating DataMart machine.
3. Enter path to installed model processor assembly into the DataMart Client application via DataMart
Client Model Settings dialog.
4. Configure additional model parameters using plugin settings dialog or configuration file.
3.1.3
Creating a Request
A plugin’s request types are displayed in a “Requests” PMN menu. When the user clicks one of the
request type menu items to create a new request, the following process is started.
1. The first HTTP GET request comes as a result of the user being redirected from PMN after the user
clicked a plugin request type.
2. The plugin’s site authenticates the user, if necessary.
2/9/2016
Company Confidential
Page 12 | 30
3. The plugin’s web page is displayed to allow the user to build the request.
(this may include several roundtrips to the plugin’s web server, other redirects, or whatever rich
interaction the plugin may require).
4. The plugin waits for the user to denote the request is complete.
5. Once the complete, the plugin’s web page controller uses the Request Token from the initial request
URL string and decrypts it for use in calling the PMN plugin web service.
6. The plugin optionally calls PMN web service (REST or SOAP) to fetch metadata from each
participating DataMart and determines which DataMarts are suited for the request Serializes the
request into a content stream.
7. The plugin calls PMN web service (REST or SOAP) passing it the serialized request built by the user.
8. Finally, the plugin redirects the user back to PMN using URL returned by the web service metadata
to signal the operation is complete.
3.1.4
Processing a Request
Once the request has been approved and submitted to the DataMarts, it is fetched by each DataMart
and displayed in a request queue within the DataMart Client application. Once the user chooses to
execute the request, the following process is initiated:
1. The DataMart Client application uses the Model’s identifier to dispatch the request to the correct
model processor
2. The model process is dynamically loaded and the request it passed to the processor via the
IModelProcessor interface (see section 4.4.2 Model Processor) along with any configuration settings
for the model.
3. The model processor de-serializes the request and prepares it for execution.
4. The DataMart Client application calls the model processor to start the request.
5. The DataMart Client application periodically checks for completion of the request.
6. Once the request is complete, the model processor serializes the response into one or more
documents that are passed to the DataMart Client application via the IModelProcessor interface.
The DataMart administrator views the list of response documents and potentially the actual result if it’s
a mime type it understands. The response is either rejected or uploaded to the PMN portal.
3.1.5
Viewing a Response
Users monitor the status of the request across the DataMarts to which it was submitted. When a user
attempts to view the response detail, the following processor is initiated.
1. The plugin receives a HTTP GET request from a user as a result of the user being redirected from
PMN.
2. The plugin’s site authenticates the user, if necessary.
3. The plugin takes the Response Token out of the query string and decrypts it.
2/9/2016
Company Confidential
Page 13 | 30
4. The plugin calls PMN plugin web service to get the serialized response data (previously obtained by
PMN from DataMarts).
5. The plugin de-serializes the response data.
6. Displays the response in a user view.
3.1.6
Aggregating a Response
The user may need to combine individual DataMart responses into an aggregated response. When this
happens, the following process is initiated.
To Be Determined
3.2 User Experience Using Plugins
The following sections present the user experience when using a plugin.
3.2.1
Creating a Request
1.
2.
3.
4.
5.
The user logs into PMN.
The user chooses a Model from a menu.
The user chooses a Request Type from a submenu.
The user is navigated away from PMN to the plugin’s web page where the request is constructed.
The user completes the request building process and clicks a control on the web page to indicate the
request is ready to be submitted.
6. The user is navigated back to a PMN page where the user completes the request by entering any
required information not supplied by the plugin and selects the DataMarts to process the request.
7. The user clicks the “Submit” button to start the request processing.
8. The user is navigated to a page that displays the status of request at each DataMart.
3.2.2
Retrieving a Response
1. The request status page enumerates requests along with their status.
2. Once the request is complete, the user chooses to display the response.
3. Depending on the mime type of the response, and rights of the user, it may be displayed within
PMN.
4. The user may choose to view the response in the plugin by clicking a control on the PMN response
detail page which navigates the user back to the plugin’s page to see the response.
5. AGGREGATION PROCESSING TBD
2/9/2016
Company Confidential
Page 14 | 30
3.3 PMN perspective
The following sections describe the use of plugins within the PMN framework.
3.3.1
Registering a new Plugin with PMN
In order to become integrated into PMN, a plugin author provides:
1.
2.
3.
4.
“Create Request” URL. This URL must have a space reserved for a Request Token (see below).
“Retrieve Response” URL. This URL must have a space reserved for a Response Token (see below).
Public key from a public/private asymmetric cryptographic key pair.
List of Request Types, each having:
A. User-friendly name
B. Identifier (unique within the plugin)
5. Metadata including:
A. Model Name
B. Model Id
C. Model Description
3.3.2
Creating a request
1.
2.
3.
4.
5.
6.
PMN authenticates a user.
Displays known Models in a menu, and their Request Types in submenus.
Waits for the user to choose a Request Type.
Creates a Request object in the persistent storage.
Generates a unique Request Token (say, a GUID) and associates it with the Request.
Encrypts the Request Token with the plugin’s public key obtained through the plugin registration
file.
7. Responds to the user with HTTP 301 Redirect to the plugin’s “Create Response” URL with the
encrypted Request Token inserted in the appropriate place in the URL.
8. Receives calls in its plugin web service to post the request.
9. Gets a notification by the plugin application the calls from the plugin’s site and notification.
3.3.3
1.
2.
3.
4.
5.
6.
Retrieving a response
PMN authenticates a user.
Displays the list of user’s past requests.
Waits for the user to choose a request that already has a response.
Generates a unique Response Token and associates it with the chosen Response.
Encrypts the Response Token with the plugin’s asymmetric key.
Redirects the user to the plugin’s “Retrieve Response” URL, inserting the encrypted Response Token.
2/9/2016
Company Confidential
Page 15 | 30
7. Expects web service calls from the plugin’s site, using Response Token for both authentication and
Response identification.
4
Module Plugin Design
4.1 Overview
The interaction of PMN with plugins follows the “call in context” semantics. That is, we “call” a plugin to
perform certain function, and the plugin may demand certain services from us in connection with the
current “call”.
The “calling” here is represented with HTTP 301 Redirect. That is, when a user asks us to do something
that requires a “call” to plugin, we respond with a “Redirect” code, which takes the user to the plugin’s
web page. There, the user performs some interaction with the plugin’s web site, and after the user is
done, he is redirected back to PMN.
(NOTE: depending on objections from the parties involved, an iframe or a separate browser window
may be used instead of redirect; or we may even have several possibilities for customers to choose from
including a native MVC based plugin that provides a seamless user experience).
The “context” here is represented by a unique “Token” – a free-form chunk of data that is unique over
time and over data such as a GUID.
We pass the Token to the plugin via the URL that we redirect the user to. For example, we could
redirect the user to a URL like
http://www.plugin.com/PMNIntegration.php?Command=CreateRequest&RequestToken=12345.
Essentially, we use the user’s browser as a “channel” for passing the token. However, since that
“channel” may be compromised, we have to protect the token from interception. To achieve that, we
use asymmetric cryptography. PMN has the public key of a key pair, and the plugin’s site has the private
key. We encrypt the token and give the encrypted version of it to the user, and the plugin’s site decrypts
it after getting it from the user via the query string.
Once the plugin site has the token, it may call PMN by using a web service API using either SOAP or
REST. Providing the plugin a request token serves as both authentication and identification of the
current “call”. This WS interface, combined with the token, acts as the “context” through which we
provide services to the plugin. Those services may include getting information about the current
request, current user, current response data, lists of DataMarts, etc.
The remaining sections describe the details of the interface points required to fully support the plugin.
2/9/2016
Company Confidential
Page 16 | 30
4.2 Model Registration
As we described in the use cases, the plugin is introduced to the PMN host by presenting a configuration
file formatted as XML. This file contains the information PMN needs to interact with the plugin including
the following items:



Configuration file contains settings of each model
Used to build request menu
Provides information used to communicate with native application
4.2.1
Sample Registration File
The following figure is a sample registration file.
<?xml version="1.0" encoding="utf-8"?>
<Model xmlns="http://lincolnpeak.com/schemas/DNS4/ModelConfiguration"
Id="{B43BC315-4B1A-4EC5-BA10-D3A4A3BB055B}" Name="Model1" Version="1.0">
<Description>Sample Model</Description>
<RequestType Id="{74E6B4DB-E0F8-4636-AB01-56F1188BDA35}" Name="Request1">
<Description>Sample Model Request</Description>
<CreateRequestUrl>http://localhost:39218/SampleModel/CreateRequest?sessionToken={0}</CreateRequestUrl>
<RetrieveResponseUrl>http://localhost:39218/SampleModel/RetrieveResponse?sessionToken={0}</RetrieveResponseUrl>
</RequestType>
<RequestType Id="{84E6B4DB-E0F8-4636-AB01-56F1188BDA35}" Name="Request2">
<Description>Some Request Ipsum Lorem Request</Description>
<CreateRequestUrl>http://some.client.com/dns_integration/create_request.php?requestId={0}</CreateRequestUrl>
<RetrieveResponseUrl>http://some.client.com/dns_integration/view_response.php?token={0}</RetrieveResponseUrl>
</RequestType>
<RequestType Id="{74E6B4DB-E0F8-4636-AB01-56F1188BDA36}" Name="Request3">
<Description>Some Request Ipsum Lorem Request</Description>
<CreateRequestUrl>http://some.client.com/dns_integration/create_request.php?requestId={0}</CreateRequestUrl>
<RetrieveResponseUrl>http://some.client.com/dns_integration/view_response.php?token={0}</RetrieveResponseUrl>
</RequestType>
</Model>
Figure 4 – Plugin Registration Configuration File
4.2.2
Model Registration File Elements
The following figure presents the tags and elements that comprise the model registration file.
2/9/2016
Company Confidential
Page 17 | 30
Tag / Element
<Model>
Child Tag / Element
Description
Id
Model identifier GUID used to dispatch request to
plugin model processor
Name
Model name displayed in PMN
Version
Model version used to validate model processor
plugin
<Description>
<RequestType>
Model description displayed in PMN
Id
Request Id used to dispatch request to model
processor
Name
Request name displayed in PMN menus / UI controls
<Description>
Request description displayed in PMN UI controls
<CreateRequestUrl>
Plugin’s URL used to display request builder page
<RetrieveResponseUrl> Plugin’s URL used to display a response to a request
Figure 5 – Plugin Registration Definition
4.3 Plugin Web Service
4.3.1
Overview
The plugin passes serialized requests to PMN through a web service API that accepts new requests,
provides metadata information gathered from DataMarts, and provides Responses generated by the
request. The service will be available as either a SOAP or REST service using .NET WCF (Windows
Communication Foundation). The location of the web service, the service URL, will be passed to the
plugin as a token on the CreateRequestURL and RetrieveResponseURL, or otherwise be made known to
the plugins as part of a PMN deployment. The final decision is still TBD.
4.3.2
Plugin Web Service API
The following sections present the plugin web service API.
4.3.2.1 Web Service Structures
The following figure presents a set of structures that are referenced by the web services API.
2/9/2016
Company Confidential
Page 18 | 30
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct SessionMetadata
{
[DataMember] public string ReturnUrl { get; set; }
[DataMember] public string ModelId { get; set; }
[DataMember] public string RequestTypeId { get; set; }
}
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct InvalidSessionFault
{
public static readonly InvalidSessionFault Instance = new InvalidSessionFault();
}
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct DataMart
{
[DataMember] public int Id { get; set; }
[DataMember] public string Name { get; set; }
[DataMember] public Document[] Metadata { get; set; }
}
/// <summary>
/// Identifies a document which is a part of a response. A response consists of multiple documents,
/// because it may have come from multiple datamarts and each datamart may return multiple documents as
well.
/// </summary>
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct Document
{
/// <summary>
/// Identifier, unique in the context of current communication session
/// </summary>
[DataMember]
public int Id { get; set; }
/// <summary>
/// Total size of the document, in bytes
/// </summary>
[DataMember]
public int Size { get; set; }
/// <summary>
/// MIME type of the document
2/9/2016
Company Confidential
Page 19 | 30
/// </summary>
[DataMember]
public string MimeType { get; set; }
}
/// <summary>
/// This fault means that the requested document was either not found or
/// </summary>
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct DocumentNotFoundFault
{
[DataMember]
public int DocumentId { get; set; }
}
Figure 6 – Web Service Structures
4.3.2.2 IRequestService
The following figure presents the web service API used to pass Requests to PMN.
[ServiceContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public interface IRequestService
{
/// <summary>
/// Retrieve metadata associated with the current session
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
/// <returns>Metadata</returns>
[OperationContract]
[FaultContract(typeof(InvalidSessionFault))]
SessionMetadata GetSessionMetadata( string sessionToken );
/// <summary>
/// This operation must be called by the Model Provider at the end of processing a request
/// to indicate that the creation of the request has been completed, and to provide the
/// result of that process - the request itself in serialized form.
/// This must be the last call in the current session. The sessionToken will not be valid for any more calls after
this.
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
/// <param name="requestHeader">Header. Common attributes of a request.</param>
/// <param name="requestMimeType">MIME type of the request.</param>
/// <param name="requestBody">The created request in serialized form.</param>
/// <param name="applicableDataMartIds">The list of data marts that are applicable to the current request.
2/9/2016
Company Confidential
Page 20 | 30
/// This should be a subset of the list returned by <see cref="GetApplicableDataMarts"/>. If there are any
extra
/// data marts in this list, they are ignored. This list may be left empty, in which case all applicable data marts
are used.</param>
[OperationContract]
[FaultContract( typeof( InvalidSessionFault ) )]
void RequestCreated( string sessionToken, RequestHeader requestHeader, string requestMimeType, byte[]
requestBody, int[] applicableDataMartIds );
/// <summary>
/// This operation must be called by the Model Provider if the user has elected to abandon the request
creation.
/// This must be the last call in the current session. The sessionToken will not be valid for any more calls after
this.
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
[OperationContract]
[FaultContract( typeof( InvalidSessionFault ) )]
void RequestAborted( string sessionToken );
/// <summary>
/// Adds an accompanying document to the request that is currently being constructed.
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
/// <param name="documentName">Name of the document. If there is already a document with this name
associated
/// with the request being constructed, that document will be replaced.</param>
/// <param name="documentMimeType">MIME type of the document</param>
/// <param name="documentBody">Content of the document</param>
[OperationContract]
[FaultContract( typeof( InvalidSessionFault ) )]
void PostRequestAccompanyingDocument( string sessionToken, string documentName, string
documentMimeType, byte[] documentBody );
/// <summary>
/// This operation may be called by the Model Provider during processing of a request to obtain a list
/// of all data marts, along with their metadata, that are may be applicable to the current request.
/// The primary purpose of this operation is to have the Model Provider filter out some data marts
/// based on some model-specific criteria.
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
/// <returns>List of data marts applicable to the current request</returns>
[OperationContract]
[FaultContract( typeof( InvalidSessionFault ) )]
DataMart[] GetApplicableDataMarts( string sessionToken );
}
2/9/2016
Company Confidential
Page 21 | 30
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public enum RequestPriority
{
[EnumMember] Low,
[EnumMember] Normal,
[EnumMember] High
}
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public class RequestHeader
{
[DataMember] public string Name { get; set; }
[DataMember] public string Description { get; set; }
[DataMember] public string Activity { get; set; }
[DataMember] public string ActivityDescription { get; set; }
[DataMember] public DateTime Date { get; set; }
[DataMember] public RequestPriority Priority { get; set; }
}
Figure 7 – IRequestService Web Service Interface
4.3.2.3 IResponseService
The following figure presents the web service API used to retrieve Responses from PMN.
[ServiceContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public interface IResponseService
{
/// <summary>
/// Retrieve metadata associated with the current session
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
/// <returns>Metadata</returns>
[OperationContract]
[FaultContract(typeof(InvalidSessionFault))]
ResponseSessionMetadata GetSessionMetadata( string sessionToken );
}
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct ResponseSessionMetadata
{
[DataMember] public SessionMetadata Session { get; set; }
[DataMember] public DataMartResponse[] DataMartResponses { get; set; }
}
2/9/2016
Company Confidential
Page 22 | 30
/// <summary>
/// Describes response that came from a single datamart - which includes identification
/// of the datamart in question and one or more documents.
/// </summary>
[DataContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public struct DataMartResponse
{
[DataMember] public DataMart DataMart { get; set; }
[DataMember] public Document[] Documents { get; set; }
}
Figure 8 – IResponseService Web Service Interface
4.3.2.4 IDocumentService
The following figure presents the web service API used to retrieve Responses from PMN.
[ServiceContract( Namespace="http://lincolnpeak.com/schemas/DNS4/API" )]
public interface IDocumentService
{
/// <summary>
/// Retrieve a chunk of a document. Chunk is defined as "a range of bytes" and is identified by
/// startOffset and length arguments. When these arguments define a range that is wholly or partially outside
/// of the actual document body, then the intersection of the two is assumed.
/// </summary>
/// <param name="sessionToken">Identifies the current communication session.</param>
/// <param name="partId">ID of the document in question</param>
/// <param name="startOffset">Starting offset of the requested chunk, in bytes, relative to the beginning of
the document body</param>
/// <param name="length">Length of the requested chunk</param>
/// <returns>The requested chunk.</returns>
[OperationContract]
[FaultContract( typeof( InvalidSessionFault ) )]
[FaultContract( typeof( DocumentNotFoundFault ) )]
byte[] ReadDocument( string sessionToken, int documentId, int startOffset, int length );
}
Figure 9 – IDocumentService Web Service Interface
2/9/2016
Company Confidential
Page 23 | 30
4.4 Model Request Processor
4.4.1
Overview
Models associated with a given Network may be supported by one or more DataMarts by providing a
Model Processor used to process the Model’s requests. The Model Processor is a .NET assembly that
implements the Model Interface. Once a Model is linked to a DataMart, the DataMart will advertise that
it supports the model within the Network. This allows the model’s requests to be routed to the
DataMart.
4.4.2
Model Processor Interface
A Model Processor implements the Model Processor Interface. The interface provides a way to pass a
request to the model processor, monitor its status, optionally cancel the request, and finally get the
response to the request. The response is returned in two parts, one is the binary stream of the response
data, and the second part is an HTML stream used to display the response to the user within both the
DataMart client.
4.4.2.1 Model Processor Classes
The following figure lists the model processor interface classes and enumerations.
/// <summary>
/// Reaon codes for Stop method.
/// </summary>
public enum StopReason
{
Abort = 0,
Cancel = 1
}
/// <summary>
/// Encapsulates current status code and message if any after a RequestDocument is made.
/// </summary>
public class RequestStatus
{
public enum StatusCode
{
Complete = 2,
// 000010
CompleteWithMessage = 3, // 000011
Pending = 4,
// 000100
InProgress = 8,
// 001000
Canceled = 16,
// 010000
2/9/2016
Company Confidential
Page 24 | 30
Error = 32
// 100000
}
public StatusCode Code
{
get;
set;
}
public string Message
{
get;
set;
}
}
/// <summary>
/// Provides information about Document to be transferred to a Model.
/// </summary>
public class Document
{
/// <summary>
/// Document identifier
/// </summary>
public string DocumentId
{
get;
set;
}
/// <summary>
/// Document mime type
/// </summary>
public string MimeType
{
get;
set;
}
/// <summary>
/// Document size
/// </summary>
public int Size
{
get;
2/9/2016
Company Confidential
Page 25 | 30
set;
}
/// <summary>
/// Is Document viewable on the Portal
/// </summary>
public bool IsViewable
{
get;
set;
}
/// <summary>
/// Constructor
/// </summary>
/// <param name="documentId"></param>
public Document(string documentId)
{
DocumentId = documentId;
}
}
/// <summary>
/// Information about the IModelProcessor implementation
/// </summary>
public interface IModelMetadata
{
/// <summary>
/// Returns the Model Name.
/// </summary>
string ModelName { get; }
/// <summary>
/// Returns the Model Id.
/// </summary>
string ModelId { get; }
/// <summary>
/// Returns the Model Version.
/// </summary>
string Version { get; }
/// <summary>
/// List of capabilities of the Model.
/// </summary>
IDictionary<string, bool> Capabilities { get; }
2/9/2016
Company Confidential
Page 26 | 30
/// <summary>
/// List of properties of the Model. These are properties whose values will be stored by the DataMartClient.
/// </summary>
IDictionary<string, string> Properties { get; }
}
/// <summary>
/// Exception to fire for any Model related errors.
/// </summary>
public class ModelException : Exception
{
public ModelException() : base() { }
public ModelException(string message) : base(message) { }
public ModelException(string message, Exception innerException) : base(message, innerException) { }
}
Figure 10 – IDocumentService Web Service Interface
4.4.2.2 IModelProcessorInterface
The following figure lists the model processor interface.
/// <summary>
/// Information about the IModelProcessor implementation
/// </summary>
public interface IModelMetadata
{
/// <summary>
/// Returns the Model Name.
/// </summary>
string ModelName { get; }
/// <summary>
/// Returns the Model Id.
/// </summary>
string ModelId { get; }
/// <summary>
/// Returns the Model Version.
/// </summary>
string Version { get; }
2/9/2016
Company Confidential
Page 27 | 30
/// <summary>
/// List of capabilities of the Model.
/// </summary>
IDictionary<string, bool> Capabilities { get; }
/// <summary>
/// List of properties of the Model. These are properties whose values will be stored by the DataMartClient.
/// </summary>
IDictionary<string, string> Properties { get; }
}
/// <summary>
/// Exception to fire for any Model related errors.
/// </summary>
public class ModelException : Exception
{
public ModelException() : base() { }
public ModelException(string message) : base(message) { }
public ModelException(string message, Exception innerException) : base(message, innerException) { }
}
/// <summary>
/// Interface the Model must implement for the plugin.
/// </summary>
public interface IModelProcessor
{
/// <summary>
/// Gets metadata from the model processor
/// </summary>
IModelMetadata ModelMetadata { get; }
/// <summary>
/// Passes a request to the model processor.
/// </summary>
/// <param name="requestDocuments">List of Documents that may be passed with this request</param>
/// <param name="RequestTypeId">Request type identifier</param>
/// <param name="Settings">User settings for the Model</param>
/// <param name="desiredDocuments">The document Documents desired by the Model</param>
/// <returns>Request instance id to be used to identify all subsequent calls associated with this
request</returns>
string Request(Document[] requestDocuments, string requestTypeId, IDictionary<string,object> settings, out
Document[] desiredDocuments);
/// <summary>
/// Called repeatedly to provide the Model with the specified Documents indicated by the desiredDocuments
2/9/2016
Company Confidential
Page 28 | 30
collection on the Request method.
/// </summary>
/// <param name="requestId">Request instance id</param>
/// <param name="documentId">The id of the Document being transferred</param>
/// <param name="contentStream">Stream pointer to read the document</param>
void RequestDocument(string requestId, string documentId, Stream contentStream);
/// <summary>
/// Notifies the model processor to beging processing a request
/// </summary>
/// <param name="requestId"></param>
void Start(string requestId);
/// <summary>
/// Stops a request.
/// </summary>
/// <param name="requestId">Request instance id</param>
/// <param name="stopReason">Reason code</param>
void Stop(string RequestId, StopReason reason);
/// <summary>
/// Return status of request
/// </summary>
/// <param name="requestId">Request instance id</param>
/// <returns>RequestStatus denoting the state of the request</returns>
RequestStatus Status(string requestId);
/// <summary>
/// Returns information about the list of Documents that can be returned.
/// Called when RequestStatus is Complete.
/// </summary>
/// <param name="request">Request instance id</param>
/// <returns>Document collection </returns>
Document[] Response(string requestId);
/// <summary>
/// Gets input stream for the specified Document.
/// </summary>
/// <param name="requestId">Request instance idr</param>
/// <param name="documentId">The id of the document being transferred</param>
/// <param name="contentStream">Stream pointer to a specified Document</param>
///
void ResponseDocument(string requestId, string documentId, out Stream contentStream);
/// <summary>
/// Closes the specified request. Closed request cannot be restarted.
2/9/2016
Company Confidential
Page 29 | 30
/// </summary>
/// <param name="requestId">Request instance id</param>
void Close(string requestId);
}
Figure 11 – IModelProcessor Interface
4.4.3
Model Processor Settings
Model processors may capture and store settings used by their query engine by providing a dialog
within their model processor assembly. The settings dialog is displayed to the user in the context of the
DataMart Client application settings dialog when the user selects “Model Settings” from the list of
models supported by the DataMart. These settings are perisisted along with other DataMart settings
and passed into the Model Processor when a request is dispatched to it. A reference implementation
for a simple settings dialog that presents a property list may be used by plugin developers.
5
Open Items
The following figure contains a description of all current open items.
Item
Response Aggregation
Plugin Service URL
Description
Need to determine who to call out to plugin to
perform aggregation
Need to determine who to publish the plugin
service URL. Options include passing it on the
CreateRequest query string, or make it a config
parameter within the host plugin application
Figure 12 – Open Items
2/9/2016
Company Confidential
Page 30 | 30