Home > Calculation Setup > Output Definitions

Output Definitions

Output Definitions are instructions to ProAdmin for selecting and storing calculation results as well as basic member data. The results can later be used to provide individual member information via web pages, estimate letters to terminating members, annual statements, etc. This gives you the flexibility to customize the results to meet the requirements for the delivery of the information. When you click on an existing entry, or on the New button the Output Definitions dialog box is displayed with the following:

Name is a text field in which to enter a helpful descriptive name that the entry will be known as in the library. This may be any phrase, including spaces. All characters are available.

Application Type defines which of the three possible types of Output Definition library entries applies to the current item: Server, Desktop (Access) or Desktop (XML).

Server type Output Definitions are used in conjunction with ProAdmin Server, where benefit calculation requests are sent through input XMLs and results are written to output XMLs. Server-type Output Definitions must contain an XML Output Linkage that defines the structure of the output XML. The name of Server type Output Definitions is preceded by an SRV designation within ProAdmin and, when run as an estimate, a final calculation or a date/age/service calculation within ProAdmin, can be saved to Excel, CSV or a text file. If you want to check what will be written to XML on the Server, make a copy of the Output Definition and change its type to Desktop (XML). Everything but the Input Pass Thrus will be available (for Server, Input Pass Thrus are defined in the XML Output Linkage; for Desktop XML, they are defined in the Output Definition). If you want to see these Input Pass Thrus in the output XML, you can add each one to the Output Definition and link it to the appropriate Input Pass Thru in the XML Output Linkage. Now, if you use this Desktop (XML) Output Definition in a calculation, after viewing the Output Definition results, you have the option of saving the results to XML.

Desktop (Access) type Output Definitions are used when the output data is to be stored in an Access database. The access database structure created can be used with the Fulfillment Tool as well as other writing applications. The name of Desktop (Access) type Output Definitions is preceded by an ACC designation within ProAdmin and, when run on ProAdmin Desktop, can also be saved to Excel, CSV or a text file.

Desktop (XML) type Output Definitions are used when the output data is to be stored in an XML file. Each Desktop (XML) type must have an entry from the XML Output Linkage library that defines the structure of XML file. The name of Desktop (XML) type Output Definitions is preceded by an XML designation within ProAdmin and, when run on ProAdmin Desktop, can also be saved to Excel, CSV, a text file or an XML file.

Select an XML Output Linkage, available for Server or Desktop (XML) application type Output Definitions, is a multi-choice field box that allows you to select an entry from the XML Output Linkage Library. The XML Output Linkage defines the fields to which the calculation results will be mapped. Note, two XML Output Linkages may appear to be identical, but their internal ids for their Plan Dependent and Input Pass Thru fields may differ, so if you have an Output Definition, and switch the XML Output Linkage, the Output Definition fields may change without explanation (because the internal ids are different). That's why the the internal ids are shown in the XML Output Linkage -- it's easy to see why something changes. Since the internal ids are shown on the XML Output Linkage view as well, it is easy and advisable to compare XML Output Linkages before changing the reference in an Output Definition to make certain that only the desired changes are made.

The Output Fields section lists each of the fields that will be included in the output in a sortable listview with the following columns:

Type indicates the type of output: BEN for benefit detail, DAS for date, age or service output, IPT for an input pass thru or STD for a standard ProAdmin output field.

Field, applicable to the Desktop (Access) application type, is the name of the Access table column to which the results will be written.

XML Output Field, applicable to Server and Desktop (XML) application types, is the name of the XML Output Field where the results will be written.  This field is blank for Input Pass Thru output that is written directly to XML tags.

@, applicable to Server and Desktop (XML) application types where the selected XML Output Linkage includes fields with the PADescription attribute, indicates whether the field will use its Description as an attribute in the XML output. 

n, applicable to Server and Desktop (XML) application types where the selected XML Output Linkage includes fields that are nillable in the XML Schema and where "Write nillable nodes to the XML output" is checked, indicates whether the field is nillable.  This is relevant, for example, if cash balance output is nillable and the participant is not eligible for the cash balance benefit.  Note that other nillable fields in the XML Schema not referenced in the Output Definition will also be included in the XML output if they are in an XML node to which other results are being written.

Description is the output field's description.  This is also what is written out as a field attribute for Server and Desktop (XML) application types if the at sign (@) is present in the @ column.

Varies by, applicable to Server and Desktop (XML) application types, indicates whether the results will vary by decrement, commencement, or payment form.  If this column is blank (such as for an input pass through), the results will be included at the top of the XML results before the "varies by" sections.

Doubleclick on the name of an output field or click on the name and then click the Edit... button to edit it, or click the Add… button to create a new output field of one of the following types of output fields:

Benefit Detail, denoted by the prefix BEN, is available for all Application Types.

Date/Age/Service, denoted by the prefix DAS, is also available for all Application Types.

Input Pass Thru, denoted by the prefix IPT, is only available for the Desktop (Access) and Desktop (XML) Application Types. Each Input Pass Thru can be a scalar (i.e., a single value) or an array. Input Pass Thrus for the Server Application Type are defined in the Output Definition's XML Output Linkage, not here in the Output Definition.

Standard, denoted by the prefix STD, is only available for the Desktop (Access) Application Type.

Checking the Exclude Date/Age/Service output when ineligible for benefits checkbox suppresses all output of the date/age/service type for members not eligible for any benefit. By definition there is always no Benefit Detail type output for these participants.

Checking the Include interest rate details in the output checkbox will add the following information to your Output Definition results:

For each Interest Rate Table referenced in the calculation, (e.g., actuarial equivalence and benefit formula components):

A summary of the interest rates actually used in the calculation for each output item that references interest rates. These values reflect any constant amounts, database fields, minimums, maximums, projections and overrides, in addition to any underlying interest rate tables. The following is provided:

Note, that an entity will only appear if it is actually used in the calculation, and it will only appear in both sections if it references an Interest Rate Table (directly or indirectly). For example, a Cash Balance component which only uses a constant 6% interest rate will only appear in the interest rates in use section, and not the table references section.

If you are using either the Desktop (XML) or Server application types, the interest rate detail will be added to the output XML within the decrement level container. The interest rate detail requires a specific XML structure which is provided in the technical reference article  "Reserved XML Elements".

Checking the Include Plan Constants in the output checkbox will add any Plan Constants used in your calculation to your Output Definition results. For an Access Output Definition, Plan Constants are written to the Results_which_do_not_vary_by_Commencement_Date table where the column names are the Plan Constant names (e.g., @Test1) and the values are written to the appropriate columns. For Desktop (XML) and Server Application Types, you need to add the ProAdminPlanConstants XML element from the technical reference article  "Reserved XML Elements" to your XML Output Linkage's schema (above the payment form level). Then, the name (e.g., @Test1) and value of each Plan Constant used in the calculation will appear within the ProAdminPlanConstants container. 

For Desktop (XML) or Server Application Types, you can check the box to Use an XSL stylesheet to transform the XML results.  When this option is selected, ProAdmin will first create a standard XML document from your Output Definition's calculation results and then use it to create the final XML in accordance with the stylesheet, making the XML documents generated by ProAdmin easier for your external systems to consume. For example, you could use an XSL stylesheet to move an input pass thru from the decrement level into every payment form, or you could use it to combine 2 or more payment forms into a single payment form.

Clicking on the XSL Stylesheet button will display three choices:  Import, Export and View.

Clicking Import brings up the Import XSL Document dialog, allowing you to browse to and select the XSL stylesheet that you need. After selecting the XSL stylesheet, which may have either a .xsl or a .xslt extension, click the Open button. A message will display indicating if the import was successful.

Clicking Export displays the Export XSL Document dialog box. On this dialog box, you can browse to a folder and enter the name for the XSL stylesheet that you are exporting. After selecting the file, click on the Open button. If the file name that you entered does not exist, a message box will be displayed asking if you want to create this file. If you select Yes, the XSL document will be created. If you select No, you will return to the Output Definition dialog. 

Clicking View displays a formatted version of the current XSL stylesheet, including the name and path of the originating XSL or XSLT document. You can then print or save the report.

When loading (importing) the XSL stylesheet into ProAdmin, you may pick any file with an *.xsl or *.xslt extension, but the only test is that the XSL stylesheet is valid XML: no XSL validation is performed. Once a stylesheet has been loaded, its name will be displayed at the bottom of the dialog box.

Here is a sample XSL stylesheet that simply copies the XML document, changing nothing:

<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>

  <!-- 
    Copy everything: 
      node() (the document node and all elements, text() nodes, comments, etc.)
      @* all atributes
  -->
  <xsl:template match="node()|@*">
    <xsl:copy>
      <xsl:apply-templates select="node()|@*"/>
   </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

This sample XSL stylesheet combines two different 50% J&S payment forms (payment form codes 50 and 51) into a single 50% J&S payment form and inserts a zero certain period node:

     <?xml version="1.0"?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>

  <!-- Copies everything but PaymentForm nodes -->
  <xsl:template match="node()|@*">
    <xsl:copy>
      <xsl:apply-templates select="node()|@*"/>
   </xsl:copy>
  </xsl:template>

  <!-- Handles all PaymentForm nodes -->
  <xsl:template match="PaymentForm">
    <xsl:choose>
      <xsl:when test="PFCode=50">
        <!-- add 50 and 51 member and beneficiary benefits -->
        <xsl:variable name="JSMem">
          <xsl:value-of select="sum(MemAmount|../PaymentForm[PFCode='51']/MemAmount)"/>
        </xsl:variable>

        <xsl:variable name="JSBene">
          <xsl:value-of select="sum(BeneAmount|../PaymentForm[PFCode='51']/BeneAmount)"/>
        </xsl:variable>
  
        <PaymentForm>
          <MemAmount>
            <xsl:value-of select="format-number($JSMem,'#0.00')" />
          </MemAmount>
          <CertainPeriod>0</CertainPeriod>
          <PFCode>50</PFCode>
          <BeneAmount>
            <xsl:value-of select="format-number($JSBene,'#0.00')" />
          </BeneAmount>
          <JSPercent>0.5</JSPercent>
        </PaymentForm>
      </xsl:when>
      <xsl:when test="PFCode=51">
        <!-- drop this PaymentForm node: 50 and 51 were added together, no longer needed -->
      </xsl:when>
      <xsl:otherwise>
        <!-- Copy everything in these PaymentForm nodes, we don't want to change anything -->
        <xsl:copy>         
          <xsl:apply-templates select="node()|@*"/>
        </xsl:copy>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

</xsl:stylesheet>

This sample XSL stylesheet copies the early retirement factor to each payment form:

   <?xml version="1.0"?>
   <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   <xsl:output method="xml" indent="yes" encoding="UTF-8"/>
   
     <!-- Copy everything but PaymentForm nodes -->
     <xsl:template match="node()|@*">
       <xsl:copy>
         <xsl:apply-templates select="node()|@*"/>
      </xsl:copy>
     </xsl:template>
   
    <xsl:template match="PaymentForm">
       <PaymentForm>
          <xsl:copy-of select="node()|@*"/>
   
          <!-- Copy the early retirement factor node here, but keep it simple! Just use enough of the 
               xpath to uniquely identify the node you want to copy. 
    
                 select="//EarlyRetFactor" finds all nodes named EarlyRetFactor in the xml document
   
                 select="//CalcResults/EarlyRetFactor" finds the nodes named EarlyRetFactor in any 
                 CalcResults sections in the xml document
   
                 You could specify the complete xpath, starting with the root node, but if the 
                 schema changes, then you have more to change/update.
          -->   
   
         <xsl:copy-of select="//EarlyRetFactor"/>
   
       </PaymentForm>
     </xsl:template>
   
   </xsl:stylesheet>

When viewing Output Definition calculation results (for Desktop (XML) or Server application types) you have the option of viewing the XML document that was created and, if used, the XML document created by applying the XSL stylesheet. In the Output Definition calculation result viewer, among the buttons along the top, there is a multi-choice field to display:

Output Definition results:     the Output Definition results

XML results:                           the XML directly from the Output Definition

XML+XSL results:           the XML after the XLS stylesheet is applied.  This option is only available if a stylesheet was referenced in the Output Definition.

You can save any of these views to a file. Note that if there was a problem generating either the XML document (e.g., there is a bug in the XSL stylesheet), you will see the error message instead of the XML document.

?When viewing the results for a Desktop (Access) Output Definition, you have an additional option to export the Output Definition results to a Microsoft SQL database by pushing the MS SQL... button.  (This is equivalent to saving the Output Definition results to an MS Access database). You can use Windows Authentication, SQL Server Authentication or an Encrypted connection string to connect to your SQL database. If using Windows or SQL Server Authentication, you must specify the Server Name and select either an Existing database or Create a new database (and you must supply a new valid database name). For an encrypted connection string, which can only be created through the Database Linkage and then the string copied to this dialog, the server and database specified in the encrypted connection will be used.

Should there be a problem with an encrypted connection, you'll get a general message that there is a problem with your encrypted connection string and to please contact your system administrator. (This was done to prevent encrypted information about the database connection being shown in various ADO error messages.) To determine what is actually causing the problem, you or your system administrator will need to temporarily use an un-encrypted connection string to see the actual ADO error details.

If an encrypted connection string is used, the system administrator may have required that the user be prompted for a userid and/or password.  If this is the case, you will be prompted for the necessary information the first time during the client session that you connect to the database.  Then during the rest of that session, the prompted userid and/or password will be automatically supplied. Every time you logout out of ProAdmin or switch clients, all prompted userids and passwords are destroyed, and you will be re-prompted the first time you connect to the database.