Packages file content

Advanced
PDF

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.

{
    "bootstraps": [
        ... // The string array that contains relative paths to bootstrap files.
    ]
}
{
    "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.

(function() {
    require.config({
        paths: {
            "Module name": "Link to the file content",
            ...
        }
    });
})();
(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.

Attention. 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.

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.

Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -destinationPath="C:\WebApplication\Creatio\Terrasoft.WebApp" -force=true -logPath=C:\wc\log
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.

Attention. 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:

Attention. 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.