Something that is a common task in development, yet one that I get a lot of questions about, is how to programatically add a new record in SalesLogix Web using the entity model. This is an easy task, but unless you have some examples to learn from you might not know where to start. Let's take a look.

The EntityFactory is something you need to get familiar with. Get Reflector and dig around the Sage.Platform.dll to take a look. You'll use the EntityFactory to Create & Delete data. You can also use it to get a record by ID and to get a repository to query data in the entity model. Let's just take a look at using it to Create a new entity instance that we can save (which will add the new record to the database).

Scenario

Let's say we have an entity named Certification, which has a 1:M relationship to the Contact. We'll create a form under the contact where the user can choose a "certification" from a picklist and click an "add" button. We'll also put a DataGrid on the Form to display the certifications for the contact. When the "add" button is clicked we'll programatically create the certification record using the value the user selected in the picklist. Since the only selection to make is the certification, I like to do things like this instead of using a separate "add" form in a dialog that only contains a single control (the picklist). We've done away with the need to use an add dialog by just placing the picklist and add button controls right above the grid on the form itself.

The Code

The code that we'll execute on the Click of the add button would look as follows:

// make sure the user has selected a certification in the picklist
if (picklistCert.PickListValue != string.Empty)
{
    // get a reference to the current Contact
    Sage.Entity.Interfaces.IContact contact = this.BindingSource.Current as Sage.Entity.Interfaces.IContact;
    
    // programatically create a Certification and save it.
    // use the EntityFactory to create a new instance of the Certification entity
    Sage.Entity.Interfaces.ICertification certification = Sage.Platform.EntityFactory.Create<Sage.Entity.Interfaces.ICertification>(); 
    // now just set the properties & save
    certification.Contact = contact;
    certification.CertificationName = picklistCert.PickListValue;
    certification.Save();
    
    // add the certification to the contact's Certification collection. 
    // this is only needed to cause the grid bound to contact.Certifications to refresh
    contact.Certifications.Add(certification);
    
    picklistCert.PickListValue = string.Empty;
}
else
{
    // if the user clicked the add button without first choosing a certification display a message
    this.DialogService.ShowMessage("You must first select a certification to add. Please try again");    
}

You can see that the only tricky part is knowing how to create the new entity instance using the EntityFactory (I've bolded that line in the code above). Once you have that it is just a matter of setting the needed properties and saving it. Much easier than using a SQL INSERT statement or even adding a new record to an updateable ADO Recordset like how you would do this in the LAN client.