External IDEs basics

Level: intermediate

Use an external integrated development environment (IDE) like Visual Studio or WebStorm to speed up Creatio solution development.

External IDEs let you create, edit, and compile Creatio solution code as well as debug it, develop in a multi-user environment, use version control systems, and much more.

note

You can use Community, Professional, Enterprise editions of Microsoft Visual Studio version 2017 (with latest updates) and later to develop in the file system.

Development in the file system

Creatio supports external IDEs using the file system development mechanism of configuration packages.

File system development (FSD) mode lets you:

• Download package contents from the database as files.
• Edit the schema source code using the IDE.
• Upload changed packages to the database.

FSD has the following special features:

1. If FSD is enabled, only schemas of the Source code and ClientUnitSchema types support full-fledged development.

   Important

   If FSD is enabled and you save client schemas of the Source code and ClientUnitSchema types to the corresponding Designer of Creatio IDE, Creatio will also save resources of those schemas to the file system.

   The following rules apply to other package elements, for example, resources or SQL scripts:

   • After you download the elements from the database to the file system, the downloaded elements will replace the elements in the file system. Schemas of the Source code and ClientUnitSchema type are not replaced.
   • After you upload the elements from the file system to the database, the uploaded elements will replace the existing elements in the database. Creatio will still work with schemas of the Source code and ClientUnitSchema types from the file system.

2. If FSD is enabled, integrate a version control system (SVN) using a third-party tool instead of the out-of-the-box Creatio SVN integration.

   The Configuration section still lets you install packages from the SVN repository to help to manage all the connected packages. We recommend using third-party utilities, such as TortoiseSVN, to install individual packages.

   To use the out-of-the-box SVN repository integration, disable FSD.

Set up Creatio to work with the file system

1. Enable FSD.

   .NET Framework. In the Web.config file in Creatio root directory, set the enabled attribute of the fileDesignMode element to true.

   .NET Core or .NET 6. Perform a similar setup in the Terrasoft.WebHost.dll.config file in the root Creatio directory.

2. Disable the retrieval of static file content from the file system.

   FSD is not currently set up to work with retrieving static content from files that have already been generated. To ensure that FSD works correctly, disable retrieving static client content from the file system.

   .NET Framework. In the Web.config file in Creatio root directory, set the UseStaticFileContent flag to false.

   .NET Core or .NET 6. Perform similar setup in the Terrasoft.WebHost.dll.config file in the root Creatio directory.

   Web.config for .NET Framework

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

   Terrasoft.WebHost.dll.config for .NET Core or .NET 6

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

3. Compile Creatio.

   Execute the Compile all action on the Configuration section toolbar.

   After you enable FSD, the File system development mode action group in the Configuration section becomes active:

   • Download packages to file system. Downloads packages from the Creatio database to the [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg directory.
   • Update packages from file system. Uploads packages from the [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg directory to the database.

   

4. Grant IIS access to the configuration directory.

   To make sure Creatio works as intended with the configuration project, grant the OS user who runs the IIS application pool full access to the [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration directory. Usually, this is a built-in IIS_IUSRS user.

   

Manage packages

Create a package

If you are not using SVN, the procedure to create a package with FSD enabled is the same as the general procedure.

Important

If you do not fill out the Version control system repository field, Creatio does not bind the package to a repository. You can version such a package only if you connect it from the file system manually.

Add a package element

We recommend adding new elements to the package, for example, a schema or resource, only from the Configuration section. To create and edit a new element in a user-made package, follow these steps:

1. Select a user-made package in the Configuration section and add a new element to the package, such as client schema, source code, etc.

2. Add resources to the schema if needed, for example, localizable string.

3. Select the Download packages to file system action of the Actions drop-down list in the Configuration section.

4. Use the IDE, for example, Visual Studio, to edit the source code of the schema or localizable resource stored in the files of the [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg[Package name] directory.

5. Execute the Update packages from file system action to upload the changes to the Creatio database.

   Important

   Changes to client schemas are available in Creatio immediately. You do not need to upload the client schemas from the file system. You only need to refresh the browser page.

6. Compile Creatio if you changed schemas of the Source code type.

   note

   When developing C# schemas of the Source code type, it is more convenient to compile the code directly in Visual Studio, rather than in the Configuration section in Creatio.

Write C# code

Compilation options in Visual Studio

1. Use the default Visual Studio compiler. However, this option might not take into account package dependencies and positions.
2. Use the WorkspaceConsole utility integrated with Visual Studio. The option has the following advantages:
   • Compilation is sped up since the configuration assembly is divided into separate compilable modules. The utility recompiles only modules whose packages were changed.
   • You do not need to exit debugging mode or detach from the IIS process to recompile a configuration assembly.

Set up WorkspaceConsole for compilation

1. Enable FSD for WorkspaceConsole.

   The WorkspaceConsole utility is delivered together with Creatio. Before using the utility, ensure that it is set up correctly. Besides general setup, enable FSD in the Terrasoft.Tools.WorkspaceConsole.exe.config configuration file as well.

   Enable FSD

   <fileDesignMode enabled="true" />

   To speed up compilation, divide the configuration assembly into separate compilable modules. In this case, set the CompileByManagerDependencies setting to true in the internal Web.config file of the Terrasoft.WebApp directory and the Terrasoft.Tools.WorkspaceConsole.exe.config file of the WorkspaceConsole utility.

   Set up the internal Web.config

   <appSettings>
       ...
       <add key="CompileByManagerDependencies" value="true" />
       ...
   </appSettings>
   

2. Integrate Microsoft Visual Studio with WorkspaceConsole.

   1. Execute the Tools → External Tools... menu command in the Visual Studio environment. This opens a dialog.

   

   2. Add and set up the following commands that call the WorkspaceConsole utility:

      • Build Workspace. Compiles the configuration project changes.

        Build Workspace command properties

        Command

        Structure [Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe Example C:\creatio713\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

        Arguments

        Structure -operation=BuildWorkspace -workspaceName=Default -webApplicationPath="[Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp" -confRuntimeParentDirectory="[Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp" Example -operation=BuildWorkspace -workspaceName=Default -webApplicationPath="C:\creatio713\Terrasoft.WebApp" -confRuntimeParentDirectory="C:\creatio713\Terrasoft.WebApp"

      • Rebuild Workspace. Fully compiles the configuration project.

        Rebuild Workspace command properties

        Command

        Structure [Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe Example C:\creatio713\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

        Arguments

        Structure -operation=RebuildWorkspace -workspaceName=Default -webApplicationPath="[Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp" -confRuntimeParentDirectory="[Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp" Example -operation=RebuildWorkspace -workspaceName=Default -webApplicationPath="C:\creatio713\Terrasoft.WebApp" -confRuntimeParentDirectory="C:\creatio713\Terrasoft.WebApp"

      • Update Workspace Solution. Updates the Visual Studio solution from the Creatio database. Applies the changes made by Creatio users.

        Update Workspace Solution command properties

        Command

        Structure [Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe Example C:\creatio713\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

        Arguments

        Structure -operation=UpdateWorkspaceSolution -workspaceName=Default -webApplicationPath="[Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp" -confRuntimeParentDirectory="[Path to the directory that contains an installed Creatio instance]\Terrasoft.WebApp" Example -operation=UpdateWorkspaceSolution -workspaceName=Default -webApplicationPath="C:\creatio713\Terrasoft.WebApp" -confRuntimeParentDirectory="C:\creatio713\Terrasoft.WebApp"

   3. Select the Use Output window checkbox for all commands.

      

Set up debugging in Visual Studio

Execute the Debug → Options... menu command. This opens a dialog. Change the following settings:

• Enable Enable Just My Code to ensure that the debugger does not try parsing source code that is not a part of the project.
• Disable Enable Edit and Continue. Since Creatio restarts automatically after the configuration compilation, the setting is not supported.
• Make sure Suppress JIT optimization on module load is enabled so that the debugger stops at breakpoints correctly.

Write C# code in a configuration project

The Terrasoft.Configuration.sln configuration project is a Visual Studio solution delivered together with Creatio and located in the [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration directory.

The configuration project has the following advantages for development:

• The configuration project is a fully configured solution for developing complex back-end functionality.
• You can use the entire scope of the IDE functionality: debugging, refactoring, autocomplete, etc.

The configuration project has the following limitations:

• Performance is relatively low since the entire configuration part of Creatio (Terrasoft.Configuration.dll) is recompiled.
• FSD of C# code is possible only by interacting with the on-site Creatio database.

To begin FSD using a configuration project, open [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration\Terrasoft.Configuration.sln in Visual Studio.

Configuration project structure

Directory	Purpose
Lib	Stores the downloaded third-party class libraries bound to packages.
Autogenerated\Src	Stores the files that contain the autogenerated source code for pre-installed package schemas. The files are non-editable.
Pkg	Stores the downloaded packages required for FSD.
bin	Stores the downloaded compiled configuration and third-party libraries.

Write C# code in a custom project

The custom project is an individual class library project that is preconfigured for interaction with Creatio.

To debug and test the development results in a custom project, you can use a local database connected via the WorkspaceConsole utility or Creatio in the cloud connected via the special Executor utility.

Development in a custom project has the following advantages:

• Speed of change testing, compilation and execution is high.
• Visual Studio functionality is fully supported.
• Any tools within the Continuous Integration pipeline are supported, for example, unit testing.
• Project setup is simple and does not require the configuration source code.
• Both Creatio on-site and cloud databases are supported.

Development in a custom project has the following limitations:

• Only the development and debugging of individual classes or small back-end functionality blocks are supported.
• Required Creatio class libraries must be added to the project dependencies individually.

Write JavaScript code

To develop front-end functionality using external IDEs, follow these steps:

1. Preconfigure Creatio for FSD.

2. Create, obtain, or update a package from the SVN repository

3. Create a client schema to code in the Configuration section.

4. Download the schema from the database to the file system.

5. Write the schema source code in an external IDE.

   To write code, open the file that contains the schema source code in the preferred IDE (or any text editor) and add the needed source code.

6. Save the schema and debug the source code.

Every time you make changes to the schema source code, refresh the browser page that has Creatio open. This can slow down the development significantly.

To mitigate this, we developed functionality that reloads the browser page automatically after the source code is changed.

Set up the automatic display of JavaScript code changes

When Creatio starts, it creates an object that tracks changes to the *.js file that contains the source code of the developed module in the file system. If changes are made, a message is sent to the client Creatio instance notifying it of the changes. An object in the client application listens to the message, defines the objects that the changed module uses, destroys connections, registers new paths to modules, and attempts to reload the changed module. As a result, the browser requests the initialized modules from new paths, and the modules load changes from the file system.

The automatic display of JavaScript code changes has the following advantages:

• It will save you time spent on the interpretation and load of other modules. The individual development page lets you omit loading a number of auxiliary modules, for example, left and right panel, notification panel, etc.
• This reduces the number of server requests.
• It will help you detect redundant module connections. This approach to the development of individual modules lets you find unnecessary dependencies early and eliminate them.

The automatic display of changes to the JavaScript code has the following limitations:

• Code syntax errors cause issues. If the module source code has a syntax error, Creatio does not refresh the page automatically. You have to force a refresh, for example, by pressing F5. Once the error is fixed, the page becomes operable again.
• Module coupling is strong. Not all Creatio modules can be downloaded separately.

To enable the automatic display of JavaScript code changes, take the following steps:

1. Install the JavaScriptOnlineLoader package.

   Enable FSD and add the JavaScriptOnlineLoader directory that contains the needed package to the [Path to Creatio]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg directory.

   

   Important

   The package is available on GitHub. You can also download the package archive via the following link: Download package.

   Execute the Update packages from file system action. This will load the package to your configuration.

   As a result, Creatio will display the package in the package workspace.

2. Open the page of the developed module in the browser.

   To do this, open the ViewModule.aspx page with the following parameter added: ?vm=DevViewModule#CardModuleV2/<Module name>

   For example, the user-made package includes a KnowledgeBasePageV2 schema that replaces the schema of the Knowledge base section edit page.

   URL of the KnowledgeBasePageV2 page that contains the functionality that displays changes automatically

   http://localhost/creatio/0/Nui/ViewModule.aspx?vm=DevViewModule#CardModuleV2/KnowledgeBasePageV2
   

   where http://localhost/creatio is the URL of Creatio on-site.

   Follow the URL to open the ViewModule.aspx page that contains the loaded module.

   

3. Change the source code of the developed schema.

   You can change the source code of the developed schema in any text editor, for example, Notepad. After you save the changes, Creatio refreshes the browser page automatically.

---

See also

Creatio IDE

Version control in Subversion

Packages basics

Delivery in WorkspaceConsole

---

Resources

Front-end development Freedom UI Creatio documentation

Front-end development Creatio documentation

Back-end development Creatio documentation

JavaScriptOnlineLoader package