Business Component InsertOrUpdate method

Official Content
This documentation is valid for:

This method can be applied to a variable based on a business component type of a transaction in order to perform an “upsert” operation; that is to say, an addition will be attempted, but if it fails because a duplicate key is found, an update will be performed.

Syntax

    &BCVariable.InsertOrUpdate()

Where:
   &BCVariable is a scalar or collection variable based on a Business Component type.  

Type returned
    Boolean

Examples

1) Let's suppose we define the following transaction as Business Component (by setting its Business Component property = True):

Customer
{
  CustomerId*     
  CustomerName
  CustomerAddress
  CustomerPhone
  CustomerEmail
  CustomerAddedDate
}

So, a business component data type of the Customer transaction is automatically created in the KB and we are able to define in any object, a variable of the new type created. 

Thus, the following procedure receives a &Customer variable based on the Customer type, and in its source, the InsertOrUpdate method is applied to the variable in order to try to insert the customer or update it if the addition fails because the key is duplicated.

Procedure: InsertOrUpdateCustomer
   Rules
      parm(in:&Customer)
   Source
      &Customer.InsertOrUpdate()
      if &Customer.success()
         commit
      else
         rollback
      endif


2) Let's suppose we 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 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 InsertOrUpdate method is applied to it as follows:

&Products=DPProducts()
if &Products.InsertOrUpdate()
    Commit    
else
    Rollback
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 InsertOrUpdate method is applied to the collection variable. Each insertion will be tried, and if some product of the collection already exists physically, it will be updated.

3) Now, let's suppose we define the following two-level transaction as Business Component (by setting its Business Component property = True):

Country
{
  CountryId*     
  CountryName
  CountryFlag 
  CountryPopulation 
  City
  {
   CityId*
   CityName
  }
}

So, a business component data type of the Country transaction is automatically created in the KB and we are able to define in any object, a variable of the new type created. 

Let's suppose that a record with CountryId=1 is already stored, its corresponding CountryName='Uruguay', its CountryPopulation=3300000, the CountryFlag has the corresponding stored image and the following related cities are also stored:

1, 1, Montevideo
1, 2, Maldonado
1, 3, Colonia

After that, in some object, a variable named &Countries is defined based on the Country type and it is set as a collection. The DPCountries Data Provider loads the &Countries variable (for example inside an event). Once the &Countries variable is loaded, the InsertOrUpdate method is applied to it as follows:

&Countries=DPCountries()
&Countries.InsertOrUpdate()
if &Countries.success()
    Commit    
else
    Rollback
endif

Look at the DPCountries Data Provider definition:

Data Provider: DPCountries
Properties: Output:Country / Collection:True

Source:
Country
{
  CountryId = 1
  CountryPopulation = 3445863
  City
  {
    CityId = 4
    CityName = 'Salto'
  }
  City
  {
    CityId = 5
    CityName = 'Paysandu'
  }
}

Country
{ 
  CountryId = 2 
  CountryName = Argentina
  CountryFlag = ArgentinaFlag.Link()
  CountryPopulation = 43000000
  City
  { 
    CityId = 1
    CityName = 'Buenos Aires'
  }
  City
  { 
    CityId = 2
    CityName = 'Rosario'
  } 
  City
  {
    CityId = 3
    CityName = 'Cordoba'
  } 
}

For the CountryId=1, the insertion will be tried, but the CountryId=1 already exists. So, its CountryPopulation will be updated and the CityId=4 and the CityId=5 will be added related to it. Then, For the CountryId=2 , the insertion will be tried and it will be successful.


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 the developer to commit the changes depending on the errors or not. 
If the developer wants to know which BCs had an error, he has to scan the list and check each one; for example, after applying the InsertOrUpdate method, he may write the following code: 

For &Product in &Products
    if &Product.GetMessages().Count > 0
       //msg(...)
    endif
endfor

 

Availability

This method is available since GeneXus 15.

Notes: 

  • For iOS offline is available as from GeneXus 15 Upgrade 2.
  • If the primary key has its Autonumber property set to True, the method will always insert, since it's never going to happen that a duplicate key is detected (because always a new identifier value is generated). 

 

See also

Error handling in Business Components

 



Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.