GS_08_Update_existing_data - XLRIT/gears GitHub Wiki

Until now you have created new results. Of course another result would be changes to existing data.

In this chapter we will change existing data both automatically and manually.

1. Table of content

2. Change existing data automatically

To change existing data, we use the for each|for the only|for the first|for the last} construct (as described in SN3 Language Reference Manual).

This will also be the first time that you will create a process without input from a users/actor. It is simply creating a process that has no input from. Let's start:

  1. Create a new file called Increase prices automatically.sn file under folder specs.
  2. Fill it with the following content:
process 'Increase prices automatically' startable by PRODUCT_MANAGER

results in:
    "all prices are increased by 10%"

"all prices are increased by 10%" =
    for each PRODUCT in PRODUCTS applies:
        PRODUCT.price = PRODUCT.price * 1.1

Most you already know about, but there are some new parts:

Text Explanation
startable by PRODUCT_MANAGER will make it possible for a user with role PRODUCT_MANAGER to start this process.
for each PRODUCT in PRODUCTS applies: create results or change existing data for each PRODUCT in the collection of all PRODUCTS.
PRODUCT.price = PRODUCT.price * 1.1 this changes the price of each PRODUCT to the existing price times 1.1. In other words, this will increase the price with 10%.
  1. Do a GEARS: Generate. It should result in an error Error in process 'Increase prices automatically': the initial dependency graph contains an unelided cycle.

This is the first time you come across a "circular dependency" and that is because SMART Notation is a declarative language. This means it defines the end result of a process and not the steps needed to achieve this end result. This has a lot of benefits, but it also introduces problems such as using a piece of information that is also being updated in that same end result. In this example the value of PRODUCT.price that is needed to update the value of the same PRODUCT.price.

  1. To resolve this simply add the word current in front of PRODUCT.price * 1.1.

This refers to the value of PRODUCT.price before it was changed by this process.

  1. Do a GEARS: Generate, GEARS: Run Application, GEARS: Load data and run the process Increase prices automatically.

You will so that you can not run the process. That is because we forgot to add the product_manager role to the test data and also assign somebody to that role. You have done a similar thing already as part of GS_03_Create_first_working_app when you added the customer role and assigned user demo to it.

  1. Do that now.
  2. Do a GEARS: Run Application, GEARS: Load data and run the process Increase prices automatically.

It will seem like nothing happened. But it did. However, it worked completely autonomously, so without needing any input. Let's check if it actually did anything:

  1. In the application open menu Products and check the prices. This how it should look like:

  1. Run the process Increase prices automatically again and open menu Products to see if the prices have indeed been increased with 10%. This is probably how it would look like

As you can see the prices have indeed been increase by 10%.

3. Change data manually

Although changing prices automatically, it is often more logical to change prices manually. That would be as simple as to add an input from to fill the PRODUCT.price. Let's try that now.

  1. Copy paste the existing file Increase prices automatically.sn and rename the copy to Update products.sn.

In the next step we are going to remove add or change existing text. We will use diff notation to make to easier.

  • A - line followed by a + means a replacement.
  • A - without a following + means that you need to delete that text.
  • And a + without a - before it means you only need to add. The surrounding text should make clear where to add text.
  1. Make the following changes:
-process 'Increase prices automatically' startable by PRODUCT_MANAGER
+process 'Update products'
 
-"all prices are increased by 10%"
+"all products are updated"

+        PRODUCT.name  = input from PRODUCT_MANAGER
+        and
-        PRODUCT.price = current PRODUCT.price * 1.1
+        PRODUCT.price = input from PRODUCT_MANAGER
+                        labeled 'New price'
+                        default current PRODUCT.price * 1.1 
+                        based on {'Old price': current PRODUCT.price}

Here is the explanation for the parts that may be new to you:

Text Explanation
labeled 'New price' To give a specific label to this input.
default this indicates the default value of this input
based on defines the information that the user needs to be able to give the input. Most often this information is expressed with a tuple (remember...tuples are those key value pairs we used in GS_07_Create_DOCX_or_PDF_output...)
  1. Do a GEARS: Generate, GEARS: Run Application, GEARS: Load Data and execute this new process Update products.

The resulting screen should look a bit like this:

4. Schedule automatic processes

You can schedule to run processes. For instance every day, week, month, year, etc. at a certain time like for instance 0:00h. The way to do that is described here: Schedule processes.

This can be used to for instance update the prices automatically every year at a certain moment in time. For this getting started it is not required to try this out, but we highly recommend you to try it anyway. So, go for it. Try to schedule the Increase prices automatically process to say every 1 minutes and see if it actually works.

5. Tidy up and commit/sync your work

You should now know how to tidy up and commit/sync your work, so simply do that as you did in the previous chapters.

6. Do it yourself

TODO.

6.1. Situation: TODO

6.2. Assignment: TODO