This method can be applied to a variable based on a Business Component type of a Transaction, in order to try to insert in the database the data previously assigned to the variable.
When the Insert method is executed, the data previously assigned into memory will be inserted only if the referential integrity doesn't fail (because it is checked) and if error rules don't occur (because the rules defined in the Transaction are triggered).
The method always returns a boolean value that informs if the addition to the database could be executed successfully or not. The boolean value can be evaluated by you or not.
&BCVariable.Insert()
Where:
&BCVariable is a scalar or collection variable based on a Business Component type.
Type returned
Boolean
Consider the following Transaction as Business Component (by setting its Business Component property = True):
Customer
{
CustomerId* (Autonumber property = True)
CustomerName
CustomerAddress
CustomerPhone
CustomerEmail
CustomerAddedDate
CustomerTotalMiles
}
Customer rule:
Default(CustomerAddedDate,&today);
Thus, a business component data type of the Customer Transaction is automatically created in the KB and you are able to define in any object, a variable of the new type created.
Assume you define a variable named &customer based on the Customer type in any object.
1) The following code (defined for example in a Procedure source or inside an event in a Web Panel object) is inserting a customer:
&Customer=new() //in this case the new operator can be ommited, but if more than one customer is inserted, it must be used
&Customer.CustomerName = 'Mary'
&Customer.CustomerLastName = 'Brown'
&Customer.CustomerAddress = '767 5th Avenue'
&Customer.CustomerEmail = 'mbrown@gmail.com'
&Customer.Insert()
if &Customer.Success()
commit
else
msg(&Customer.GetMessages().ToJson(), status)
endif
2) The following code (defined for example in a procedure source or inside an event in a Web Panel) is inserting a customer. It is almost equal to the previous example with the unique variant that the result of applying the Insert() method is directly evaluated with an if sentence:
&Customer=new() //in this case the new operator can be ommited, but if more than one customer is inserted, it must be used
&Customer.CustomerName = 'Mary'
&Customer.CustomerLastName = 'Brown'
&Customer.CustomerAddress = '767 5th Avenue'
&Customer.CustomerEmail = 'mbrown@gmail.com'
if (&Customer.Insert())
commit
else
msg(&Customer.GetMessages().ToJson(), status)
endif
3) The following procedure is called from several objects. It receives a &Customer variable based on the Customer type and it only has to perform the addition in the database:
Procedure: InsertCustomer
Rules
parm(in:&Customer)
Source
&Customer.Insert()
if &Customer.Success()
commit
else
msg(&Customer.GetMessages().ToJson(), status)
endif
4) Now, suppose you define the following Transaction as Business Component (by setting its Business Component property = True):
Product
{
ProductId*
ProductName
ProductStock
}
So, a business component data type of the Product Transaction is automatically created in the KB and you are able to define in any object, a variable of the new type created (and it can be set as a collection).
Thus, in a certain object, a variable named &Products is defined based on the Product type and it is set as a collection. The DPProducts Data Provider loads the &Products variable (for example inside an event). Once the &Products variable is loaded, the Insert method is applied to it as follows:
&Products=DPProducts()
if &Products.Insert()
Commit
else
msg(&Products.GetMessages().ToJson(), status)
endif
Look at the DPProducts Data Provider definition:
Data Provider: DPProducts
Properties: Output:Product / Collection:True
Source:
Product
{
ProductId = 100
ProductName = 'X Muscular Pain Medicine'
ProductStock = 1000
}
Product
{
ProductId = 101
ProductName = 'J Headache Medicine'
ProductStock = 1500
}
In conclusion, a collection of products is loaded and after that, the Insert method is applied to the collection variable. Each product in the collection will be inserted.
If there's an error in a BC from the list, are the following BCs processed?
Yes, all elements in the list are processed whether or not an error occurs. Then, it's up to you to commit the changes depending on the errors or not.
If you want to know which BCs had an error, he has to scan the list and check each one; for example, after applying the Insert method, he may write the following code:
For &Product in &Products
if &Product.GetMessages().Count > 0
//msg(...)
endif
endfor
This method is available since GeneXus 15.
Business Components - Differences between the Save method and the Insert and Update methods
Error handling in Business Components