Migration notes for M5

This page summarizes key changes from the previous milestone.

zero.data

Removal of start event

Several sample applications, including employee.demo, leveraged the "start event" in the Zero application start up lifecycle as a hook to create tables and populate some initial data. Since this event has been removed in M5, the runsql CLI task is now provided in order to allow developers to execute SQL from the command line.

Removal of zero.data.setup and zero.data.setup.webtools

bug 3443 The above setup components have been removed in favor of the runsql CLI task that is apart of the zero.data component. This means that

runsql

bug 3442 The runsql CLI task can be used from the command line to execute SQL anywhere on the file system:

zero runsql [dbKey] path/to/file.sql

If the command line isn't convenient, you can replicate a CLI invocation from Eclipse, from Ant, or programmatically using Application Launcher.

From Eclipse, simply specify arguments as Java application arguments as follows:

From Ant, use the exec task:

<exec executable="${zero.sh}">
  <arg value="runsql" />
  <arg value="path/to/file.sql" />
</exec>

For programmatic invocation (often from JUnit tests):

// there is some weirdness here at this point with passing in arguments to "runsql" and then setting the
// task as "runsql" after...but it works...
ApplicationLauncher _launcher = new ApplicationLauncher("EmployeeManagerTest", ".", "path/to/file.sql");
_launcher.setTask("runsql");
_launcher.start();
_launcher.stopApplication();

Zero Resource Model

Removal of start event

ZRM leveraged the "start event" in the Zero application start up lifecycle as a hook to create database artifacts requisite to support the declared models for an application and its dependencies and populate some initial data. Since this event has been removed in M5, the syncdb CLI task is now provided in order to allow developers to execute this functionality from the command line.

syncdb

Prior to the removal of the start handler, ZRM would create necessary artifacts at startup. Since this is no longer an option, the "syncdb" CLI task has been created. Use it as follows from the application root:

zero syncdb

CLI invocation can be replicated as illustrated in the runsql CLI task section of this document.

Model declaration syntax changes

ZRM removed the Groovy-based model declaration syntax and added a JSON-based one. The data structure syntax is nearly identical. For, instance, compare the following two code snippets:

M4 => /app/models/person.groovy:

fields = [
  name: [type: 'CharField'],
  age: [type: 'IntegerField'],
  email: [type: 'EmailField']
]

M5 => /app/models/person.json:

{
  "fields" : {
    "name" : {"type": "string"},
    "age": {"type": "integer"},
    "email": {"type": "string", "format": "email"}
  }
}

Note the obvious change is the JSON syntax. Next, that JSON contents in the model file MUST be a JSON Object. Which is why there is an opening and closing squiggly braces. The file

Finally, note that the Field variants are no longer valid for the "type" parameter for field definitions. Rather, there is a set of base primitive types: auto, boolean, string, date, date-time, decimal, float, integer, and time. Further, as in the case of the "email" field, there are string variants. These are specified using the "format" parameter. Valid parameters to string types are: large, phone, email. and region.

More details can be found in the ZRM declaration documentation.

Field improvements

ZRM has a number of field related improvements.

Changed field parameter names

• 'choices' is now 'options'
• 'help_text' is now 'description'
• 'verbose_name' is now 'title'
• 'editable' is now 'readonly'

For instance, consider the following examples:

M4 names and Groovy syntax:

// these are the old parameters
fields = [
  gender: [type: 'CharField', choices: ['M', 'F'], verbose_name: 'Person's gender', help_text: 'Gender is the sex of the person', editable: false],
]

Is replaced with M5 names and JSON syntax:

{
  "fields" : {
    "gender": {"type": "string", "options": ["M", "F"], "label": "Person's gender", "description": "Gender is the sex of the person", "readonly": true}
  }
}

New field parameters

• 'default_value' allows the developer to provide a default value when a value isn't provided on creation
• 'label' replaces 'verbose_name' as described above, but also takes on new characteristics ... if a value is not provided, 'title' defaults to a generated value from the field's name

{
  "fields" : {
    "first_name": {"type": "string", "label": "Person's name"},
    "last_name": {"type": "string"},
    "workphone": {"type": "string", "format": "phone"},
    "emailAddresss": {"type": "string", "format": "email"}
  }
}

first_name => is mapped to "Person's name" because it is explicitly provided last_name => is mapped to "Last name" workphone => is mapped to "Workphone" emailAddresss => is mapped to "Email address"

Removal of unused field parameters

• indexed
• unique
• empty_strings_allowed

Connectivity

There have been some minor configuration syntax changes for:

• /config/connection/destinations
• /config/connection/https

zero.assemble.flow

1. Change the event name convention of activity to make it more clear

The original event name convention of activity is "_[Activity Type]", e.g. we have the helloWorld activity, its event name will be "_helloWorld"

We will change it to [Activity Type]Activity, e.g. helloWorldActivity. Which is more clear to identify it is an Activity.

2. GC path changes for the Activity inputs to make it more understandable

access input list from /event/content to /event/inputs

access input map from /event/contentMap to /event/inputMap

Samples in groovy

event.inputs[0] will return the first input

event.inputMap["attachment"] will return the input named "attachment"

3. Simplify the way to return result of the activity

Sample in Groovy

def onHelloWorldActivity() {
   def input= event.inputs[0]
   event.result = "Hello, " + input
}

in Java

void onHelloWorldActivity() {
   String input = zget("/event/inputs#0");
   zput("/event/result", "Hello, " + input);
}

Note: Return the result by just setting it to event.result ("/event/result")

4. Using the convention to define the extension activity

In /app/assemble/activities directory, the developer can create the extension activity with Groovy in helloWorld.groovy

def onHelloWorldActivity() {
   def input= event.inputs[0]
   event.result = "Hello, " + input
}

metadata = [
   "inputOccurrence" : 1
]

Note:

• No need to add config in the zero.config
• We provide the ActvityResolver, which will resolve the Activity on demand in the runtime
• The metadata will be used to validate the activity by parser and tooling. And it is written in Groovy syntax.
• The original way to create the extension activity is also supported without any changes.