How to write deployment scripts

Moved here
[TOC]

Definition

A deployment script is a group of steps which must be taken to deploy a feature or bug fix once on a server. Currently the import of impex scripts and the execution of Sql, Beanshell and Groovy scripts is supported.

Examples of Deployments Scripts

The release contains the extension arecoDeploymentScriptsExamples which shows examples of deployments scripts:

Structure of a deployment script

• One deployment scripts is just a folder containing one or more files with SQL, Impex, Groovy or BeanShell code.
• The files have the extensions impex, sql, groovy or beanshell.
• It may contain a configuration file with the extension conf.
• All the deployment scripts must be in the directories resources/update-deployment-scripts or resources/init-deployment-scripts of an extension.
• There can be many extensions containing these folders. A good practise is to have the deployment scripts in an extension which is related to them.

How to write a UPDATE deployment script

Choose the right extension

• Find the extension which is more related which the issue you are working on.
• If it doesn't have the directory resources/update-deployment-scripts, you must create it.
• Create a directory with the current date and the ticket number. This is your new deployment script.

Impex scripts

• Create a file with the extension impex.
• Edit it and write the Impex code.
• Check that the content is UTF-8.

SQL Scripts

• Create a file with the extension sql.
• Edit it and write SQL query.
• Only one statement per file is allowed.
• The statement must not end with a semicolon.
• All valid SQL statements are allowed except for Selects because they return rows. This means that you can do, for example, updates, inserts (of numberseries), deletes, alter tables and create indexes.
• The pattern {table_prefix} can be used before the name of each table to make the queries work on any tenant. The replacement is case insensitive and it is used as in this example:

select p_value from {TABLE_PREFIX}taxes where p_code = 'dummySqlScriptTax'

• Check that the content is UTF-8.
• Check that the queries are compatible with all the databases engines used on your project.
• Hybris Cache: After a SQL script is run the cache automatically is emptied.
• Hybris Models must be refreshed: Because the models cache the values of their attributes, all the affected models must be resfreshed manually after the SQL script is run.

BeanShell Scripts

• Create a file with the extension beanshell.
• Edit it and write beanshell code.
• You could test your code using the scripting console in the Hybris Administration Console (HAC).
• If everything when right the beanshell must return the string "OK". This informs the deployment manager that there were no errors.
• Check that the content is UTF-8.

Groovy Scripts

• Create a file with the extension groovy.
• Edit it and write Groovy code.
• You could test your code using the scripting console in the Hybris Administration Console (HAC).
• If everything when right the script must return the string "OK". This informs the deployment manager that there were no errors.
• Check that the content is UTF-8.

Configuration of the scripts

• It defines the allowed environments and tenants for the deployment script.
• Create a property file with the extension conf.
• You could configure the following properties:

Property	Example Value	Description
runonlyonenvironments	DEV,TEST	List of names of deployment environments where this deployment script is allowed to run. The names are separated by commas and they are case insensitive. If the deployment script is started in the wrong environment, it is ignored. The execution result would be Ignored Other Environment.
runonlyontenants	junit	List of names of tenants where this deployment script is allowed to run. The names are separated by commas and the names are case-sensitive. If the deployment script is run in the wrong tenant, it is ignored. The execution result would be Ignored Other Tenant.
runmultipletimes	true	If the script will run multiple times during each essential or project data creation step. Normally script run once and this setting is considered false if absent. Because the initialization is run once, init scripts will always run once.

If you would like to use another environment names. Please read the [FAQ] to learn how to do the change.

Here are some examples of configuration files: [Examples of script Configuration files]

How to write a INIT deployment script

If you need to run your deployment script during the initialization, just put it in the folder resources/init-deployment-scripts and it will be executed.

This is a special case of deployment script and it is useful to import configuration data for the developers or test data for the integration tests.