Modify Entity

Make changes to properties or attributes of an entity.

Introduction

Familiar with Lava's Entity command for data retrieval? The Modify Entity command extends its capabilities, allowing you to update or insert data directly into your database, enhancing your data management toolkit.

While the Modify Entity command is a powerful tool, it comes with significant security responsibilities. It's crucial to thoroughly understand and implement the security measures outlined in the following section before integrating this command into your Lava workflows.

The modify entity command allows you to update a single entity in your database. Below is a very simple example where we are changing the nick name, connection status and an attribute of a specific person in the database.

{% assign personId = 12 %}
{% assign nickName = 'Ted' %}
{% assign connectionStatus = 67 %}
{% assign employer = 'Rock Solid Church' %}

{% modifyperson id:'{{ personId }}' %}

    [[ property name:'NickName' ]]{{ nickName }}[[ endproperty ]]
    [[ property name:'ConnectionStatusValueId' ]]{{ connectionStatus }}[[ endproperty ]]

    [[ attribute key:'Employer']]{{ employer }}[[ endattribute ]]

{% endmodifyperson %}

Pretty cool right?! Let's look at some of the input options at your disposal.

• id - This is a required input that tells us what entity we want to update. The value for 'id' can be an integer, guid or IdKey. If you provide an id of '0' then we'll know to create a new entity instead of updating an existing record. We strongly recommend using GUIDs when passing data to your endpoints for the Modify Entity command. This approach significantly enhances security by making it harder for someone to manipulate your endpoint by altering an ID integer.

• securityenabled (true) - Determines if entity security should be checked. Be careful with modifying individuals as there is no security on the person entity.

• clientvalidationenabled (false) - When enabled the block will wire-up client-side validation for you. See the Client-Side Validation section below.

• result (ModifyResult) - The key designated for the merge field to hold the command's results.

Properties

To edit an entity's property, simply specify the property name and the desired value. Ensure that the provided data type and value are accurate and appropriate for the property.

• name - The name of the property to update. Note that names are case-sensitive.

• injectionpreventionenabled - This setting is defaulted to true and instructs the command to check and prevent any potential script injection strings within the value. By default this setting is enabled. You should not disable this unless you fully trust the source of the value. When enabled your value will create a validation error if it contains '<' character followed by any single digit, lowercase letter, uppercase letter, or the '/' character. This matches the logic of other places in Rock. (SQL injection prevention is provided by .Net's Entity Framework.

Attributes

Updating an entity's attribute requires specifying the attribute's key along with a new value. Similar to properties, the provided value must match the expected format for the specific attribute. For guidance on the raw values required by different attribute types, refer to the documentation on this page.

• key - The attribute key for the attribute that you want to update.

• injectionpreventionenabled - This setting is defaulted to true and instructs the command to check and prevent any potential script injection strings within the value. By default this setting is enabled. You should not disable this unless you fully trust the source of the value. When enabled your value will create a validation error if it contains '<' character followed by any single digit, lowercase letter, uppercase letter, or the '/' character. This matches the logic of other places in Rock. (SQL injection prevention is provided by .Net's Entity Framework.

Property and Attribute Validation

Both the property and attribute elements can handle data validation for you through additional settings. These settings mimic the HTML validation API. The Rock data model does enforce some validation for you (e.g. a group must have a name) but these settings allow you to go above and beyond.


• isrequired - When set to true, the field will require a value.

• min - Ensures that the value is numeric and less than the value provided.

• max - Ensures that the value is numeric and more than the value provide.

• minlength - Verifies that the value's length does not exceed the specified limit.

• maxlength - Verifies that the value's length is more than the specified value.

• pattern - Ensures that the value provided matches the RegEx pattern you provided. This pattern must be a valid C# regex. In most cases the same pattern you use in HTML will also work here. validationmessage - The message to show if these rules above are not matched. If not provided a default message will be displayed.

• control - An optional parameter to determine what front-end control provided the value.

• validationmessage - The message to use when the value is not valid. Used for client-side validation.

Result Merge Fields

The properties and attributes you wish to modify should be specified within the Lava block. We will explore each of these in detail.

The command will insert a merge field labeled ModifyResult (this can be change by the result parameter), providing details about the update's outcomes. The field has the following properties:

• Success - A boolean value that determines if the record was saved successfully.

• Object - The modified object will be available using the key of the object type. For instance if you modified a person the key would be ModifyResult.Person, a group would be ModifyResult.Group.

• ErrorMessage - Should any issues occur, this field will detail the nature of the problem.

• ValidationErrors - This is a list of the validation errors that occurred.

  • ErrorMessage - Specific validation message.

  • SourceControl - The control that was linked to the message. This is provided through the control setting on the property or attribute.

Below is some sample Lava showing error information.

 {% if ModifyResult.Success == false %}
    <div class="alert alert-warning">
        <strong>{{ ModifyResult.ErrorMessage }}</strong><br>
        Validation Messages<br>
        <ul>
        {% for message in ModifyResult.ValidationErrors %}
            <li>{{ message.ErrorMessage }}</li>
        {% endfor %}
        </ul>
    </div> 
{% endif %}

Client-side Validation

Client-side validation only works with Lava Applications when using the Lava Application Content Block and Endpoint.

When this clientvalidationenabled property is set to true and validation configuration is added to properties and/or attributes the endpoint can send configuration back to the client to display the validation messages for you and to highlight the control that needs attention.