Version: 8.0

Create an entity using a web form

Level: advanced

The Contact entity contains the CustomRequiredTextColumn required text column. When an event participant (EventTarget) is created via a web form, Creatio searches for the corresponding contact. By default, if Creatio cannot find the contact, a new contact is created. Saving the contact leads to an error since the CustomRequiredTextColumn required field is not populated. To ensure the contact is saved successfully, implement a custom handler and call it before an event participant is created.

Example

Implement a custom handler that runs before an event participant is created.

Before you implement the example, set up a web form that creates a custom object. Add a CustomRequiredTextColumn required custom field to the web form. To do this, follow the instructions in a separate article: Set up web form for a custom object.

1. Implement a custom handler

Go to the Configuration section and select a user-made package to add the schema.
Click Add → Source code on the section list toolbar.
Go to the Schema Designer and fill out the schema properties:
- Set Code to "UsrCustomWebFormEventTargetPreProcessHandler".
- Set Title to "CustomWebFormEventTargetPreProcessHandler".
Click Apply to apply the properties.

Implement a custom handler that runs before an event participant is created.

Add a Terrasoft.Configuration namespace in the Schema Designer.
Add namespaces whose data types to utilize in the class using the using directive.
Add a class name that matches the schema name (the Code property).
Specify the WebFormEventTargetPreProcessHandler class as a parent class.

View the source code of the UsrCustomWebFormEventTargetPreProcessHandler schema of the Source code type below.

UsrCustomWebFormEventTargetPreProcessHandler
namespace Terrasoft.Configuration
{
    using System;
    using System.Linq;
    using Core.Entities;
    using Core;
    using GeneratedWebFormService;

    #region Class: UsrCustomWebFormEventTargetPreProcessHandler
    /// <summary>
    /// Call the custom handler before the event participant is saved.
    /// </summary>
    /// <seealso cref="Terrasoft.Configuration.IGeneratedWebFormPreProcessHandler" />
    public class CustomWebFormEventTargetPreProcessHandler: WebFormEventTargetPreProcessHandler, IGeneratedWebFormPreProcessHandler
    {

        #region Properties: Private
        private UserConnection _userConnection { get; set; }
        private FormData _formData { get; set; }
        #endregion

        #region Methods: Private
        private string GetCustomRequiredColumnValue(string customColumnName) {
            var customFormField = this._formData.formFieldsData
                .FirstOrDefault(x => x.name == customColumnName);
            if (customFormField == null) { 
                throw new Exception($"There is no required form field {customColumnName}");
            }
            if (string.IsNullOrEmpty(customFormField?.value)) {
                throw new Exception($"Required value is empty for field {customColumnName}");
            }
            return customFormField.value;
        }
        #endregion
        
        #region Methods: Protected
        /// <summary>
        /// Create a contact entity whose custom required text column is populated with the form value.
        /// </summary>
        /// <param name="contactId">The unique contact ID.</param>
        /// <param name="contactNameField">The required contact name field of the form.</param>
        protected override void CreateContactEntity(Guid contactId, FormFieldsData contactNameField) {
            EntitySchema contactSchema = _userConnection.EntitySchemaManager.GetInstanceByName(nameof(Contact));
            Entity contact = contactSchema.CreateEntity(_userConnection);
            contact.SetDefColumnValues();
            contact.SetColumnValue("Id", contactId);
            contact.SetColumnValue("Name", contactNameField.value);

            // Set the value of the custom required column.
            var customRequiredColumnName = nameof(Contact.CustomRequiredTextColumn);
            var customRequiredColumnValue = GetCustomRequiredColumnValue(customRequiredColumnName);
            contact.SetColumnValue(customRequiredColumnName, customRequiredColumnValue);

            contact.Save(false);
        }
        #endregion

        #region Methods: Public
        /// <inheritdoc/>
        /// Overload the inherited method so that it initiates the <see cref="UserConnection"/> and <see cref="FormData"/> instances.
        public new FormData Execute(UserConnection userConnection, FormData formData,
                IWebFormImportParamsGenerator paramsGenerator) {
            _userConnection = userConnection;
            _formData = formData;
            return base.Execute(userConnection, formData, paramsGenerator);
        }
        #endregion
    }
    #endregion
}

Click Save then Publish on the Designer's toolbar.

2. Register a custom handler in the database

To implement the custom handler, register it in the [WebFormProcessHandlers] database table.

You can register the custom handler in the database in several ways:

using a lookup

To register the custom handler in the database using a lookup:
1. Click to open the System Designer.
2. Go to the System setup block → Lookups.
3. Add a new handler record to the Web form process handlers entity lookup. By default, this lookup is absent from the index of Creatio lookups. To add the Web form process handlers lookup to Creatio, create a lookup and select the Web form process handlers object as the lookup object.
4. Fill out the lookup fields:
  - Set Entity name to "EventTarget".
  - Set FullClassName to "Terrasoft.Configuration.CustomWebFormEventTargetPreProcessHandler, Terrasoft.Configuration".
  - Select the Is active checkbox.

using an SQL query

To register the custom handler in the database using an SQL query, execute the following SQL query.

SQL query
INSERT INTO WebFormProcessHandlers (Id, EntityName, FullClassName, IsActive)
    VALUES (NEWID(), N'EventTarget', 'Terrasoft.Configuration.CustomWebFormEventTargetPreProcessHandler, Terrasoft.Configuration', 1)

Since the schema inherits from the out-of-the-box handler and the custom schema calls the base logic, you must disable the out-of-the-box handler.

You can disable the out-of-the-box handler in the following ways:

using a lookup

To disable the out-of-the-box handler using a lookup:
1. Click to open the System Designer.
2. Go to the System setup block → Lookups.
3. Open the lookup and clear the Is active checkbox for the EventTarget entity that has the "Terrasoft.Configuration.CustomWebFormEventTargetPreProcessHandler, Terrasoft.Configuration" value in the FullClassName field.

using an SQL query

To disable the out-of-the-box handler using an SQL query, execute the following SQL query.

SQL query
UPDATE WebFormProcessHandlers
SET IsActive = 0
WHERE FullClassName = 'Terrasoft.Configuration.WebFormEventTargetPreProcessHandler, Terrasoft.Configuration'

Outcome of the example

To view the outcome of the example, restart the application pool.

As a result, Creatio will add a new contact when a form is submitted with required fields populated, including the CustomRequiredTextColumn field.

1. Implement a custom handler​

2. Register a custom handler in the database​

Outcome of the example​

1. Implement a custom handler

2. Register a custom handler in the database

Outcome of the example