GetEntityCollection<>

Prerequisites

The GetEntityCollection<> activity is available in Workflow Composer version 2.7 and later and requires the following minimum versions of activities and contracts:

Anthology Student version 20.0.x

— OR —

CampusNexus CRM version 12.2.x

The minimum Cmc.Core.dll version installed in Program Files (x86)\CMC\Workflow must be 5.1.167 or greater.

Note: If you use the activity with Student 19.0 and Workflow Composer 2.7, you won’t see any errors in Workflow Composer (because it has minimum Cmc.Core.dll version), but you’ll see a server error at runtime.

Purpose

The GetEntityCollection<> activity provides the ability to retrieve a collection of values (i.e., rows in a database table) for a given entity by passing in an array of Ids. The activity returns an array of entities in the “Entities” output argument.

When you drag the GetEntityCollection<> activity into the Designer window, you are prompted to select the entity type (TEntity).

Select Entity Type

When you select the 'Browse for Type' option, the list of assemblies and associated entities is displayed. Find and select the entity and click OK.

Note that the in and out arguments for the activity are of type ICollection.

Properties

GetEntityCollection<> Properties
Property	Value	Required	Notes
DisplayName	`String`	No	Specify a name for the activity or accept the default.
Entities	`OutArgument<ICollection<Entity>>`	Yes	Specify the entity array using a VB expression or variable.
EntityIds	`InArgument<ICollection<Int32>>`	Yes	Specify the entity identifier array using a VB expression or variable.
ResponseItems	`OutArgument<ICollection <EntityServiceResponse<Entity>>>`	No	This is an optional output argument for items retrieved by the activity. This is a variable that can be used as input for subsequent workflow activities. To identify the variable type, in the Variable type field of the Variables pane, select Browse for Types.... In the 'Browse and Select a .NET Type' window, navigate to the entity that matches the previously selected entity type and click OK.
ValidationMessages	`InArgument <ICollection<ValidationMessage>>`	No	Specify a variable that can be used to capture validation messages. For more information, see Capture Validation Errors.

Get/Save EntityCollection Example

This workflow example is associated with a Forms Builder sequence that retrieves a collection of records for the StudentRelationshipAddressEntity and exposes the records in a grid control. The user of the form sequence is allowed to add and edit data in the grid. The new and modified records are saved to the database.

In Form Designer, create a form using the Grid component.
Bind the Grid component to the workflow using the Model property value vm.models.myAddresses.
Configure the Columns property to allow the user to add, edit, and delete data.
In Sequence Designer, add the form to a sequence and open the workflow for the sequence.
In Workflow Composer, create the variables shown below.
Create an argument of type ICollection<StudentRelationshipAddressEntity> for the myAddresses model value that binds the grid to the workflow. The path to browse to the argument type is: System.Collections.Generic.ICollection<Cmc.Nexus.Common.Entities.StudentRelationshipAddressEntity>.
The GetEntityCollection<> activity needs a list of ids for the collection of the same entity type to retrieve. To achieve this, drag an ExecuteQuery activity into the Entry section of the Welcome form. This activity retrieves a set of document ids for a student from the database and returns the data in a variable named addrSet (see variables created above).

The Command property is defined as "select syaddressid from syaddress where systudentid = 51850" where the systudentid value is hard-coded. Use a variable for the systudentid as appropriate in your environment.
Drag a ForEach<> activity below the ExecuteQuery activity. The ForEach<> is activity converts the dataset type argument returned by ExecuteQuery to a collection of Int32 ids to pass to GetEntityCollection<> activity using the Values property addrSet.Tables(0).AsEnumerable.
Drag an AddToCollection<> activity into the Body section of the ForEach<> activity. The AddToCollection activity adds items to the collection when users enter new data on the form.

The collection is defined by the variable addrs of type List<Int32> with a default value of new List(Of Int32).

The Item property value CINT(item("SyAddressId")) converts the data to integers.
Drag a GetEntityCollection<> activity below the ForEach<> activity. The GetEntityCollection<> activity uses the StudentRelationshipAddressEntity.

The input argument is the addrs variable.

The output argument is the myAddresses argument that binds the grid to the workflow.
Drag a ForEach<> activity into the Next transition following the form the contains the Grid component.

The Values property holds the myAddresses argument that binds the grid to the workflow.

This instance of the ForEach activity gathers all rows in the grid including rows that were added by the form user.
Drag an If activity into the Body section of the ForEach<> activity. Specify the following condition to detect if an item was added to the StudentRelationshipAddressEntity:
item.EntityState = Cmc.Core.EntityModel.EntityState.Added

Drag an Assign activity into the Then branch to the associate the hard-coded studentid with the itemEntityState array.

Add another Assign activity to set the item.Id to -1. This assign statement ensures that a new item is appended to the array. The last element of an array is the length of the array - 1.
Drag a SaveEntityCollection<> activity into last Next transition of the sequence. The activity will handle add, edit and delete of any entity in the. In our example, the activity saves the changes passed in through myAddresses to the ICollection<StudentRelationshipAddressEntity>.
Finally, in the Condition field of the last Next transition, specify not formInstance.ValidationMessages.HasErrors to catch any form errors.