Operations and values

•
Environment: cloud
• 5 minutes to read
 • 5 minutes to read

Except for Toggle, every operation has a predefined list of parameter dependencies. For example, this means that when the SearchAndReplace operation is set, the FieldValueInfo.Values property is expected to contain at least three items, but can optionally contain up to 7 entries.

Each operation type has a different number of required parameters.

One of the simplest operations BulkUpdateSystem.OperationTypes.Toggle, simply flips the current value from true to false, or 0 to 1, and vice versa. Therefore, it’s not necessary to add any values to the FieldValueInfo.Values property to successfully perform the operation.

List of operations

Tip

Details of expected values are located in the entities and field types section and reference.

OperationTypes Description
SelectOne One or two values are expected for this operation.
Clear No values are used for this operation. Whatever value exists will be set to an empty string.
Set One or two values are expected for this operation.
Check One value is expected for this operation.
Check is used for mostly Boolean and short field types.
Toggle No values are used for this operation. Boolean fields will be Set to this opposite Setting. Fields with number values are either 1 or 0 and will be swapped accordingly.
AddItems Multiple values allowed. Values are added to the target.
RemoveItems Multiple values allowed. Values are removed from the target.
Add Two values expected.
Remove One value expected.
ReplaceWith Two values expected. Removes existing items and updates matching records.
SearchAndReplace Finds all matches and replaces existing information.
RegEx Uses in conjunction with SearchAndReplace, for advanced search scenarios.

Most updates of existing values will only need one or two values.

The trickiest thing about bulk updates is that for different operations, which not only expect different numbers of parameters, the parameters must be passed in specific indexes within the Values array.

Example

Using the Set operation as an example, only the first index of the array is expected to exist with a value to populate the field property. However, the SearchAndReplace operation expects the Values array to contain at least three but up to four indexes. Fields that accept the Set, Clear, SearchAndReplace, and RegEx operation types, and perform a SearchAndReplace operation only use the second ([1]) and third ([2]) index for execution.

Values array for: Set, Clear, SearchAndReplace, RegEx:

Bulk update Values array

When used with a field that accepts the Add, Remove, ReplaceWith, Clear, SearchAndReplace, and RegEx operation types, SearchAndReplace expects parameters to exist in the third ([2]) and fourth ([3]) index.

Values array for: Add, Remove, ReplaceWith, Clear, SearchAndReplace, RegEx:

Bulk update Values array

Note

There will be cases when some index values are populated but not used. Take the following code example, where a RegEx operation is performed. The first four indexes in the Values property are not used. For performing a RegEx operation, only the last three indexes are required.

// search for all companies where name begins with 'super'
var select = S.NewSelect<ContactTableInfo>(cti => cti.Name.Like("super%"));

// get all company id's from the search results 
var companyIds = select.Records(select.Table.ContactId).Select(r => r.Table.ContactId[r]).ToArray();

if (companyIds != null)
{
    // use BulkUpdateSystem.GetAvailableContactFields to get the Name FieldValueInfo
    var contactNameFieldValueInfo = BulkUpdateSystem.GetAvailableContactFields().Where(
        v => v.Key == BulkUpdateSystem.ContactFieldValueKeys.Name).FirstOrDefault();

    // use a set operation to update the field
    contactNameFieldValueInfo.CurrentOperationType = BulkUpdateSystem.OperationTypes.RegEx;
    
    // define the new value
    contactNameFieldValueInfo.Values = 
    new[]
    {
        "", // 0 Not Used
        "", // 1 Not Used
        "", // 2 Not Used
        "", // 3 Not Used
        @"super\s?office", // 4 RegEx (Locate)
        "SuperOffice",     // 5 Replace
        System.Text.RegularExpressions.RegexOptions.IgnoreCase.ToString(), // 6 RegexOptions
    };

    // instantiate a new BulkUpdate BackgroundJob
    BulkUpdateSystem.BackgroundJob updateJob = new BulkUpdateSystem.BackgroundJob(

    // define the target table name
    SuperOffice.CRM.Data.ContactTableInfo.DictionaryTableName,

    // set then FieldValueInfo
    new[] { contactNameFieldValueInfo },

    // set the company Ids that will be updated
    companyIds);

    // execute the job
    bool updateSuccess = updateJob.UpdateFieldsAsync();

    while (!updateJob.Done)
    {
        Thread.Sleep(500);
    }
}

Next: In Entities and field types, each field details what parameters are expected at which index in the Expected Field Values column.