enable apps review

Author: sr-remsha

docs/tutorials/1.developers/4.apps-development/3.enable-app.md

@@ -14,29 +14,31 @@ DIAL-native applications can be categorized as either schema-rich or apps withou
 
 ##### Schema-rich applications
 
-Schema-rich apps, in comparison with apps without schemas, allow users to edit application properties via DIAL Core API that are normally hidden in the app's internal environment and cannot be changed. There is a method in DIAL SDK (`application_properties = await request.request_dial_application_properties()`) that returns application properties with a configuration request to DIAL Core.
+Schema-rich apps, in comparison with apps without schemas, allow users to create instances of applications with different properties via DIAL Core API that are normally hidden in the app's internal environment and cannot be changed. There is a method in DIAL SDK (`application_properties = await request.request_dial_application_properties()`) that returns application properties with a configuration request to DIAL Core.
 This goes beyond simply adjusting the basic settings of an application container, offering dynamics and flexibility compared to apps without schemas.
 
-[Schema-rich applications](#enable-schema-rich-applications) are defined by a JSON schema that conforms to the main [meta schema](https://github.com/epam/ai-dial-core/blob/development/config/src/main/resources/custom-application-schemas/schema). Meta schema specifies the application type's structure, including properties and endpoints (completion, configuration, and other). Meta schema may also include a URL for an application editor (enabling a wizard in the UI for creating/editing applications), a URL for a custom application UI, [custom buttons](/docs/tutorials/1.developers/4.apps-development/1.custom-buttons.md) used by the application.
+[Schema-rich applications](#enable-schema-rich-applications) are defined by a JSON schema that conforms to the main [meta schema](https://github.com/epam/ai-dial-core/blob/development/config/src/main/resources/custom-application-schemas/schema). JSON schema describes the application's structure, including properties and endpoints (completion, configuration, and other), can include URLs for application editor (enabling a wizard in the UI for creating/editing applications) and custom application UI, [custom buttons](/docs/tutorials/1.developers/4.apps-development/1.custom-buttons.md) used by the application.
 
-Schema-rich applications are usually associated with a specific **Application Type** - a template for creating applications of that type. 
+Schema-rich applications are usually associated with a specific **Application Type** - a template for creating applications of that type.  
+
+![](../img/schema-rich-apps.svg)
 
 :cloud: DIAL SaaS edition includes application types such as Quick app, Code app and Mindmap. 
 
 :floppy_disk: In self-hosted deployments of DIAL, you can add new application types, featuring custom application UI (`applicationTypeViewerUrl`) and wizards (`applicationTypeEditorUrl`) and enabling end-users to create applications of that type. Refer to [Agentic Platform](/docs/platform/0.architecture-and-concepts/4.agentic-platform.md#application-types) to learn more about available application types.
 
 ##### Applications without schemas
 
-[Applications without schemas](#enable-applications-without-schemas) are not tied to any specific application type. When enabling such an app, you must explicitly specify all properties and available endpoints the application offers. All application properties are part of the application code and the container it runs in, meaning they cannot be modified through the DIAL Core API, contrary to schema-rich applications. To enable two apps without schemas, you need to launch two containers, whereas for schema-rich apps, you can make just two API calls.
+[Applications without schemas](#enable-applications-without-schemas) are not tied to any specific application type. When enabling such an app, you must explicitly specify (in the [API PUT request](#using-api-1)) standard parameters of the application and available endpoints the application offers. Properties that define the logic and behavior of the application are part of the application code and the container it runs in, meaning they cannot be modified through the DIAL Core API, contrary to schema-rich applications. For example, to enable two apps without schemas, you may need to launch two containers, whereas for schema-rich apps, you can make just two API calls.
 
 ## Enable Schema-Rich Applications
 
-You can enable schema-rich apps either by using DIAL API or by a direct modification of the DIAL Core configuration.
+You can enable schema-rich apps either by using [DIAL API](#using-api) or by a [direct modification of the DIAL Core configuration](#using-dial-core-config).
 
 **Prerequisites**:
 
 - A schema of the application type must be included in the DIAL Core configuration.
-- You must have a running container with your app accessible via the endpoint specified in the meta schema.
+- Having a running container for each application type. These containers must be accessible via the endpoints specified in the JSON schema for their respective application types.
 
 ### Using API
 
@@ -50,9 +52,9 @@ Send a [PUT](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomAppl
 - `applicationTypeSchemaId`: The identifier of the schema for the application type you want to use as a template. You can retrieve available schemas via the [GET Schemas](https://rail-landing.staging.deltixhub.io/dial_api#tag/Applications/operation/listCustomApplicationSchemas) API call.
 - `applicationProperties`: A valid JSON object representing the application's structure, conforming to the specified schema. If the JSON object is invalid, the request will fail.
 
-  - If `applicationTypeSchemaId` is absent or `NULL`, `applicationProperties` are not required.
+  - If `applicationTypeSchemaId` is absent or `NULL`, `applicationProperties` are not required. If `applicationTypeSchemaId` is not provided, then this is not a schema-rich application.
   - If `applicationTypeSchemaId` is provided but `applicationProperties` are `NULL`, the application is considered a "stub" and can be updated later, but completion requests will not be possible until then.
-  - For applications with schemas, all requests are routed **ONLY** to endpoints specified in the schema. If you specify endpoints in the request, such request will fail.
+  - For applications with schemas, all requests are routed **ONLY** to endpoints specified in the schema. If you specify endpoints in the [PUT](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomApplication) request, such request will fail.
 
     Example:
 
@@ -64,7 +66,7 @@ Send a [PUT](https://dialx.ai/dial_api#tag/Applications/operation/saveCustomAppl
         "applicationTypeSchemaId": "https://mydial.epam.com/custom_application_schemas/quickapps",
         "applicationProperties": {
           "temperature": 0.8,
-          "instructions": "You should help explore the document containing the Copilot Deck. You must query the document first to do that. You should answer using only the information in the document. Answer \"I don't know\" if there are any other questions.",
+          "instructions": "Answer using only the information in the document.",
           "model": "gpt-4o-2024-05-13",
           "web_api_toolset": [],
           "document_relative_url": "files/DpZGXdhaTxt4FYCWNadE2Ln/GPT%20Deck.docx"
@@ -79,7 +81,7 @@ The configuration of the enabled app is saved as a BLOB in the DIAL Core file sy
 
 #### UI Wizard
 
-Schemas of application types can include `applicationTypeEditorUrl` to enable users to create and edit applications using UI wizards. 
+JSON Schemas of application types can include `applicationTypeEditorUrl` to enable a UI for users to create and edit applications. 
 
 :cloud: SaaS DIAL edition includes wizards for Quick app, Code app and Mindmap application types. 
 
@@ -89,7 +91,7 @@ Schemas of application types can include `applicationTypeEditorUrl` to enable us
 
 ### Using DIAL Core Config
 
-DIAL admins can create schema-rich applications by including a valid JSON object with the application representation in the [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) configuration for the `applications` keyword.
+DIAL admins can create schema-rich applications by including a valid JSON object with the application representation in the [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) configuration in the `applications` section.
 
 Example:
 
@@ -101,10 +103,10 @@ Example:
       "applicationTypeSchemaId": "https://mydial.epam.com/custom_application_schemas/quickapps",
       "applicationProperties": {
         "temperature": 0.8,
-        "instructions": "You should help explore the document containing the Copilot Deck. You must query the document first to do that. You should answer using only the information in the document. Answer \"I don't know\" if there are any other questions.",
+        "instructions": "Answer using only the information in the document.",
         "model": "gpt-4o-2024-05-13",
         "web_api_toolset": [],
-        "document_relative_url": ["files/DpZGXdFYCWNadE2Ln/GPT%20Deck%20text.docx", "files/DpZGXdhaTxtaR67V4FYCWNadE2Ln/GPT%20Deck%20text.docx"]
+        "document_relative_url": ["files/DpZGXdFYCWNadE2Ln/GPT%20Deck%20text.docx"]
       }
     }
 ```
@@ -113,11 +115,11 @@ Example:
 
 ## Enable Applications without Schemas
 
-Applications without schemas, in comparison with schema-rich apps, are not associated with any specific application type and do not have properties that are described in a schema. To enable such an app, you provide a JSON object with a complete configuration, including all application endpoints and properties. Refer to [dynamic setting of DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) to see all the supported parameters for `applications`.
+Applications without schemas, unlike schema-rich apps, are not tied to a specific application type and their business logic cannot be defined through properties in a JSON schema. 
 
-To enable such applications in DIAL, you can either include a JSON object with apps representation in the DIAL Core configuration or use the DIAL API.
+To enable such an app in DIAL, you can add its representation in JSON format directly into the [DIAL Core config](#using-dial-core-config-1) or make an [API request](#using-api-1) where you provide all application endpoints and standard parameters - refer to [dynamic setting of DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) to see all the supported parameters for `applications`.
 
-**Prerequisite**: You must have a running container with your app accessible via the endpoint you provide in the request.
+**Prerequisite**: You must have a running container with your app accessible for DIAL Core via the endpoints you provide in the [PUT request](#using-api-1).
 
 ### Using API
 
@@ -157,7 +159,7 @@ The configuration of an application is saved as a BLOB in the DIAL Core file sys
 
 ### Using DIAL Core Config
 
-DIAL admins can create an application by including a valid JSON object with the application representation in the [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) configuration for the `applications` keyword.
+DIAL admins can create an application by including a valid JSON object with the application representation in the [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings) configuration for the `applications` section.
 
 Example:
 
@@ -181,13 +183,16 @@ Example:
 
 > Refer to [Access & Cost Control](/docs/platform/3.core/2.access-control-intro.md) to learn how access control to system resources is implemented in DIAL.
 
-If you want your app to be available to other users and listed on the DIAL Marketplace, you need to:
+If you want your app to be available to other users and listed on the DIAL Marketplace, you need to associate your app with a specific role by including `userRoles` in the app's configuration.
 
-- Associate your app with a specific role by including `userRoles` in the app's configuration.
-- Add your app to the scope of the selected role. Additionally, you can set limits for user roles, such as restricting the number of tokens that can be sent to your app within a defined time interval.
+Applications use language models on behalf of users, provided both model and application can be accessed by a specific user role. In this case, costs of using a model are defined by the limits configured for a specific user role.
 
 Example of roles and limits configuration in [DIAL Core](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings):
 
+You're absolutely right. Thank you for catching that. Here's the corrected version:
+
+In the following example, the `my_app` application is accessible to users with the `app_user` role. For this user role, usage limits are set on the `chat-gpt-35-turbo` model, as specified in the `limits` section. When a user with the `app_user` role uses the application, the app will use the `chat-gpt-35-turbo` model within these prescribed limits.
+
 ```json
 "applications":
   "my_app": {
@@ -196,7 +201,7 @@ Example of roles and limits configuration in [DIAL Core](https://github.com/epam
 "roles": {
     "app_user": { // the name of the role
         "limits": {
-            "my_app": {
+            "chat-gpt-35-turbo": {
               "minute": "100000", //number of tokens per minute
               "day": "10000000", //number of tokens per day
               "week": "10000000", //number of tokens per week
@@ -209,27 +214,35 @@ Example of roles and limits configuration in [DIAL Core](https://github.com/epam
 
 ## Sharing & Publications
 
-As the author of a schema-rich application, I can enable my colleagues to use it by sharing or publishing the app. Refer to [Collaboration](/docs/platform/7.collaboration-intro.md) to learn more about sharing and publications.  
+Applications can rely on resources like documents and files to operate. It is crucial to ensure that these resource are accessible, if needed, to all involved parties in the operation flow. This is particularly important when applications are shared or published, as well as when files are supplied by users or shared between applications.
+
+File sharing in DIAL applications can occur in several scenarios:
+
+1. When an application is shared with other users
+2. When an application is published
+3. When files are supplied by a user to an application
+4. When files are shared as part of a request from one application to another
+
+The handling of these scenarios differs significantly between schema-rich applications and those without schemas.
 
-If the application's configuration includes links to resources (e.g., files or documents), these can be marked in the schema using the `"dial_file": true` property. When this property is applied, all referenced files are automatically shared or published alongside the application.  
+##### For applications without schemas
 
-This behavior applies to all schema-rich applications, regardless of whether they are enabled via configuration or created using the UI or API.  
+Developers must incorporate custom logic to handle file access when the application is shared or published. It requires careful implementation to ensure all necessary resources are available for authorized users and apps.
 
-### Automatic File Sharing Behavior  
+##### For schema-rich applications
 
-When a field in the application schema is marked with `"dial_file": true`, the following actions occur:  
+The JSON schema of schema-rich apps can include links to resources (e.g., files or documents). 
 
-- Files referenced by the application are shared automatically when the app is accessed by another application using per-request API keys.  
-- Files are shared when the app is published or shared by a user or the app's author.  
-- Files are included in all interactions, such as chat completion or configuration requests made to DIAL Core.  
+The following logic applies to resources marked with the `"dial_file": true` property, regardless of whether the app was enabled via configuration or created using the UI or API.
 
-For example, if a user submits a request to the app through DIAL Chat, the DIAL Core identifies the `"dial_file": true` fields in the app schema and automatically includes the corresponding files as attachments to the request.  
+* Files are automatically shared or published alongside the application (scenarios 1 and 2).
+* Files are automatically included in chat completion requests or when making API calls between applications (scenarios 3 and 4).
 
-### Preventing Automatic File Sharing  
+![](../img/files-sharing.svg)
 
-To prevent specific resources from being shared automatically, avoid marking their schema properties with `"dial_file": true`. You can use other types, such as `"string"`, to exclude them from this behavior.
+To prevent specific resources from being shared automatically, avoid marking their schema properties with `"dial_file": true`. 
 
-### Example  
+##### Example  
 
 A schema for a RAG application might define a field like `rag_files`:  
 
@@ -259,8 +272,8 @@ In this example, the files listed in the `rag_files` field will automatically fo
 
 ##### Custom UIs
 
-You can create application types with custom UIs to replace the default DIAL UI, even for non-conversational apps. Additionally, you can implement separate custom wizards as needed. Custom UIs can follow any logic and are defined in the application type schema using `applicationTypeViewerUrl` for UI and `applicationTypeEditorUrl` for wizard.
+You can create schema-rich application types with custom UIs to replace the default DIAL UI, even for non-conversational apps. Additionally, you can implement separate custom wizards as needed. Custom UIs can follow any logic and are defined in the application type schema using `applicationTypeViewerUrl` for UI and `applicationTypeEditorUrl` for wizard.
 
 ##### Application Endpoint
 
-You can register your application's endpoint in DIAL Core as a `route`. You can apply roles, usage limits, and associate API keys with these routes, enabling seamless integration with DIAL Core features. This allows other applications in DIAL to interact with your app's endpoint. For details on registering routes, refer to [DIAL Core dynamic settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings).
+To enable DIAL apps to communicate with your application, you can register your application's endpoint in DIAL Core as a `route`. You can apply roles, usage limits, and associate API keys with these routes, enabling seamless integration with DIAL Core features. For details on registering routes, refer to [DIAL Core dynamic settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings).