Dynamics 365 Business Central: How to insert a record with a specified SystemId in AL

Hi, Readers.
Today I would like to talk briefly about how to insert a record with a specified SystemId in AL.

As you know, we can insert data directly through AL, which is very common during customization. The Record.Insert() method is used.

Record.Insert() Method: The Insert method inserts a record in a table.

Let’s look at a very simple example,

Customer.Init;
Customer."No." := '1120';
Customer.Insert();

And the inserted record will automatically get assigned a SystemId by the platform. (It has nothing to do with whether the OnInsert Trigger is executed or not)

What is the SystemId field?

SystemId field (APPLIES TO: Business Central 2019 release wave 2 and later)

The SystemId field is a GUID data type field that specifies a unique, immutable (read-only) identifier for records in the table. The SystemId field has the following characteristics and behavior:

All records must have a value in the SystemId field.
You can assign your own value when a record is inserted in the database. Otherwise, the platform will automatically generate and assign a value.
Once the SystemId has been set, it can’t be changed.
There’s always a unique secondary key on the SystemId field to ensure records don’t have identical field values.
The SystemId field is given the field number 2000000000.

The SystemId field can be used as a binding key to an API: For example,

And as I mentioned in Integrate with Microsoft Dataverse via APIs (Not using the standard Dataverse connector) two days ago, when integrating with Dataverse, we can couple it through a Guid field. I added a new field at the time, but if I could pass the value to the standard SystemId field, I wouldn’t have to add a new field.

So can we insert a record with a specified SystemId in AL? Yes, it’s not difficult, to assign a specific SystemId instead of the one assigned by the platform, use Insert(Boolean, Boolean) instead.

RunTrigger
Type: Boolean
If this parameter is true, the code in the OnInsert Trigger is executed. If this parameter is false, the code in the OnInsert trigger is not executed. The default value is false.

InsertWithSystemId
Type: Boolean
If this parameter is true, the SystemId field of the record is given a value that you explicitly assign. If a value is not assigned, then the platform assigns one. If this parameter is false, the SystemId field is given a value that is auto-generated by the platform. The default value is false.

Let’s look at another simple example,

Very simple.

Important
After the SystemId is set on a record, it can’t be changed.

Well, if you want to manually specify the SystemId field when inserting data, please use this method. Give it a try!!!😁

PS:
1. Dynamics 365 Business Central: The difference between Record.Validate() Method and assignment statement

2. Dynamics 365 Business Central: Can we insert/modify/delete posted data (Posted Documents & Posted Entries) via AL???

3. Dynamics 365 Business Central: How to get a record by its SystemId

END

Hope this will help.

Thanks for reading.

ZHU