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.

General Information

General Data Collection Process and Delivery Method

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

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

One XML file can contain multiple plans. We recommend the following file naming conventions:

  • We recommend using the file name “ClientID_plan_date.xml”. ClientID is the code that Morningstar creates.
  • When sending test files, please use file names that differentiate them from Production Files, such as “ClientID_plan_date_test.xml.
  • If a single file is very large (e.g., larger than 100MB), you may split the data into several files named “ClientID_plan_date_1.xml”, “ClientID_plan_date_2.xml” etc, by appending sequence numbers to them. Use the same file names for each subsequent update.

File 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). 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. 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. Additionally, the batch import process will generate error reports for the following events: if any funds in the batch file are not found in our database or if the plan does not meet compatibility requirements. The Morningstar team will work with you to identify and resolve any processing errors that occur.

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

Important Notes

  • 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.
  • 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.
  • 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.
  • 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.
  • The XML file(s) should follow the sequence defined in the schema.

How to Read the XML Schema

You will receive a file of the schema for the Morningstar Retirement Manager XML Plan Data Specification called PlanBatchImport_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. You will also receive a schema to be used in conjunction with the PlanBatchImport_3.1.xsd called CommonTypes_3.1.xsd. The purpose of the CommonTypes_3.1.xsd schema is to define common data types that are 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.

Plan Level Data: Detailed Element Descriptions

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. Please note the following:

  • 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. Other fields are optional, and will be indicated as such. Some elements are not needed. When this is the case, “N/A” will appear in the column.
  • 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.
  • 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. 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.
  • Some data points may be required in other special situations and are specified accordingly in the ‘Comments’ column.
  • The ‘Displayed’ column will indicate whether that field can be auto-populated in the Morningstar interface for Morningstar Web Applications.
  • For any items that have an ‘Element Type’ of ‘Boolean’, the values of true/false or 1/0 can be used.
  • Unless otherwise specified in the ‘Comments’ column, the element is applicable for all types of plans.
  • 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.

Detailed Element Descriptions

Loading table data...