More information

Utilities

Site Specific Notes

Summaries Utility

The Summaries utility is one of two utilities used to create or update a row in the Summaries data table. This action links a Summary name (label) and data together to form a Summary data row. (The Years utility is also available to create or update Summary data rows, using different functions from those available in the Summaries utility.)

There are two steps in the use of the Summaries utility.

  1. Launch the Assign Summary Definition utility interface as a standalone program (outside of your regular Millennium interface) and create any number of possible individual Summary definitions. Save and name the entire set of definitions that you want to apply to the database (as a unit) with the run of a single set of report criteria.
  2. Use the Millennium Reporter to create a set of criteria that will select the constituents for whom the Summary rows will be created/updated, and which will calculate all of the appropriate totals to be used with any Summary definitions that require them. When the report is launched, you will be prompted to choose from the names of the existing sets of Summary definitions that you want to execute for the constituents identified in the work table.

As it processes the Summary definitions, the utility will automatically search for the existence of a Summary data row using the same Summary name, for each selected constituent. If found, that data row will be updated in accordance with the definition being used by the utility. If no matching Summary data row is found for a constituent, a data row of that Summary name will automatically be created.

Utility Classification

This utility alters existing and creates new data rows and is classified as a system administrator Utility.

Background on the Summaries Data Table

The Summaries Utility is used to create or update rows in the Summaries data table. That data table differs from most others in Millennium because data can only be entered or edited in the rows in that table by using this utility or the Years utility, and not by standard data entry techniques. The data that is held in this table is not "new" information that is input. Instead, it is calculated or compiled from data that is already present in the Giving data tables, or it is a descriptor that is assigned to all constituents identified in an export work table.

The standard, and minimal display of a row from the Summaries table consists of a label followed by data. There are additional data fields which your institution may choose to use as well, but they are not part of the standard display. See Additional Summary Fields.

The labels are defined by your institution via the Memory Names lookup table. The entries in this lookup table are available for use in defining the label that will identify a Summary row, and be stored in the memname field in the Summaries data row.

The data may be one of several things. It may be a dollar amount representing a single transaction; a dollar amount that represents the sum of many transactions; a count of a set of transactions; a textual descriptor that you want to assign to a particular Summary such as a giving club name; a count of the years in which a certain type of giving occurred, or the year in which a particular type of giving occurred. If it is a dollar amount or a count, that data is stored in the memamount field in the Summaries data row. If it is a textual descriptor, then it is placed in the memdescrp field, which is driven by the Memory Descriptors lookup table. One or the other of these two fields displays in each Summary row.

For additional information see the topic, Summaries within the Profiles World.

Using the Summaries Utility

When your institution is ready to create and maintain Summary rows in the Profiles World, perhaps the most critical element to the success of that project is careful and detailed planning within your offices on matters that are not strictly part of the operation or function of the software. Due to the nature of this data table, it is vitally important that before the utility is even used, your institution develop a plan for the exact set of Summary definitions that you want to create, that you determine the assignment of responsibilities for the creation and maintenance of this data, and that a plan and schedule for the maintenance of the information be devised and rigorously implemented. It will be of little benefit to your institution to begin this project without the resolve to maintain the information once it has been created. Of course, many Summaries based on historical data would not need to be updated often but others that may include new information should be updated regularly.

For example, if you define Summary rows to show total giving to the Annual Fund for each of the past five years, that data should not be changing and those rows would not need to be updated once the year is passed. A Summary row that shows the current year's giving total to the Annual Fund could be changing daily and if the Summary row is not updated frequently, a user viewing the Summary data could be operating under a false impression of a constituent's current giving.

You should consider such questions as whether you want to maintain all Summary rows for all constituents, only certain constituents, or only certain Summaries for particular segments of your constituency. For those Summaries that show data that is subject to change, you must determine the frequency of your updates. Since Summary rows may show data that is compiled from Giving information, you must determine appropriate security access for the Summaries data table, in accordance with a user's access to the Giving data tables.

When you have defined the kinds of Summary data you want to maintain, you must use that information to update the Memory Names and (if appropriate) Memory Descriptors lookup tables prior to the use of the utility.

We strongly encourage you to create a log book in which you keep a record of each time that the Summaries utility has been run on your system. This log should contain a printout of the report criteria and the Summary options that were used.

Running the Utility

Some of the standard Millennium utilities make use of certain Microsoft applications and associated files. While we ensure that the required applications are present and registered on the IIS machine as part of the installation process, Millennium's thin-client architecture does not install them on every workstation at your institution. Therefore, to ensure success, the Assign Summary Definitions component of the Summaries utility must be executed from the IIS machine. You must be the database administrator (sa or MILLORA user ID) or a Millennium system administrator in order to execute this component of the Summaries utility. (When executing the component that uses Millennium Reporter, the user must have Insert and Update permissions on the memories data table, and the user's security Views on any data tables referenced in the criteria will affect the selection results).

The Summaries utility (the interface used to create and save the definitions) is run outside of the interface you use to access Millennium, in the utility's own application window. It must be activated by locating the program file (Inetpub\WWWRoot\Mill\Tools\AssignSummaryDefinition.exe) using the Windows Explorer or other appropriate tool, and then double clicking the program name.

When you access the utility's interface, you are doing so for the purpose of creating or editing the Summary Definitions. The definitions that you save and name via the utility interface are then available for use in the second step of the process of creating or editing Summary data rows. The definitions are stored in the System Table, memory_definitions. The second step requires the run of a set of criteria in the Millennium Reporter that specifies the Summaries Utility as its output destination (rather than a format). When the criteria is run, you will be prompted with the names of all of the sets of Summary definitions that were created via the Assign Summary Definitions interface, to be applied to the constituents identified in the generic work table that is created by the run of the report. The data rows in the database are not created or updated until that step of the process has been completed.

Utility Interface

The utility form shows the components necessary for you to compose the definitions for a set of Summary rows. These rows will be created or edited by the run of a set of criteria in which you specify the names of the definitions you want to use, for the constituents identified in the work table. Multiple Summary rows can be created or updated by the same run of the criteria and the utility.

There are two distinct areas of the of the utility interface window. The top area is used to Define Numeric Memories and also to define a New Calculation. The second area is used to Define a Memory Descriptor.

When the utility is first opened, it is ready for the creation of a new definition. If you have already been working with the utility interface and have had definitions displayed, you may begin the creation of a new set of definitions by using the New file button or the File, New command from the menu bar.

Define Numeric Memories

At the top of the window and within the Define Numeric Memories area are two lists. One shows the Summary Names that your site assigned through lookup table maintenance, and one to the right shows a list of Totals. Between the Summary Name list and Total list are two option buttons, labeled Add and Replace.

Below that is a task list area that will hold the set of numeric Summary definitions as you construct them.

When linking a Summary Name to a particular Total, you may specify that the numeric value in the Total be added to the current numeric value of that particular Summary, or you may specify that the numeric value in the Total replace the current numeric value of that Summary. This is done using the option buttons Add (add the numeric value of the Total to the current numeric value of the Summary data row of the same name) or Replace (replace the numeric value of the Summary data row of the same name, with the numeric value of the Total that is being linked to that Summary name).

To create a numeric definition, highlight a Summary name in the first list. Highlight a Total in the second list. Activate the preferred option button, either Add or Replace. Next you will click the rectangular Add button to the left of the larger list area just below. You should see your definition in that list, saying something similar to:

Important! When Using the Add (rather than Replace) option: If more than one person is responsible for maintaining Summaries, or if careful attention is not given to when and how Summaries are updated, or if the process is interrupted, you could inadvertently add the same data to an existing Summary more than once or update part of the database but not all that you intended. It may be advisable to re-calculate and replace a Summary rather than using the Add feature if you are uncertain of the control that has been exercised in maintaining Summaries.

To delete a definition from the list, highlight the line you want to erase and click on the Delete button.

The utility interface will not allow you to save this set of definitions until you have assigned at least one Numeric Memory or a Descriptor definition.

Define a Calculation

You may also define Calculations which may be used in the definitions of Summaries, either numeric or descriptors. These can involve Totals or constant numbers or both. To create a new calculation, press the New button to the left of the Calculation list area. The New button and list area are replaced with a frame containing three combo boxes and a command button labeled 'Finished'.

The first and third combo boxes contain lists of all possible Totals and all previously defined Calculations. You may either choose one of those items from the pull-down lists or you may type in a numeric value. Decimals are acceptable but commas are not allowed. The middle list box contains the functions: Plus, Minus, Times, Divide. To define a Calculation, choose or enter values for each of the three text boxes to create an expression. When you have done so, click on 'Finished'. The New button and Calculation List will reappear, showing the Calculation you just defined, along with any others that had been previously defined.

To edit a calculation, double click on its definition in the Calculation List box. The Calculation frame will reappear with the values to be edited in the combo boxes.

To delete a calculation, click to highlight it in the list area and then click on the Delete button to the left.

Once defined, calculations may be used in the definition of Numeric Summaries, Descriptor Summaries, or used in the definition of other Calculations.

Define a Descriptor

The bottom portion of the Summaries Utility window is used to define Summaries that use Descriptors rather than numeric values. Unlike the numeric Summaries, a single descriptor Summary may be defined with a series of conditional statements that you construct, using Totals, calculations, constant numeric values, comparisons (greater than, less than, equal to, between, etc.), Summary Names, and Summary Descriptors.

Example:

If your institution defined giving clubs as Bronze, Silver, and Gold, based on total giving, you might construct Descriptor definitions similar to the following (where Total 1 is defined as the sum of giving transactions, where 'Giving Club' is the Summary Name, and where 'Bronze', 'Silver', and 'Gold' are Memory Descriptors):

To create the definitions for Descriptor Summaries, you must fill in list boxes in the Define A Memory Descriptor area of the window. As you do, a conditional statements will be created.

When the statement is complete and you click on Finished, the individual definition is displayed in the list area below. Unlike numeric Summaries which are defined by a single definition, descriptor Summaries may involve multiple definitions that each define a range to be associated with particular descriptors. Therefore, the descriptor list area could show several lines of definitions referring to the same Summary name. You should take care to ensure that those definitions are mutually exclusive.

Additional Summary Fields

When you have added at least one numeric Summary definition to the display area in the top portion of the main utility window, the Map Additional Summary Fields item in the menu bar will be enabled. This item allows you to define data for the custom fields in the Summaries data table, and associate the definitions with particular Summary Names. At the present, this function is only available for use with numeric Summaries. (They are not available for use with Memory Descriptor definitions, nor for use with Summaries defined by the Years Utility.)

When you click on the item Map Additional Summary Fields in the menu bar at the top of the utility window, a drop down list of the types of data fields is shown. If you click on any of the items in the list, a new, smaller window will open, with text and list boxes specific to the type of field you chose.

Each of the pop-up dialog windows begins with a list box showing the names of all of the Summaries that have been defined in the main utility dialog window, which is still open behind the pop-up. In that main window, they are shown in the list box to the right of the Add and Delete buttons, along with the definition of each. In the pop-up window list boxes, only the names are shown. The mapping process for the additional fields begins when you highlight a Summary Name. There are multiple fields of most of the different types, and you will next need to specify which one you want to define for the highlighted Summary. The types are described below.

Money

A list box shows the fifteen fields that may hold a money amount (memmny1 - memmny15). You may scroll the list to locate the desired one.

To the right are the Add and Replace option buttons. If you click the Add button, when the Summary definitions are used to update the database, the amount defined for this field will be added to the amount that is currently shown for that field in a Summary of that type. If you click the Replace button, when the Summary definitions are used to update the database, the amount defined for this field will replace the value that is currently shown for that field in a Summary of that type.

The item to the right is a list box showing the names of the fifteen possible Totals that may be defined in a set of reporting criteria, and any calculations that have been defined in the main form for this . You may scroll the list and highlight the desired Total or calculation, or you may type a fixed amount into the text box.

When you have highlighted choices or values for each of the items, you must click the rectangular Add button just below and to the left of the display area in the window. This adds that mapping definition to the list of any others that may have already been defined. Once a definition is in place, you may remove it by highlighting it in the display area and clicking the Delete button to the left.

Dates

There ten possible date fields which you may associate with a Summary Name. The pop-up window shows the typical list of the Summary Names, a scrolling list of the names of the fields (memdate1 - memdate10), and a calendar control. After selecting a Summary Name and highlighting one of the date field names, you may use the pull-down lists above the calendar to scroll to and highlight the desired month and year, and then click within the calendar to select the day. When you click on the Add button, the definition will be shown in the display area.

Lookups

A list box shows the three possible lookup table-driven fields (memlookup1, memlookup2, memlookup3). When you highlight one of the field names, the current values from that lookup table are shown in the list box to the right. To map to any of these columns, you must highlight the Summary Name, the field name, the lookup value and then click the Add button to have the definition added to the display area.

Yes No Flags

A scrolling list box shows the names of the four possible fields in the Summaries table which are designed to be a yes/no flag (memyesno1 - memyesno4). To the right is a list box with No and Yes. To map to any of these columns, you must highlight the Summary Name, the field name, either No or Yes, and then click the Add button to have the definition added to the display area.

Campaign Year

There is a single field in the Summaries table designed to hold a Campaign Year designation. To include this in a definition, you must highlight the Summary Name, type in the desired Campaign Year in the box to the right of the expression, 'memcampyr =', and then click the Add button to have it added to the display area.

Comment

There is a single, 4000 character field in the Summaries table, designed to hold any free text comment that you want to associate with a particular Summary. The mapping pop-up window for this field shows the Summary Names and a large text box where you may type or cut and paste a lengthy comment. When you click the Add button to have the definition added to the display area. To conserve space, the entire comment text is not shown in the display area, but instead the expression, 'has been assigned' is shown. To see the entire text, you may use the View button just below the Add and Remove buttons. If you do, another pop-up box appears, showing the entire text of the comment. You may edit the text within that pop-up and use the Save & Close button to preserve your changes.

Text

In addition to the lengthy comment field, each Summary row may have two additional, 255 character, free-text fields (memtext1, memtext2). After highlighting a Summary Name, you may select one of the field names and then type or paste in any free text that you want in the scrolling text box to the right, before using the Add button to have it added to the display area. As with the Comment, the text is not shown, but instead the expression, 'has been assigned' is shown. To see the entire text, you may use the View button just below the Add and Remove buttons. If you do, another pop-up box appears, showing the entire text. You may edit the text within that pop-up and use the Save & Close button to preserve your changes.

For any of the types of additional Summary columns, you may repeat the process of mapping the fields, to associate them with a highlighted Summary Name and chosen data as often as needed. Each field may be mapped once for each Summary Name. Thus, the list box may show mappings for multiple fields into multiple Summaries in the same list.

When the display area shows all of the definitions you want to create for the current type of additional column, you may simply click the Close button in the lower right corner of the pop-up window. This preserves all of the current definitions as shown in the display area.

Saving the Definition

When all of the individual definitions have been created in the utility interface as you intend (both in the main window and in any of the Map Additional Summary Fields pop-up windows), you must save and name the current set of individual definitions as a unit. When you click the Save button or use File > Save you will be prompted to save the entire set with a single definition name of your choosing. When you enter a name (up to 50 characters), the system saves the specifications for each of the individual Summaries in individual rows in the system table, memory_definitions. Each of those rows is identified each with the definition name that you just assigned.

By creating these individual definitions as a set, you then have the ability when the report criteria is run, to specify that the entire set of definitions be applied to the selected constituents, rather than having to specify them individually.

Thus, a saved set of definitions may consist of many individual definitions, or as few as a single definition.

Editing Definitions

A saved set of definitions may be re-opened to enable you to edit individual Summary definitions within it. To do so, you may click on the File Open button or use the corresponding commands from the menu bar. You will be prompted to choose the name of the definition to be opened (the name of the set) from a list box showing the names of all saved definitions. When you click on the desired name, the utility interface will show all of the individual definitions from that set in the appropriate list areas (numeric or descriptors) as well as the definition of any calculations that are part of that definition.

To edit a numeric definition, you may highlight its old definition in the list area and then click on the delete button to remove it, and then create a new definition for that Summary name. Alternately, if you attempt to create a new definition for a Summary name when one already exists, you will be given a message box to that effect. You may remove the old definition and save your new one by confirming your intentions in that message box.

To edit any of the descriptor definitions, double click on the individual definition in the Descriptor list box. The pieces of that definition will be restored to the combo boxes above, for editing. When you have made any desired changes, you may click the Finished button to return that individual definition to the list area.

When all individual edits have been made, you must re-save the entire set of definitions to preserve your changes. Note that you may either save the edited version with the same definition name by using the Save button or the File, Save command, or you may save the edited version with another name by using the File, Save As command.

Using the Summaries Utility to Update Summary Data Rows

Preliminary Procedures

  1. Ensure that you have a current and functional backup of the Summaries data table.
  2. Use the Assign Summaries utility (AssignSummaryDefinition.exe) to review the details of the definition that you plan to use to create or update the data rows. You should verify that all Numeric Summaries and Summary Descriptors that you want to update at this time are included. EQUALLY IMPORTANT - you should verify that those you do NOT want to update are NOT included. The utility will automatically update all Summaries that are part of the definition.
  3. You should verify that any Additional Summary Fields that you have associated with a particular numeric Summary are defined as you intend.
  4. You should also examine the definition and verify that all Totals that are used as part of any definition are correctly defined in the report that you will be running. (Remember that while Totals may be used to define Summaries or Descriptors, the Totals themselves are defined within the Millennium Reporter, not within the Summaries Utility.)
  5. Important! Any Total that is cited as part of a Numeric Memory or Memory Descriptor definition in the Utility but not defined in the report criteria within the Millennium Reporter will be calculated to equal zero and the Summaries Utility will update constituent records accordingly!

  6. After checking the Summaries definition, save it (if not already saved) and close the utility interface.

Assigning Summary Definitions

Defining Numeric Summaries

  1. From the IIS machine, use the Windows Explorer to navigate to mill\tools\AssignSummaryDefinitions.exe and double click on it to launch the utility interface. You will be prompted to make an ODBC connection. Do so using Web SQL. Use either the database administrator (sa or MILLORA ) or a Millennium system administrator User ID and password.
  2. If you want to create definitions for numeric Summaries, click to highlight a Summary name from the first list box.
  3. Click either the Add or the Replace option to indicate whether the utility should add the numeric value to the existing value of the Summary, or replace the existing value with the numeric value as calculated by the run of the criteria and utility.
  4. Choose a numbered Total from the pull-down list that has been (or will be) defined to calculate the appropriate amount for this Summary name, OR choose a Calculation which has been defined in the following area of this interface.
  5. Click the Add button to the left of the list area to add the definition to the list. If desired, repeat this process for any number of additional Summary names.
  6. If desired, click on the Map Additional Summary Fields item in the menu bar (enabled once a numeric Summary has been defined.) From the pull-down list of field types, choose the kind of field that you want to make part of the numeric Summary definition. Use the resulting pop-up window to assign a value to the chosen field name and associate it with a numeric Summary Name. Use the Add button to preserve that assignment. Repeat this process until all such desired assignments have been made, for fields of the same or of alternate types.

Define a Calculation

  1. If desired, click on the New button in the Calculations area. The form will automatically present a set of text boxes.
  2. In the first list box, either choose the name of a Total, a previously defined Calculation, or type in a numeric value.
  3. In the second list box, choose a numeric operator (plus, minus, multiply, divide).
  4. In the third box, choose either the name of a Total, a previously defined Calculation, or type in a numeric value.
  5. Click Finished. The Calculation list box should re-appear, showing the Calculation you just created, automatically named with the next available number.

Define a Summary Descriptor

  1. If you want to define Summaries based on Descriptors, in the first text box choose either the name of a Total, a previously defined Calculation, or type in a numeric value.
  2. In the second list box, choose a comparison (greater than, greater than or equal to, less than, less than or equal to, equal to, not equal to, between, not between). If you choose between, or not between, the following text box will be replaced with a pair of text boxes.
  3. In the next text box(es), choose either the name of a Total, a previously defined Calculation, or type in a numeric value.
  4. In the next text box (following the word, THEN) choose one of the available Summary Names from the lookup table. (Only those lookup entries with a Group of 'desc' will be shown.)
  5. In the final text box, choose one of the available entries from the Summary Descriptors lookup table to complete the conditional statement.
  6. Click Finished to add the conditional statement to the list area just below. Repeat this process to create additional conditional statements until the definition of that Summary Name is complete. You may also create additional conditional statements for other Summary Names.

Saving a Definition

When the utility interface shows all of the definitions for individual Summaries that you want to create as a set, you must save them and assign a name to the entire set.

  1. Click the Save button, or use File > Save, or File> Save As. You will be presented with a pop-up window with a text box for the Summary Definition name.
  2. Type in a name for this set of individual definitions. It may be up to 50 characters in length.
  3. Click OK.

Running the Summaries Utility

The following instructions assume that you are familiar with the use of the Millennium Reporter. For more information about any procedure described in the following steps, use the hyperlinks to read more on that subject.

  1. Use the Millennium Explorer to navigate to the Millennium Reporter and access a Report Form via the item New Criteria, and then the item Custom, or via one of the report library templates.
  2. In the Report Form, click on Options > Report. In the resulting form, the following items are significant for the run of this utility.
  3. The Output List should be set to Utilities.
    The Salutation check box should be unchecked.
    The Address option should be set to None.
    Remove Spouses should be set to No.
    The Worktable format should be set to Generic.
  4. Click OK. You will be returned to the Report Form.
  5. The Formats/Utilities list should now show the utility names. Select the item, Summaries Utility.
  6. Create a name for your report and type it into the Report Name text box. The report name can be up to 50 characters in length. Avoid using punctuation, except for the underscore character, in the report name.
  7. Set up the Report Options. You should use Do not combine spouse names, and Remove duplicates. Deceased options may be set as you want.
  8. Create criteria statements that will identify the constituents for whom the Summary rows should be created or updated. You may use any data table as the key table in the set of criteria.
  9. Define Giving Totals that will identify the transactions that should be considered for the creation of a particular Summary row. It must address each of the following Total components.
  10. Create criteria statements that identify the transactions that should be included in the set of those to be considered for the Total.
  11. Give the Total a descriptive Total Name.
  12. Specify the Options that should be used for including or excluding matching or joint amounts.
  13. Specify the Calculation Amount to be used. This will be the Amount, the Net Present Value, the Asset Amount, or the Pledged Amount.
  14. Specify the Calculation Type for the Total. It may calculate the sum, a count, or identify the largest transaction from the set that are selected by the Total criteria.
  15. If desired, you may create up to fifteen different Totals in the criteria. All of these Totals will be available for use in creating or updating Summary rows.
  16. If desired, you may create additional report criteria statements that use a Total as the field or the object portion of the statement.
  17. When all elements of the report criteria have been set and created, click on the Save As button. Select a report library and assign a name to the report. When that has been successful, click that completion message to return to the report form.
  18. Click the Run button. You will be given a Run Options form.
  19. Choose the User ID for whom the criteria will be run. (Remember that this user must have Insert and Update permissions on the memories table, and that user's security Views on any data tables referenced in the criteria will affect the selection results.)
    Select the Queue you want to use for the run of the report.
    Set Format Names to No.
    the Save Export option may be set as you want, although we suggest that you save the file and print out a list of the Constituent ID's that were affected.
    the Print Criteria option may be set as you want, although we suggest that you print and save the criteria in a notebook as a log.
    You may set the run Priority as you want.
    When all options are set as desired, click on OK. The system will present a Summary Definition Name form.
  20. In the Summary Definition Name form, choose the name of an existing Definition (which may include the definitions for multiple Summary names).
  21. The report will immediately be sent to the Queue, where it will be launched in accordance with the Run Options you specified. You may check on its progress via the Queue Management item in the Millennium Explorer.
  22. Results of each Summaries Utility run are written to a log file named CreateSummariesOut.log. The log will note the utility start date and time, the number of records selected by your criteria, the number of distinct id numbers within the records selected, the number of records read, the number of new Summary rows created, and the number of Summary rows that are updated. SQL or programming errors generated by the utility run will also be noted. If the utility successfully runs to completion, the finish date and time will print. The user monitors this log file by using Windows Explorer to navigate to its location in the Queue directory on the Queue machine. This log will continue to show information about all Summaries Utility runs until it is cleared or deleted. Clear the log by using Windows Explorer to navigate to its location on the Queue machine, open the log, and then delete its contents. Or, use Windows Explorer to navigate to its location on the Queue machine and then delete the file; when the Summaries Utility is next run, a new CreateYearsOut.log will be created.

Top of Page