Custom sub-entities derive from MutableEntity just like Contacts, Groups and Companies. Working with custom sub-entity data is just like working with data in those other mutable entities.
The CustomSubEntityManager provides methods to create new row objects and delete row objects.
The CreateCustomEntity method creates a new custom sub-entity object that represents a row in the database for that custom sub-entity. The return type for the method is a generic type T. This will be set to whatever the type you retrieved the CustomSubEntityManager for.
This allows you to work with custom sub-entities in a strongly typed fashion and provides type safety for your operations. This is especially useful if your application is using more than one custom sub-entity.
After you call CreateCustomEntity you can use the returned reference to set field data and add parent entities to the record.
To persist the object to the database you call the Update method.
To set field data you can either get field descriptors and set the values on the field descriptors to your CustomSubEntity object or use the Fields property indexer of the CustomSubEntity object.
The CustomSubEntityManager provides methods to get all the field descriptors for the custom sub-entity, to get field descriptors by name (alias, real or display), and to get the fields by type.
This is the same pattern for getting field descriptors used in the other mutable entities, Contacts, Groups and Companies.
To get all the fields for a custom sub-entity use the GetCustomEntityFieldDescriptors method. This returns an array of CustomEntityFieldDescriptors. This method will only return the fields for the custom sub-entity the CustomSubEntityManager was retrieved for.
The GetCustomEntityFieldDescriptor method allows you to get a field descriptor by name. There is a new enumeration you can use when getting the field descriptor that lets you use alias to get the field. FieldNameType is the enumeration and there is an overload for GetCustomEntityFieldDescriptor that takes it. The enumeration can be used to indicate whether the field name is the real name, display name or the alias for the field.
Once you have retrieved a field descriptor you can use the SetValue method to set the data for that field. You pass in the CustomSubEntity object you want to set the value on and the value you want to set.
Another way to set the value of a field is to use the Fields property on the CustomSubEntity object. The fields property returns a fields collection that has an indexer where you use the field name to indicate which field you would like to set the value of.
C# example:
account.Fields["ACCOUNT_TYPE",
Act.Framework.MutableEntities.FieldNameType.Alias] =
"Checking";
This example uses the alias to set the value of a field to a string.
The other way to add a custom sub-entity record is to use .NET data binding.
The only required data for saving a custom sub-entity is a parent entity record to associate the record to. If your custom sub-entity hangs off of Contacts you will need to set at least one contact as the owner of a custom sub-entity row before it will save to the database.
The CustomSubEntity object provides methods to set Contacts, Groups, and Companies as parent records for the custom sub-entity row. SetContacts, SetGroups and SetCompanies methods allow you to specify a ContactList, GroupList and/or CompanyList as the parent records for the custom sub-entity.
There are also methods to clear the parent records for each parent entity type. ClearContacts, ClearGroups and ClearCompanies methods delete all the appropriate parent entities for the custom sub-entity row.
Make sure you set the Contacts, Groups and/or Companies on the CustomSubEntity object before calling the Update method to save your custom sub-entity row. If the object is not set, you will get an exception indicating that you have to have at least one parent row for a custom sub-entity record.
Custom sub-entities work just like notes or histories, they do not have ACLs (access control lists). They can only be set public or private.
You have to have access to at least one parent entity to be able to see a custom sub-entity row as well. More about how the security model works for retrieval can be found in retrieving custom sub-entity rows.
To set a custom sub-entity’s row level security, use the AccessType property. It can be set to either public or private using the AccessType enumeration.