Packages basics

PDF
Beginner

Any Creatio product is a set of packages.

A Creatio package is a collection of configuration elements that implement certain functionality. On the file system level, a package is a directory that defines a set of subdirectories and files.

Package classification 

  • Simple packages:

    • : preinstalled packages. They are part of Creatio. Predefined packages are available in the workspace by default. They cannot be modified.

      Preinstalled package types:

    • : custom packages. They are created by other Creatio users. Custom packages are locked in the version control system. They cannot be modified.
    • : custom packages. They are created by the current user or retrieved from the version control system. They can be modified.
  • Project package is a package that lets you develop functionality similarly to a standard C# project. Learn more in a separate article: Project package.
  • Assembly package is a package whose source and automatically generated code is compiled into a separate assembly. Creatio IDE depicts assembly packages as custom packages (). Learn more in a separate article: Assembly package.

Compare Creatio packages using the table below.

Creatio package comparison
Links to other packages
Package configuration elements
File content
Development in Creatio IDE
Code compilation path
Package
+
+
+
+
...\Terrasoft.WebApp\Terrasoft.Configuration\Terrasoft.Configuration.dll
Project package
+

(use an external IDE)

For .NET Framework: ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Package name]\Files\Bin\[Package name].dll

For .NET Core and .NET 6: ...\Terrasoft.Configuration\Pkg\[Package name]\Files\Bin\netstandard\[Package name].dll

Assembly package
+
+
(with restrictions)
+
+

For .NET Framework: ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Package name]\Files\Bin\[Package name].dll

For .NET Core and .NET 6: ...\Terrasoft.Configuration\Pkg\[Package name]\Files\Bin\netstandard\[Package name].dll

This article covers simple packages.

To expand or modify functionality, install the package with the desired features. Development of additional functionality or modification of the existing functionality is only possible with custom packages.

Primary packages 

Creatio’s primary packages include packages available in all products.

Primary packages
Package name
Description
Base Base schemas of the primary objects and Creatio sections, as well as connected objects, pages, process schemas, etc.
Platform Modules and pages of the Section Wizard, List Designer, Dashboard Designer, etc.
Managers Client modules of the schema managers.
NUI Functionality connected to the Creatio UI.
UIv2
DesignerTools Schemas of Designers and their elements.
ProcessDesigner Process Designer schemas.

Custom package 

The Section Wizard and Detail Wizard create various schemas that must be saved to a custom package. A fresh Creatio installation has no packages open for modification except for the Custom preinstalled package. You can add schemas to this package manually or using the Wizards.

The Custom package specifics:

  • The Custom package cannot be added to the version control system. As such, you can transfer the package’s schemas to a different environment only using the export and import functionality.
  • Unlike other preinstalled packages, the Custom package cannot be exported to the file system via the WorkspaceConsole utility.
  • The Custom package has all of the other preinstalled packages as dependencies. If you create or install a custom package, the new package becomes a dependency for the Custom package automatically. Therefore, always place the Custom package the last in the package hierarchy.
  • Custom packages cannot have the Custom package as a dependency.

We recommended using the Custom package if:

  • You are not going to transfer changes to a different environment.

    Not only do the Section Wizard and Detail Wizard create various schemas, they also bind data to the current package. The Custom package does not support the standard package import mechanism. Therefore, if the Custom package is your current package, you can only transfer the bound data to another custom package via database queries. We strongly recommend against this method as the changes can affect the database structure and render Creatio inoperable.

    If you have to modify Creatio functionality significantly, create a custom package and use a version control system.

  • You customize Creatio either manually or using Wizards, and the changes are minor.
  • You do not need to use a version control system.

Custom package 

To develop in a custom package, specify the name of the relevant package in the Current package (CurrentPackageId code) system setting.

Package structure 

If you upload the package to the version control system, the directory that matches the package name is created in the package repository.

The structure of the package directory:

  • The branches directory.

    Stores the versions of the current package. Each version is a subdirectory whose name matches the package version number in Creatio. For example, 7.18.0.

  • Tags directory.

    Stores tags. The tags in the version control system are a snapshot of the project, i. e., a static copy of files made to preserve a development stage.

SVN integration is enabled in Creatio by default. To set up SVN integration, modify the value of the defPackagesWorkingCopyPath setting’s connectionString attribute in the ConnectionStrings.config configuration file. This setting contains the path to the directory that stores working copies.

ConnectionStrings.config
<add name="defPackagesWorkingCopyPath" connectionString="TEMP\APPLICATION\WORKSPACE\TerrasoftPackages" >

Creatio makes and uses a working copy of each custom package with versioning enabled in SVN integration mode. The working copy contains custom packages organized as a set of directories and files. The Creatio SVN client synchronizes this data with an SVN repository. We recommend specifying the path to a permanent directory in the defPackagesWorkingCopyPath system setting. The OS might clear the temporary directory specified by default. Do not specify ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg as the repository of working package copies in Creatio .NET Framework.

The package directory structure in the file system:

  • The Schemas directory contains the package schemas.
  • The Assemblies directory contains third-party builds bound to the package.
  • The Data directory contains data bound to the package.
  • The SqlScripts directory contains SQL scenarios bound to the package.
  • The Resources directory contains the localized package resources.
  • The Files directory contains the package file content.
  • The Descriptor.json file stores the package metadata in JSON. The package metadata includes the ID, title, version, dependencies, etc.

Package dependencies and hierarchy 

Creatio application development follows the basic principles of software design, including the “don’t repeat yourself” (DRY) principle.

Creatio architecture implements this principle using package dependencies. Each package contains certain Creatio functionality, which the other packages should not duplicate. If a package requires functionality from a different package, set up dependencies between the corresponding packages.

Dependency types:

  • If the current package must inherit the entire Creatio functionality, set the package next to the Custom package in the hierarchy as the parent package.
  • If the current package must inherit the functionality of a package, set the package with the functionality to inherit as the parent package.

Packages can have multiple dependencies. For example, package C depends on packages A and D. Thus, the functionality of packages A and D is available in package C.

Package dependencies form hierarchical chains. This means that the package contains the functionality of the inheritor package and the functionality of all packages that depend on the inheritor. The closest analogy to the package hierarchy is the class inheritance hierarchy in object-oriented programming. For example, package E contains not only functionality of package C on which it depends, but also the functionality of packages A, B, and D. In addition, package F contains the functionality of packages B and D.

As of version 8.0.1, Creatio adds dependencies of custom packages automatically. Dependencies are added based on the entire package hierarchy. This lets you add fewer dependencies manually. For example, if a business process uses configuration elements of the Base, UIv2, and Completeness packages, only the Completeness package is added as a dependency of the current package, since it depends on the UIv2 package, which, in turn, depends on the Base package.

Creatio package hierarchy 

View the package hierarchy and dependencies on the package dependencies diagram. To open the diagram:

  1. Go to the Configuration section.
  2. Select Package dependencies diagram in the Packages group of the Actions dropdown list on the toolbar.

The dependencies diagram opens in a new tab.

Click a diagram node with the package name to view the package dependencies as animated arrows. For example, the SalesEnterpriseSoftkey_Obsolete package in the SalesEnterprise product depends only on the SalesEnterpise package and its parent packages. Also, the SalesEnterpriseSoftkey_Obsolete package is a parent package to the Custom package.

Add package dependencies 

You can add dependencies to a custom package at any time.

To add dependencies:

  1. Go to the package page.
  2. Click Add on the Depends on packages detail in the Dependencies tab. This open the package lookup dialog.
  3. Select the desired package in the dialog and click Select.

As a result, Creatio will display the selected package in the current package’s list of dependencies. If you add other dependencies to the current package, Creatio will hide the packages you have already selected from the lookup.

Creatio adds new packages to the dependencies of the Custom preinstalled package automatically.

List of dependencies in the package metadata 

Creatio stores the list of dependencies in the package metadata. View the metadata in the DependsOn property of the object defined in the descriptor.json file.

The DependsOn property is an array of objects that contain the package name, version, and unique ID. Use the ID to define the package in the Creatio database. Creatio adds separate descriptor.json files for each package version.

Descriptor.json file
{
    "Descriptor": {
        "UId": "51b3ed42-678c-4da3-bd16-8596b95c0546",
        "PackageVersion": "7.18.0",
        "Name": "UsrDependentPackage",
        "ModifiedOnUtc": "\/Date(1522653150000)\/",
        "Maintainer": "Customer",
        "DependsOn": [
            {
                "UId": "e14dcfb1-e53c-4439-a876-af7f97083ed9",
                "PackageVersion": "7.18.0",
                "Name": "SalesEnterprise"
            }
        ]
    }
}

Bind data to the package 

Developers often need to provide certain data together with the developed functionality when transferring changes between environments.

Creatio lets you bind the following elements to a package:

  • Data generated by the Section Wizard and bound to a package automatically
  • data that must be bound to a package manually

    • lookup contents
    • section contents
    • system settings
    • dashboards
    • Word reports and FastReports

As of version 8.0.1, Creatio adds package dependencies automatically when binding data in the current package. Dependencies are added for bindings performed in the Configuration section and advanced configuration mode of the Application Hub section. When data is bound, you can select any objects and their columns. This mechanism is based on the app’s package hierarchy rather than the dependencies of the current package. After the binding is done, Creatio adds the packages that contain the objects used in the binding to the current package as dependencies automatically.

Automatic data binding 

When you create a section using the Section Wizard, Creatio binds data required for registration and correct operation of the section to the package automatically.

Manual data binding 

Attention. The order of object data binding depends on the object relationship. If one of the objects depends on the other, bind an object that does not depend on the new objects first.

To bind data to a package manually:

  1. Implement a Data type schema. To do this, follow the instructions in a separate article: Data.
  2. Fill out the Object property of the data binding page. The number of Data type schemas required depends on the UI element whose data is being bound to the package. I. e., create a single Data type schema based on a single object.

    Available values of the Object property
    Binding description
    Required number of the Data type schemas
    Object property
    Lookup contents
    Binding the contents of a lookup implies binding data of the custom object to the package based on which the lookup was built.
    1
    Select a lookup object.
    Section contents
    Binding the contents of a section implies binding its demo records to the corresponding package. When you bind the contents of a custom section, Creatio binds data of the custom object based on which the section was built.
    1
    Select a section object.
    System settings
    Binding a system setting to a package implies binding the system setting code and value.
    2
    Select "SysSettings." This is the database table that stores codes of Creatio system settings.
    Select "SysSettingsValue." This is the database table that stores values of Creatio system settings.
    Dashboards
    Binding a dashboard to a package implies binding the dashboard added to the section record page.
    1
    Select "SysDashboard." This is the database table that stores the connections of dashboards to Creatio sections.
    Word reports
    Binding a Word report to a package implies binding the printable and tabular part of the report.
    2
    Select "SysModuleReport." This is the database table that stores configured printables.
    Select "SysModuleReportTable." This is the database table that stores tabular parts of Word reports.
    FastReports

    Attention. FastReport functionality is deprecated since Creatio 8.0.3.

    Binding a FastReport to a package implies binding the template, data source, and printable of the report.

    3
    Select "FastReportTemplate." This is the database table that stores FastReport templates.
    Select "SysModuleReportTable." This is the database table that stores FastReport data sources.
    Select "SysModuleReport." This is the database table that stores configured FastReport printables.
  3. Select data to bind to the package in the data binding page’s workspace.

    1. Select the columns that contain object data on the Columns setting tab.
    2. Select the records to bind to the package on the Bound data tab. Use the filter by object name to search for the corresponding data.
  4. Click Save on the data binding page’s toolbar to save the changes to schema metadata.
Create a custom package
Easy

1. Create a package 

  1. Click the button to open the System Designer.
  2. Click Advanced settings in the Admin area block.
  3. Click the button in the package workspace. This will open the package mini page.

2. Fill out the package properties 

Fill out the properties on the package mini page.

The package properties:

  • Name – the package name. Required. The package name cannot match the names of other packages.
  • Description – the package description. For example, package functionality details.
  • Version control system repository – the name of the version control system repository that will store the package changes. Required. Only repositories from the configuration storage list that are marked as active will be available in the dropdown list.

    Attention. The Version control system repository field will become non-editable after you create the package.

  • Version – the package version. Required. The field accepts digits, Latin characters, as well as “.” and “_” characters. The value must start with a digit or a letter. All package elements are of the same version as the package itself. The package version does not have to match the actual Creatio version.

Creatio will save the package properties to the package metadata.

The package property metadata:
{
    "Descriptor": {
        "UId": "1c1443d7-87df-4b48-bfb8-cc647755c4c1",
        "PackageVersion": "7.18.0",
        "Name": "NewPackage",
        "ModifiedOnUtc": "\/Date(1522657977000)\/",
        "Maintainer": "Customer",
        "DependsOn": []
    }
}

In addition to these properties, the package metadata contains information about the dependencies (DependsOn property) and the developer (Maintainer). Set the value of the Maintainer property in the Publisher (Maintainer code) system setting.

3. Define the package dependencies 

If the current package must inherit Creatio functionality, define the package dependencies.

To add dependencies:

  1. Click Create and add dependencies on the package mini page.
  2. Set the relevant dependencies in the Depends on packages detail on theDependencies tab. If the current package must inherit the entire Creatio functionality, set the package that follows the Custom package in the hierarchy as the parent package.
scr_pkg_create_dependencies.png

4. Check the Custom package dependencies 

The Custom package must depend on all Creatio packages. As such, make sure that the [Custom] package depends on the new package as well.

Bind data to a package
Advanced

Example. Bind demo records as well as connected records of other section to the Books custom section.

Demo records:

  • David Flanagan, JavaScript: The Definitive Guide: Activate Your Web Pages, ISBN 978-0596805524, Apress, $33.89.
  • Andrew Troelsen, Pro C# 7: With .NET and .NET Core, ISBN 978-1484230176, Apress, $56.99.

1. Create a section 

For this example, create the Books section in the Section Wizard. Take the section fields from the table below.

The columns and their properties on the section record page
Title
Code
Data type
Required
Name
UsrName
String
Yes
ISBN
UsrISBN
String
 
Author
UsrAuthor
Contact lookup
Yes
Publisher
UsrPublisher
Account lookup
Yes
Price
UsrPrice
Decimal
 

Learn more about how to create a section: Section.

2. Add demo records to the section 

To add records to the Books section list:

  1. Add a record to the Contacts section and enter "David Flanagan" in the Full name field.
  2. Add a record to the Contacts section and enter "Andrew Troelsen" in the Full name field.
  3. Add a record to the Accounts section and enter "Apress" in the Name field.
  4. Add the JavaScript: The Definitive Guide: Activate Your Web Pages book:
    1. Go to the Books section.
    2. Click New.
    3. Fill out the fields of the book mini page:
      • Enter "JavaScript: The Definitive Guide: Activate Your Web Pages" in the Name field.
      • Enter "978-0596805524" in the ISBN field.
      • Select "David Flanagan" in the Author field.
      • Select "Apress" in the Publisher field.
      • Enter "33.89" in the Price field.
  5. Add the Pro C# 7: With .NET and .NET Core book in a similar way.

The Books section list must look like on the figure below.

3. Bind data to the package 

Since the Books section records are connected to the Contacts section records by the UsrAuthor column, bind the author data to the package first.

To bind data to the package:

  1. Bind the contacts:
    1. Go to the Configuration section and select a custom package.
    2. Click Add on the workspace toolbar and select the Data configuration type.
    3. Fill out the properties of the data binding page:
      1. Enter "ContactsInBooks" in the Name property.
      2. Select "Contact" in the Object property.
      3. Select "Installation" in the Installation type property.
      4. Select the records with "David Flanagan" and "Andrew Troelsen" values in the Full name field on the Bound data tab.
      5. Save the data.
  2. Bind the account:
    1. Go to the Configuration section and select a custom package.
    2. Click Add on the workspace toolbar and select the Data configuration type.
    3. Fill out the properties of the data binding page:
      1. Enter "AccountsInBooks" in the Name property.
      2. Enter "Account" in the Object property.
      3. Select "Installation" in the Installation type property.
      4. Select the record with the "Apress" value in the Name field on the Bound data tab.
      5. Save the data.
  3. Bind the books:
    1. Go to the Configuration section and select a custom package.
    2. Click Add on the workspace toolbar and select the Data configuration type.
    3. Fill out the properties of the data binding page:
      1. Enter "Books" in the Name property.
      2. Select "UsrBooks" in the Object property.
      3. Select "Installation" in the Installation type property.
      4. Select the records with the "JavaScript: The Definitive Guide: Activate Your Web Pages" and "Pro C# 7: With .NET and .NET Core" values in the Name field on the Bound data tab.
      5. Save the data.

4. Check the data bindings 

As a result, Creatio will bind the data of the Books, Contacts, and Accounts" sections to the custom package.

You can transfer the package between environments using the package export and import mechanism in Creatio IDE. After you install the package into another environment, the bound records will be displayed in the corresponding sections.