Participant Data Specification — XML

General Information

Purpose of This Document

This document details the content and format Morningstar Investment Management LLC supports for Morningstar real-time and batch participant communications with Recordkeepers in XML. If the file is for one of the Morningstar Web Applications, it will be sent real-time. If the file is for one of the offline processes, it will be sent in batch format.

Morningstar uses the data you provide to make retirement planning recommendations for participants. This document outlines the format and definition of the participant level data points used by Morningstar.

Core vs. Wrappers

To integrate with Advice or Advisory services, a core real-time XML will need to be coded for each participant. Once the initial core real-time XML is coded, it can be used across services. Each service may also have additional data required in the XML specific to the access point being used to reach the service, such as the phone representative's ID when accessing Advice through a call center. The additional data required will be coded as a wrapper and sent with the core XML in the same participant real-time XML file. Each time a participant accesses a service, the data from the core XML, along with the data from appropriate wrapper for that service, will be prepopulated for the participant as applicable.

Real-Time Communications

Protocol

SAML 2.0 is the standard single sign-on (SSO) process for Morningstar^® Retirement Manager^SM. Using this method, the participant first logs into the client website. Upon clicking the Morningstar link from the client website, the participant will be taken to the Morningstar^® Retirement Manager^SM home page without needing to log in again to access Morningstar^® Retirement Manager^SM. When the participant clicks on the single sign-on link, the client will populate the SAML packet used for single sign-on with the participant real-time XML file containing the participant's information. On receipt of the SAML packet and after successful processing of the SAML assertation, the participant will be automatically logged into the Morningstar^® Retirement Manager^SM website. During the participant log in to the site, Morningstar will invoke the participant information web service hosted by the client to retrieve participant information, which will be used to pre-populate the Morningstar^® Retirement Manager^SM intereface.

For participants use the HTTPS post SSO method to link directly from their plan provider/plan sponsor website, Morningstar Web Applications need to receive the complete URL that will be used to call back to the provider or record-keeper to retrieve and/or send information during Seamless Log-in. This URL will be sent as a parameter in Seamless Log-in using HTTPS. The data exchange is done on a per-user and plan basis. For complete details on the data retrieval process, please refer to the Single Sign On Specification document.

Batch Communications

Protocol

You will prepare the batch XML file to our schema specifications for the Proposal and Managed Accounts. (Note that “Proposal” is the new product name for Statement/Offer Letter). If the client gets Progress Reports as part of the Managed Accounts service, the batch files sent for quarterly batch processing will also be used as input files for the Progress Report generation process.

Files are uploaded to Morningstar using the ftp service (ftp.morningstar.com). A User Name and Password will be assigned during implementation. PGP encryption and SSL FTP can be used for additional security.

Update Procedures and Data Validation

On an ongoing basis, Morningstar must receive complete batch transfers of all participant-level data. Even if only one data item is changed, all data should be included. For Managed Accounts, the data transfer should be done when there are any new participants, participants that have changes, and/or on a quarterly basis for quarterly portfolio rebalancing, Progress Report processing (if applicable), and annual portfolio review. For the Proposal, Morningstar must receive a complete participant batch file containing all participants who are to receive a Proposal for the given Proposal run.

File Naming Convention

One XML file can contain multiple participants.

For Managed Accounts, Morningstar recommend using the file name “ClientID_MA_part_date.xml”. The ClientID is the assigned by Morningstar.
When sending test files, please use file names that differentiate them from Production Files, such as “ClientID_MA_part_date_test.xml” for Managed Accounts.
If a single participant Managed Accounts batch file is very large (e.g. larger than 100MB), you may split the data into several files named “ ClientID_MA_part_date_time_1.xml”, “ClientID_MA_part_date_time_2.xml”, etc, by appending sequence numbers to them. Use the same file names for each subsequent update.
For Proposal, Morningstar recommend using the file name “ClientID_ST_part_date.xml”. The ClientID is the four-digit code assigned by Morningstar.
When sending test files, please use file names that differentiate them from Production Files, such as “ClientID_ST_part_date_test.xml” for Proposal.
If a single participant Proposal batch file is very large (e.g. larger than 100MB), you may split the data into several files named “ClientID_ST_part_date_time_1.xml”, “ClientID_ST_part_date_time_2.xml”, etc, by appending sequence numbers to them. Use the same file names for each subsequent update.

File Processing

On an ongoing basis (depending on how frequently you send your files), Morningstar will retrieve your batch file from our FTP server and import the data into the database. We will set times to load the files depending on the schedule for generating the Proposal or implementing Managed Accounts transactions. If the batch file does not conform to our schema, or if there are errors in the XML syntax, the batch import process will fail, and the file will not be imported. The Morningstar team will work with you to identify and resolve any processing errors that occur.

Additionally, the participant batch import process will also generate error reports for critical data that is missing or invalid. The Morningstar team will send these error reports to you so that they may be corrected.

Real-Time and Batch Communications

Important Notes

Only those fields marked “required” are required fields in the schema. However, we recommend that you provide us with all the requested data, as it greatly improves the user experience.
You should validate your data transfers against the schema called ExternalParticipantData_3.1.xsd to ensure that they are well formed and valid.
Any string longer than the length limit will be considered an error, and the participant would appear in the error report in the output directory on the FTP site.
If you have no value on your system for a particular data element, either omit the element tag altogether or send a NULL value, but do not send a zero. Zero will be treated by our system as a value.
The XML file(s) should follow the element sequence defined in the schema.

How to Read the XML Schema

You will receive a file of the schema for the XML Participant Data Specification called ExternalParticipantData_3.1.xsd. The purpose of the schema is to explain which elements may appear in the XML file, how they will appear, and what the elements’ contents are. Following this section is the schema for the Morningstar XML Participant Data Specification. In the schema, there will also be a brief text description of what the element is. This description will appear with the following syntax:

<xs:annotation>

<xs:documentation>description</xs:documentation>

</xs:annotation>

Validating the XML File with the Schema

The XML document sent by the client will be validated against the schema that is sent to the client during implementation.

Detailed Element Descriptions

Loading table data...

XML Wrappers

Participant XML data must be sent to us for Real-time single sign on, the Call Center offering, and the Proposal offering. The data in the following examples are nearly the same, but the top level XML node will change based on the offering to the RTParticipantinput, STParticipantinput, or CTParticipantinput.

Real-Time Wrapper

This wrapper is sent if the user logs into the Web Application via seamless login.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="http://www.morningstar.com/retirement" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns="http://www.morningstar.com/retirement" elementFormDefault="qualified" attributeFormDefault="unqualified" id="RealTimeParticipantInput">
	<xs:include schemaLocation="ExternalParticipantData_3.1.xsd"/>
	<xs:element name="RTParticipantInput">
		<xs:annotation>
			<xs:documentation>Description of a participant definition batch file</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence maxOccurs="unbounded">
				<xs:element name="ParticipantData">
					<xs:annotation>
							<xs:extension base="ParticipantDataType"/>
						</xs:complexContent>
					</xs:complexType>
				</xs:element>
			</xs:sequence>
			<xs:attribute name="TimeStamp" type="xs:dateTime" use="required"/>
			<xs:attribute name="ReturnCode" type="xs:int" use="required"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="ParticipantData">
		<xs:annotation>
			<xs:documentation>Data for individual participant</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:complexContent>
				<xs:extension base="ParticipantDataType"/>
			</xs:complexContent>
		</xs:complexType>
	</xs:element>
</xs:schema>

Loading table data...

Real-Time Call Center Wrapper

This wrapper is required in the real-time file if a Call Center representative is seamlessly logging in on behalf of a participant (for the Advice, Guidance, or Managed Accounts service options through a Call Center).

<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="http://www.morningstar.com/retirement" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns="http://www.morningstar.com/retirement" elementFormDefault="qualified" attributeFormDefault="unqualified" id="CallCenterParticipantInput">
	<xs:include schemaLocation="ExternalParticipantData_3.1.xsd"/>
	<xs:element name="CCParticipantInput">
		<xs:annotation>
			<xs:documentation>Description of a participant definition batch file</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence maxOccurs="unbounded">
				<xs:element name="ParticipantData">
					<xs:annotation>
						<xs:documentation>Data for individual participant</xs:documentation>
					</xs:annotation>
					<xs:complexType>
						<xs:complexContent>
							<xs:extension base="ParticipantDataType"/>
						</xs:complexContent>
					</xs:complexType>
				</xs:element>
			</xs:sequence>
			<xs:attribute name="TimeStamp" type="xs:dateTime" use="required"/>
			<xs:attribute name="ReturnCode" type="xs:int" use="required"/>
			<xs:attribute name="PhoneRepID" use="required">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:maxLength value="24"/>
						<xs:minLength value="1"/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
	<xs:element name="ParticipantData">
		<xs:annotation>
			<xs:documentation>Data for individual participant</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:complexContent>
				<xs:extension base="ParticipantDataType"/>
			</xs:complexContent>
		</xs:complexType>
	</xs:element>
</xs:schema>

Loading table data...

Proposal Wrapper

This wrapper is used when the file is for the Proposal process.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="http://www.morningstar.com/retirement" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns="http://www.morningstar.com/retirement" elementFormDefault="qualified" attributeFormDefault="unqualified" id="StatementParticipantInput">
	<xs:include schemaLocation="ExternalParticipantData_3.1.xsd"/>
	<xs:element name="STParticipantInput">
		<xs:annotation>
			<xs:documentation>Used in batch process for statement participant</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence maxOccurs="unbounded">
				<xs:element name="ParticipantData">
					<xs:annotation>
						<xs:documentation>Data for individual participant</xs:documentation>
					</xs:annotation>
					<xs:complexType>
						<xs:complexContent>
							<xs:extension base="ParticipantDataType"/>
						</xs:complexContent>
					</xs:complexType>
				</xs:element>
			</xs:sequence>
			<xs:attribute name="TimeStamp" type="xs:dateTime" use="required"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="ParticipantData">
		<xs:annotation>
			<xs:documentation>Data for individual participant</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:complexContent>
				<xs:extension base="ParticipantDataType"/>
			</xs:complexContent>
		</xs:complexType>
	</xs:element>
</xs:schema>

# Participant Data Specification — XML

# General Information

# Purpose of This Document

# Core vs. Wrappers

# Real-Time Communications

# Protocol

# Batch Communications

# Protocol

# Update Procedures and Data Validation

# File Naming Convention

# File Processing

# Real-Time and Batch Communications

# Important Notes

# How to Read the XML Schema

# Validating the XML File with the Schema

# Detailed Element Descriptions

# XML Wrappers

# Real-Time Wrapper

# Real-Time Call Center Wrapper

# Proposal Wrapper

Participant Data Specification — XML

General Information

Purpose of This Document

Core vs. Wrappers

Real-Time Communications

Protocol

Batch Communications

Protocol

Update Procedures and Data Validation

File Naming Convention

File Processing

Real-Time and Batch Communications

Important Notes

How to Read the XML Schema

Validating the XML File with the Schema

Detailed Element Descriptions

XML Wrappers

Real-Time Wrapper

Real-Time Call Center Wrapper

Proposal Wrapper