Customize delivery process

Level: intermediate

Creatio lets you execute CRUD operations with data as part of package installation using SQL scripts. However, if you execute CRUD operations with data using SQL scripts, you will not be able to completely roll back the configuration, including any data changes. This is because SQL scripts make irreversible changes to the database as part of the package installation process. To prevent that, use the install step functionality instead. The install step functionality is designed to execute CRUD operations with data as part of package installation in a way that does not cause irreparable changes to the database.

Creatio lets you use backward compatible SQL scripts to completely back the configuration. Learn more in a separate article: Backward compatible SQL scripts.

Use the install step functionality to execute the following actions as part of package installation:

• execute the previous setup for the Creatio instance
• populate the values of new columns
• move data to a new object structure
• generate app demo data

Important

Creatio lets you set up the install steps only for assembly packages. To set up the install steps for a simple package or project package, convert the package to an assembly package. Learn more about assembly packages and package conversion in separate articles: Assembly package, Package conversion.

Steps to customize delivery process

1. Implement an install script
2. Add the install script to the installation steps

1. Implement an install script

A package install script is a Source code package schema. The install script implements the IInstallScriptExecutor interface. Use the Entity class to implement CRUD operations with data. Do not use C# classes listed in a separate article: C# classes to avoid in install scripts. The purpose of install scripts is to execute C# code as part of package installation. Install script executes database queries using the ORM model. Use install scripts to ensure you can roll the configuration back completely. An install script corresponds to one install step.

To implement an install script:

1. Create a Source code schema. Learn more about creating a schema in a separate article: Source code (C#).

2. Create a class that implements the install script.

   • Add the Terrasoft.Core namespace in the Schema Designer.
   • Implement the Terrasoft.Core.IInstallScriptExecutor interface.

   We recommend creating an object using the EntitySchemaManager.GetEntityByName(string name, UserConnection userConnection) method that lets you receive an object with new fields that are being delivered for the first time.

3. Click Publish on the Source Code Designer’s toolbar to compile the schema.

Click the Run as install script button on the Source Code Designer’s toolbar to debug the install script during development.

2. Add the install script to the installation steps

1. Open the Configuration section and select a custom package.

2. Select Properties in the package menu.

3. Go to the Installation steps tab to set up the execution order of install steps as part of package installation.

   The Installation steps tab contains the following start events:

   • Before package installation
   • After package installation
   • Before package deletion

   

4. Add the install script to the start event.

   1. Click + Add in the block of the start event.
   2. Select the schema that contains the install script.
   3. Click Select.

   Creatio lets you execute the following actions on the Installation steps tab:

   • Add multiple install steps to a start event.
   • Drag install scripts within the block of a start event to change the execution order.
   • Click the button to delete an install step.
   • Click Run manually on an install step record to execute the script for the current Creatio instance without installing the package.

   If you use an install script to add a new record to an object that is being delivered for the first time, add the script to the After package installation start event. Otherwise, the install script execution will result in an error.

5. Click Apply.

As a result, Creatio will execute the added install scripts as part of package installation.

Creatio executes the Execute() method of the class that implements the Terrasoft.Core.IInstallScriptExecutor interface as part of package installation. The method is called from Source code schemas specified on the Installation steps tab. If the Source code schema contains more than 1 interface of a class, Creatio executes the Execute() method for each class that inherits from the Terrasoft.Core.IInstallScriptExecutor interface.

Work with big data

The execution time of install scripts is comparable with SQL scripts when working with small data sets. When working with large data sets, for example, 10,000 records, the script execution time increases the installation time significantly.

The effect of running the install script on the total installation time can differ depending on various factors, such as:

• the size of the data set with which the script is working
• computationally expensive operations within the script
• the resources allocated to the application server and the database, etc.

For example, you need to operate on a large data set, and the execution time of the install script is critical. Maximum number of records that you can obtain by EntitySchemaQuery request is specified in the MaxEntityRowCount (the default value is 20000). When working with large data sets, all records are loaded into memory, which can cauze the app to freeze. To prevent that, use pagination in EntitySchemaQuery requests.

When you work with large data sets, we recommend following these recommendations:

1. Use SQL scripts rather than install scripts.
2. Clear the Backward compatible checkbox for the used SQL script.
3. If the package installation ends with an error, restore the configuration from a database backup.

---

See also

Assembly package

Package conversion

Source code (C#)

Creatio IDE

Packages basics

Backward compatible SQL scripts