Properly adding child records using the SalesLogix entity model

The SalesLogix entity model offers a really great way of working with data in SalesLogix and letting the system establish all of the links for you- as long as you know what you are doing.

One of the really great things that you can do is to add child entities to a parent, even if the parent is not yet in the database.  This is especially helpful if you need to create child records while still on an insert screen, like when inserting a contact being able to add multiple history records for the contact, even before the contact is created.

If we were working in the LAN you would have the problem of not having the contact in the database and available for you to get its ID so that you could use the ID when inserting child records.  Normally in the LAN client you would need to generate an ID and then set the ContactID value with that before saving the record.  In this way you forced the system to use your record ID rather than wait for the record to be committed. Each child record you added you would need to pass the ContactID and properly set the foreign key field so that the child records were linked to the opportunity.  And if the user later decided not to actually insert the contact, you had to remember to go in and delete any child records you may have inserted already.  In short, a big headache.

With the entity model you simple tell the system you want to add a new child entity into the parent entity’s collection.  The system automatically worries about if it exists yet and how to actually do the linking for you.

Lets take look at the proper way of doing this.

First of all, lets talk about one way of doing it that should not be used.  Using the entity Save() method.  The reason that this should not be used is because calling Save() on a child record will actually roll-up and save all parent entities and all child entities of the parent.  This could lead to premature saving that could bypass important business validation logic.  Lets look at one example.

Say we have the insert Contact screen and when the Contact Status is set to a certain value we want to create some activity record. To do so we could use code like:

Sage.Entity.Interfaces.IContact contact = this.BindingSource.Current as Sage.Entity.Interfaces.IContact
Sage.Entity.Interfaces.IActivity act = Sage.Platform.EntityFactory.Create<Sage.Entity.Interfaces.IActivity>();
act.AccountId =  contact.Account.Id.ToString();
act.AccountName = contact.Account.AccountName;
act.ContactId =  contact.Id.ToString();
act.Description = "Something"
//...
act.Save()

Now the problem with this code is three fold.

1. We do not yet have the contact.Id property filled in.  This is only generated after the Contact entity has been saved and not during the insertion process.  If the Activity entity had a entity relationship property called Contact which represented Sage.Entity.Interfaces.IContact, we could instead pass in act.Contact = contact, but again this is not the best approach because of the next point.
2. Calling the act.Save() will actually save the new Activity record but also save it’s parent, the new Contact we are inserting.  At this point maybe the contact is not fully completed.  We do not want to trigger the parent Save method prematurely.  For this reason, lets look at the right way of doing it
3. Using the Save() method like this also means you would need to remove this saved record, should the user decide to not complete the insertion of the new contact.  However that would also be complicated since by calling the child’s Save() method you have already actually saved the Contact record!

The proper way of adding children to an entity is by inserting records into the parents collection.  So instead of the code above having

act.Save();

at the end, we would instead want to add the new Activity record to the Contacts, Activity collection like so:

contact.Activities.Add(act);

Using this method simply adds the Activity into a temporary collection that will be actually added to the database once the user chooses to insert the contact.  When the contact.Save() method is eventually called it will save all of the parent data and any data residing in child collections.  Conversely if the user cancels the insertion all of the pending child collections are flushed automatically.

Again, the Entity Model, if understood, simplifies how you do things in the SalesLogix web client.  You no longer need to worry about if your parent record exists, or how to correctly bind records together.  Using the Entity Model correctly takes care of these things for you.