Version: 8.2

Handle system-level data using Creatio AI

Level: advanced

Creatio AI is natively embedded AI functionality in the core of the Creatio Freedom UI platform, designed to empower organizations with intelligent automation by acting as a virtual agent assistant to the end user performing tasks. Creatio AI's unified AI approach brings together prescriptive, generative, and agentic AI to deliver a comprehensive solution for modern business automation.

In Creatio AI, an AI Skill represents a comprehensive, end-to-end AI-enabled task that can be executed for a user. It serves as the way for Creatio AI to acquire new AI capabilities. AI Skills empower users to achieve complex tasks without the need to execute each step manually. They provide a structured and efficient approach to task completion, enhancing the overall user experience.

The AI Skill's mode, specified by the Usage mode property, determines how it is used. The options for using AI Skills are as follows:

Interactive Creatio AI conversations, i.e., the Usage mode property is set to "Chat."
Directly on the system level, i.e., the Usage mode property is set to "API." For Creatio 8.2.0, low-code tools are required.

This article covers the configuring and usage of AI Skills in the "API" mode only. Learn more about configuring AI Skills in "Chat" mode: Develop Creatio AI Skill (user documentation).

1. Develop AI Skill

Open the Creatio AI setup section (Copilot setup section in Creatio 8.2.0). To do this, click in the top right → System setup → Creatio AI setup (Copilot setup in Creatio 8.2.0).
Add an AI Skill. To do this, click New.

Fill out the properties of the AI Skill.

Fill out the Code* property in Creatio 8.2.0. The property is populated automatically in Creatio 8.2.1 and later.

Property	Property description
Title*	AI Skill title.
Code*	Code of the AI Skill required for custom development.
Description*	Description of the AI Skill. Creatio AI uses it to determine which AI Skill to run upon user's requests.
Status*	Whether the AI Skill is active. Select "Active" to use it.
Usage mode*	Mode of the AI Skill. Select "API."

Specify the user's goal when using the AI Skill.

Property	Property description
Prompt	Initial instruction for the LLM (Large Language Model) that clearly defines the task the user wants to accomplish. For "API" mode, LLM uses AI Skill parameters if they are specified in the Input parameters and Output parameters blocks and available to use.

Property

Property description

Prompt

Initial instruction for the LLM (Large Language Model) that clearly defines the task the user wants to accomplish.

For "API" mode, LLM uses AI Skill parameters if they are specified in the Input parameters and Output parameters blocks and available to use.

Learn more about creating the most efficient prompts: AI Skill development recommendations (user documentation).

For Creatio 8.2.1 and later, specify input parameters of AI Skill that are used by AI Skill and handled by LLM.

Go to the Input parameters block based on your business goals.
Click New.

Fill out the parameter properties.

Property	Property description
Code*	Code of the parameter required for custom development.
Name*	Parameter title. Creatio AI uses it to determine which parameter to use. Create a title that helps users to understand parameter purpose.
Description*	Brief parameter description. Create a description that helps users to understand what data the parameter includes.
Data type*	Type of parameter data. Available values: "Unlimited length text," "Unique identifier," "Integer," "Currency," "Date/Time," "Date," "Time," "Lookup," "Boolean," "Text (500 characters)," "Decimal (0.01)." By default, "Unlimited length text."

Recommendations for usage of input parameters:

For Creatio 8.2.0, the template for the name of the input parameter is as follows: [# someInputParameter #], where someInputParameter is the name of the input parameter. The number of spaces between the parameter name and the [# and #] characters is arbitrary.

View the example that demonstrates how Creatio AI works with input parameters in the table below.

User-defined value of the Prompt property

For Creatio 8.2.1 and later, "Your task is to display the following information: inputText"

For Creatio 8.2.0, "Your task is to display the following information: [# inputText #]"

The user-defined value of the input parameter specified in the Prompt property

Greetings, user!

The resulting value of the Prompt property after Creatio AI handled data

Your task is to display the following information: Greetings, user!

The names of input parameters are case-sensitive.
The names of input parameters start with a letter and can contain Latin letters, digits, underscores and dots.
Creatio AI uses an empty string instead of the input parameter name if the value of the input parameter is neither defined by the user nor received from the instance.

For Creatio 8.2.1 and later, specify output parameters of AI Skill that are used by AI Skill and handled by LLM.
1. Go to the Output parameters block based on your business goals.
2. Click New.
3. Fill out the parameter properties. Properties of input and output parameters are the same. Read more >>>
Since version 8.2.1, Creatio AI lets you use Error message, Response text, Status, Warning message output parameters out of the box when implementing the business logic of data handling in both the Freedom UI page schema and business process so you no longer need to add them manually. The parameter values match the property values of the Creatio.Copilot.CopilotIntentCallResult class in the back-end and the CopilotIntentCallResult interface in the front-end. View a detailed comparison in the table below.

Output parameter
Property
Front-end
Back-end
Error message
errorMessage
ErrorMessage
Response text
content
Content
Status
status
Status
Warning message
warnings
Warnings

Learn more: Creatio AI API.
Save the changes.

Output parameter	Property
Front-end	Back-end
Error message	errorMessage	ErrorMessage
Response text	content	Content
Status	status	Status
Warning message	warnings	Warnings

As a result, Creatio will add the AI Skill to the Creatio AI setup section (Copilot setup section in Creatio 8.2.0) and you can use it while implementing the business logic of handling system-level data using Creatio AI.

2. Set up the data handling using Creatio AI

Using the "API" mode of the Creatio AI, you can extend out-of-the-box Creatio AI functionality and handle system-level data depending on your business goals. Clicking a button on the Freedom UI page will call Creatio AI that handles data in the Freedom UI page schema or business process, depending on the implemented business logic.

Handle data using Creatio AI (Freedom UI page schema)

Implement the business logic of data handling using Creatio AI in the Freedom UI page schema.

Detailed example: Handle system-level data using Creatio AI in the Freedom UI page schema.

To implement the business logic of data handling using Creatio AI in the Freedom UI page schema:

Add a button that calls the AI Skill if needed. Instructions: Set up Button components (user documentation).
Add the dependencies if needed to implement the custom request handler. Instructions: Display the value of a system variable (similarly to step 2). Instead of the SysValuesService service, use the HttpClientService service that sends HTTP requests.
Set up how to handle the action executed on button click. Instructions: Optimize the execution of a custom business logic (step 4).

Implement the custom request handler (optional).

For example, implement the custom usr.SomeCustomRequest request handler. To do this:

Go to the handlers schema section.
Retrieve the instance of the HTTP client from @creatio-devkit/common.
Send the crt.CopilotExecuteIntentRequest base request that runs the AI Skill.
Specify code of the AI Skill.
Specify input parameters of the AI Skill.
If Creatio can run the AI Skill, AI Skill fulfills its task. Otherwise, handle an error if it occurs during the AI Skill execution.
Call the next handler if it exists and return its result.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* Implement the custom request handler. */
        handler: async (request, next) => {
            const context = request.$context;

            /* Retrieve the instance of the HTTP client from "@creatio-devkit/common." */
            const handlerChain = sdk.HandlerChainService.instance;

            /* Send the base request that runs the AI Skill. */
            const copilotCallResult = await handlerChain.process({
                type: 'crt.CopilotExecuteIntentRequest',

                /* Code of the AI Skill to run. */
                intentName: 'CodeOfSomeAISkill',

                /* Parameters of the AI Skill. */
                parameters: {
                    somepromptparameter1: 'some parameter value',
                    somepromptparameter2: 'some parameter value'
                },
                $context: request.$context,
                scopes: [...request.scopes]
            });

            /* If Creatio can run the AI Skill, AI Skill fulfills its task. */
            if (copilotCallResult.isSuccess) {
                /* Implement custom business logic that handles the "copilotCallResult.content". */
                ...

            } else {
            
                /* Implement custom business logic that handles an error and "copilotCallResult.errorMessage". */
                ...

            }

            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

As a result, when you click the button on the Freedom UI page, Creatio AI will handle data based on business logic of the Freedom UI page.

Handle data using Creatio AI (business process)

Implementation of the data handling business logic in the business process differs in Creatio 8.2.1 and later and Creatio 8.2.0:

For Creatio 8.2.1 and later, implement the business logic of data handling using Creatio AI via Call Creatio AI element in the business process.
For Creatio 8.2.0, implement the business logic of data handling using Creatio AI via Script task element in the business process.

Detailed example: Handle system-level data using Creatio AI in the business process.

To implement the business logic of data handling using Creatio AI in business process:

Set up a Read data element that reads Creatio data to handle using Creatio AI. Instructions: Read data process element (user documentation).

Implement the business logic that runs the AI Skill.

For Creatio 8.2.1 and later

Set up a Call Creatio AI element.

Go to the element setup area.
Set Which skill to call? property to code of the AI Skill to run.
Specify values of AI Skill input parameters.

For Creatio 8.2.0

Set up a Script task element. Learn more: Script task process element (user documentation).

Ensure the Methods tab has the Creatio.Copilot namespace added.
Go to the element setup area.

Implement the logic of working with process parameters.

Some script task
// IMPORTANT: When implementing
// long-running operations,
// it is crucial to enable timely and
// responsive cancellation. To achieve
// this, ensure that your code
// is designed to respond appropriately
// to cancellation requests using
// the context.CancellationToken
// mechanism. For more detailed
// information and examples,
// please, refer to our documentation.

/* Retrieve the input parameter of the AI Skill. */
var someVariable = Get<string>("SomeInputParameter");

/* Create a "CopilotIntentCall" instance. */
var request = new CopilotIntentCall {

    /* Code of the AI Skill to run. */
    IntentName = "CodeOfSomeAISkill",

    /* Parameters of the AI Skill. */
    Parameters = new Dictionary<string, object> {
        { "SomeInputParameter", someVariable }
    }
};

/* Create an instance of the "CopilotIntentCall" object. */
CopilotIntentCallResult result = UserConnection.CopilotEngine.ExecuteIntent(request);

/* Status of the Creatio AI execution. */
Set("ParameterThatStoresExecutionStatus", result.Status.ToString());

if (!result.IsSuccess) {
    /* If Creatio cannot run the AI Skill, implement custom business logic that handles an error. */
    ...
    return true;
}

/* Outcome of the Creatio AI work. */
Set("ParameterThatStoresCreatioAIResult", result.Content);

return true;

If needed, add a button that calls the business process. Instructions: Button (user documentation).

As a result, when you click the button on the Freedom UI page, Creatio AI will call the business process, which, in turn, will handle data based on business logic of the Call Creatio AI element (Script task element in Creatio 8.2.0).

1. Develop AI Skill​

2. Set up the data handling using Creatio AI​

Handle data using Creatio AI (Freedom UI page schema)​

Handle data using Creatio AI (business process)​

See also​

1. Develop AI Skill

2. Set up the data handling using Creatio AI

Handle data using Creatio AI (Freedom UI page schema)

Handle data using Creatio AI (business process)

See also