Create changes

Scripts that Firefly should execute during the migration process are called “change”. All your changes are stored in a folder called “changes”. This folder needs to be located at the root of your extension. To manage your changes, Firefly uses a XML based data format. You can link the XSD in your favourite IDE using the URL: https://raw.githubusercontent.com/neuland/firefly/master/resources/schema/firefly-v1.xsd Every XML file located in the change folder needs to be compliant with this schema.

Organise your changes

There are two ways to organise your changes. You can either use change list files or use changes directly. What you want to use, will differ from extension to extension. If you have many changes and many committers you will probably use change list files. Otherwise the direct usage of changes will be sufficient.

Example:

changes/0.1_createJob.xml
changes/0.2_addPaymentMethod.xml
changes/0.3_cleanCustomerData.xml

Direct change files

All files found in the change directory will be executed by in alphabetically order.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<changeDescription xmlns="http://firefly.neuland-bfi.de/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://firefly.neuland-bfi.de/v1 https://raw.githubusercontent.com/neuland/firefly/master/resources/schema/firefly-v1.xsd">
    … List of changes …
</changeDescription>

Change list files

As with direct change files, all files found in the change directory will be executed by in alphabetically order. But in a change list file you can link other change files in any order you like. This can be very helpful if you want to define the order of execution during a merge in your VCS.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<changeList xmlns="http://firefly.neuland-bfi.de/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://firefly.neuland-bfi.de/v1 https://raw.githubusercontent.com/neuland/firefly/master/resources/schema/firefly-v1.xsd">
   <change file="unitTest/noOp.xml"/>
   <change file="unitTest/anotherNoOp.xml"/>
</changeList>

Meta information for your changes

You can add as many changes to a change file as you need. Within a change file, every change must be identified uniquely using the author and id attributes. Every script can be added to the change as content of the XML or can be linked and store in a different file.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<changeDescription xmlns="http://firefly.neuland-bfi.de/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://firefly.neuland-bfi.de/v1 https://raw.githubusercontent.com/neuland/firefly/master/resources/schema/firefly-v1.xsd">
   <beanShell author="jUnit" id="1">
       print(ctx.getBeanDefinitionNames().length);
   </beanShell>
   <groovy author="jUnit" id="2"><![CDATA[
       println ctx.beanDefinitionNames.size()
   ]]></groovy>
   <sql author="jUnit" id="3">
       SELECT COUNT(p_name) AS EXTENSION_COUNT FROM FireflyExtension;
   </sql>
   <sql author="jUnit" id="4">
       UPDATE FireflyExtension SET p_name = p_name;
   </sql>
   <impEx author="jUnit" id="5"><![CDATA[
       INSERT_UPDATE FireflyExtension;name[unique=true]
       ;firefly
   ]]></impEx> 
   <groovy author="jUnit" id="6" file="scripts/beans.groovy" /> 
</changeDescription>

Preconditions

If you want to execute your changes online if certain conditions are met, you can add preconditions. The precondition is a groovy script that must return a boolean value. If null is returned, the result is treated as false.

Example:

<groovy author="jUnit" id="6" description="Change with precondition" 
       precondition="fireflyContext" onPreconditionFail="MARK_RAN">
   println "I will be skipped"
</groovy>
<precondition id="fireflyContext">
   fireflyContext.FIREFLY_JUNIT
</precondition>

Precondition Failure

For every chnage a behaviour for precondition failure can be defined. These are the possible values:

Value	Descriotion
HALT	Halt the migration. This is the default value.
CONTINUE	Contiue the migration. The change will not be executed, but the precondition will be checked during the next migration.
MARK_RAN	Contiue the migration. The change will be marked as executed and the precondition will ne be checked during the next migrations.
WARN	Contiue the migration, but log the precondition result. The change will not be executed, but the precondition will be checked during the next migration.

Evaluating Context

The values definined in the firefly.context propertiy are passed into the fireflyContext-Map. More than one context condition can be evaluated using groovy logic. Example:

fireflyContext.DEV || fireflyContext.LOCAL

Evaluating SQL

Native SQL can be executed (read only) to check the current state of the database. An connected instance of groovy.sql.Sql can be accessed using sql. Example:

sql.rows("SELECT p_name FROM FireflyExtension WHERE p_name='firefly-junit'").isEmpty()

Evaluating flexible search queries

The hybris Spring context is injected into the script enviroment. This offers a wide range of possibilities. One of which is to execute and evaluate a flexible search query.
Example:

ctx.getBean('flexibleSearchService').search("""
   SELECT {pk} FROM {FireflyExtension} WHERE {name} = 'firefly-junit'
""").count == 0