Marketplace app licensing

Level: intermediate

Licensing lets you control usage of paid Marketplace apps. Learn more: Licensing (user documentation).

The licensed options of the Marketplace app depend on the license type and licensed element.

General procedure to license paid Marketplace app:

Define the license type. Read more >>>
Define the licensed elements. Read more >>>
Implement the license verification. Read more >>>
Send data obtained on previous steps to the Creatio Marketplace support (marketplace@creatio.com) when publishing the Marketplace app via the Creatio Marketplace Console. Instructions: Steps to publish the Marketplace listing using Creatio Marketplace Console.
Creatio Marketplace support generates licenses for the Marketplace app based on the received data.

The developer must take steps 1–3 when developing the Marketplace app.

1. Define the license type

View the license types provided by Creatio in the table below.

License type	License description
Personal	Grant access to the app for specific users. Bound to the user account and cannot be used by other users. The system administrator can redistribute licenses among users at any time. Instructions: Distribute or recall licenses for multiple users (user documentation).
Server	Grant access to the app without binding access to specific users. All Creatio users that have the corresponding permissions have access to the licensed functionality.

Licenses last for 365 days regardless of the type. The license expiration date is specified in the license and controlled by Creatio.

2. Define the licensed elements

View the licensed elements in the table below.

Licensed element	Description of licensed element
Licensed objects	Names of custom objects added to the Marketplace app. Licensed objects are any custom objects, for example, section, detail, or lookup objects.
Licensed operations	Names of operations added to the Marketplace app logic to verify the license for specific functionality. For example, an additional action was added to a base Creatio section. The action must be connected to the licensed operation. When the action is called, the app business logic verifies the license. Based on the result, Creatio executes or interrupts the functionality.

The license can include one or more licensed elements. Make sure the licensed elements meet the Requirements for Pricing and support tab properties. The licensed elements do not depend on the license type.

Important

Do not use personal and server licenses that control the same objects and operations at the same time.

View the licensed options of the Marketplace app in the table below.

Licensed element	Example of functionality	License type	Subscription type
Licensed objects	New Creatio section.	Personal	Paid per user that works with the section.
	New Creatio section.	Server	Fixed price regardless of the number of users that work with the section.
	Key object that contains active data changes.	Personal	Paid per user that works with the key object.
	Key object that contains active data changes.	Server	Fixed price regardless of the number of users that work with the key object.
Licensed operations	Connector to an external service, for example, a telephony connector.	Personal	Paid per user that can access to the service. For example, access to a telephony connector is paid per individual user.
	Connector to an external service, for example, web chat that registers leads or requests in Creatio.	Server	Fixed price regardless of the number of users that have access to the service.
	Freedom UI component	Server
Licensed objects and operations	Section with records that use connectors to various external services.	Personal	Paid both per user that can access the section and per service connector. For example, the Requests section was improved. The section is integrated with an external system that registers requests. The customer pays for access to the section functionality per user.

3. Implement the license verification

Since Creatio verifies the licenses that include licensed objects using out-of-the-box tools, you do not need to implement the license verification for licensed objects.

If the license includes licensed operations, implement the license verification in the source code of a Marketplace app. Creatio can verify the licenses both from back-end and front-end.

Implement the license verification from the back-end

Call the method that verifies licenses.

View the methods of the Terrasoft.Core.LicHelper class that check license restrictions, in the table below.

Method	Method parameter	Method description
GetHasOperationLicense(string sysPackageOperationCode);	`sysPackageOperationCode` is a string parameter that contains the name of the licensed operation. Specify this name in the `Licensed operations` property on the revision page when publishing the Marketplace app. Instructions: Release details tab.	If the license is found, returns `true`. Otherwise, returns `false`.
CheckHasOperationLicense(string sysPackageOperationCode);		If the license is found, returns `true`. Otherwise, generates the `LicException` exception.

View the examples that check the status of the SomeLicensedOperation.Use licensed operation in the back-end below.

Example that uses the GetHasOperationLicense() method
Example that uses the CheckHasOperationLicense() method

UserConnection.LicHelper.GetHasOperationLicense("SomeLicensedOperation.Use");

UserConnection.LicHelper.CheckHasOperationLicense("SomeLicensedOperation.Use");

Handle the result.

Implement the license verification from the front-end

Creatio lets you implement the license verification from the front-end in the source code of both Freedom UI page and remote module.

Implement the license verification in the source code of a Freedom UI page

Add the dependencies. To do this, add @creatio-devkit/common library as a dependency.

@creatio-devkit/common includes the LicenseService service to check license restrictions.

Call the method that verifies licenses.

View the method of the LicenseService service that checks license restrictions in the table below.

Method	Method parameter	Method description
getLicenseOperationStatuses(operationCodes: string[]);	`operationCodes` is a string parameter that contains the list of the licensed operation names. Specify this name in the `Licensed operations` property on the revision page when publishing the Marketplace app. Instructions: Release details tab.	Returns an object that has keys as operation codes and values as operation statuses.

View the example that checks the status of the MrktShowButton.Use licensed operation in the Freedom UI page below.

MrktSomeApp_Page
/* Declare the AMD module. */
define("MrktSomeApp_Page", /**SCHEMA_DEPS*/["@creatio-devkit/common"]/**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
    return {
        ...,
        handlers: /**SCHEMA_HANDLERS*/[
            {
                request: "mrkt.SomeHandleRequest",
                /* The custom implementation of the request handler. */
                handler: async (request, next) => {
                    /* Create an instance of the "LicenseService" service from "@creatio-devkit/common." */
                    const licenseService = new sdk.LicenseService();
                    /* Retrieve data about status of the "MrktShowButton.Use" licensed operation. */
                    const licenseStatus = await licenseService.getLicenseOperationStatuses(['MrktShowButton.Use']);
                    const mrktShowButtonLicenseStatus = licenseStatus['MrktShowButton.Use'];
                    /* Set the "SomeAttribute" attribute to "mrktShowButtonLicenseStatus". */
                    request.$context.SomeAttribute = mrktShowButtonLicenseStatus;
                    /* If the user has license restrictions for using the "MrktShowButton.Use" licensed operation, Creatio displays "NotLicensedFunctionalityMessage" notification message. "NotLicensedFunctionalityMessage" is a localizable string. */
                    request.$context.NotLicensedFunctionalityMessage = mrktShowButtonLicenseStatus ? "" : await request.$context.Resources.Strings.UsrNotLicensedFunctionalityMessage;
                    /* Call the next handler if it exists and return its result. */
                    return next?.handle(request);
                },
            }
        ]/**SCHEMA_HANDLERS*/,
        ...,
    };
});

Handle the result.

Implement the license verification in the source code of a remote module

Open the some-mrkt-component.component.ts file.
Import the LicenseService functionality from the @creatio-devkit/common library into the component.

@creatio-devkit/common includes the LicenseService service to check license restrictions.
Call the method that verifies licenses.

Handle the result.

View the example that checks the status of the MrktShowButton.Use licensed operation in the remote module below.

some-mrkt-component.component.ts
/* Import the required functionality from the libraries. */
import { LicenseService } from '@creatio-devkit/common';
...
export class SomeMrktComponent {
  private readonly _licenseService: LicenseService;
  constructor() {
    /* Create an instance of the "LicenseService" service from "@creatio-devkit/common." */
    this._licenseService = new LicenseService();
  }

  public async getButtonLicenseOperationsStatus(): Promise<boolean> {
    /* Retrieve data about status of the "MrktShowButton.Use" licensed operation. */
    const licenseStatus = await this._licenseService.getLicenseOperationStatuses(['MrktShowMyButton.Use']);
    return licenseStatus.['MrktShowMyButton.Use'];
  }
}

Specify additional settings depending on the functionality to be licensed. If you use remote module to implement a custom Freedom UI component, specify the following additional settings.

Add a single custom Freedom UI component to a single package.

Set the package as a licensed package.

Download the package that contains the functionality of custom Freedom UI component to be licensed.
Extract the *.zip archive that contains the package using the Clio utility. Instructions: official vendor documentation.
Open the ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\SomePackage\descriptor.json file.

SomePackage is a package that contains the functionality of custom Freedom UI component to be licensed.

descriptor.json file stores the package properties including codes of licensed operations.
Add the LicOperations property that contains an array of configuration objects.
Add the configuration object of licensed operation.

Fill out the properties of licensed operation.

Property	Property description	Property example
Code	Code of licensed operation added to the Marketplace app logic to verify the license for specific functionality.	MrktTimerComponent.Use
Name	Name of licensed operation added to the Marketplace app logic to verify the license for specific functionality. Must correspond to the component functionality and be understandable for end users. Creatio uses the `Name` property value in the notification when a user installs a package that includes a custom Freedom UI component for which they do not have a license. The notification pattern is as follows: `You have no license for the following components: "SomeComponent" (SomePackage), ... . Contact the system administrator to receive the license. Otherwise, access to the components will be forbidden.`, where `SomeComponent` is the `Name` property value.	Timer

Property

Property description

Property example

Code

Code of licensed operation added to the Marketplace app logic to verify the license for specific functionality.

MrktTimerComponent.Use

Name

Name of licensed operation added to the Marketplace app logic to verify the license for specific functionality. Must correspond to the component functionality and be understandable for end users.

Creatio uses the Name property value in the notification when a user installs a package that includes a custom Freedom UI component for which they do not have a license. The notification pattern is as follows: You have no license for the following components: "SomeComponent" (SomePackage), ... . Contact the system administrator to receive the license. Otherwise, access to the components will be forbidden., where SomeComponent is the Name property value.

Timer

Save the changes.

View the example of the descriptor.json file that uses MrktTimerComponent.Use licensed operation, below.

descriptor.json file
{
    "Descriptor": {
        ...,
        "LicOperations": [
            {
                "Code":"MrktTimerComponent.Use",
                "Name": "Timer"
            },
            ...,
        ]
    }
}

Resources

Official Clio utility documentation

Marketplace updates

1. Define the license type​

2. Define the licensed elements​

3. Implement the license verification​

Implement the license verification from the back-end​

Implement the license verification from the front-end​

Implement the license verification in the source code of a Freedom UI page​

Implement the license verification in the source code of a remote module​

See also​

Resources​