eTS Technical - interuniversity.ns.ca · June 26, 2015 V1.0 – First complete version for review and discussion Nov 24, 2015 V2.0 – Updated to reflect decisions on hosting environment

Submitted by:

The Barrington Consulting Group Inc. 1326 Barrington Street

Halifax, Nova Scotia, B3J 1Z1 Canada

Contact: Aaron Spanik

Phone: (902) 209-3498; Fax: (902) 425-1127 Email: [email protected]

Submitted to:

Ruth Blades – Project Manager

Submission Date: June 26, 2015

Nova Scotia Electronic Transcripts System

eTS Technical

Blueprint

Document Details

Author(s): Aaron Spanik, Business/Technical Analyst, Barrington Consulting

Participants / Reviewers:

Ruth Blades, Project Manager, Dalhousie University

Revision History

Date: Description:

June 22, 2015 V0.9 – Initial version released for review June 26, 2015 V1.0 – First complete version for review and discussion

Nov 24, 2015 V2.0 – Updated to reflect decisions on hosting environment and location and decisions on PESC fields and schemas to be implemented

Document Approval

Approved By: Ruth Blades

Title: Project Manager, EIF Projects

Signature:

Date: June 26, 2015

Table of Contents 1 Introduction ........................................................................................................................................ 1

1.1 Project Overview ........................................................................................................................... 1

1.2 Related Documentation ................................................................................................................ 2

2 Solution Overview ............................................................................................................................. 2

2.1 Background ................................................................................................................................... 2

2.2 Technologies ................................................................................................................................. 2

2.3 Additional Systems and Integration Targets ................................................................................. 3

3 Technical Requirements .................................................................................................................... 4

3.1 Infrastructure ................................................................................................................................ 4

3.2 Environments ................................................................................................................................ 6

3.3 Technologies ................................................................................................................................. 7

3.4 Security ......................................................................................................................................... 8

3.5 Authentication & Authorization .................................................................................................. 11

4 Technical Architecture ..................................................................................................................... 13

4.1 Conceptual Architecture Diagram (DRAFT) ................................................................................ 13

4.2 Document Flow ........................................................................................................................... 13

4.3 Message Standards Design ......................................................................................................... 14

4.4 Message Protocols ...................................................................................................................... 19

4.5 SOAP Headers ............................................................................................................................. 21

4.6 Message Creation Process Flow .................................................................................................. 24

4.7 Message Flow – Atomic .............................................................................................................. 26

4.8 Message Flow – Process ............................................................................................................. 27

5 High-Level Application Design ..................................................................................................... 28

5.1 Architectural Guidelines ............................................................................................................. 28

5.2 Additional Guidelines .................................................................................................................. 28

5.3 Pre-Conditions/Code Changes .................................................................................................... 28

5.4 Inbound Data Exchange Service .................................................................................................. 29

5.5 Message Processing Service ........................................................................................................ 32

5.6 Message Transfer Service ........................................................................................................... 34

5.7 Administration Interface ............................................................................................................. 35

1 Appendix “A” – DTS version 2.0 WSDL ...................................................................................... 36

eTS Business Requirements| Electronic Transcripts System Project Page 1

1 Introduction

This document describes, from a technical perspective, how the Nova Scotia Electronic Transcripts

System (eTS) solution will be designed and developed in accordance with the needs of the

Postsecondary Institutions of Nova Scotia and the Nova Scotia Department of Education and Early

Childhood Development.

This document will be informed by the business requirements, project-related agreements and

documents as well as project meetings and workshops. When complete, it will provide a source for all

technical requirements for the project and will serve as the basis for the detailed business and technical

designs for the system. It will also inform the test planning, knowledge sharing and training processes

and will provide a location to capture any challenges, changes, and decisions that affect the technical

side of the project.

1.1 Project Overview The Government of the Province of Nova Scotia, through the Excellence in Innovation Fund (EIF) has

identified several opportunities to explore collaboration between Nova Scotia Postsecondary

Institutions (PSIs) and reduce operating costs. One such opportunity is the Electronic Transcripts System

(eTS) that is aimed at increasing the efficiency of, and reducing the costs and efforts associated with, the

postsecondary admissions process, especially as relates to applications coming from Nova Scotia High

School Students.

The eTS is intended to provide a conduit through which transcript data may be electronically passed to

Nova Scotia PSIs. The initial design, development and deployment will be focussed on enabling Nova

Scotia High Schools, through their respective school boards and the Nova Scotia Department of

Education and Early Childhood Development (EECD), to send transcript data for Nova Scotia students

applying to Nova Scotia publicly funded PSIs.

Future integration work is expected to expand the scope of the eTS to similarly allow high school

transcripts from other sources in Nova Scotia, including the Mi'kmaw Kina'matnewey School Board,

independent / private schools and others. In future phases will also include transcript exchange between

universities and colleges in Nova Scotia, and the exchange (to and from) of both high school and post-

secondary transcripts with transcript hubs in other provinces in Canada.

The first phase of the project is intended to drastically reduce the exchange of paper transcripts

between Nova Scotia High Schools and Nova Scotia Post-Secondary Institutions as well as the associated

processing efforts. This is expected to have the following benefits:

It is vital to recognize that this Technical Blueprint is a living document which will provide a

base for each successive phase of eTS Project. Please refer to the revision history of this

document for information about its current status.


Reduce costs associated with producing and sending paper transcripts;

Reduce errors associated with misdirected/waylaid paper transcripts;

Reduce processing time and costs associated with receiving paper transcripts;

Improve accuracy by eliminating data entry processes;

Improve processing time; and,

Improve turnaround time on admission decisions.

Overall, the initial goal is to reduce the cost, time and effort associated with the Nova Scotia PSI admission

process for Nova Scotia high school students while improving accuracy and turnaround times.

1.2 Related Documentation The documents listed below have informed this document and should be used for reference. Additional

documents will be added to this list as they become available.

eTS Project Documentation

PESC XML to NS High School Transcript data mapping

PESC Documentation

Located at www.pesc.org, - STANDARDS.

XML High School Transcript - Version 1.5.0

High School Transcript XML Schema

Academic Record XML Schema

CoreMain v1.14.0.xsd

Version 1.3.0 Implementation Guide (not current to Version 1.5.0 but a helpful resource)

Functional Acknowledgement - Version 1.2.0

Functional Acknowledgement XML Schema

Request and Response of the XML Transcript -

Version 1.4.0

Transcript Request XML Schema

Transcript Response XML Schema

Batch XML Transcript - Version 2.1.0

Academic Record Batch XML Schema

Data Transport Specification (DTS) - Version 2

Data Transport Standard v 2.0 Specification

http://www.pesc.org/


2 Solution Overview

2.1 Background The technical solution for this integration is informed by various sources:

The work-to-date of the eTS Project Working Group;

The business requirements for the eTS;

The published standards and implementation guides of PESC:

o XML Schema Definitions for High School Transcript;

o XML Schema Definitions for Academic Record Batch;

o XML Schema Definitions for Transcript Request & Response;

o XML Schema Definitions for Functional Acknowledgement; and

o Data Transfer Standard (DTS) version 2.

2.2 Technologies Consistent with the background above, several of the technologies that will be involved in the creation

of the eTS have been determined:

eXtensible Markup Language (XML);

XML Schema Definition (XSD);

Hypertext Transfer Protocol over Secure Sockets Layer (HTTPS);

SOAP Web Services;

WS-Security v1.1 (aspects):

o XML-Sig;

o Binary Security Token; and,

o Timestamp.

X.509 Certificates;

Zlib compression; and,

Base64 encoding.

Many of these technologies will be further described in other sections of this document.


2.3 Additional Systems and Integration Targets In addition to the eTS itself, there are additional integration targets in play for the eTS project that will

exert some influence on the implementation, if not the design, of the eTS. These additional systems

correspond to the data exchange partners who will be using the eTS for message exchanges. The

expected exchange partners in the initial deployment phase of the eTS include:

A system owned and operated by EECD that will receive requests and provide high school transcript information for students attending high schools governed by the public school boards of Nova Scotia; and,

Systems owned and operated by the post-secondary Institutions of Nova Scotia who will request and receive high school transcripts.

Future phases of the eTS project are expected to include the following additional integrations:

A system owned and operated by the Mi’Kma Kina'matnewey School Board that will receive and provide high school transcript information for students attending Mi’Kmaw high schools in Nova Scotia;

Systems owned and operated by independent / private high schools that will receive requests and provide high school transcript information for students attending those schools;

Further integrations with the systems owned and operated by post-secondary institutions in Nova Scotia to allow the request and fulfillment of college and university transcript requests between those institutions; and,

Integrations with systems outside of Nova Scotia, whether to enable the exchange of high school or college and university transcripts for students applying for admission to Nova Scotia post-secondary institutions.


3 Technical Requirements

3.1 Infrastructure Infrastructure in this context refers to the hardware, software and supporting elements that comprise

both the eTS itself and the ecosystem in which it is deployed. The Steering Committee has entered into

an agreement with Higher Education IT Shared Services (HISS) to manage eTS server which will be

physically located at Dalhousie University. This section describes, in general, the infrastructure that will

be required for the eTS.

3.1.1 Hardware

As with all software applications, a hardware platform will be required on which the eTS can be run.

There is no particular requirement for this system to specifically run on physical hardware and, in fact,

there may be significant benefits to a virtualized hardware platform such as the ability to add resources

and the ability to quickly and easily create and mount additional environments on an as-needed basis.

It is not expected that the eTS will require inordinate computing resources or capacity; in sizing a system

for the eTS the following should be taken into account:

Processing (CPU) Capability – Although the eTS will not be required to perform any significant processing of messages beyond examination to determine routing, there is some resource cost to the use of digital signatures. Though it does not follow that the performance of the system will necessarily be CPU-bound, reasonable CPU resources will be required to handle the necessary public key cryptography processes.

Memory (RAM) – In effect the eTS will operate in a store-and-forward fashion, so although the eTS may process transcript batches of significant size there is no requirement for real-time or near real-time message processing, thus the system should not require extensive RAM resources.

Storage (Disk) – As the eTS will behave as a broker system in a hub-and-spoke topology and as such will not be required to store significant amounts of data beyond transaction logs, a large storage subsystem is not required, however for the sake of reliability and recovery potential, transparently redundant (e.g., RAID 0) storage is recommended.

Network – The eTS should be equipped with high-quality network interfaces with if possible; multiple interfaces operating in a bonded or fail-over configuration would be ideal.

3.1.1.1 Sample System Spec

The below table illustrates a sample system specification that is expected to be sufficient for the initial

implementation of the eTS.


Resource Recommendation

CPU At minimum, the equivalent of 4 physical CPU cores, e.g., 2 dual-core processors, 1

quad-core processor, or 4 cores allocated by a virtual machine container. Server-class

processors (e.g., Intel Xeon) should be used.

Memory Minimum 8GB RAM, preferably ECC.

Storage Minimum of 100GB available storage, preferably in an internally redundant

configuration such as RAID 1.

Network Minimum 100Megabit single port, preferably 1Gigabit single or dual port network

interface.

3.1.2 Software

Operating System – Nothing about the design of the eTS makes it more or less suited to any particular operating system; however, Microsoft Windows Server has been selected as the operating system, based on the service agreement with the host facility.

Platform – As with operating system, there are no significant technical differentiators in play that would lead to a requirement for one technology platform or another. Any requirement or decision regarding the application platform (e.g., J2EE, .Net) should thus be informed largely in terms of the capabilities of the implementation partner.

3.1.3 Environment

Network – the eTS is defined as a message passing system and will need stable and reliable connectivity to all networks that host exchange partner systems. Further, per the requirements of Certificate Validation and potentially time synchronization, some access to the Internet will be required.

Time Synchronization – In order for timestamps included in XML messages to be meaningful, every server participating in message exchanges must endeavour to maintain system clocks that are as close to in synchronization as possible. This can be accomplished through the use of public time servers or by leveraging a local time server that is itself synchronized with public time servers.

Firewall – The facility selected to host the eTS will provide firewall protection to the system that can be configured to maximize the security and network efficiency of the system.

Backup – Although the eTS is not intended to house extensive amounts of data, its logs are intended to be useful in support and troubleshooting processes. In addition, restoring a system

This specification should be revisited for validation as early as possible in the implementation

phase to ensure that any impacts from decisions regarding the target technology platform

and hosting are reflected in this document and the design of the system.


from backup is generally the most efficient means of returning a failed system to production. To that end, at a minimum the logs and deployed code of the eTS should be backed up on a regular basis however a full system backup is preferable.

3.1.4 Integrated Systems

Given the structure of the eTS project where the exchange partners are effectively external entities, the

requirements for the systems that will integrate with the eTS cannot be defined to any great degree by

the eTS project itself. Trading partners have varied systems, some which may have interfaces defined

and supported by a vendor, some which are expected to be built to suit. Agreements must be sought

between the exchange partners to determine a minimal level of cooperation with regards to

technologies used in data exchanges.

With respect to communications from partners to the eTS, those interactions will be according to the

specifications defined in this document and later in the detailed technical design.

With respect to communications from the eTS to partner systems, those interactions will be governed

by the interfaces made available by the partners. It may be useful to define a minimum standard or set

of technologies that will be accepted, e.g., that SOAP Web Service endpoints must be made available for

communicating with the eTS. A more stringent agreement might mandate the implementation of a

particular set of SOAP operations or even a particular WSDL, leaving partners to handle any adaptation

to back-end systems locally.

3.2 Environments Best practices for software development and implementation projects generally prescribe four types of

environments, two of which are specific to development and system and integration testing and two

that are geared towards user acceptance testing (UAT) and production. These four types of

environments are usually categorized as Development, Test, Staging (or Pre-Production), and

Production:

Environment Description

Development Development environments are intended to be those where development of

functionality can be performed independently with minimal chance of impacting the

test environment and little or no chance of impacting the staging or production

environments. The development team may maintain several individual development

environments as well as be provided access to a shared, integrated environment for

testing.

Test Test environments are those that provide the capability to test both the functionality

that is internal to the application as well as end-to-end integration. Although multiple

test environments may be useful or necessary on larger projects, generally a single

testing environment is sufficient for systems and integration testing.


Staging (Pre-

production)

A staging environment is intended to be one where a full deployment and

configuration can be tested to ensure that the deployment process and associated

documentation is sound. Generally there is a single staging environment and this

environment is also leveraged for User Acceptance Testing (UAT).

Production A production environment is the deployment target and will not be engaged in any

way until the deployment and launch of the live service.

The degree to which environments should match production ideally becomes more stringent from

development to test and from test to staging; the ideal staging environment is identical in all ways

except configuration to the production environment. Practically speaking, exact correspondence

between environments is difficult, however the software and versions deployed in each environment

should remain consistent throughout development cycles once a baseline has been established.

In an ideal situation, data exchange partners will provide a similar outlay of environments. At minimum

each partner must mount an appropriate staging environment for UAT however a separate test

environment for systems and integration testing is highly recommended.

3.3 Technologies Although some of the technologies involved in the implementation of the eTS will be determined during

the detailed technical design, there are some that have been determined by the decision to leverage the

standards of PESC. These include:

3.3.1 XML

Extensible Markup Language (XML) is an industry standard for creating messages in a format that is

generally both machine- and human-readable. The PESC standards already selected for use by the eTS

are XML-based, therefore XML documents will be the message format used.

3.3.2 XSD

Where XML is a markup language that simply places structure on document formatting, XML Schema

Documents are one means to define the structure of a document such as what elements it must or may

contain and what order the elements must appear. The PESC standards include XSDs suitable for

structuring XML documents of various transcript exchange-related types and conformance to these

schemas will ensure regular and well-structured data is passed to and from the eTS.

3.3.3 SOAP Web Services

A web service is generally considered to be a software component that is designed to support

interactions between devices on a network. Although there are multiple types of web services, the

protocol specification known as SOAP is the one leveraged by the Data Transfer Standard published by

PESC for data exchange. SOAP web services are defined through the use of Web Service Definition

Language (WSDL) documents that specify both the operations that can be performed and the types of


messages that will be sent and received in the process. SOAP is implemented using XML documents for

messages and generally leverages Hypertext Transfer Protocol (HTTP) for transport. The eTS will

leverage the PESC DTS and as such will implement SOAP web services.

3.3.4 HTTP(S)

Although the SOAP standard allows for implementation over multiple protocols, HTTP is the most

common and is considered the most desirable. Further, the PESC DTSv2 is designed around the use of

HTTP. All SOAP web service connections in which the eTS is involved will use HTTP as the transport.

In addition, the administrative interface to the eTS will use HTTP as its underlying protocol.

3.3.4.1 HTTP Server

A Hypertext Transfer Protocol (HTTP) server (also known as a “web server”) will be required as a host

platform for the SOAP Web Services. Although SOAP services can be deployed as standalone

applications that handle HTTP transactions internally, leveraging a separate web server generally creates

efficiencies in administration and configuration as well as providing built-in functionality such as Secure

Sockets Layer (SSL) capabilities and load-balancing that would otherwise need to be built explicitly.

Using a discrete HTTP server will also enable the eTS administration interface, which will not be

implemented using web services.

3.3.4.2 SSL

Secure Sockets Layer (SSL) is a means of providing end-to-end encryption network communications. It

involves the use of public key cryptography with X.509 certificates serving to identify one party to the

other and provide security for a session key exchange used to encrypt a communications session. As

described below, the PESC DTSv2 calls for all communications between systems to be encrypted using

SSL, therefore all transcript data-related exchanges involving the eTS will take place over HTTP-over-SSL

(a.k.a. HTTPS).

The administrative interface to the eTS will also leverage HTTPS for all communications.

3.4 Security The security and privacy of the overall eTS solution has several aspects: the network(s) over which

messages are delivered, the operating system and platform on which the system is deployed, the

application itself and the standards defined for message exchange.

3.4.1 Network Security

Network security involves controlling where, what kind and how much traffic may flow within a given

network. As multiple networks will be in play for the overall eTS initiative, network security

configuration will be a joint effort. The security considerations for the local network where the eTS is

deployed include:

Restricting access to the eTS data exchange web services to particular external IP addresses provided by exchange partners and the specific service port on which the eTS web services are listening;


Restricting access to the eTS administration interface to networks from which administrative sessions could reasonably be expected to be initiated and to the specific service port on which the eTS administrative interface listens;

Restricting all other network access to the system hosting the eTS except that which is required to administer and manage the system; and,

Implementing any other applicable network security policies and/or best practices after assessing any potential impacts to the operation of the eTS.

3.4.2 Operating System Security

Operating System security refers to those measures taken to restrict access to the operating system

running beneath the platform and application that comprise the eTS. Without a determination of host

operating system it is not possible to list specific measures, however the following general

considerations should form the basis for operating system security:

Restricting all access to the operating system to individuals with a reasonable reason to be accessing the system (e.g., system administrators, other resources as-needed);

Ensuring that all access to the operating system is authenticated;

Ensuring that all remote access to the operating system is over encrypted transport; and,

Implementing any other applicable operating system security policies and/or best practices (e.g., encrypted storage) after assessing any potential impacts to the operation of the eTS.

3.4.3 Application Platform Security

Application Platform security involves controlling access and capabilities with respect to the application

platform to which the components of the eTS application are deployed. Different platforms and

platform implementations will have different specifics, however at a minimum the following general

considerations should be implemented:

Restricting all access to any administrative interface of the application container to individuals with a reasonable reason to be accessing that interface (e.g., application administrators, other resources as-needed);

Ensuring all access to any administrative interface of the application container is authenticated;

Ensuring that all remote access to any administrative interface is over encrypted transport;

Ensuring access levels are configured such that anyone accessing any administrative interface has access only to features and functions required for that person’s role in administering the platform; and,

Implementing any other applicable platform security policies and/or best practices after assessing any potential impacts to the operation of the eTS.


3.4.4 Application Security

Ensuring the security of the eTS application itself will involve ensuring, through design and

implementation, that the PESC DTSv2 is implemented for message exchange, that the administrative

interface allows access only to authenticated, named users, that the logging mechanisms do not expose

personal information and that any personal information temporarily stored on the system is correctly

removed once messages are correctly forwarded to the required partners or abandoned.

3.4.5 Messaging Security

Messaging security, that is, ensuring the privacy and security of the information passed in the actual

transcript data exchange messages, is largely ensured by the adherence of the design and

implementation to the DTSv2 published by PESC. The security specifics of the DTSv2 can be summarized

in terms of encryption, to ensure that messages are not exposed during transport, digital signatures to

ensure that the integrity of the message and the identity of the sender can be validated, timestamps to

provide resistance to certain types of attacks, the inclusion of binary security tokens to eliminate the

need for out-of-band key exchanges and Certificate Validation to ensure that the binary security tokens

are trustworthy.

3.4.5.1 Encryption

Although the Web Services Security (WS-Security) standard of the World Wide Web Consortium (W3C)

defines an XML Encryption standard (XML-Enc), a means by which the payloads of SOAP web service

XML messages may be protected using encryption, and though the PESC DTSv2 specifies the use of WS-

Security, it does not require the use of XML-Enc for message payload encryption. It does, however,

specify that SSL must be enabled for all communications sent and received by a DTS-compliant web

service. Thus there is a requirement that the eTS support HTTPS communications for all transcript-

related messaging.

3.4.5.2 Signatures

Digital signing is a means of using public key cryptography to validate both the integrity of a message

and the identity of the sending party. The WS-Security standard leverages XML Digital Signatures (XML-

Sig or XML-DSig) to provide these facilities and, in turn, the PESC DTSv2 specifies the use of this element

of WS-Security on all transcript-related messages. The ‘signature’ is, in effect, a digest (also known as a

hash) of the message that has been encrypted using the private key of the sender. A recipient can verify

both that the message is actually from the sender and that it has not been tampered with by decrypting

the signature using the sender’s public key and then comparing the resulting digest to a digest it

generates from the message.

3.4.5.3 Timestamp

The WS-Security standard provides a means for a sending party to indicate the ‘freshness’ of the security

semantics of a message by including a timestamp element. At a minimum, this element specifies the

creation time of the message but it may also specify an expiry as well. The PESC DTSv2 specifies the

inclusion of creation and expiry elements within the timestamp element in order to protect against both

man-in-the-middle interception attacks as well as transaction replay attacks. A message recipient must


then validate that a message has not been received past its expiration time and should raise an error if it

has. The implementation of timestamps requires the use of time synchronization in order to ensure that

significant variation in system clocks does not result in either incorrect determination of validity or false

expiry errors. Partners must also agree upon a reasonable timeframe for message security expiry.

3.4.5.4 Binary Security Token

As defined in the WS-Security standard, binary security tokens are the public portion of a public/private

keypair, included in an XML message in the form of a X.509 certificate. The token that is included is the

public key needed to validate the digital signature applied to the XML message. While the PESC DTSv1

did not prescribe the use of binary security tokens, the v2 standard requires their use. The use of the

binary security token element to include public key information alleviates the need for partners to

exchange public keys out-of-band and prior to engaging in data exchanges and also the need for

extensive key maintenance.

3.4.5.5 Certificate Validation

The use of binary security tokens for key exchange does have security implications in that an attacker

could potentially intercept a message, modify it and re-sign it with another key that then overwrites the

original binary security token. Certificate validation is the means by which this attack vector is

neutralized. The PESC DTSv2 requires that certificates used for applying digital signatures to messages

be issued by a trusted certification authority with a verifiable certificate chain and that message

recipients must check each received certificate for both expiry and revocation. If any of these checks fail,

the message is taken to be invalid.

3.5 Authentication & Authorization Authentication and authorization refer to two key processes in gating access to a resource.

Authentication is the process of a party asserting its identity and that assertion being validated.

Authorization is the process of checking whether a party is entitled to access a particular resource.

Authentication and authorization come into play for the eTS both with the web services interface and

the administration interface.

3.5.1 Authentication

In terms of the SOAP web services that will be implemented as part of the eTS, the aspects of WS-

Security specified by the PESC DTSv2 standard provide for authentication in the form of the digital

signature that is applied to each message that is sent. The digital signature is applied using the public

key (X.509 certificate) of the signing party and the public key is then included in the message. The

identity of the signing party is validated by examining the public key itself, which has been signed by a

Certificate Authority who has done some level of due diligence to validate the identity of the party

before issuing the certificate.

For the administration interface to the eTS, credentials in the form of username and password will be

used to gain access. Management and issuance of the credentials may be built into the eTS itself, or the

capability to leverage an external credential store may be included instead.


3.5.2 Authorization

The DTS does not specify any particular controls with respect to authorization; if a sender is able to

connect to the eTS and send a valid message, including passing all security checks, the message will be

accepted.

On the administration side, it is not expected that there will be a complex hierarchy of capabilities given

the limited data available.


4 Technical Architecture

4.1 Conceptual Architecture Diagram (DRAFT)

4.2 Document Flow The current understanding of the high-level flow of XML documents through the eTS, will be as follows:

A Transcript Request document will be generated, packaged and sent by a transcript consumer to the eTS;

The Transcript Request document will be examined by the eTS to determine routing;

The Transcript Request document will be repackaged and sent by the eTS to the appropriate transcript producer;

The transcript producer will process the Transcript Request document;

A Functional Acknowledgement document will be generated, packaged and sent by the transcript producer to the eTS;

The Functional Acknowledgement document will be examined by the eTS to determine routing;


The Functional Acknowledgement document will be repackaged and sent by the eTS to the appropriate transcript receiver

A Batch of Transcript and/or Transcript Response documents will be generated, packaged and sent by the transcript producer to the eTS;

The Batch document will be examined by the eTS to determine routing;

The Batch document will be repackaged and sent by the eTS to the appropriate transcript consumer;

A Functional Acknowledgement document will be generated, packaged and sent by the transcript consumer to the eTS;

The Functional Acknowledgement document will be examined by the eTS to determine routing;

The Functional Acknowledgement document will be repackaged and sent by the eTS to the appropriate transcript producer

4.3 Message Standards Design The Message Standards Design for the eTS has effectively been determined by the decision to adopt the

standards of PESC for messaging. These standards are well documented and are freely available from

the PESC website along with implementation guides designed to assist in the process of building PESC-

compliant messaging systems.

4.3.1 PESC Schemas

The PESC organization is concerned with enabling data interoperability within the Educational Domain,

attempting to help provide standards and structure that can be applied to information exchanges

between partners. To that end, PESC has ratified and published a library of XSDs that can be leveraged

for data exchange. Use of and adherence to the PESC schemas improves the opportunities for future

integration with other exchange partners.

PESC Schemas are defined hierarchically, with common elements appearing at the root and message-

and sector-specific schemas referencing and extending into specific types of exchange. This design

pattern ensures elements that are common across all data exchanges to be consistently implemented in

all areas, while allowing different business exchanges to use similar terminology without incurring

namespace conflicts.

It is vital to recognize that the Message Standards Design can only be said to govern the

interactions between integrated systems and the eTS. Until more is known about the other

systems that the eTS will be required to integrate with, it is not possible to describe those

interactions. Further, depending on the nature of the interfaces in question, the required

capabilities of the eTS in terms of message processing may vary widely.


4.3.2 Schema Versions

As an organization, PESC frequently engages its stakeholder community in an effort to add additional

documents for exchange, to consider new types of exchange and to respond to issues and concerns

brought forward. As a result, the PESC standards and schemas are subject to change, with new versions

being released on a somewhat frequent basis. All such changes are subject to a review and ratification

before being released.

In terms of what version of the schemas to implement, it is recommended that the eTS Project opt to

delay the nomination of a specific schema version until the implementation is underway; this will allow

selection of the most recently-released version of each schema and, hopefully, maximize the time

available until the next release.

It is important to note that different PESC Schemas themselves may refer to different versions of a

common schema. For instance, the current versions of the TranscriptRequest.xsd and

TranscriptResponse.xsd schemas (both at v1.3.0) reference AcademicRecord.xsd version 1.8.0 whereas

Academic-RecordBatch.xsd (at v2.1.0) requires version 1.9.0 of the AcademicRecord.xsd. For reasons

such as these it may be required for the eTS to support multiple versions of the same schema, albeit for

different purposes.

It is unavoidable that at some point new schemas will be released that supersede the versions elected

for implementation. A decision process will need to be created as to dealing with schema changes, e.g.,

implementing the new schemas, proceeding with the old schemas, or implementing services that can

handle both the new and the old schemas.

4.3.3 NoteMessage and UserDefinedExtension

Virtually all of the structural (that is, document-defining) schemas in the PESC standard and a large

number of the complex types defined in the type-defining schemas contain two optional elements:

NoteMessage and UserDefinedExtension. Both elements are available as supplements that allow

additional information to be passed that does not naturally fit within the schemas as they are currently

defined. NoteMessage allows for free-form string data, whereas UserDefinedExtension allows the

inclusion of structured XML data that conforms to a user-defined structure.

Although these elements are available, PESC strongly discourages their use, as they represent a

departure point from PESC standards. It is understood that the eTS Project intends to avoid, where

possible, using any instance of either of these elements in any data exchanges unless the viability of the

The mapping of transcript information to the High School Transcript schema is a business

analysis task that is well underway. Additional effort will need to be invested in mapping the

additional schemas that are required in order to support all of the message types that are

required for data exchange. This will flow naturally from decisions regarding

acknowledgements and routing information.


project is threatened and their use represents the only viable solution. To that end, when discussing

schemas and elements below, these elements will generally not be mentioned.

4.3.4 Schemas Required for High School Transcript Exchange

One of the specific sectors addressed by the PESC schemas is Transcript Exchange with specific schemas

available for both College/University and High School transcripts. In addition, batch schemas have also

been developed to enable the concatenation of multiple transcript requests and responses into single

exchange documents

4.3.4.1 CoreMain.xsd

The so-called “Core Main” CoreMain.xsd schema (CoreMain.xsd) is the heart of the PESC schema

hierarchy. It is a type-definition schema containing the definitions for many of the simple and complex

types required for a structured implementation of all PESC-defined data exchanges. All other PESC

schemas refer back to the CoreMain schema.

4.3.4.2 Academic Record

The Academic Record schema (AcademicRecord.xsd) is a type-definition schema that underlies all

schemas that are specific to the exchange of transcripts between exchange partners. This includes both

the College/University and High School Transcript schemas themselves along with the request, response

and batch schemas. Like CoreMain, the Academic Record schema consists of simple and complex type

definitions.

4.3.4.3 Transcript Request

The Transcript Request Schema is a structural schema that defines an XML document type, in this case a

request for a transcript. A Transcript Request document will be generated by a transcript consumer for

each student that the consumer is interested in receiving a transcript for. It contains two required

elements: TransmissionData and Request.

The TransmissionData element represents the first level of envelope data. It contains several sub-

elements designed to provide information about the exchange as it pertains to the exchanges for a

particular transcript. It contains several sub-elements designed to provide information about the

exchange, including source and destination, Document ID, timestamp, document and transmission type.

The Request element contains several sub-elements, including information about who is making the

request, information about where the response should be sent and the identifying information of the

student whose transcript is being requested. The student information is used by the transcript provider

to locate the appropriate student record.

4.3.4.4 High School Transcript

The High School Transcript schema (HighSchoolTranscript.xsd) is a structural schema that defines an

XML document type, in this case a response containing the XML representation of the information

contained within a High School Transcript. A HighSchoolTranscript XML document will be generated by a

transcript producer for each transcript request that was requested by a consumer if and only if the


student described in the request was successfully located in the producer’s records. The top-level

element in the document is HighSchoolTranscript and it contains two required sub-elements:

TransmissionData and Student.


elements designed to provide information about the exchange as it pertains to the exchanges for a

particular transcript. It contains several sub-elements designed to provide information about the

exchange, including source and destination, Document ID, timestamp, document and transmission type.

The Student element is of K12StudentType and contains several sub-elements, two of which are

required: Person and AcademicRecord. The information contained within these two complex elements is

effectively the student transcript.

4.3.4.5 TranscriptResponse

The Transcript Response schema (TranscriptResponse.xsd) is a structural schema that defines an XML

document type, in this case a response that does not contain transcript information.

A TranscriptResponse document can be generated by a transcript producer for several purposes: to

indicate the receipt of a transcript request, to indicate a transcript has been previously sent, to indicate

a transcript has been sent out-of-band (e.g., paper transcript via mail), or as a negative response to a

request from a transcript consumer. Reasons for a negative response may include, no match was found

for the information in the request, multiple matches were found for the information in the request or

that the transcript cannot be released due to a hold on the student record. In the case of the eTS this

will most likely be used to indicate the inability of the transcript producer to find a matching student

record based on the information provided in the request. TranscriptResponse is the top-level element

itself contains two main elements, TransmissionData and Response.


elements designed to provide information pertaining to the data exchanges for a particular transcript. It

contains several sub-elements including source and destination, Document ID, timestamp, document

and transmission type.

The Response element is of type ResponseType, which is a complex type containing several sub-

elements, four of which are required: CreatedDateTime, RequestTrackingID, ResponseStatus, which

contains the actual response, and RequestedStudent, which contains the student information received

in the request document.

4.3.4.6 Academic Record Batch

The Academic Record Batch schema (AcademicRecordBatch.xsd) is a structural schema that defines an

XML document type, in this case a document that allows the concatenation of several XML documents

into a single document. The schema places no restrictions on the types XML documents can be included,

but does insist that they belong to a different namespace than the CoreMain namespace and that they


successfully validate against a schema. It also allows both homogenous and non-homogenous

collections.

For transcript exchanges through the eTS, the Academic Record Batch schema will be used for all

messages regardless of the number of documents – the exchange of a single document will be

implemented as a batch of one.

The AcademicRecordBatch top-level element has two sub-elements, an optional BatchEnvelope element

of type TransmissionBatchType and a BatchContent element, which is the element used to contain the

collection of concatenated documents.

The BatchEnvelope element contains envelope information about the batch and includes several

required elements: BatchID, BatchDateTime, BatchDeliveryMethod, SourceAgency and

DestinationAgency:

The BatchID provides for an identifier that will be used by transcript consumers and producers to correlate batches.

BatchDateTime is a timestamp indicating when the batch was created; this may be substantially different than both the timestamp elements in the TransmissionData elements of the individual documents contained in the batch and the timestamp element in the SOAP Header when the message is created and sent.

The BatchDeliveryMethod is used to indicate whether the batch should be delivered whole or whether the contained messages should be parsed individually. As the high-level design of the eTS calls for batches to be delivered to a single exchange partner, this element should always be set for whole delivery.

SourceAgency and DestinationAgency are used to nominate the sender and receiver of the batch; for the purposes of the exchanges through the eTS, these should be the same as the corresponding elements in the individual messages contained within the batch.

The BatchContent element will be populated with XML documents based on the purpose of the

exchange:

Requests for transcripts created by transcript consumers will be batches containing one or more TranscriptRequest documents;

Responses to requests created by transcript producers will be batches that will contain one or more TranscriptResponse documents, one or more HighSchoolTranscript documents or a mix of the two;

Acknowledgements created by transcript consumers to confirm receipt of transcripts will be batches that contain only acknowledgement messages.


4.3.4.7 Functional Acknowledgement

The Functional Acknowledgement schema (FunctionalAcknowledgment.xsd) is a structural schema that

defines an XML document type, in this case an acknowledgement that an exchange partner has received

a document from another partner. The Acknowledgement top-level element has two sub-elements: a

TransmissionData element and an AcknowledgementData element.


elements designed to provide information pertaining to the data exchanges for a particular transcript. It

contains several sub-elements including source and destination, Document ID, timestamp, document

and transmission type.

The AcknowledgementData element contains the actual information about the acknowledgement

through the use of several sub-elements: BatchID, DocumentID, AcknowledgementCode, SyntaxError

and NoteMessage:

The optional BatchID element allows correlation with a particular batch document;

The DocumentID element allows correlation with a particular document within a batch;

The AcknowledgementCode specifies whether the document is being Accepted or Rejected;

The optional SyntaxError provides a means for a means to indicate the nature of any errors that prevent the received document from being processed; and,

The optional NoteMessage element allows the ability to provide information about any non-syntax-related issues that prevent the received document from being processed.

4.4 Message Protocols The message protocol selected for use by the eTS is the one defined by the PESC Data Transport

Standard (version 2). This standard specifies the use of SOAP web services for exchanging PESC-

compliant XML documents, leveraging some aspects of the WS-Security 1.1 standard to provide security

as described elsewhere in this document.

Protocol Type Protocol Selection Remarks

Document PESC-defined XSD Academic Record Batch

Transcript Request

High School Transcript

Transcript Response

Functional Acknowledgement

Academic Record (supporting)


Core Main (supporting)

Exchange PESC Data Transport Standard v2.0

Transport HTTP over SSL (HTTPS) HTTP version 1.1 is recommended

Packaging SOAP

WS-Security 1.1

Timestamps

XML Digital Signature (XML-Sig)

Binary Security Token

Zlib compression for SOAP Body

Base64 Encoding for SOAP Body

4.4.1.1 Document Protocol

The document protocol defines the document type of the message payload, which is based on what

standard (e.g., RosettaNet, EDI, XML, etc.) is being used to support the business logic.

All PESC exchanges are defined by the use of PESC XSD schemas that must be fulfilled by the XML

messages intended to be exchanged.

4.4.1.2 Exchange Protocol

The exchange protocol defines the message exchange mechanism – how to exchange the documents

defined by the document protocol. The exchange protocol defines the headers and packaging that put

the headers and payload together along with the transport and packaging protocols for the exchange.

The PESC DTS v2 is effectively the Exchange Protocol that will be used when systems contact the eTS to

exchange messages.

There are aspects of message exchange at the business level that are not addressed by the

DTS and are left for implementation. For instance, though request and response SOAP

message types are defined, the specifics of what values are valid in the elements and what

meaning those values hold is left to be determined and agreed upon by the exchange

partners. The PESC schemas also make available multiple forms of acknowledgement

however it is up to the exchange partners to determine which acknowledgement schemas

will be used and how.


4.4.1.3 Transport Protocol

The transport protocol defines the underlying transport and its properties.

The PESC DTS insists upon the use of HTTPS (HTTPS 1.0, HTTPS 1.1) for the transporting of messages

between partners. The use of this more secure encrypted form of HTTP provides an additional layer of

security to the system.

4.4.1.4 Packaging Protocol

The packaging protocol defines the packaging mechanism, which in turn specifies the format of the

message and the metadata contained therein. Message security features such as signing and encryption

are often based on a specific packaging mechanism

The following packaging elements will be used for this integration:

SOAP

XML Digital Signature (XML-Sig)

Binary Security Token

The PESC standard defines SOAP envelopes containing XML messages for the required data exchanges.

Security is not defined by the SOAP web service WSDL, but its use specified by the DTS to include

timestamp, digital signature and binary security token, all compliant with WS-Security 1.1. The specific

digest and signature methods are not prescribed by the DTS, and will be selected from the valid WS-

Security 1.1-compliant options during implementation.

Although it cannot be strictly enforced by the WSDL, the PESC DTS also specifies that the XML body of a

compliant message be both Zlib compressed and Base64 Encoded. Zlib compression is a ubiquitous form

of compression that is highly effective on text such as XML documents. Its use will serve to drastically

reduce the size of exchanged messages. Base64 encoding is also ubiquitous and is simply a means of

encoding binary data (which Zlib-compressed data is by definition) in a text-based format.

4.5 SOAP Headers The DTS WSDL defines a single operation and two message types that are used for all SOAP messaging;

the operation is submitDTS and the message types are DTSRequest and DTSResponse. The DTSRequest

contains the message a client wishes to send and the DTSResponse is the synchronous (e.g., immediate)

reply returned by the server.

When contacting a DTS web service and executing the submitDTS operation, a client will send a

DTSRequest message composed of a DTSRequestHeader in the SOAP header (along with the required

WS-Security headers information) and a request body containing a compressed and encoded batch of

XML documents as described above. In response, the service will return to the client a DTSResponse

message composed of a DTSResponseHeader in the SOAP header (again, with security elements added)

and a response body.


The DTS WSDL provides a number of elements that are used to define the DTSRequestHeader and

DTSResponseHeader message types, the first being a DTSRouting complex element that is intended to

be used by exchange partners as the means to support defined business agreements surrounding the

exchange of messages. Each message type (request and response) then has additional elements used to

further define the nature of the exchange.

4.5.1 DTSRouting Element

The DTSRouting element is common to both the DTSRequestHeader and DTSResponseHeader. It is a

complex element contains 3 required sub-elements and two that are optional. It provides message

routing information pertinent to the exchange.

Element Required Type Purpose

DTSUUID Y String The UUID is shared between a pair

of request and response messages

to facilitate message correlation.

PESC recommendeds that the IETF

Draft UUID Specification be

leveraged for this value.

DTSSourceID Y String The unique identifier for the

message sender, preferably the

same as is used in the XML

Documents (e.g., PSIS Code)

DTSSourceIDSubCode N String This field is not required, not are

its contents prescribed. The PESC

recommendation is that it be used

to capture the name of the

organization that defines the

value used in the DTSSourceID.

DTSRecipientID Y String Similar to the DTSSourceID, the

unique identifier for the message

recipient.

DTSRecipientIDSubCode N String This field is not required, not are

its contents prescribed. The PESC

recommendation is that it be used

to capture the name of the


organization that defines the

value used in the DTSSourceID.

4.5.2 DTSRequestHeader

The DTSRequestHeader element contains the meta-information used to describe a single SOAP Request

message invoking the sendDTS operation.


DTSRequestRouting Y DTSRouting Routing information; see above.

DTSRequestServiceExpectation N String This business-defined value is intended to

identify how the transaction should be

processed.

DTSRequestPayloadType Y String This business-defined value is intended to

identify the type of payload contained in

the SOAP body.

DTSRequestPayloadBytes N String This specification-defined value is intended

to hold the uncompressed bytecount (e.g.,

size) of the payload contained in the

request body. This allows the receiving

system to make an informed decision on a

message processing strategy before

decompressing and extracting what could

be a very large message.

4.5.3 DTSResponseHeader

The DTSRequestHeader element contains the meta-information used to describe a single SOAP

Response message in response to an invocation of the sendDTS operation.


DTSResponseRouting Y DTSRouting Routing information; see above.

DTSResponsePayloadType N String This business-defined value is intended to

identify the type of payload contained in

the SOAP body.


DTSResponseAcknowledge Y String This business-defined value is intended to

identify how the service has or will handle

the request payload.

DTSResponsePayloadBytes N String This specification-defined value is intended

to hold the uncompressed bytecount (e.g.,

size) of the payload contained in the

request body. This allows the receiving

system to make an informed decision on a

message processing strategy before

decompressing and extracting what could

be a very large message.

4.6 Message Creation Process Flow The message creation process flow describes how exchange partners are expected to create the

messages used to request and fulfill transcript requests and how the eTS will generate response

messages for synchronous responses to request messages.


4.6.1 Request Messages from Partners to the eTS

To create an appropriate SOAP request message, the message sender will perform the following steps:

1. Create each of the XML documents required to create a batch; depending on the partner and the point in the overall exchange, this may be Transcript Request Documents, High School Transcript Documents and/or Transcript Response Documents, Functional Acknowledgement Documents and/or Transcript Acknowledgement Documents.

2. Create an AcademicRecordBatch XML document and:

a. Populate the BatchEnvelope element with appropriate information;

b. Concatenate all of the other XML documents together and insert the result into the BatchContent element; and,

c. Zlib compress the entire AcademicRecordBatch XML document and then Base64Encode the result.

3. Create an empty SOAP message and:

a. Populate the DTSRequestHeader with message metadata per business rules and the DTS;

b. Insert the DTSRequestHeader into the SOAP header;

c. Insert the compressed and encoded AcademicRecordBatch XML document into the SOAP body;

d. Populate the timestamp in the header; and,

e. Populate the binary security token (public certificate) in the header.

4. Create a digital signature for the message:

a. Create a digest of the SOAP message;

b. Encrypt the digest with the private key; and,

c. Insert the encrypted digest into the SOAP header.

4.6.2 Response Messages from the eTS to Partners

To create an appropriate SOAP Response message, the eTS will perform the following steps:

1. Create an appropriate response XML Document if necessary (the need for a response document will be determined later in the detailed design phase); the response body could be a Functional acknowledgement or it could simply be an empty string.

2. Zlib compress the response document and Base64 encode the result.

3. Create an empty SOAP message and:


a. Populate the DTSResponseHeader with message metadata per the business rules and the DTS;

b. Insert the DTSResponseHeader it into the SOAP header;

c. Insert the compressed and encoded response XML document into the SOAP body;

d. Populate the timestamp in the header; and,

e. Populate the binary security token (public certificate) in the header.

4. Create a digital signature for the message:

a. Create a digest of the SOAP message;

b. Encrypt the digest with the private key; and,

c. Insert the encrypted digest into the SOAP header.

4.7 Message Flow – Atomic The below diagram illustrates the current understanding of how individual messages will flow from

transcript consumers to transcript producers and back again.


4.8 Message Flow – Process The below diagram illustrates the current understanding of the process for transcript fulfillment will

work will not be used. Each transaction arrow corresponds to one of the atomic flows depicted in the

diagram above – either consumer to producer via eTS or producer to consumer via eTS. Additional

business design and agreements will be needed to determine the number and nature of

acknowledgments.


5 High-Level Application Design

This section consists of a very high-level overview of the components that are expected to be required

as part of the design and implementation of the eTS. Because the expectation is that the eTS will be

enhanced and updated over time to support additional exchange types (e.g., College Transcripts) and

exchange partners (e.g., private schools), the components of the system are couched in terms of

“services” each of which has a defined purpose and each of which may be comprised of multiple

components. This is intended as a means to clearly separate the logical aspects of message processing

and not necessarily to enforce a particular architecture. Regardless of the architectural approach and

implementation decisions (e.g., standalone Java application, Java 2 Enterprise application, Enterprise

Services Bus/Service Oriented Architecture implementation), this will hopefully support a design that is

flexible and does not require a complete rewrite each time functionality needs to be added.

5.1 Architectural Guidelines At the time of this writing, the organization with the mandate to create the eTS does not have as part of

its governance structure any adherence to particular architectural guidelines or best practices. If such

guidelines are mandated by the project or implied by another project-related decision (e.g., hosting

platform or hosting provider), this section will be updated to suit.

5.2 Additional Guidelines There are no additional guidelines currently known to be in play for the design and implementation of

the eTS. Such guidelines might include those mandated by the forthcoming Privacy Impact Assessment

(e.g., additional requirements for message encryption) or others that may arise from rendered

decisions, e.g., a hosting provider, or others that may be mandated by a trading partner.

5.3 Pre-Conditions/Code Changes In order to support the exchange of Nova Scotia High School Transcripts in electronic form according to

the PESC High School Transcript schema and to maximize the information passed, changes are required

to the structure and contents of those transcripts.

5.3.1 Course Number

During the preliminary exploration into the viability of the eTS, it was noted that while a course code

system exists for High School courses in Nova Scotia, it is not a standardized encoding and leaves

something to be desired in terms of both machine and human processing.

The eTS Working Group has developed an encoding that will be implemented as part of the data

mapping of High School transcript data to the PESC High School Transcript schema. This encoding is

intended to simplify the process of parsing course information quickly and succinctly.

The proposed format for the code is a 6-character alphanumeric value described as follows:


Characters Attribute Valid Characters

1-3 Course topic Alpha (to be determined)

4 Grade 4 – Grade 12

3 – Grade 11

2 – Grade 10

5 Credit Type A – Academic

V – Advanced

G – Graduation

O - Open

6 Program Type S – Public School Program

I – Individual Program Plan

B – International Baccalaureate

A – Advanced Placement

L – Approved Local Course

D – Independent Study / Professional Development

It will be up to transcript producers (initially EECD) to implement the new course code in their systems

and to map the code into PESC High School Transcript XML documents per the mapping agreed upon

between exchange partners. It will be up to transcript consumers to develop whatever facilities are

required to process this new course encoding.

5.3.2 Graduation Indicator

The current paper-based Nova Scotia High School Transcript does not necessarily contain a firm

indication that a student has graduated. Transcript consumers have expressed the desire to have a field

that definitively indicates that a student has completed the requirements for graduation.

It will be up to transcript producers (initially EECD) to implement this “graduation indicator” in their

systems and to map the indicator into PESC High School Transcript XML documents per the mapping

agreed upon between exchange partners. It will be up to transcript consumers to develop whatever

facilities are required to process this new indicator.

5.4 Inbound Data Exchange Service The Inbound Data Exchange Service is the web service interface that listens for incoming messages from

the exchange partners. It will be a SOAP Web Service that implements the PESC DTS version 2 using the

WSDL provided by PESC. This web service will be the only entry point for data to be exchanged through

the eTS. SOAP Request messages received by this service that do not generate an error will be

forwarded by this service to the Routing and Transformation service.

It should be noted that the nature of the eTS as an intermediary interested only in passing

messages between exchange partners necessarily means that it cannot validate the mapping

of data into the various schemas required for data exchange. The eTS may be capable of

validating an individual XML document against the declared schema, but this is not the same

as validating the contents of a particular field or fields against business rules or logic.


5.4.1 PESC Data Transfer Standard WSDL

PESC provides a Web Services Definition Language (WSDL) document that can be used to create a DTS-

compliant web service. It is recommended that this WSDL be used unmodified to create the listening

web service for the eTS. Doing so should minimize the effort involved in integrating with additional

external partners, especially if those partners have already done previous PESC integrations.

As with all WSDL documents used to define SOAP services, the DTS WSDL effectively creates a contract

that must be fulfilled in order for messages to be passed.

Full details of the DTS version 2 are available in the PESC documentation, specifically the document

entitled “Data Transport Standard v 2.0 Specification.”

The current version of the DTS WSDL is included in Appendix A of this document for reference.

5.4.2 Validation and Error Handling

The PESC DTS Specification provides a complete SOAP error handling definition using SOAP faults that

will need to be implemented as part of the Inbound Data Exchange Service. Doing so will ensure that

errors are caught in a timely fashion.

Because the DTS describes a synchronous web service, the processing required to validate the message

against the error handling requirements will need to be performed immediately upon receipt of the

message.

5.4.2.1 Non-SOAP Errors

Several types of errors are possible outside the SOAP specification, generally occurring before a message

sending event is complete. These types of errors include:

TCP/IP Errors

HTTP/S Errors

Web Service errors generated natively by programming toolkits (SDK)

These errors will be reported and handled in the fashion standard to their nature, generally by the

underlying components (e.g., Web Server for HTTP/S errors).

5.4.2.2 Validation Checks

According to the DTS, The validation checks that will lead to the return of a SOAP fault include:

WS-Security – The aspects of WS-Security defined for implementation by the DTS must validate, including:

o The presence of the required elements, including Timestamp, Binary Security Token and Digital Signature as well as the elements required to support them;


o The validation of the sender’s public key included as a Binary Security Token, including that the certificate chain is valid and leads to a recognized provider, that the certificate is not expired and that the certificate has not been revoked; and,

o The validation that the digital signature is valid: that it decrypts correctly with the sender’s public key and that the message digest compares correctly with a message digest created locally from the message.

SOAP Header Checks

o /DTSRequestHeader – element must be present.

o The following elements must both be present and non-empty: /DTSRequestHeader/DTSRouting/DTSSourceID /DTSRequestHeader/DTSRouting/DTSRecipientID /DTSRequestHeader/DTSRouting/DTSUUID /DTSRequestHeader/DTSRequestPayloadType /DTSRequestHeader/DTSRequestServiceExpectation /DTSRequestHeader/DTSRequestPayloadBytes

SOAP Body Checks

o /DTSRequest – an appropriately compressed and encoded payload must be present (element must be non-empty)

o The decoded and decompressed message payload size, as specified in the header by /DTSRequestHeader/DTSRequestPayloadBytes is larger than the system is configured to handle.

o The contents of the DTS Request element must decode using Base64 without error.

o The result of the Base64 decoding must in turn decompress without error.

If any of the above checks fail, the appropriate SOAP Fault as defined in the DTS specification will be

returned by the Inbound Data Exchange service to the caller instead of a SOAP Response.

5.4.2.3 Additional SOAP Faults

Whereas additional agreements may be put into place regarding what is included in the

DTSRequestHeader sub-elements such as DTSRequestServiceExpectation and DTSRequestPayloadType,

additional SOAP Faults may be defined in the detailed design of the service, for example “Payload type

not supported” to indicate that the eTS does not yet support the type of payload that the client is trying

to send.

5.4.3 SOAP Response Messages

Upon successfully validating a message, the Inbound Data Exchange Service will be responsible for

generating and sending a synchronous SOAP Response message for each SOAP Request message

received.


5.4.4 Logging

All SOAP request messages sent to the web service of the Inbound Data Exchange interface must be

logged. The logged information should include (but may not be limited to):

The timestamp of the receipt of the request message and every other event logged;

The timestamp information included in the SOAP header of the request message;

The UUID included in the SOAP header of the request message;

The source of the message as recorded in the SOAP header of the request message; and,

Any errors that were generated in the reception of the message.

Similar information should be logged pertaining to each SOAP response message sent in response to the

request.

5.5 Message Processing Service The Message Processing Service is responsible for examining the received messages, determining their

type and their ultimate destination and performing any transformations required. It is acknowledged

that for the initial deployment with a single exchange type (e.g., High School Transcripts) the Message

Processing Service will likely have a minimal implementation, however future phases are likely to bring

the need for increased capabilities in this service.

The Inbound Data Exchange Service will be responsible for providing the message to the Message

Processing Service. This will include the previously decoded and decompressed payload included in the

received SOAP message body, but ideally will also include the SOAP header information in order to

maximize the information available. How this is accomplished will be up to the implementation.

5.5.1 Message Classification

Although it ultimately depends on the business design and agreement between exchange partners, the

most likely means of determination for the type of message is the SOAP header element

DTSRequestPayloadType. The /AcademicRecordBatch/BatchEnvelope element does not contain a sub-

element defining the type(s) of document contained in the batch and the XML documents contained in

the BatchContent element of an AcademicRecordBatch document are not guaranteed to be

homogenous.

Additional business design is required to determine the nature of the responses, e.g., what

goes in the Response header and body. This will maximize the chances of making the

response messages meaningful to partners in the data exchange.


5.5.2 Message Routing

For High School Transcript-related exchanges, determination of the message routing will necessarily

involve examination of the payload. There are at least two locations where the destination may be

contained:

The contents of the AcademicRecordBatch/BatchEnvelope/DestinationAgency element; and,

The contents of one (or more) individual XML Documents contained in the AcademicRecordBatch/BatchContent/ element, querying the TransmissionData element that is common to all accepted document types for the identifier of the destination.

Assuming that the BatchEnvelope is being used and all messages in a batch are guaranteed to have the

same destination, the former method is preferred.

5.5.3 Message Transformation

Ideally downstream partner services will allow the eTS to forward batches of messages exactly as they

are received. It is possible, however, that one or more partners may implement an exchange service that

does not accept PESC Academic Record Batch XML Documents. In that case, a transformation will be

required from the Academic Record Batch schema to whatever schema is accepted by the exchange

partner.

If this is the case, a means of identifying what partners require transformation will be required and

available to the Message Transformation component. Message transformation will be accomplished

through the use of a XML Stylesheet Language Transformation (XSLT) that takes a PESC Academic Record

Batch XML Document as an input and produces an XML Document in the required format for partner

compatibility.

5.5.4 Logging

The Message Processing Service should log all messages and all actions taken with each message. At a

minimum the following should be logged:

A timestamp for every event logged;

The UUID of the message for correlation with log messages from the Inbound Data Exchange Service;

The BatchID, if the BatchEnvelope element is present;

An indicator of the message classification (e.g., Transcript Request Batch, Transcript Respone Batch);

An indicator of the message source as taken from the message itself or information provided by the Inbound Data Exchange Service;

An indicator of the routing destination determined for the message;


An indicator of any transformations performed on the message and any subsequent identifiers generated; and,

Any errors encountered during the processing of the message.

5.6 Message Transfer Service The Message Transfer Service will be responsible for repackaging the message in a format suitable for

transfer to its destination, managing a send queue and sending the messages. This service will be highly

dependant on the nature of the partner systems with which it must integrate and thus may be required

to deal with multiple types of partner service (e.g., SOAP web service, RESTful web service, etc.).

5.6.1 Message Creation and Packaging

Message creation and packaging refers to the process of taking the payload that was received and

potentially transformed and then adding whatever additional information is required in order to make

the message acceptable to the service the message will be sent to. This is analogous to what partner

systems do to create a message that will be sent to the eTS.

Each partner will create and publish an appropriate service that will listen for messages; the message

creation and packaging component must be capable of inserting the PESC payload into generated

messages that are compatible with all of these services, regardless of the service type.

5.6.2 Message Queuing

In order to deal with the possibility of a partner endpoint being unavailable for some period of time,

e.g., due to a network or service outage, the eTS must have the capability to queue messages for some

length of time, retrying until a time or attempt threshold is reached and an error message is generated

and returned to the sender. This queue will be implemented within the Message Transfer Service.

5.6.3 Message Sending

The message sending component will be capable of taking a packaged message, adding any last-minute

items (e.g., WS-Security-related elements for compliance with the security model of the downstream

service) and actually sending the message to the listening endpoint of the partner service. This

component will also be responsible for handling any synchronous replies or error messages returned by

the exchange partner.

5.6.4 Logging

The Message Transfer Service should log all messages and all actions taken with each message. At a

minimum the following should be logged:

A timestamp for every event logged;

The newly-generated UUID of the message for correlation with log messages;

The BatchID, if the BatchEnvelope element is present for correlation purposes;


An indicator of the message classification (e.g., Transcript Request Batch, Transcript Respone Batch);

An indicator of the original message source;

An indicator of the message destination;

An indicator of any actions performed on the message and any subsequent identifiers generated;

A log entry for each attempt to send the message; and,

Any errors encountered during the processing of the message, including those returned by the downstream service.

5.6.5 Errors

The Message Transfer Service will be responsible for reporting errors back to the original sender of a

message. This will necessarily include both any errors returned by the downstream exchange service

when an attempt is made and errors specifying failure to forward the message due to an issue in

communicating with the downstream service at all.

Although this will need to be formally decided as part of the business design, it is likely that the PESC

Functional Acknowledgement schema can be used to generate error messages to be returned to the

original message sender in the event that a payload cannot be delivered to the desired partner.

5.7 Administration Interface Other than the Inbound Data Exchange interface, the administrative interface will be the only means of

interaction with the eTS and the only one with a user interface. This interface is not intended to be full-

featured, but must provide certain functionality in order to assure that the business requirements are

met.

5.7.1 User Access

As described elsewhere in this document, user access to the Administration interface will be protected

with username and password authentication and all interactions will take place over encrypted HTTPS

connections.

Because there is not anticipated to be a large number of users with access to the administrative

interface user management (e.g., user creation, modification and deletion) is expected to be either built-

in to the eTS or leveraged from the platform upon which it is built.

Access levels are not expected to be complex and either a one- or two-tier access model should be

implemented. In the case of a two-tier model, the only difference in access levels will be the ability to

manage other users in the system.


5.7.2 Queue Viewing

Users with access to the Administrative interface will be granted the ability to view the queue of

messages waiting to be sent to downstream partners. The information that expected to be presented in

the interface includes:

Timestamp indicating when the message entered the queue;

Destination of the message;

Original source of the payload included in the message;

Message type (e.g., Transcript Request Batch, Transcript Response Batch, Acknowledgement);

An indication of how many attempts to send the message have previously been made; and,

An indication of why the message has not yet been sent (e.g., brief error message from previous attempt).

Information about messages that have successfully sent should appear in the queue viewer for a period

of time after sending. Similarly, messages that have failed permanently and will not be attempted again

should also continue to appear for a time in this interface.

The interface will support sorting and filtering of the queue display.

5.7.3 Log Viewing

Similar to the Queue Viewing interface, a basic Log Viewing interface will be available to view the log

messages generated by the eTS. This should allow for a more detailed examination of events in the

system. Log messages should include all information available from the relevant log entries and the

interface should support sorting and filtering of the log display.

5.7.4 Configuration

There are various elements of the operation of the system that are expected to be configurable. These

include, but are not limited to:

Service addresses for downstream partner exchange services;

Message types for downstream partner exchange services;

Number of retries to attempt when sending a message to a downstream partner;

Total queue time allowed when sending a message to a downstream partner; and,

The ability to disable data exchange.

An interface will be required to manage these configuration items through the web interface.


5.7.5 Logging

As with the rest of the application, the administrative Interface should log events that take place within

its functional areas. This should include at minimum:

A timestamp for all events;

An identifier for the user associated with the event; and,

Any configuration changes made by the user.

These logs should themselves be visible in the Log Viewing interface.

5.7.6 Disabling Data Exchange

It is a common practice for message-passing systems to require a means by which data exchange can be

disabled. This capability can be required for a myriad of reasons, including:

The detection of a security issue and the need to prevent the transport of personal information until the issue can be investigated and addressed;

An issue with communications to one or more exchange partners that makes the acceptance of further messages problematic and likely to create a queue of messages waiting to be sent; and

In preparation for a service outage that will affect the eTS.

Towards the end of handling these situations and potentially others, it is recommended that the eTS

have the following capabilities built-in to the administration interface with respect to disabling data

exchange:

The ability to selectively disable delivery attempts to each exchange partner; and,

The ability to disable the listening web service that receives messages from all exchange partners.

These capabilities should be mutually exclusive so that, e.g., if listening is disabled, queued messages

can still be delivered until the queue is drained.

It is not anticipated as a requirement that the eTS be able to selectively disable receiving messages

destined for a particular partner.


1 Appendix “A” – DTS version 2.0 WSDL


      <wsdl:definitions targetNamespace="urn:org:pesc:datatransport" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="urn:org:pesc:datatransport" xmlns:intf="urn:org:pesc:datatransport" xmlns:tns="urn:org:pesc:datatransport" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsdl:types> <xsd:schema elementFormDefault="qualified" targetNamespace="urn:org:pesc:datatransport" xmlns:tns="urn:org:pesc:datatransport" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:import namespace="ttp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" schemaLocation="http://docs.oasis-open.org/wss/v1.1/oasis-200401-wss-wssecurity-secext-1.0.xsd"/> <xsd:element name="DTSRequestHeader"> <xsd:complexType>

<xsd:all> <xsd:element maxOccurs="1" minOccurs="1" name="DTSRequestRouting" type="tns:DTSRouting"/> <xsd:element maxOccurs="1" minOccurs="0" name="DTSRequestServiceExpectation" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="1" name="DTSRequestPayloadType" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="0" name="DTSRequestPayloadBytes" type="xsd:string"/>

</xsd:all> </xsd:complexType> </xsd:element> <xsd:element name="DTSResponseHeader">

<xsd:complexType> <xsd:all> <xsd:element name="DTSResponseRouting" type="tns:DTSRouting"/> <xsd:element name="DTSResponseAcknowledgement" type="xsd:string"/> <xsd:element name="DTSResponsePayloadType" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="0" name="DTSResponsePayloadBytes"

type="xsd:string"/> </xsd:all> </xsd:complexType>

</xsd:element> <xsd:complexType name="DTSRouting">

<xsd:all> <xsd:element maxOccurs="1" minOccurs="1" name="DTSUUID" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="1" name="DTSSourceID" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="0" name="DTSSourceSubCode" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="0" name="DTSRecipientID" type="xsd:string"/> <xsd:element maxOccurs="1" minOccurs="0" name="DTSRecipientSubCode" type="xsd:string"/>

</xsd:all> </xsd:complexType>


<xsd:element name="DTSRequest" type="xsd:string"/> <xsd:element name="DTSResponse" type="xsd:string"/> </xsd:schema> </wsdl:types> <wsdl:message name="DTSRequest">

<wsdl:part element="tns:DTSRequest" name="DTSRequest"/> </wsdl:message> <wsdl:message name="DTSResponse">

<wsdl:part element="tns:DTSResponse" name="DTSResponse"/> </wsdl:message> <wsdl:portType name="submitDTS">

<wsdl:operation name="submitDTS"> <wsdl:input message="tns:DTSRequest"/> <wsdl:output message="tns:DTSResponse"/> </wsdl:operation>

</wsdl:portType> <wsdl:binding name="submitDTS" type="tns:submitDTS">

<wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

<wsdl:operation name="submitDTS"> <wsdlsoap:operation

soapAction="http://www.datatransportstandard.com/submitDTS"/> <wsdl:input> <wsdlsoap:body use="literal"/> <wsdlsoap:header message="tns:DTSRequestHeader" part="DTSRequestHeader"

use="literal"/> </wsdl:input> <wsdl:output> <wsdlsoap:body use="literal"/> <wsdlsoap:header message="tns:DTSResponseHeader" part="DTSResponseHeader"

use="literal"/> </wsdl:output> </wsdl:operation>

</wsdl:binding> <wsdl:service name="submitDTS">

<wsdl:port binding="tns:submitDTS" name="submitDTS"> <wsdlsoap:address location="http://localhost:8080/DTS2.0/services/ReferenceImplementation"/>

</wsdl:port> </wsdl:service> </wsdl:definitions> 1111111111111