Data Model Expressions - Revision history

Dgreenwood: /* LINQ: Accessing values in collections */

2025-10-15T14:30:34Z

LINQ: Accessing values in collections

← Older revision		Revision as of 09:30, 15 October 2025
Line 393:		Line 393:
	=== LINQ: Accessing values in collections ===		=== LINQ: Accessing values in collections ===

	~~'''~~Field values in collections can be accessed using LINQ expressions.~~'''~~		<big>Field values in collections can be accessed using LINQ expressions.</big>
	* Collections are multi-instance Data Sections and Data Tables.
	: LINQ expressions take the following general format:		"Collections" are multi-instance Data Sections and Data Tables. Values in collections are not normally easily accessible in Grooper expressions except through a few functions such as <code>SumOf("''Data Column''")</code>
	:* <code>From ''item'' In ''Collection'' Where ''condition'' Select ''item.Field'' OrderBy ''key''</code>
	:* <code>''item''</code> is a variable name used to iterate through each item in the collection.		LINQ expressions take the following general format:
	:** An "item" is a section instance for Data Sections		<code>From ''item'' In ''Collection'' Where ''condition'' Select ''item.Field'' OrderBy ''key''</code>
	:** An "item" is a row for Data Tables.		* <code>''item''</code> is a variable name used to iterate through each item in the collection.
	:* <code>''Collection''</code> is the Data Section or Data Table.		** An "item" is a section instance for Data Sections
	:* <code>''Field''</code>is the Data Field in that Data Section or Data Column in that Data Table.		** An "item" is a row for Data Tables.
	:* The <code>Where</code> and <code>OrderBy</code> components are optional.		* <code>''Collection''</code> is the Data Section or Data Table.
	* Examples:		* <code>''Field''</code>is the Data Field in that Data Section or Data Column in that Data Table.
	** <code>(From row in Line_Items Select row.Line_Total).Sum</code>		* The <code>Where</code> and <code>OrderBy</code> components are optional.
	*** This returns the sum of the "Line Total" Data Column values in a "Line Items" Data Table.
	*** <code>From row in Line_Items Select row.Line_Total</code> selects all "Line Total" Data Column values for each row in the "Line Items" Data Table.		Examples:
	*** <code>.Sum</code> adds all the values returned by the LINQ expression.		: <code>(From row in Line_Items Select row.Line_Total).Sum</code>
	** <code>(From sem In Semester Select sem.Earned_Hours).Max</code>		:* This returns the sum of the "Line Total" Data Column values in a "Line Items" Data Table.
	*** This returns the maximum of the "Earned Hours" Data Fields from all section instances collected by a "Semester" Data Sections.		:* <code>From row in Line_Items Select row.Line_Total</code> selects all "Line Total" Data Column values for each row in the "Line Items" Data Table.
	*** <code>From sem In Semester Select sem.Earned_Hours</code> selects all "Earned Hours" Data Field values for each instance in the "Semester" Data Section.		:* <code>.Sum</code> adds all the values returned by the LINQ expression.
	*** <code>.Max</code> selects the largest value from the LINQ expression.		: <code>(From sem In Semester Select sem.Earned_Hours).Max</code>
	** <code>(From sem In Semester Where sem.Year < DateTime.Now.Year Select sem.Earned_Hours).Sum</code>		:* This returns the maximum of the "Earned Hours" Data Fields from all section instances collected by a "Semester" Data Sections.
	*** This returns the total "Earned Hours" for semesters prior to the current year.		:* <code>From sem In Semester Select sem.Earned_Hours</code> selects all "Earned Hours" Data Field values for each instance in the "Semester" Data Section.
	*** <code>From sem In Semester Where sem.Year < DateTime.Now.Year Select sem.Earned_Hours</code> selects all "Earned Hours" Data Field values for each instance in the "Semester" Data Section that match the <code>Where</code> condition.		:* <code>.Max</code> selects the largest value from the LINQ expression.
	*** <code>Where sem.Year < DateTime.Now.Year</code> restricts values to the condition set by its expression. In this case, where the "Year" value in the section instance (<code>sem.Year</code>) is less than (<code><</code>) the current year (<code>DateTime.Now.Year</code>).		: <code>(From sem In Semester Where sem.Year < DateTime.Now.Year Select sem.Earned_Hours).Sum</code>
	*** <code>.Sum</code> adds all the values returned by the LINQ expression.		:* This returns the total "Earned Hours" for semesters prior to the current year.
			:* <code>From sem In Semester Where sem.Year < DateTime.Now.Year Select sem.Earned_Hours</code> selects all "Earned Hours" Data Field values for each instance in the "Semester" Data Section that match the <code>Where</code> condition.
			:* <code>Where sem.Year < DateTime.Now.Year</code> restricts values to the condition set by its expression. In this case, where the "Year" value in the section instance (<code>sem.Year</code>) is less than (<code><</code>) the current year (<code>DateTime.Now.Year</code>).
			:* <code>.Sum</code> adds all the values returned by the LINQ expression.

			A larger article on LINQ can be found [[LINQ in Grooper\|here]].

	=== Other tips ===		=== Other tips ===

Dgreenwood: /* Referencing sibling, descendent and ancestor fields */

2025-10-15T14:20:43Z

Referencing sibling, descendent and ancestor fields

@@ Line 361: / Line 361: @@
 * Sibling fields (in the same branch a Data Model hierarchy) are accessed by name only (Ex: <code>Field_Name</code>).
 * Fields in Data Sections are accessed with dot-notation (Ex: <code>Section_Name.Field_Name</code>)
 **<li class="attn-bullet"> Be aware: Only fields in '''single-instance''' Data Sections can be accessed this way.
@@ Line 377: / Line 390: @@
 *:::: {{IconName|Data Field}} Early Payment Discount ''Data Field''
 ** A Calculated Value expression on the "Early Payment Discount" field could access the "Invoice Date" value with the following expression <code>Invoices.Header_Details.Invoice_Date</code>
 === LINQ: Accessing values in collections ===

Dgreenwood: /* Other tips */

2025-10-15T13:52:51Z

Other tips

← Older revision		Revision as of 08:52, 15 October 2025
Line 406:		Line 406:
	*** <code>.Sum</code> adds all the values returned by the LINQ expression.		*** <code>.Sum</code> adds all the values returned by the LINQ expression.

	==== Other tips ====		=== Other tips ===

	'''IntelliSense in the expression editor will help you.'''		'''IntelliSense in the expression editor will help you.'''

Dgreenwood: /* LINQ: Accessing values in collections */

2025-10-15T13:52:42Z

LINQ: Accessing values in collections

← Older revision		Revision as of 08:52, 15 October 2025
Line 379:		Line 379:
	*<li class="attn-bullet"> Be aware: This method will '''not''' work to crawl Data Elements inherited from a parent Content Type's Data Model.		*<li class="attn-bullet"> Be aware: This method will '''not''' work to crawl Data Elements inherited from a parent Content Type's Data Model.

	==== LINQ: Accessing values in collections ====		=== LINQ: Accessing values in collections ===

	'''Field values in collections can be accessed using LINQ expressions.'''		'''Field values in collections can be accessed using LINQ expressions.'''

Dgreenwood: /* Referencing sibling, descendent and ancestor fields */

2025-10-15T13:52:33Z

Referencing sibling, descendent and ancestor fields

← Older revision		Revision as of 08:52, 15 October 2025
Line 356:		Line 356:
	** CON: The expression is less human-readable. Backtracking to find out what Data Field corresponds to a GUID in an expression may be challenging in larger Data Models.		** CON: The expression is less human-readable. Backtracking to find out what Data Field corresponds to a GUID in an expression may be challenging in larger Data Models.

	==== Referencing sibling, descendent and ancestor fields ====		=== Referencing sibling, descendent and ancestor fields ===

	'''Sibling fields and fields in Data Sections are accessed differently.'''		'''Sibling fields and fields in Data Sections are accessed differently.'''

Dgreenwood: /* Referencing field values in expressions */

2025-10-15T13:52:17Z

Referencing field values in expressions

← Older revision		Revision as of 08:52, 15 October 2025
Line 336:		Line 336:
	* Is Valid		* Is Valid
	* Is Required		* Is Required

			=== Referencing fields by name (or GUID) ===

	'''Fields are referenced by Data Field/Data Column name.'''		'''Fields are referenced by Data Field/Data Column name.'''
Line 354:		Line 356:
	** CON: The expression is less human-readable. Backtracking to find out what Data Field corresponds to a GUID in an expression may be challenging in larger Data Models.		** CON: The expression is less human-readable. Backtracking to find out what Data Field corresponds to a GUID in an expression may be challenging in larger Data Models.

	'''~~Peer~~ fields and fields in Data Sections are accessed differently.'''		==== Referencing sibling, descendent and ancestor fields ====
	* ~~Peer~~ fields (in the same branch a Data Model hierarchy) are accessed by name only (Ex: <code>Field_Name</code>.
			'''Sibling fields and fields in Data Sections are accessed differently.'''
			* Sibling fields (in the same branch a Data Model hierarchy) are accessed by name only (Ex: <code>Field_Name</code>).
	* Fields in Data Sections are accessed with dot-notation (Ex: <code>Section_Name.Field_Name</code>)		* Fields in Data Sections are accessed with dot-notation (Ex: <code>Section_Name.Field_Name</code>)
	**<li class="attn-bullet"> Be aware: Only fields in '''single-instance''' Data Sections can be accessed this way.		**<li class="attn-bullet"> Be aware: Only fields in '''single-instance''' Data Sections can be accessed this way.
Line 374:		Line 378:
	** A Calculated Value expression on the "Early Payment Discount" field could access the "Invoice Date" value with the following expression <code>Invoices.Header_Details.Invoice_Date</code>		** A Calculated Value expression on the "Early Payment Discount" field could access the "Invoice Date" value with the following expression <code>Invoices.Header_Details.Invoice_Date</code>
	*<li class="attn-bullet"> Be aware: This method will '''not''' work to crawl Data Elements inherited from a parent Content Type's Data Model.		*<li class="attn-bullet"> Be aware: This method will '''not''' work to crawl Data Elements inherited from a parent Content Type's Data Model.

			==== LINQ: Accessing values in collections ====

	'''Field values in collections can be accessed using LINQ expressions.'''		'''Field values in collections can be accessed using LINQ expressions.'''
Line 399:		Line 405:
	*** <code>Where sem.Year < DateTime.Now.Year</code> restricts values to the condition set by its expression. In this case, where the "Year" value in the section instance (<code>sem.Year</code>) is less than (<code><</code>) the current year (<code>DateTime.Now.Year</code>).		*** <code>Where sem.Year < DateTime.Now.Year</code> restricts values to the condition set by its expression. In this case, where the "Year" value in the section instance (<code>sem.Year</code>) is less than (<code><</code>) the current year (<code>DateTime.Now.Year</code>).
	*** <code>.Sum</code> adds all the values returned by the LINQ expression.		*** <code>.Sum</code> adds all the values returned by the LINQ expression.

			==== Other tips ====

	'''IntelliSense in the expression editor will help you.'''		'''IntelliSense in the expression editor will help you.'''

Dgreenwood: /* Referencing field values in expressions */

2025-10-10T21:53:32Z

Referencing field values in expressions

← Older revision		Revision as of 16:53, 10 October 2025
Line 345:		Line 345:
	'''Fields may also be referenced by Id (GUID)'''		'''Fields may also be referenced by Id (GUID)'''
	* Instead of using its code friendly name, you can opt to use its Id value instead.		* Instead of using its code friendly name, you can opt to use its Id value instead.
	* Use the <code>GetFieldValue()</code> ~~function~~ to do so (Ex: <code>GetFieldValue("12345678-90ab-cdef-1234-567890abcdef")</code>)		* Use the <code>GetFieldValue()</code> or <code>GetFieldTypedValue()</code> functions to do so (Ex: <code>GetFieldValue("12345678-90ab-cdef-1234-567890abcdef")</code>)
			**<code>GetFieldValue()</code> always returns a string value.
			**<code>GetFieldTypedValue()</code> returns the fields .NET value type (Ex: If a Data Field's Value Type is a datetime value, this will return its value as a datetime value )
	* There are some pros and cons to referencing fields this way:		* There are some pros and cons to referencing fields this way:
	** PRO: If the Data Field/Data Column's name changes, you don't need to update the expression.		** PRO: If the Data Field/Data Column's name changes, you don't need to update the expression.

Dgreenwood: /* Referencing field values in expressions */

2025-10-10T20:10:24Z

Referencing field values in expressions

← Older revision		Revision as of 15:10, 10 October 2025
Line 332:		Line 332:
	== Referencing field values in expressions ==		== Referencing field values in expressions ==

	Field values (Data Field and Data Column cell values) can be referenced in the following expressions:		Field values (Data Field and Data Column cell values) can be referenced in the following Data Model expressions:
	* Calculated Value		* Calculated Value
	* Is Valid		* Is Valid
Line 342:		Line 342:
	* Special characters are replaced with underscores (Ex: "Yes/No" becomes <code>Yes_No</code>)		* Special characters are replaced with underscores (Ex: "Yes/No" becomes <code>Yes_No</code>)
	* Multiple sequential spaces and special characters are replaced with a single underscore (Ex: "Yes / No" becomes <code>Yes_No</code>)		* Multiple sequential spaces and special characters are replaced with a single underscore (Ex: "Yes / No" becomes <code>Yes_No</code>)

			'''Fields may also be referenced by Id (GUID)'''
			* Instead of using its code friendly name, you can opt to use its Id value instead.
			* Use the <code>GetFieldValue()</code> function to do so (Ex: <code>GetFieldValue("12345678-90ab-cdef-1234-567890abcdef")</code>)
			* There are some pros and cons to referencing fields this way:
			** PRO: If the Data Field/Data Column's name changes, you don't need to update the expression.
			** CON: The field's GUID does not show up in IntelliSense. You have to track it down before entering the expression.
			***<li class="fyi-bullet"> You can find a Data Field/Data Column's GUID in their "Advanced" tabs under "ID".
			** CON: The expression is less human-readable. Backtracking to find out what Data Field corresponds to a GUID in an expression may be challenging in larger Data Models.

	'''Peer fields and fields in Data Sections are accessed differently.'''		'''Peer fields and fields in Data Sections are accessed differently.'''

Dgreenwood: /* Is Required Expressions */

2025-10-10T19:11:47Z

Is Required Expressions

← Older revision		Revision as of 14:11, 10 October 2025
Line 299:		Line 299:
	=== Is Required Expressions ===		=== Is Required Expressions ===

	~~You can set a field to be~~ required ~~in Grooper by setting the '''''Required''''' property to true. If~~ the field is ~~not extracted~~ during ~~the '''~~Extract~~''' step (in other words, "blank"~~)~~, the field will be flagged as invalid~~. ~~However, what if whether or not a~~ field is ~~required is based on~~ the value ~~of some other field? You would want that field to be ''conditionally'' required, based on some set criteria or parameter~~.		In Grooper, "required" fields are flagged for human review when the field is empty (i.e. no value was collected during Extract). The field is set to an error state, alerting Review users to manually input the value in the Data Viewer.

	~~That's what ''~~'''Is Required ~~Expressions~~'''~~'' are for~~. ~~An '''''~~Is Required ~~Expression'''''~~ is a ~~snippet~~ of ~~VB.Net code that sets a field’s “Required” status conditionally~~.		Data Fields and Data Columns can be made required in two ways:
			* By enabling the "Required" property if the field always needs to be collected from the document in all cases.
			* By configuring an "'''Is Required'''" expression to conditionally determine if the field is required.

			"Is Required" expressions dynamically specify whether a value is required at runtime. These expressions allow users to implement conditional requirements, making a field required based on the value of another field.

	==== Return Type ====		==== Return Type ====
Line 314:		Line 318:

	In the following example, there are two fields.		In the following example, there are two fields.
	* ~~“Marital Status”~~ is a ~~Boolean~~ field ~~with a true value of “Married” and a false value of “Single~~.”		* "Marital Status" is a restricted-choice string field. It can be either:
	* ~~“Spouse Name”~~ is a string field. ~~It has~~ the the ~~following '''''Is Required Expression''''':~~		** <code>married</code>
	** <code>~~Marital_Status = True~~</code>		** <code>single</code>
			* "Spouse Name" is a string field.
			** This would be conditionally required, based on the value of "Marital Status".
			** If they're married ("Marital Status" is <code>married</code>), the "Spouse Name" should be filled.
			** If they're single ("Marital Status" is <code>single</code>), it should be empty.

	~~When the "Marital Status" field is set to "Single" (therefore "False"), the "Spouse Name" field is not required.~~
	* The condition set by the '''''Is Required Expression''''' <code>Marital_Status = True</code> is met. The "Marital Status" field's value equates to "False". So, the expression returns "False"
	* The field remains an optional field. No value is required to be entered.

	~~If “Marital Status” is “Married” (therefore~~ "~~True~~"), the ~~“Spouse Name”~~ field ~~then becomes required~~.		The following "Is Required" expression would implement this logic for the "Spouse Name" field.
	* The condition set by the '''''Is Required Expression''''' <code>Marital_Status = ~~True~~</code> ~~is met. The "Marital Status" field's value equates to "True". So, the expression returns "True"~~		: <code>Marital_Status = "married"</code>
	* The field will be in error and turn red until a value is entered.

	== Referencing field values in expressions ==		== Referencing field values in expressions ==

Dgreenwood: /* Return Type */

2025-10-10T18:53:38Z

Return Type

← Older revision		Revision as of 13:53, 10 October 2025
Line 305:		Line 305:
	==== Return Type ====		==== Return Type ====

	'''''~~Is Required Expressions~~''''' must return a Boolean (True/False) value:		'''''Boolean'''''
	* If the expression ~~returns “True,”~~ the field becomes required.
	* If the expression ~~returns “False,” it~~ remains optional.		Is Required expressions must return a Boolean (True/False) value.
			* When the expression evaluates to <code>true</code> the field becomes required. The field will be placed in an error state if empty/blank.
			* When the expression evaluates to <code>false</code> the field remains optional.

	==== Example Is Required Expression ====		==== Example Is Required Expression ====