Plan Data Specification — XML
Purpose of this Document
Morningstar Investment Management LLC uses XML format to receive plan level information for Morningstar Retirement Manager data collection. This document outlines the specific data points as well as the format for each.
Table of Contents
- General Information
- Important Notes
- Plan Level Data: Detailed Element Descriptions
- Detailed Element Descriptions
General Information
Overview
This section covers the fundamental aspects of XML data collection for Morningstar Retirement Manager integration.
Data Collection Process and Delivery Method
Key Steps:
- Morningstar will assign your firm a Client code
- You will prepare the batch XML file to our specifications and include your internal plan identifiers as well as the fund lineups in each plan
- Files are uploaded to Morningstar using the ftp service (
ftp.morningstar.com) - There will be a separate folder for each client's files
Update Procedures and Data Validation
Update Requirements:
- On an ongoing basis, we must receive complete transfers of all plan-level data for any plans that have changes
- Even if only one data item is updated all data should be included for the changed plans
- Ultimately, you control how often you update your data
Naming Convention
File Naming Requirements:
One XML file can contain multiple plans. We recommend the following file naming conventions:
Recommended Naming Patterns
| File Type | Pattern | Description |
|---|---|---|
| Production files | ClientID_plan_date.xml | ClientID is the code that Morningstar creates |
| Test files | ClientID_plan_date_test.xml | Use file names that differentiate them from Production Files |
| Large files (>100MB) | ClientID_plan_date_1.xml, ClientID_plan_date_2.xml | Split data into several files by appending sequence numbers. Use the same file names for each subsequent update |
File Processing
Automated Processing
We will automatically retrieve production batch files from the FTP server. Production files for Morningstar Retirement Manager will be loaded to the database on a daily basis (or less frequent basis, depending on how frequently you send your files).
Test File Processing
If test files need to be loaded from the FTP site, please let the contact at Morningstar know, and the files will be loaded, as it is not an automated process.
Error Handling
| Category | Details |
|---|---|
| Failure Conditions | 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. |
| Error Reports Generated | - Any funds in the batch file are not found in our database - The plan does not meet compatibility requirements - Critical plan data that is missing or invalid |
| Resolution Process | The Morningstar team will work with you to identify and resolve any processing errors that occur. The Morningstar team will send these error reports to you so that they may be corrected. |
How to Read the XML Schema
Schema Files Overview
You will receive two schema files for the Morningstar Retirement Manager XML Plan Data Specification:
| Schema File | Purpose |
|---|---|
PlanBatchImport_3.1.xsd | Explains which elements may appear in the XML file, how they will appear, and what the elements' contents are |
CommonTypes_3.1.xsd | Defines common data types used throughout the PlanBatchImport_3.1.xsd schema |
Element Descriptions
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.
Important Notes
Critical Requirements and Best Practices
| Category | Requirement | Details |
|---|---|---|
| Field Requirements | Required vs Optional | Only those fields marked "required" are required fields. However, we recommend that you provide us with all the requested data, as it greatly enhances the user experience. |
| Data Validation | Schema Validation | You should validate your data transfers against the schema that has been made available to you via your client team to ensure that they are well formed and valid. |
| String Length | Length Limits | Any string longer than the length limit will be considered an error, and the plan would appear in the error report in the output directory on the FTP site. |
| Missing Values | Null Handling | If you have no value on your system for a particular data element, either omit the element tag or send a NULL value, but do not send a zero. Zero will be treated by our system as a value. |
| XML Structure | Sequence Requirements | The XML file(s) should follow the sequence defined in the schema. |
Plan Level Data: Detailed Element Descriptions
Integration Guidelines
In order to provide a meaningful analysis of retirement income goals and investment recommendations for Morningstar Web Applications and offline processes, we recommend that you provide us with as much of the requested information as possible.
Field Requirements and Guidelines
| Field Type | Identification | Description |
|---|---|---|
| Required Fields | "Required?" field | Some data points are required in the schema and must be included in the batch file. These fields will be indicated in the "Required?" field. |
| Optional Fields | "Optional" indication | Other fields are optional, and will be indicated as such. |
| Not Needed | "N/A" in column | Some elements are not needed. When this is the case, "N/A" will appear in the column. |
| Critical Impact | 'Comments' column | Some data points that have a significant impact on retirement income projections and/or recommendations are required if they are applicable to the plan. These fields will be designated as such in the 'Comments' column. |
| Special Situations | 'Comments' column | Some data points may be required in other special situations and are specified accordingly in the 'Comments' column. |
Strategy Report Reference
Throughout this specification, "Strategy Report" is used as the name for the marketing piece used to encourage participants to enroll in the managed accounts (Managed by Morningstar) service.
Handling Missing Critical Fields
We understand that some of these data points may not be available on your recordkeeping system. If you are unable to provide one of these fields, we recommend that you determine a reasonable default value (if a default value is appropriate for the specific data element) and add that value to the batch file for the field. In the event that this approach will not work, the Morningstar team will work with you to evaluate other possible solutions.
Interface and Display Information
| Column | Purpose |
|---|---|
| 'Displayed' Column | Indicates whether that field can be auto-populated in the Morningstar interface for Morningstar Web Applications |
Data Type Guidelines
| Data Type | Accepted Values | Applicability |
|---|---|---|
| Boolean | true/false or 1/0 | For any items that have an 'Element Type' of 'Boolean' |
| All Elements | As specified | Unless otherwise specified in the 'Comments' column, the element is applicable for all types of plans |
Roth Contributions
Understanding Roth Contributions
Throughout this specification, some data points refer to "Roth" contributions, which are a newer, post-tax contribution type that receives tax-advantaged status when money is withdrawn in retirement. This contribution type is only available to certain 401(k), 403(b), and 457(b) plans that choose to offer this option. (This is not to be confused with contributions to a Roth IRA). Roth contributions can be collected as a separate contribution type or bundled.