Packages file content basics

Level: advanced

The package file content comprises files (*.js, *.css, images, etc.) added to custom Creatio packages. Since the file content is static, the webserver does not process it. This helps to improve Creatio performance.

The types of file content:

• Client content generated in real time.
• Pre-generated client content.

Special aspects of client content generated in real time:

• The pre-generation of client content is not needed.
• The calculation of package and schema hierarchy, as well as the generation of content, put a load on the CPU.
• The retrieval of package and schema hierarchy, as well as the generation of content, put a load on the database.
• The caching of client content takes up memory.

Special aspects of pre-generated client content:

• The load on the CPU is minimal.
• The pre-generation of client content is required.
• The database queries are not needed.
• The IIS tools cache the client content.

Storage structure of package file content

File content is an integral part of the package. You can pre-generate the file content in the dedicated ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\<PackageName>\Files Creatio directory to improve Creatio performance and reduce the load on the database. If the IIS server receives a request, it will search for requested content in this directory and send the content to Creatio immediately. You can add any files to the package, however, Creatio will use only the files required for its client part.

We recommend structuring the Files directory as below.

Recommended Files directory structure

-PackageName
    ...
    -Files
        -src
            -js
                bootstrap.js
                [other *.js files]
            -css
                [*.css files]
            -less
                [*.less files]
            -img
                [image files]
            -res
                [resource files]
        descriptor.json
    ...
descriptor.json

js – the directory with JavaScript *.js source code files

css – the directory with *.css style files

less – the directory with *.less style files

Img – the directory with images

res – the directory with resource files

descriptor.json – the file content descriptor that stores the information about package bootstrap files

View the descriptor.json file structure below.

descriptor.json file structure

{
    "bootstraps": [
        ... // The string array that contains relative paths to bootstrap files.
    ]
}

descriptor.json file example

{
    "bootstraps": [
        "src/js/bootstrap.js",
        "src/js/anotherBootstrap.js"
    ]
}

To add file content to a package, place the file in the corresponding subdirectory of the Files package directory.

Package bootstrap files

Package bootstrap files are *.js files that handle the loading of client configuration logic. The file structure may vary.

bootstrap.js file structure

(function() {
    require.config({
        paths: {
            "Module name": "Link to the file content",
            ...
        }
    });
})();

bootstrap.js file example

(function() {
    require.config({
        paths: {
            "MyPackage1-ContactSectionV2": Terrasoft.getFileContentUrl("MyPackage1", "src/js/ContactSectionV2.js"),
            "MyPackage1-Utilities": Terrasoft.getFileContentUrl("MyPackage1", "src/js/Utilities.js")
        }
    });
})();

Creatio loads bootstrap files asynchronously after loading the core, but before loading the configuration. Creatio generates _FileContentBootstraps.js auxiliary file in the static content directory to ensure the bootstrap files are loaded correctly. The auxiliary file contains information about bootstrap files of all packages.

_FileContentBootstraps.js file content example

var Terrasoft = Terrasoft || {};
Terrasoft.configuration = Terrasoft.configuration || {};
Terrasoft.configuration.FileContentBootstraps = {
    MyPackage1: ["src/js/bootstrap.js"],
};

File content versioning

Creatio generates _FileContentDescriptors.js auxiliary file in the static file content directory to ensure the file content versioning works correctly. The auxiliary file contains information about files in the file content of all packages, displayed as a "key-value" collection. Each key (filename) corresponds to a unique hash code. This ensures the browser will receive the up-to-date file version.

_FileContentDescriptors.js file content example

var Terrasoft = Terrasoft || {};
Terrasoft.configuration = Terrasoft.configuration || {};
Terrasoft.configuration.FileContentDescriptors = {
    "MyPackage1/descriptor.json": {
        Hash: "5d4e779e7ff24396a132a0e39cca25cc",
    },
    "MyPackage1/Files/src/js/Utilities.js": {
        Hash: "6d5e776e7ff24596a135a0e39cc525gc",
    },
};

Auxiliary file generation

To generate auxiliary files (_FileContentBootstraps.js and FileContentDescriptors.js), execute the BuildConfiguration operation using the WorkspaceConsole utility.

BuildConfiguration operation parameters

Parameter	Description
-operation	The name of the operation. Set the value to BuildConfiguration – the operation that compiles the configuration.
-useStaticFileContent	Enables the static content. Set the value to false.
-usePackageFileContent	Enables the package file content. Set the value to true.

Auxiliary files generation

Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -destinationPath=Terrasoft.WebApp\ -configurationPath=Terrasoft.WebApp\Terrasoft.Configuration\ -useStaticFileContent=false -usePackageFileContent=true -autoExit=true

As a result, Creatio will generate _FileContentBootstraps.js and _FileContentDescriptors.js auxiliary files in the ...\Terrasoft.WebApp\conf\content static content directory.

Learn more about the parameters of the utility: WorkspaceConsole parameters.

Static file content pre-generation

Creatio generates the file content in the .\Terrasoft.WebApp\conf special directory. The directory contains *.js files with schema source code, *.css style files, *.js resource files of all Creatio cultures, as well as images.

Important

The user of the IIS pool that runs Creatio must have modification permissions for static content generation in the .\Terrasoft.WebApp\conf directory to work properly. Set up permissions in the Handler Mappings section on the server level. Learn more: Set up Creatio application server on IIS (user documentation).

Set the name of the IIS pool user in the Identity property. Click Advanced Settings on the Application Pools tab of the IIS manager to open this property.

The following events trigger static file content generation or re-generation:

• Saving a schema in the Client Schema Designer and Client Objects Designer.

• Saving in the Section Wizard and Detail Wizard.

• Installing and deleting applications via Marketplace and *.zip archive.

• Applying translations.

• Running Compile and Compile all actions in the Configuration section.

  Run these actions after you delete schemas or packages from the Configuration section.

  Run the Compile all action after you install or update a package from SVN version control system.

note

The Compile all action fully re-generates the static file content. Other Creatio actions re-generate only the modified schemas.

File content generation

To generate the file content, execute the BuildConfiguration operation using the WorkspaceConsole utility.

BuildConfiguration operation parameters

Parameter	Description
-workspaceName	The workspace name. Set to Default by default.
-destinationPath	The directory to which to generate the static content.
-webApplicationPath	Path to the web application from which to read the information about the connection to the database. Optional. If you do not specify a value, Creatio will establish a connection to the database specified in the connection string of the Terrasoft.Tools.WorkspaceConsole.config file. If you specify a value, Creatio will establish the connection to the database from the ConnectionStrings.config file of the web application.
-force	Optional. Set to false by default. If you leave the value as is, Creatio will generate the file contents only for modified schemas. If you set the value to true, Creatio will generate the content for all schemas.

Generate the file content (option 1)

Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -destinationPath="C:\WebApplication\Creatio\Terrasoft.WebApp" -force=true -logPath=C:\wc\log

Generate the file content (option 2)

Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -webApplicationPath="C:\WebApplication\Creatio" -destinationPath="C:\WebApplication\Creatio\Terrasoft.WebApp" -force=true -logPath=C:\wc\log

Client content generation when adding a new culture

After you add new cultures in the Creatio UI, run the Compile all action in the Configuration section.

Important

If you cannot log in to Creatio after adding a new culture, open the Configuration section via the http://[Creatio path]/0/dev URL.

Retrieve the image URL

The browser requests images in the client part of Creatio with the URL specified in the src attribute of the img HTML element. Creatio generates this URL using the Terrasoft.ImagesUrlBuilder (imagurlbuilder.js) module with the getUrl(config) public method for retrieving the image URL. This method expects the config JavaScript configuration object that contains the parameters object in the params property. Creatio generates the image URL to add to the page based on this property.

params object structure

config: {
    params: {
        schemaName: "",
        resourceItemName: "",
        hash: "",
        resourceItemExtension: ""
    }
}

schemaName – the schema name (string)

resourceItemName – the image name in Creatio (string)

Hash – the image hash (string)

resourceItemExtension – the image file extension. For example, ".png."

View the example that generates the parameters configuration object needed to retrieve the static image URL below.

Generate the parameters configuration object

var localizableImages = {
    AddButtonImage: {
        source: 3,
        params: {
            schemaName: "ActivityMiniPage",
            resourceItemName: "AddButtonImage",
            hash: "c15d635407f524f3bbe4f1810b82d315",
            resourceItemExtension: ".png",
        },
    },
};

Compatibility with the file system development mode

It is not possible to retrieve client content from pre-generated files in the file system development mode. To ensure the correct operation of the file system development mode, disable the retrieval of static client content from the file system. To disable this feature, set the UseStaticFileContent flag in the Web.config file to false.

Disable the retrieval of static file content from the file system

<fileDesignMode enabled="true" />
...
<add key="UseStaticFileContent" value="false" />

Transfer changes between environments

File content is an integral part of the package. The content is stored in the version control system repository along with other package content. You can transfer the file content to another environment:

• We recommend using the SVN version control system to transfer changes to the development environment.
• We recommend using the export and import mechanism in Creatio IDE to transfer changes to pre-production and production environments.

Important

Creatio will add the Files directory when installing packages only if there are files to place in it. If there is no such directory, create it manually to begin development.

---

See also

Delivery in WorkspaceConsole

Set up Creatio application server on IIS (user documentation)

Version control in Subversion

Environments

Delivery in Creatio IDE