External IDEs. Visual Studio

Version 8.0

This documentation is provided under restrictions on use and are protected by intellectual property laws. Except as

expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate,

broadcast, modify, license, transmit, distribute, exhibit, perform, publish or display any part, in any form, or by any

means. Reverse engineering, disassembly, or decompilation of this documentation, unless required by law for

interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you

find any errors, please report them to us in writing.

4
4
4
5
5
11
11
12
13
13
13
17
18
18
18
23
26
26
29
30
Table of Contents
External IDEs. Visual Studio
Development in the file system
Main limitations of development in the file system
IDE settings for development
Visual Studio configuration steps
Application settings for development in the file system
Terrasoft.Configuration package
Getting Started with the configuration
Developing the server code
The general procedure for Creatio development
Developing the server code in the Terrasoft.Configuration.sln solution
Developing the configuration server code in the user solution
Advantages of developing in user solution
Preliminary settings
Development of the configuration server code for on-site application
Development of the configuration server code for Cloud application
Developing the client code
General outline:
Automatic displaying of client codechanges
Configuration steps
Table of Contents | 3
© 2022 Creatio. All rights reserved.

External IDEs. Visual Studio

Medium

Development in the file system

Using an Integrated Development Environment (IDE) maximizes development speed. Examples of the IDE include Visual

Studio, WebStorm, and other tools. An IDE usually enables you to create, modify and compile the source code, debug it,

run team development, use version control systems, etc. IDEs usually use text files stored in the file system to work with

the source code.

Development in Microsoft Visual Studio became possible after implementing the configuration packages in the file system

mechanism in Creatio. With this mechanism, you can export the packages from the database to a set of files, edit the

package source code using an IDE and upload the updated packages back to the database.

The WorkspaceConsole utility integrated into Visual Studio is used to compile applications. The WorkspaceConsole has

the following benefits:

Attention. You can also compile the configuration project using the Visual Studio compiler. However, it may not

take into account the dependencies and the position of packages.

Note. You can use Microsoft Visual Studio Community, Professional, and Enterprise version 2017 (with latest

updates) for development in the file system and higher.

You can configure Creatio configuration packages in the file system. With this mechanism, you can export the packages

from the database to a set of files, edit the package content using an IDE and upload the updated packages back to the

database. Using Visual Studio, you can debug custom source code of the schemas of the “Source code” (

SourceCodeSchema ) type.

Use Creatio built-in tools if there is no need or possibility to develop in the file system.

Main limitations of development in the file system

When the development in the file system mode is enabled, a full-fledged development is supported only for schemas of

the “Source code” ( SourceCodeSchema ) and “Client schema” ( ClientUnitSchema ) types.

For other package elements (such as resources and SQL scripts), the following rules are used:

Attention. When the file system development mode is enabled, resources of these schemas are also saved in the

Significantly speeds up the compilation process because the whole configuration assembly is split into independently

compiled modules. Only the modules that contain modified packages are compiled.

Compilation does not require exiting the debugging mode or disconnecting from the IIS process.

When exporting packages from the database to the file system, the package elements stored in the database will

replace the corresponding items in the file system. The source code schemas and client schemas will not be replaced.

When uploading packages to the database, source code schemas and client schemas will replace the database's

corresponding items. The application will keep using source code schemas and client schemas from the file system.

External IDEs. Visual Studio | 4

file system after saving client schemas ( ClientUnitSchema ) and source code schemas ( SourceCodeSchema ) in the

corresponding designers.

Integration with the version control system (SVN) with enabled development in the file system is performed with third-

party tools. Creatio built-in mechanism of working with SVN is not used. It is still possible to install packages from the SVN

repository in the [ Configuration ] section (this simplifies working with related packages). Use third-party utilities, such as

TortoiseSVN, to install separate packages.

Note. To use the built-in capabilities of working with the SVN repository, disable the development mode in the file

system.

IDE settings for development

Advanced

Visual Studio configuration steps

1. Enable compilation mode in the IDE

To enable compilation mode in the IDE, edit the Web.config file (located in the root folder with the installed application)

and set the enabled attribute of the fileDesignMode element to true .

Attention. Currently, the development in the file system is no compatible with getting client content from

preliminary generated files. For the correct work of the development in the file system, you need to disable getting

static client content from the file system. Set the “false” for the UseStaticFileContent flag in the Web.config file to

disable these functions.

If the development mode in the file system is enabled, IIS will use the Terrasoft.Configuration.dll library only from the

file system.

After switching to the file system development mode for the first time, the user is redirected to the "Configuration"

section upon logging in. At this time, "The "Default" workspace assembly is not initialized" error appears. To eliminate this

error, run the "Compile all items" action.

After enabling the development in the file system, two buttons will appear on the [ Actions ] tab in the [ Configuration ]

section.

...

IDE settings for development | 5

To integrate the application with the configuration project, grant full access to the

path to the installed application\Terrasoft.WebApp\Terrasoft.Configuration\Pkg folder for the OS user who runs the IIS

application pool. Usually, this is the built-in IIS_IUSRS user.

2. Configure the WorkspaceConsole to compile the application.

Configuration projects are compiled via the WorkspaceConsole utility, which is included in the application setup files. The

utility should be configured before use. In addition to the settings covered in the "WorkspaceConsole parameters” article,

you must also enable the development mode in the file system in the Terrasoft.Tools.WorkspaceConsole.exe.config

configuration file.

[Download packages to file system] – exports the packages from the database to the following folder:

[path to the installed application]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg .

[Update packages from file system] – uploads the packages to the database from the following folder:

[path to the installed application]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg .

IDE settings for development | 6

To speed up the compilation by splitting the configuration assembly into independently compiled modules, set the

CompileByManagerDependencies setting to “ true ” in the “internal” Web.Config (located in the Terrasoft.WebApp directory)

and in the Terrasoft.Tools.WorkspaceConsole.exe.config file of the WorkspaceConsole utility.

3. Configure Microsoft Visual Studio

To use the WorkspaceConsole utility for compilation in Visual Studio, set up External Tools . To do this, execute the Tools

> External Tools... command in the Visual Studio.

In the opened dialog window, add and set up three commands for calling the WorkspaceConsole utility. The

Build Workspace and Rebuild Workspace commands initiate compilation of changes and full compilation of configuration

projects. The Update Workspace Solution command updates the Visual Studio solution of the configuration package from

the application database. It applies all changes made by the users within the application. Select the Use Output window

checkbox for all three commands.

...

...

</appSettings>

IDE settings for development | 7

Update Workspace Solution command properties

Title Update Workspace Solution

Command [ Path to the catalog with installed application

]\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

Example:

C:\Creatio\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

Arguments --operation=UpdateWorkspaceSolution --workspaceName=Default --webApplicationPath="[ Path to

the catalog with installed application ]\Terrasoft.WebApp" --confRuntimeParentDirectory="[ Path to the

catalog with installed application ]\Terrasoft.WebApp"

Example:

--operation=UpdateWorkspaceSolution --workspaceName=Default --

webApplicationPath="C:\Creatio\Terrasoft.WebApp" --

confRuntimeParentDirectory="C:\Creatio\Terrasoft.WebApp"

IDE settings for development | 8

Build Workspace command properties

Title Build Workspace

Command [ Path to the catalog with installed application

]\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

Example:

C:\creatio\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

Arguments --operation=BuildWorkspace --workspaceName=Default --webApplicationPath="[ Path to the catalog

with installed application ]\Terrasoft.WebApp" --confRuntimeParentDirectory="[ Path to the catalog with

installed application ]\Terrasoft.WebApp"

Example:

--operation=BuildWorkspace --workspaceName=Default --

webApplicationPath="C:\creatio\Terrasoft.WebApp" --

confRuntimeParentDirectory="C:\creatio\Terrasoft.WebApp"

Rebuild Workspace command properties

Title Rebuild Workspace

Command [ Path to the catalog with installed application

]\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

Example:

C:\creatio\Terrasoft.WebApp\DesktopBin\WorkspaceConsole\Terrasoft.Tools.WorkspaceConsole.exe

Arguments --operation=RebuildWorkspace --workspaceName=Default --webApplicationPath="[ Path to the catalog

with installed application ]\Terrasoft.WebApp" --confRuntimeParentDirectory="[ Path to the catalog with

installed application ]\Terrasoft.WebApp"

Example:

--operation=RebuildWorkspace --workspaceName=Default --

webApplicationPath="C:\creatio\Terrasoft.WebApp" --

confRuntimeParentDirectory="C:\creatio\Terrasoft.WebApp"

To prevent the debugger from accessing the source code that is disabled in the project, execute the Debug > Options...

menu command and enable the Enable Just My Code option in the opened dialog. For more information about the

Enable Just My Code , please refer to this page.

IDE settings for development | 9

After the configuration is compiled, the application is automatically restarted. The Enable Edit and Continue option is not

supported and should be disabled.

For the debugger to stop correctly on breakpoints, ensure that the Suppress JIT optimization on module load option is

enabled.

IDE settings for development | 10

Application settings for development in the file system

To enable development in the file system, edit the Web.config file (located in the root folder with the installed application)

and set the enabled attribute of the fileDesignMode element to true .

Attention. Currently, the development in the file system is no compatible with getting client content from

preliminary generated files. For the correct work of the development in the file system, you need to disable getting

static client content from the file system. Set the “false” for the UseStaticFileContent flag in the Web.config file to

disable these functions.

Terrasoft.Configuration package

A configuration project is a Visual Studio solution supplied with Creatio setup files. The solution can be found here:

[path to the installed application\Terrasoft.WebApp\Terrasoft.Configuration .

To start development in the file system, open the following file in Visual Studio:

...

IDE settings for development | 11

path to the installed application\ Terrasoft.WebApp\Terrasoft.Configuration\Terrasoft.Configuration.sln .

The configuration project structure is available in table 1.

Table 1. Configuration project structure

Folder Purpose

Lib The folder where package-bound third-party class libraries are exported.

Autogenerated\Src The folder with files that contain auto-generated source code of the preset package

schemas. These files cannot be edited.

Pkg The folder where the packages for development in the file system are exported from the

database.

bin A folder for compiled configuration and third-party libraries.

Getting Started with the configuration

Creating a package

If you do not intend to use SVN in the development process, then creating a package in the file system development

mode is the same as that in the normal mode. For more information on creating packages, please refer to the Create a

package for development article.

Attention. The working with SVN mode is enabled in the Creatio by default. If the [ Version control system

repository ] field is empty when creating a package, the package will not be bound to the repository. The versioned

development of this package can be performed only after manually binding it to the repository from the file system.

More information about creating a custom package and binding it to the SVN repository can be found in the "Create a

package in the file system development mode” article.

Working with new package elements

It is recommended to add new elements (schema or resource) to the package only from the [ Configuration ] section. To

create and edit a new item in a custom package:

Attention. Changes made in client schemas are available in the application immediately, without uploading to the

Select a custom package in the [Configuration] section and add a new element to it (see Create a client schema,

“Create the [Source code] schema”).

Add resources (such as localized strings) to the schema if needed.

Click [Download packages to file system] (Fig. 1).

Use an IDE (such as Visual Studio) to edit the source code of the schema or localized resource in the files (located in

the [Path to the installed application]\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\[Package name] folder). The

package properties are described in the Package structure article.

Click [Update packages from file system] to upload changes to the application database (Fig. 1).

IDE settings for development | 12

database. You only need to update the page in the browser.

Note. When developing source code schemas in C #, compile them directly in Visual Studio. More information

about compilation and debugging in Visual Studio can be found in the "Developing the server code” article.

Developing the server code

Advanced

Creatio has the ability to debug program code using the integrated functions of the Visual Studio development

environment. The Visual Studio debugger enables developers to freeze the execution of program methods, check

variable values, modify them and monitor other activities performed by the program code.

The general procedure for Creatio development

Attention. After successful compilation, the resulting Terrasoft.Configuration.dll assembly will be placed to the

Bin catalog, while IIS will automatically use it in Creatio application.

Developing the server code in the Terrasoft.Configuration.sln

solution

1. Perform preliminary settings

Creatio and Visual Studio setup for development in the file system is described in the “IDE settings for development”

article.

Note. For development in the file system, you can use Microsoft Visual Studio Community, Professional and

Enterprise version 2017 (with latest updates) and higher.

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

Creating a custom package with or without SVN is described in the “Create a package for development” and “Create a

package in the file system development mode” articles. Installing and updating packages is described in the Installing

packages from repository and Updating package from repository articles.

If you changed a source code schema, then you must compile the application.

Perform preliminary settings in Creatio and Visual Studio.1.

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

Create a [Source code] schema for development.3.

Perform development in Visual studio.4.

Save, compile and debug the source code.5.

Developing the server code | 13

Note. We recommend using Tortoise SVN or Git for working with version control repositories.

3. Create a [Source code] schema

Learn more about the process of creating the [ Source code ] schema in the “Create the [ Source code ] schema” article.

4. Conduct development in the Visual Studio

Before you start development in Visual Studio, make sure that you export existing schemas from the database to the file

system.

For example, if the [ Source code ] schema with the name UsrGreetingService was created in the

sdkPackageInFileSystem package, the file of the source code of the UsrGreetingService.cs schema appears in the file

system in the Pkg\sdkPackageInFileSystem\Schemas\ directory. In this case, the system generated

UsrGreetingServiceSchema.sdkPackageInFileSystem_Entity.cs file will be placed in the Autogenerated\Src directory.

Developing the server code | 14

Note. To add a schema to SVN, you must add the entire UsrGreetingService directory, including the JSON files.

Open the Terrasoft.Configuration.sln solution in Visual Studio to start the development (see “Development in MS Visual

Studio”). In Visual Studio Solutions Explorer, enable the display of all file types (1), open the UsrGreetingService.cs file (2)

and add the required source code (3).

Below is an example of source code implementation, which must be added to the contents of the UsrServiceGreeting.cs

file, using Visual Studio

namespace Terrasoft.Configuration

{

using System.ServiceModel;

using System.ServiceModel.Activation;

using System.ServiceModel.Web;

// Class that implements configuration service.

[ServiceContract]

[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]

public class UsrGreetingService : System.Web.SessionState.IReadOnlySessionState

{

// Service operation.

[OperationContract]

[WebInvoke(Method = "GET", UriTemplate = "Hello")]

public string TestHello()

Developing the server code | 15

For more information about the purpose of the attributes of the class that implements configuration services, please

refer to the Create a configuration service article.

5. Save, compile and debug source code

After modifying the source code, and before compiling and debugging it, be sure to save the code. Normally, this is done

by Visual Studio automatically, but since Visual Studio compiler is not used, the developer must save the code manually.

After saving, the source code must be compiled with the “Build Workspace” or “Rebuild Workspace” commands (see

“IDE settings for development”). If the compilation is successful, the code becomes available. In the example described

previously, the service will become available at the following address

To begin debugging, attach to the IIS server process, where the application runs. Execute the Debug > Attach to process

menu command.

In the opened window, select the working IIS process in the list of processes, where the application pool is running.

{

return "Hello!";

}

http://[Application URL]/0/rest/UsrGreetingService/Hello

Developing the server code | 16

Note. The name of the working process can be different, depending on the configuration of the IIS server being

used. With a regular IIS, the process is w3wp.exe , but with IIS Express, the process name is iisexpress.exe .

By default, the IIS working process is run under the account whose name matches the name of the application

pool. To display processes of all users, set Show processes from all users checkbox (Fig. 6).

After attaching to a working IIS process, execute compilation one more time. After that, begin the debugging process

using the Visual Studio debugger. For example, you can set the stop points, view variable values, call stacks, etc. For

more information on the Visual Studio debugger, please refer to the corresponding documentation.

For example, after setting up the breakpoint on the return line from the TestHello() method, and re-compiling the

application and executing the service request, the debugger will stop the program execution on the breakpoint.

Attention. The debugging feature depends on the correct configuration of Visual Studio.

Developing the configuration server code in

the user solution

Advanced

Developing the configuration server code in the user solution | 17

Advantages of developing in user solution

This development of server code in the file system using the Terrasoft.Configuration.sln solution is inconvenient because

of low performance connected with recompilation of all Creatio configuration (Terrasoft.Configuration.dll). This is

significant if the application contains several Creatio products. In addition, the development of server code in the file

system could only be performed by interacting with the database of the application deployed on-site.

Due to the described inconveniences, this approach can be efficiently used to perform complex configuration revision of

the Creatio. It is more efficient to use the built-in Creatio development tools to develop a simple server code (see the

Creatio IDE article). But the built-in development tools do not support full IDE functions: debugging, IntelliSense,

Refactoring, etc.

To develop and debug separate classes or small blocks of server functionality, you can create a separate class library

project and configure it. Then, connect corresponding Creatio class libraries (for example, Terrasoft.Core) and perform

development and debugging of the server code. To debug and test the development result you can use a local database

(use the WorkspaceConsole utility to connect to the database) or an application located in the cloud by connecting to it

via the Executor utility.

Advantages of this approach:

Preliminary settings

For connecting the libraries of the Creatio classes, deploying the local database from an archive copy and working with

the WorkspaceConsole utility, you can use the Creatio installed locally. In all examples of this article used the Creatio

installed to the C:\creatio local folder.

The Executor utility located in the C:\Executor folder is used as an example of working with the Creatio Cloud service.

You can use the following link to download the utility configured for processing the example.

Development of the configuration server code for on-site

application

If you have access to the Creatio local database, to develop configuration server logic do the following:

1. Restore the database from a backup (if need)

Backup of the application database is located in the db folder of the application (for example, C:\creatio\db ).

2. Configure the WorkspaceConsole utility

To operate with the database, you need to configure the WorkspaceConsole utility using the application files. More

information about configuration of the utility is described in the "Transfer solutions (WorkspaceConsole utility)" article. To

configure the utility:

High speed of testing modifications, compiling and execution

Full usage of the Visual Studio functions

Ability to use any tools for Continuous Integration, for example, Unit testing.

Simplicity of configuration – you do not need configuration source codes

You can use the database of an application deployed on-site or in Cloud.

Open the Terrasoft.WebApp\DesktopBin\WorkspaceConsole folder of the application (for example,

C:\creatio\Terrasoft.WebApp\DesktopBin\WorkspaceConsole ).

Developing the configuration server code in the user solution | 18

Note. Ensure that the SharpPlink-xXX.svnExe and SharpSvn-DB44-20-xXX.svnDll files were copied to the

Terrasoft.WebApp\DesktopBin\WorkspaceConsole folder from the corresponding folder (x64 and x86) after executing

the .bat file.

Specify parameters of connection to the database in the Terrasoft.Tools.WorkspaceConsole.exe.config file from the

Terrasoft.WebApp\DesktopBin\WorkspaceConsole folder of the application (for example,

C:\creatio\Terrasoft.WebApp\DesktopBin\WorkspaceConsole). For example, if the creatioDB database is deployed on the

dbserver server, the connection string will be as follows

3. Create and configure Visual Studio project

For this, create a standard class library project. More information about creating a new Visual Studio solution and

managing projects is described in the "Solutions and Projects in Visual Studio" Microsoft documentation article.

Execute one of the .bat files: PrepareWorkspaceConsole.x64.bat or PrepareWorkspaceConsole.x86.bat, depending

on the Windows version.

<add name="db" connectionString="Data Source=dbserver; Initial Catalog=creatioDB; Persist Security Info=True; MultipleActiveResultSets=True; Integrated Security=SSPI; Pooling = true; Max Pool Size = 100; Async = true; Connection Timeout=500"

</connectionStrings>

Developing the configuration server code in the user solution | 19

On the [ Debug ] tab of the properties window of the created class library project, specify the full path to the configured

WorkspaceConsole utility in the [ Start external program ] property. The WorkspaceConsole is used as the external

application for debugging the developed program logic.

In the [ Command line arguments ] properties specify following launch arguments of the WorkspaceConsole:

The example of the WorkspaceConsole launch arguments

More information can be found in the "WorkspaceConsole parameters" article.

Attention. In the properties of the Visual Studio project that operates with the application 7.11.0 or higher, you

need to specify the version of the .NET Framework 4.7 (the [ Target framework ] property of the [ Application ]

tab).

To work with the classes of the server-side of Creatio core, set the dependencies from the necessary Creatio class

-filename – full path to the debug version of developed class library.

-typeName – full name of the class in which the program logic (including the names of all namespaces) is being

developed. For example, CreatioCustomServerLogic.MyContactCreator .

-operation – WorkspaceConsole operation. The "ExecuteScript" value should be specified.

workspaceName – the workspace name. The "Default" value should be specified.

-confRuntimeParentDirectory — path to the parent catalog of the conf directory (see Deployment

(WorkspaceConsole utility) article). This directory is usually located in the Terrasoft.WebApp catalog of the deployed

application.

-filename="C:\Projects\CreatioCustomServerLogic\CreatioCustomServerLogic\bin\Debug\CreatioCustomServerLogic.dll" -typeName=CreatioCustomServerLogic.MyContactCreator -operation=ExecuteScript -workspaceName=Default -logPath=C:\Projects\Logs -confRuntimeParentDirectory=C:\creatio\Terrasoft.WebApp -autoExit=true

Developing the configuration server code in the user solution | 20

libraries in the created project. For example, add the dependency from the Terrasoft.Core.dll library. More information

about adding the dependencies can be found in the "Managing references in a project" Microsoft documentation article.

Class libraries of the Creatio namespace can be found in the Terrasoft.WebApp\DesktopBin\WorkspaceConsole folder of the

application.

Note. Class libraries are being copied to the Terrasoft.WebApp\DesktopBin\WorkspaceConsole folder when executing

the .bat files (see Step 2. Configure the WorkspaceConsole utility").

4. Develop the functions

For this, add a new class to the created class library project. The name of the class should match the name specified in

the typeName launch argument of the WorkspaceConsole (for example, CreatioCustomServerLogic.MyContactCreator ).

Class should implement the Terrasoft.Core.IExecutor interface.

The implementation of the class is available below:

using System;

using Terrasoft.Core;

namespace CreatioCustomServerLogic

{

public class MyContactCreator : IExecutor

{

public void Execute(UserConnection userConnection)

{

// Getting an instance of the [Contacts] schema.

var schema = userConnection.EntitySchemaManager.GetInstanceByName("Contact");

var length = 10;

for (int i = 0; i < length; i++)

{

// Create a new contact.

var entity = schema.CreateEntity(userConnection);

Developing the configuration server code in the user solution | 21

After running the project (F5 key) the WorkspaceConsole window with the corresponding message will be displayed.

You can also set a breakpoint on any line of the source code and view the current values of variables at the time of

program execution (ie, debugging). More information about breakpoints in the Visual Studio can be found in the Use

Breakpoints in the Visual Studio Debugger" Microsoft documentation article.

The result of executing of the above code can be found in the [ Contacts ] section of the Creatio application or by

executing the request to the database.

Added contacts

// Set contact properties.

entity.SetColumnValue("Name", string.Format("Name {0}", i));

entity.SetDefColumnValues();

// Save the contact to the database.

entity.Save(false);

}

// Output message to the console.

Console.WriteLine($"{length} contacts created");

}

Developing the configuration server code in the user solution | 22

Request to the table of contacts of the database

Development of the configuration server code for Cloud

application

To develop configuration server logic without direct access to the Creatio database:

1. Create class library project.

Create standard class library project (Fig. 1). More information about creating a new Visual Studio solution and managing

projects is described in the "Solutions and Projects in Visual Studio" Microsoft documentation article. Set the name of the

project (for example, "CreatioCustomServerLogic.Cloud").

To work with the classes of the server side of Creatio core, set the dependencies from the necessary Creatio class

libraries in the created project. For example, add the dependency from the Terrasoft.Core.dll library (Fig. 3). More

information about adding the dependencies can be found in the "Managing references in a project" Microsoft

Developing the configuration server code in the user solution | 23

documentation article.

Note. Class libraries of the Creatio namespace can be found in the bin folder of the application. Class libraries are

being copied to the Terrasoft.WebApp\DesktopBin\WorkspaceConsole folder when executing the .bat files (see Step 2.

Configure the WorkspaceConsole utility" of the example of configuration server code development for on-site

application).

In the created class library project, specify the full path to the configured Executor utility in the [ Post-build event

command line ] property on the [ BuildEvents ] tab of the properties window, for example C:\Executor\Executor.exe .

Also, you must select the condition for starting the library build event on this tab.

Note. The configuration process is given below on the Step "3. Executor utility configuration".

[ Build Events ] tab properties

2. Develop the functions

For this, add the class that will implement the Terrasoft.Core.IExecutor interface to the created library project. The

implementation of the class is available below:

using System;

using System.Web;

using Terrasoft.Core;

using Terrasoft.Core.Entities;

namespace CreatioCustomServerLogic.Cloud

Developing the configuration server code in the user solution | 24

3. Executor utility configuration

Note. You can use following link to download the utility configured for processing the example.

Open the Executor utility folder, for example, C:\Executor . Then, specify the values for the following configuration items

in the configuration file:

{

public class MyContactReader : IExecutor

{

public void Execute(UserConnection userConnection)

{

// Getting an instance of the [Contacts] schema.

var entitySchema = userConnection.EntitySchemaManager.GetInstanceByName("Contact");

// Create an instance of the query class.

var esq = new EntitySchemaQuery(entitySchema);

// Adding all the columns of the schema to the query.

esq.AddAllSchemaColumns();

// Getting the collection of records in the [Contacts] section.

var collection = esq.GetEntityCollection(userConnection);

foreach (var entity in collection)

{

// The output in the http-response of the request from the Executor utility of the necessary values.

HttpContext.Current.Response.Write(entity.GetTypedColumnValue<string>("Name"));

HttpContext.Current.Response.Write(Environment.NewLine);

}

Loader – URL of the Creatio application loader. Usually this is the URL of the Creatio site, for example

"https://mycloudapp.creatio.com".

WebApp – URL of the Creatio application. Usually this is a path to default configuration of Creatio, for example

"https://mycloudapp.creatio.com/0".

Password – the password of Creatio user.

LibraryOriginalPath – the path to the initial copy of the class library. Usually, this is the path by which a class library is

created after compilation in Visual Studio, for example,

"C:\Projects\CreatioCustomServerLogic\CreatioCustomServerLogic.Cloud\bin\Debug\CreatioCustomServerLogic.Cloud.dll".

LibraryCopyPath – the path by which a copy of the class library will be created for work with the remote server. This

can be a temporary folder that contains the Executor utility, for example,

"C:\Executor\CreatioCustomServerLogic.Cloud.dll".

LibraryType – full name of the class in which the developed program logic is implemented, including the names of all

namespaces. For example, "CreatioCustomServerLogic.Cloud.MyContactReader".

LibraryName – name of the class library, for example, "CreatioCustomServerLogic.Cloud.dll".

Developing the configuration server code in the user solution | 25

4. Run the developed program code

The result of executing the development program code can be observed in the [ Output ] window of the Visual Studio

after successful building of the class library.

To launch the building process use the [ Build Solution ] and [ Rebuild Solution ] menu commands.

Developing the client code

Advanced

The updated method of working with the client code in the file system enables better development flexibility. Download

the client schema source code from the database to *.js files and LESS module styles into *.less files for working with

them in the Integrated Development Environment (IDE) (e.g. WebStorm, Visual Studio Code, Sublime Text, etc.).

General outline:

1. Pre-configure Creatio

Setting up Creatio for development in the file system is described in the “Development in MS Visual Studio” article.

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

Creating a custom package with or without SVN is described in the “Create a package for development" and “Create a

package in the file system development mode” articles. Installing and updating packages is described in the “Installing

packages from repository” and “Updating package from repository” articles.

Note. We recommend using Tortoise SVN or Git to work with version control repositories.

Developing the client code | 26

3. Create a custom schema for development

Learn more about custom schemas in the “Create a client schema” article.

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

To do this, use the [ Download packages to file system ] command in the [ Configuration ] section.

For example, if you created a replacing ContactPageV2 schema ([ Display schema - Contact card ]) in a custom

sdkPackageInFileSystem package, the files in the Pkg\sdkPackageInFileSystem\Schemas\ ContactPageV2 folder will contain

the source code files of the ContactPageV2.js schema and ContactPageV2 .less styles.

5. Carry out the development of the schema source code in IDE

To perform the development, open the file with the schema source code in the preferred IDE (or any text editor) and add

the necessary source code.

Developing the client code | 27

For example, add the following source code to the ContactPageV2.js file to hide the [ Full job title ] field from the contact

edit page:

6. Save, compile and debug the source code

The [ Full job title ] will be removed from the contact edit page upon saving the ContactPageV2.js file and refreshing the

page.

define("ContactPageV2", [],

function() {

return {

entitySchemaName: "Contact",

diff: /**SCHEMA_DIFF*/[

{

"operation": "remove",

"name": "JobTitleProfile"

}

]/**SCHEMA_DIFF*/

};

});

Developing the client code | 28

Debug the code if you encounter any errors (see: “Client code debugging”).

Attention. To return to built-in Creatio development tools, do the following:

Automatic displaying of client codechanges

When developing client code in the file system, each time after making changes to the source code of the custom

schema you need to refresh the browser page on which the application is opened. This reduces the development

performance.

To avoid this, we developed the new functionality of automatic browser page reload after changes. This functionality

works in a following way.

When the application starts, it creates an object that tracks the changes of the .js file with the source code of the

developed module in the file system. If the changes have made, a message is sent to the client Creatio application. In the

client application, a specific object which is signed to this message defines dependent objects of the changed module,

destroys them, registers new paths to the modules and tries to load the modified module again. After that, all the pre-

initialized modules will be requested by the browser via new paths and load changes from the file system. It does not take

time to interpret and load other modules. Separate development page enables to avoid loading of additional modules (for

example left or right panel, communication panel, etc.). This reduces the number of requests to the server.

This approach reveals the connectivity of the modules and detects unnecessary dependencies to eliminate them.

Known issues

Update packages from file system.1.

Disable the file system development mode by setting the enabled="false" attribute of the fileDesignMode

element of the Web.config configuration file (see “Development in MS Visual Studio”).

If there is a syntax error in the source code of the module, the page will not automatically refresh. The page will need

to be forcibly refreshed (for example, by pressing the F5 key). If the error is corrected, the page will return to the

operable status.

Not all Creatio modules can be downloaded separately. The main reason is the effect of strong coupling of modules.2.

Developing the client code | 29

Configuration steps

1. Install the JavaScriptOnlineLoader package

Enable the development mode in the file system and add the JavaScriptOnlineLoader folder with corresponding package

to the Path to the installed application\Terrasoft.WebApp\Terrasoft.Configuration\Pkg folder.

More information about the development mode in the file system can be bound in the “Development in MS Visual Studio”

article.

Attention. The package is available on GitHub (https://github.com/vladimir-

nikonov/pngstore/tree/master/JavaScriptOnlineLoader). Also, the archive with the package can be downloaded by

the link.

Load the package to the configuration with the [ Update packages from file system ] action.

Developing the client code | 30

As a result, the package will be displayed on the [ Packages ] tab.

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

To do this, open the ViewModule.aspx page with the added parameter with the following format

For example, the KnowledgeBasePageV2 replacing schema (the schema of the Knowledge base section edit page ) is

added to the custom package. The page with the functions of automatic displaying of changes will be available at the

following URL

The http://localhost/creatio is a URL of the Creatio application deployed on-site.

After clicking this URL, the ViewModule.aspx page will be displayed with the loaded module.

?vm=DevViewModule#CardModuleV2/<Module name>

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

Developing the client code | 31

3. Change the source code of the developed schema

The source code of the developed schema can be changed in any text editor (for example, Notepad). After saving the

changes, the page opened in the browser will be automatically refreshed.

For example, the KnowledgeBasePageV2 replacing schema (the schema of the [ Knowledge base ] section edit page ) is

added to the sdkAutoUpdateClientLogicDev custom package. After loading to the file system, the schema code will be

available in the ..\Pkg\sdkAutoUpdateClientLogicDev\Schemas\KnowledgeBasePageV2 folder.

If the following source code will be added to the KnowledgeBasePageV2.js file and save it, the browser page will be

automatically refreshed. The changes will be displayed immediately.

define("KnowledgeBasePageV2", [],

function() {

return {

entitySchemaName: "KnowledgeBase",

diff: /**SCHEMA_DIFF*/[

{

"operation": "insert",

"parentName": "Header",

"propertyName": "items",

Developing the client code | 32

Page with changes

"name": "SomeField",

"values": {

"layout": {"column": 0, "row": 0, "colSpan": 24},

"caption": "SomeField"

}

]/**SCHEMA_DIFF*/

};

});

Developing the client code | 33