Data Cookbook definition cheat sheet

To jump start creation of a new definition according to Data Cookbook best practices, copy the Generic Definition Template, which contains most of the necessary information.

From the Definition menu, select Create a definition, and then follow the steps below to create a new definition.

Steps:

  1. Definition name
  2. Functional definition
  3. Source
  4. Classification
  5. Denodo name, Tableau extract name, and display name
  6. Sharing the definition
  7. Technical definition
  8. Functional area

1. Definition name

Naming convention

Definition names should adhere to the following naming convention:

 < Term > < Class Word >[,][Term Modifier (optional)][-][Org (optional)]

For instance:

  • rc_cd: Responsibility Center Code
  • rc_shrt_nm: Responsibility Center Short Name
  • rc_nm: Responsibility Center Name
  • Academic Career Code
  • Academic Career Code, Student
  • Academic Career Code, Course
  • Account Number, Award - IUSM

IU class word list

  • Code
  • Name
  • Amount
  • Number
  • Description
  • Short Description
  • Indicator
  • Sort Order
  • ID
  • Units
  • Date
  • Count

IU Abbreviation Exception List

  • ID – Identifier
  • FTE – Full Time Equivalent
  • URL – Uniform Resource Locator
  • API – Application Programming Interface

Naming standards

Follow these standards in naming your new definition:

  • Use proper capitalization: Capitalize the first letter of each word, with the exception of short words (for example, "a", "the", "by", "for").
  • Omit "A", "An", and "The" from the beginning of the name.
  • To speed up searching, spell out words in definition or specification names. This way, users don't need to search for both complete words and abbreviations, and they won't be confused by abbreviations that can be interpreted as whole words (for example, "no" as short for "number" or as the word "no").
    • Exceptions include the following IU abbreviations:
      • ID: Identifier
      • FTE: Full-time equivalent
      • URL: Uniform resource locator
      • API: Application programming interface
  • To avoid confusion, identify any fields used to sort data by "Sort Order", rather than by "Sort Number" or "Sort Code". In the third paragraph of the functional definition, you can specify more technical details about how the sort is handled.
  • When choosing a definition name, keep the following in mind:
    • If the thing being described is a proper noun that exists in the real world, the definition name should contain "Name".
    • If the thing being described is not a proper noun, the definition name should contain "Description".
  • Do not enter special characters in definition or specification names. The Cookbook ignores most special characters in searches and turns some of them into garbled text upon exporting. For example, the en dash (–) is changed to – in a CSV export.
    Note:
    Hyphens (-), parentheses, and slashes (/) do not break the Data Cookbook search or export functions. However, only slashes have standardized usage at this time; for now, avoid hyphens and parentheses.
  • Delete leading and trailing white spaces; these are especially easy to pick up when copying text from web pages. White spaces introduce problems and make relating definitions to each other difficult. For example, Data Cookbook will treat "Tuition Revenue " and "Tuition Revenue" as different definitions.
  • Record aggregation performed on a definition in the specification; do not create an "aggregated" definition.

2. Functional definition

Closely related definition paragraph structure

All definition information, including short descriptions and descriptions, should go in the base definition, also known as the "code" (for example, "Responsibility Center Code"). Use the second paragraph of the short description and description to demonstrate how data will display on a report and provide a link to the base definition (the "code"). The standard text for this reference will be the following:

The full business description for this term can be found in the base definition [[Base Definition Code]].

You should also include a base definition with modifier in the base definition. Use the second paragraph to demonstrate how data will display on a report and provide a link to the base definition without modifier, along with a brief description about the uniqueness of this particular definition.

For example:

Chart Code, Course

The full business description for this term can be found in the base definition [[Chart Code]].

Chart Code displays as a 2-character code primarily used to designate an individual campus.

Current valid values are:

"BL" "Bloomington"
"EA" "East"
"FW" "Fort Wayne"
"IN" "Indianapolis"
"KO" "Kokomo"
"NW" "Northwest"
"SB" "South Bend"
"SE" "Southeast"
 
In enrollment data, course subjects have been mapped to financial organization owners. The
Chart Code, Course is the chart of the financial organization offering the course. The Chart
Code, Plan is simply the Chart Code of the Course Subject Code. The valid values are the same
as for chart code.

When creating a new definition, you may find it easiest to start with an existing definition and use Data Cookbook's Copy this version functionality to clone the existing definition and then give it a new name.

First paragraph

The first paragraph is meant for the general public or someone unfamiliar with the terms being defined. As such, you should write it in common language. Jargon, links to other definitions, or highly technical details are not appropriate at this level.

For a closely related definition such as a description, the first paragraph would be in the following format:

The full business description for this term can be found in the base Definition [[Base Definition Code]]

Hyperlinks

In the interest of readability, do not include hyperlinks to other definitions in the first paragraph. Best practice is to hyperlink the first instance of a term after the first paragraph; do not hyperlink any further instances of the term. However, there are times when terms can only be defined in relation to other terms. In these cases, you may include a hyperlink in the first paragraph. This should be an 80/20 rule; avoid if possible, link when necessary.

Second paragraph

The second paragraph describes how the data will display on a report. If the definition is a code that has an accompanying description or vice versa, you should also list the description display with a link to the description definition.

Relate definitions

To relate definitions, put double brackets around the related definition name in the "Functional definition" box (for example, [[Responsibility Center Code]]).

Do not relate definitions using Add in the gray sidebar, because doing this doesn't tell users anything about how the definitions are related. If there's a relationship between definitions, explain it in the functional definition or technical definition.

Third paragraph

The third paragraph contains example information and slightly more technical information about the definition, such as other related terms. If the term created has the same base term but a different term modifier or organization from another definition, refer to the similar term in the paragraph. Include the hyperlink to the similar term.

List of definition values or validation table

After the third paragraph, list the values for the definition or reference the validation table:

  • If there are only 10 values or fewer for a definition, a list of those values will appear with the following heading: 
    A list of common <definition name> codes and descriptions are:
  • Alternatively, if there are more than 10 values, or if the values change regularly, reference the validation table. To give context for the user, provide a reference to the transaction system. For example: 
    Academic Term Code

Valid values for this code originate from the Student Information System and can be found in
the PS_TERM_TBL.

Quotation marks

Any time a specific technical example is referenced, include it in double quotation marks. For example:

Fall semester carries the academic year "2014" and the semester code of "20".

Use single quotes for multi-word nouns that represent a single concept. For example:

If you wish to see "2" instead, please use 'part of term'.

Third paragraph examples

The categories for this field are related to but are not synonymous with [[Indirect Cost Rate]]. These different levels of indirect cost rates are negotiated with the federal government.

The three valid values for this field are "Research", "Instruction", and "Service/Other".

Final paragraph

The final paragraph contains comments regarding permission limitations if applicable and a department to contact if there are further questions.

Contact information

When applicable, include contact information for the area responsible for making decisions about the underlying data. Do not include contact information for offices that are not aware of, informed of, or prepared to support this type of inquiry.

Sample wording:

For information on creation and maintenance of this code/indicator, please contact the
<office name> at <email address>.

3. Source

Use the "Source" section to provide the full functional area context of the definition; this field should resemble the format found in the "Specification Naming Convention" section, with forward slashes (/) separating the levels of the functional area hierarchy. You can populate the source field by either using a drop-down list or by creating a new source in a free-form field:

Data Cookbook definition creation page, source selection options

4. Classification

The "Classification" field represents the security associated with the definition. The drop-down menu has been populated based on the role-based access control classifications that were approved by the Data Stewards for the Decision Support Initiative. This field is not mandatory upon creation, but you can fill it in if you know the appropriate classification. The associated Data Manager will review or add this classification before final approval of the definition.

5. Denodo name, Tableau extract name, and display name

The Denodo name, Tableau extract name, and display name are similar to technical definitions. However, they predefine the standard translation that determines how the definition name will appear in these contexts.

Denodo name

Since Denodo does not have Unicode support, the standard conversion for any definition name will change uppercase letters to corresponding lowercase letters and replace spaces with underscores. For example, "Responsibility Center Code" would become responsibility_center_code.

Tableau extract name

For Tableau extract, the standard conversion is the same as Denodo.

Display name

The display name contains the common ways to label a definition name on a report. To avoid confusion, display names should be unique to a definition or business concept; however, you may sometimes need to use commonplace names that have context-dependent meanings. For example, "Institution" has a slightly different meaning depending on the context (for example, student, course, job, financial transaction), but it may be labeled identically on a report.

Try to minimize the number of display names for any given definition name. However, because labels in tools like Tableau have different amounts of available space, you may often need multiple display names of varying lengths; these will appear in the "Display Name" box delimited by semicolons (;).

The following is an example of a display name:

Academic Organization; Acad Org

6. Sharing the definition

Selecting the public checkbox shares the definition publicly with the broader Data Cookbook community. As an initial best practice, do not select this option. In the future, UITS will determine which definitions (if any) to share publicly.

7. Technical definition

The technical definition is where the definition lives in your database. The technical definition can also hold the fields and factors used to calculate the definition, or the statement/logic involved in extracting it from your system.

Definitions often have more than one technical definition. For example, there may be one for your ERP, another for your operational data store, another for your data warehouse, and another for your analytical warehouse. Technical definitions are not required when you create a definition; if you wish, you can add one later. However, if you do add a technical definition during the initial creation of a definition, you will have to fill in the technical definition completely before the definition can be submitted or saved as a draft.

The best practice is to include at least one technical definition before the final QA check. The information is intended for developers, report writers, and auditors rather than end users.

Technical definition template

Below is the suggested format for the technical definition text box:

  • Database:
  • Schema:
  • Table name(s):
  • Table type:
  • Field name:
  • Datatype:
  • SQL or logic:
  • Notes:

Technical definition template with explanations

Each data system can have only one technical definition associated with it. However, since the technical definition is a text field, you can enter multiple technical implementations by using multiple iterations of the template within one technical definition.

Below is the suggested format for the technical definition text box with explanations:

  • Database: The system in which the data item resides.
  • Schema: The schema/username associated with the data element in the system. In some systems, this might also be called a virtual database or database. For example, if you add a technical definition for Denodo, the virtual database name would be the schema.
  • Table name(s): The table name, or a list of table names, in which a data element resides. For clarity of reference, the best practice is to separate lookup/valid values tables and transactional tables into distinct entries within the technical definition.
  • Table type: Specifies whether this entry is a lookup/valid value table or a transactional table. The valid values are "Valid Value" and "Transaction".
  • Field name: The specific technical name of the field in the system. If there is more than one technical name within a system for the same definition, the best practice is to separate entries within the technical definition.
  • Datatype: The system-specific data type for the data element.
  • SQL or logic: Information related to how the data is retrieved, filtered, calculated, or transformed (for example, SQL statements, where clauses, case statements).
  • Notes: Any details that explain and clarify the information above, especially relevant contextual information, such as when a data element has more than one technical name within a system. For example, "Academic Career Code, Course" appears in SIS as both "CRSE_CAREER" and "ACAD_CAREER" depending on the situation; an explanation provides helpful context for staff who are less familiar with the system.

Technical definition template examples

Below are examples of technical definition templates.

Example one: Academic group code

Enterprise Reporting Systems»SIS ODS
    Database: PS1PRD
    Schema: SYSADM
    Table name(s): PS_ACAD_GROUP_TBL
    Table type: Valid Value
    Field name: ACAD_GROUP
    Datatype: VARCHAR2(5 BYTE)
    SQL or Logic: 
    Notes: 
    
Enterprise Reporting Systems»DSS
    Database: DSS1PRD
    Schema: DSS_SH
    Table name(s): SH_ACAD_PLAN_SV
    Table type: Valid Value
    Field name: ACAD_GRP_CD
    Datatype: VARCHAR2(5 BYTE)
    SQL or Logic: 
    Notes: The Shared Dimension Source View shows the joins needed to tie an Academic Plan to an Academic Group: DSS_SH.SH_ACAD_PLAN_SV

Example two: Grading basis code

Data System: Enterprise Reporting Systems» SIS ODS
    Database: PS1PRD
    Schema: SYSADM
    Table name(s): PS_GRADE_BASIS_TBL
    Table type: Valid Values
    Field name: GRADING_BASIS
    Datatype: VARCHAR2(3 BYTE)
    SQL or Logic: 
    Notes: 
    Database: PS1PRD
    Schema: SYSADM
    Table name(s): PS_STDNT_ENRL
    Table type: Transaction
    Field name: GRADING_BASIS_ENRL
    Datatype: VARCHAR2(3 BYTE)
    SQL or Logic: 
    Notes: 

Data System: Enterprise Reporting Systems» EBI DTR
    Database: DTR1PRD
    Schema: EBI
    Table name(s):  STU_CLS_ENRL_DTA_T, STU_MULT_PLN_WITH_MULT_CLS_T
    Table type: Transaction
    Field name:  GRD_BAS_ENRL
    Datatype: VARCHAR2(9)
    SQL or Logic: 
    Notes:

9. Functional area

Fill in this field with the lowest level functional area that is associated with this definition.

This is document anoj in the Knowledge Base.
Last modified on 2023-09-29 16:33:44.