### Properties File Naming Examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Examples of valid .properties file names following the required naming convention. ```text messages_en.properties messages_en_GB.properties messages_de.properties messages_de_CH.properties ``` -------------------------------- ### Plain Text Streamed Response Example Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Example of how plain text data chunks are aggregated. ```text data: Test data: text ---------------------- Result: Test text ``` -------------------------------- ### Navigation Data Example Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Include intent-based navigation fields to support linking to SAP applications. ```json { "order_id": "4500012345", "semantic_object": "PurchaseOrder", "action": "display" } ``` -------------------------------- ### Structured Data Examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Compare poor, metadata-heavy structures with clean, business-focused JSON objects. ```json { "__count": "2", "results": [ { "__metadata": { }, "posTitle": null, "education": { "__deferred": {} }, "usersSysId": "9601133" } ] } ``` ```json { "job_applicants": [ { "applicant_name": "John Smith", "applicant_id": "9601133", "position": "Senior Engineer", "application_status": "Under Review" } ] } ``` -------------------------------- ### Frontend Action Implementation Example Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Demonstrates using a frontend action to retrieve data and setting variables based on the success status. ```yaml action_groups: - actions: - type: frontend-action name: sap.ui.summarize.v1 result_variable: frontend_action_result - condition: frontend_action_result.status == "success" actions: - type: set-variables variables: - name: success_payloadWhen a scenario includes nested dialog functions (for example, Scenario A calls Dialog Function X, wh actions: - type: set-variables variabl frontend action), only mandatory frontend act value: frontend_action_result.content result: status: the scenario's `visibility_condition`. action_groups: - actions: content: summarize.v1 result_variable: frontend_action_result - condition: frontend_action_result.status == "success" ``` -------------------------------- ### JSON Streamed Response Example Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Example of how JSON data chunks are aggregated into a final result. ```text data: {"delta":{"content":"Test"}} data: {"delta":{"content":" text"}} --------------------------------------- Result: Test text ``` -------------------------------- ### List Consistency Examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Ensure all objects in a list share the same schema to prevent incomplete rendering. ```json [ { "name": "Order A", "amount": 1000 }, { "name": "Order B", "supplier": "Acme" } ] ``` ```json [ { "name": "Order A", "amount": "€1,000", "supplier": "Tech Corp" }, { "name": "Order B", "amount": "€2,500", "supplier": "Acme" } ] ``` -------------------------------- ### Field Naming Examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Use descriptive keys instead of generic abbreviations to provide semantic context to the LLM. ```json { "f1": "Jane Smith", "f2": "Engineering", "v": "Active" } ``` ```json { "employee_name": "Jane Smith", "department": "Engineering", "status": "Active" } ``` -------------------------------- ### Plain Text SSE Default Behavior Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Example showing how leading spaces are ignored without specific formatting. ```text data:-Test data:-text ---------------------- Result: Testtext ``` -------------------------------- ### Plain Text SSE with Leading Spaces Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Example of formatting plain text responses using leading spaces. ```text data:-Test data:--text ---------------------- Result: Test-text ``` -------------------------------- ### Complete Asynchronous API Request Workflow Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/asynchronous-api-request?locale=en-US A full example combining the asynchronous API request and a follow-up message action to display the result. ```yaml action_groups: - actions: - type: api-request method: POST async: true system_alias: Orbit path: "/thisIsMyEndpoint" headers: someHeaderKey: "someHeaderValue" body: { "someBodyKey": "someBodyValue" } result_variable: api_call_result - type: message message: type: text content: "Result: " ``` -------------------------------- ### SpEL Joule Function examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Comparison of a weather Joule function before and after applying i18n keys, along with the corresponding properties file content. ```yaml - condition: weather_result.status_code == 200 actions: - type: message message: type: text content: "In , on temperature will be between °C and °C. Details: " - condition: weather_result.status_code != 200 actions: - type: message message: type: text content: "An error occurred when fetching the weather information. The result was: " ``` ```yaml - condition: weather_result.status_code == 200 actions: - type: message message: type: text content: "" - condition: weather_result.status_code != 200 actions: - type: message message: type: text content: "" ``` ```properties # XMSG, {0} is the city name, {1} is the day of the week, {2} is the minimum temperature, {3} is the maximum temperature, {4} is the weather description WEATHER_RESULTS=In {0}, on {1} temperature will be between {2} °C and {3} °C. Details: {4} # XMSG, {0} is the error message FETCHING_WEATHER_ERROR=An error occurred when fetching the weather information. The result was: {0} ``` -------------------------------- ### Plain Text SSE with Trailing Spaces Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Example of formatting plain text responses using trailing spaces. ```text data:-Test- data:-text ---------------------- Result: Test-text ``` -------------------------------- ### Scenario File Syntax Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/defining-scenarios?locale=en-US The YAML structure for defining a scenario, including data processing policies, utterance examples, slots, and target function execution. ```yaml description: # Optional new node to indicate scenario processing details including sensitivity data_processing: policy: 'sensitive_personal' examples: - slots: - name: description: target: type: function name: parameters: - name: value: response_context: - value: description: ``` -------------------------------- ### Handlebars Joule Function examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Comparison of a Joule function before and after applying i18n keys, along with the corresponding properties file content. ```yaml - condition: is_mine == true actions: - type: message scripting_type: handlebars message: { "type": "text", "content": "Here's the link to view the profile of your manager." } - condition: is_mine == false actions: - type: message scripting_type: handlebars message: { "type": "text", "content": "Here's the link to view the profile of {{selected_person.displayName}}'s manager." } ``` ```yaml - condition: is_mine == true actions: - type: message scripting_type: handlebars message: { "type": "text", "content": "{{i18n 'LINK_TO_MANAGER_PROFILE'}}" } - condition: is_mine == false actions: - type: message scripting_type: handlebars message: { "type": "text", "content": "{{i18n 'LINK_TO_PERSONS_MANAGER_PROFILE' selected_person.displayName}}" } ``` ```properties #XMSG LINK_TO_MANAGER_PROFILE=Here's the link to view the profile of your manager. #XMSG, {0} is a person name LINK_TO_PERSONS_MANAGER_PROFILE=Here's the link to view the profile of {0}'s manager. ``` -------------------------------- ### Implement escaped i18n in YAML configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Example of using the escape helper within a YAML-defined message action. ```yaml action_groups: - actions: - type: message scripting_type: handlebars message: > { "type": "list", "content": { "total": "15", "elements": [ { "title": { "value": "{{ escape (i18n 'EXAMPLE') }}" } } ], "initialPageSize": 15, "enableDetailView": false, "title": "Available cars" }, "markdown": false, "delay": 0 } ``` -------------------------------- ### Human-Readable Values Examples Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Avoid coded values that require external interpretation by the user. ```json { "status": "t" } ``` ```json { "status": "Active" } ``` -------------------------------- ### Primary Identifier Example Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Include a clear business identifier to serve as the card or list item title. ```json { "purchase_order": "PO-4500012345", "supplier": "Tech Solutions LLC", "net_amount": "€45,000.00", "status": "Awaiting Approval", "delivery_date": "2024-03-15" } ``` -------------------------------- ### Define i18n properties with quotes Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Example of a messages.properties file entry containing double quotes. ```properties EXAMPLE=example with " (double quotes) ``` -------------------------------- ### Joule Function with i18n keys Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Example of a Joule function using SPEL and i18n keys to handle conditional logic, facilitating easier translation. ```yaml - condition: only_one_user actions: - type: message scripting_type: spel message: > { "type": "text", "content": "" } ``` -------------------------------- ### Joule Function without i18n keys Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Example of a Joule function using handlebars scripting with conditional logic inside the message string, which is discouraged for translation. ```yaml - condition: only_one_user actions: - type: message scripting_type: handlebars message: > { "type": "text", "content": {{#if selected_person}}"I found one employee, {{selected_person.displayName}}{{#if selected_person.email}} ({{selected_person.email}}){{/if}}, matching the name you provided."{{else}}"I found one employee matching the name you provided."{{/if}} } ``` -------------------------------- ### View the Joule project folder structure Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/download-and-install-joule-studio-code-editor?locale=en-US Displays the expected directory layout for a Joule project, including capability folders and configuration files. ```text └── weather ├── weather_capability │ ├── functions │ │ └── fetch_weather.yaml │ ├── scenarios │ │ └── weather.yaml | └── capability.sapdas.yaml ├── weather.da.sapdas.yaml └── da.sapdas.yaml ``` -------------------------------- ### Define Digital Assistant Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/design-time-artifact-dta-specification?locale=en-US Use this YAML structure to define the Digital Assistant name and its associated local capabilities or pre-compiled .daar files. ```yaml schema_version: 1.0.0 #DA Config Schema Version name: MyTestDigitalAssistant #name of the Digital Assistant capabilities: # capabilities to be assembled - type: local folder: ./my_capability # folder path to a local capability DTA - type: local folder: ./my_second_capability - type: local path: ./my_third_capability/my_third_capability.daar # path to a local pre-compiler daar file conversational_search: # optional: enable conversational search feature enabled: true product_filter: # products the search will be perfomed on (SAP Help Product IDs) - SAP_SUCCESSFACTORS ``` -------------------------------- ### Joule CLI Login Commands Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/authentication-back-end-requirements?locale=en-US Various methods for authenticating with a Joule tenant using the CLI, including direct credentials, SSO, and passcode-based flows. ```bash #Inline joule login -a https://myias.accounts.ondemand.com --apiurl -c -s -u -p #Inline with SSO passcode joule login -a https://myias.accounts.ondemand.com --apiurl -c -s -u --sso-passcode Temporary Authentication Code ( Get one at ): joule login -a https://myias.accounts.ondemand.com --apiurl -c -s -u --sso-passcode #Prompts joule login Authentication URL: https://myias.accounts400.ondemand.com API URL: Instance Client ID: Instance Client Secret: Username: Password: #Prompts with SSO joule login --sso API URL: Open Authentication URL?: yes/no #Prompts with sso for IAS joule login --sso API URL: Instance #Prompts with sso passcode for IAS joule login --sso-passcode Authentication URL: https://myias.accounts400.ondemand.com API URL: Instance Client ID: Instance Client Secret: ``` -------------------------------- ### User Confirmation Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines a confirmation step requiring user input before proceeding with dialog execution. ```yaml - type: user-confirmation scripting_type: "spel|handlebars" content: title: "" subtitle: "<subtitle text>" button_labels: confirm: "I confirm" cancel: "Cancel" confirmation_variable: "<variable name>" ``` -------------------------------- ### Capability Folder Structure Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/design-time-artifact-dta-specification?locale=en-US The standard directory layout for a capability, including scenarios, functions, agents, and configuration files. ```text └── sample-capability ├── scenarios │ └── sample_scenario.yaml ├── functions │ └── sample_function.yaml ├── agents │ └── agent_1.yaml │ └── agent_2.yaml │ └── agent_1.schema.json │ └── agent_2.schema.json ├── i18n │ ├── messages_de.properties │ ├── messages_en.properties │ └── messages.properties ├── capability_context.yaml ├── deployment_extension.yaml └── capability.sapdas.yaml ``` -------------------------------- ### Message Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines a message to be returned to the user. Supports SpEL or handlebars for dynamic content generation. ```yaml - type: message scripting_type: <spel (default) | handlebars> #optional message: type: text content: Weather in {{location}} is {{weatherServiceResponse.response.body.current}} ``` -------------------------------- ### file-upload Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Configures an action allowing users to select and upload files. ```APIDOC ## file-upload ### Description Allows users to choose files for upload, with support for cancellation confirmation and file constraints. ### Configuration - **type**: "file-upload" - **scripting_type**: "spel" or "handlebars" - **content**: - **message**: Display message for the upload action - **on_cancel**: Configuration for cancel confirmation (title, message, button_labels) - **allowed_file_types**: List of permitted file extensions (e.g., pdf, docx, jpg) - **max_file_size**: Maximum size per file (limit: 10 MB) - **max_files_allowed**: Maximum number of files (limit: 10) - **result_variable**: Result context variable (optional) ``` -------------------------------- ### File Upload Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines the YAML structure for enabling file uploads in a capability. ```yaml - type: file-upload scripting_type: "spel|handlebars" content: message: <message> on_cancel: title: <title> message: <message> button_labels: cancel: "yes" continue: "no" allowed_file_types: - pdf - docx - jpg max_file_size: <max_file_size> max_files_allowed: <max_files_allowed> result_variable: <result context variable> #optional ``` -------------------------------- ### Define a Set Variables Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Configuration schema for modifying local context variables using SpEL or Handlebars syntax. ```yaml - type: set-variables scripting_type: <spel (default) | handlebars> #optional variables: - name: <key 1> value: <value 1> - name: <key 2> value: <value 2> ... - name: <key n> value: <value n> ``` -------------------------------- ### User Confirmation Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines a step that prompts the user for confirmation before proceeding with dialog function execution. ```APIDOC ## User Confirmation Action ### Description The user confirmation action allows users of Joule to review and confirm their API requests before they are sent. A confirmation step can be used to get user approval before continuing the dialog function execution. ### Configuration - **type**: "user-confirmation" - **scripting_type**: "spel" or "handlebars" (Optional, default: SpEL) - **content**: - **title**: Title text (Mandatory) - **subtitle**: Subtitle text (Mandatory) - **button_labels**: - **confirm**: Label for confirm button (Mandatory) - **cancel**: Label for cancel button (Mandatory) - **confirmation_variable**: Variable name to store confirmation result ### Example ```yaml - type: user-confirmation scripting_type: "spel" content: title: "Confirm Action" subtitle: "Are you sure?" button_labels: confirm: "I confirm" cancel: "Cancel" confirmation_variable: "user_choice" ``` ``` -------------------------------- ### Dialog Function Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Executes a specified dialog function and optionally stores the result in a local context variable. ```yaml - type: dialog-function name: <dialog function name (full path)> parameters: #optional - name: <name> value: <value> result_variable: <optional result context variable> #optional ``` -------------------------------- ### Configure API-request actions for octet-stream flow Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/attachment-handling-in-joule-4f5978a487fd411e8c80fc50b0d68b06?locale=en-US Use this configuration to send a single file to an external service. The Accept header must match the Content-Type of the binary response. ```yaml action_groups: - actions: - type: api-request method: GET headers: Accept: image/jpeg #To invoke attachment service flow Accept header need to be specified and the value should be equal with value of Content-Type header from binary response (file that should be downloaded) system_alias: JpgAlias path: /images/link-icon-png/link-icon-png-12.jpg result_variable: file_metadata - type: api-request method: POST headers: Content-Type: application/octet-stream #To invoke the octet-stream flow Accept: application/json system_alias: WebHookAlias path: /574eeaad-584f-4afc-9c31-229e1017947e #Path to the external service where we want to upload the file body: <? file_metadata.body.file.id ?> #In case of octet-stream body will be file-reference id result_variable: responseData ``` -------------------------------- ### Capability Folder Structure Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/defining-scenarios?locale=en-US The standard directory layout for a Joule capability, requiring a scenarios folder at the same level as functions. ```text sample_capability ├── functions ├── scenarios ├── capability_context.yaml └── capability.sapdas.yaml ``` -------------------------------- ### OData Batch Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Performs multiple OData requests in a single batch call. Supports SpEL for specific properties like path and headers. ```yaml - type: odata-batch system_alias: <system alias name defined in capability.sapdas.yaml> path: <base url path> #optional headers: #optional <header key>: <header value> timeout: 45 #optional, available from 1.5.0 version requests: - method <GET | POST | DELETE | PUT | PATCH | MERGE> path: <relative path> headers: #optional <header key>: <header value>, Content-ID: <header value> #optional body: <body value> #optional result_key: <result key name> - ... result_variable: <result context variable> #optional ``` ```yaml - type: odata-batch system_alias: <system alias name defined in capability.sapdas.yaml> path: <your url path> headers: Accept: multipart/mixed, application/json requests: .... ``` -------------------------------- ### POST Asynchronous API Request Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/asynchronous-api-request?locale=en-US Initiates an asynchronous API request by configuring the action type as api-request with the async property set to true. ```APIDOC ## POST /api-request (Asynchronous) ### Description Initiates an asynchronous API request. The backend must acknowledge the request immediately with a non-4xx/5xx status code to prevent processing exceptions. ### Method POST ### Parameters #### Request Body - **async** (boolean) - Required - Set to true to enable asynchronous behavior. - **system_alias** (string) - Required - The alias of the target system. - **path** (string) - Required - The endpoint path. - **headers** (object) - Optional - Custom headers to include in the request. - **body** (object) - Optional - The payload for the request. - **result_variable** (string) - Required - The variable name where the callback result will be stored. ### Request Example ```json { "type": "api-request", "method": "POST", "async": true, "system_alias": "Orbit", "path": "/thisIsMyEndpoint", "headers": { "someHeaderKey": "someHeaderValue" }, "body": { "someBodyKey": "someBodyValue" }, "result_variable": "api_call_result" } ``` ``` -------------------------------- ### Accessing $transient variables in a dialog function Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/accessing-context-information?locale=en-US Demonstrates how to reference $transient variables within a capability definition to set variables and pass them to a dialog function. ```yaml parameters: - name: name action_groups: - actions: - type: message message: type: text content: "Here are the details for the train station:" - type: set-variables variables: - name: "country_code" value: "<? $transient.app_context["com.trains.appInfo"].country ?>" - type: dialog-function name: train/station_lookup parameters: - name: query value: "<? name ?>" - name: conutry value: "<? country_code ?>" result_variable: station_details result: station: <? station_details ?> ``` -------------------------------- ### Status Update Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Provides progress updates to the user during long-running dialog functions. Supports dynamic messaging via SpEL or handlebars. ```yaml - type: status-update scripting_type: < spel | handlebars> #optional message: <text message, may include scripting> ``` -------------------------------- ### SpEL i18n syntax Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US General syntax for using i18n in SpEL with native var-args support. ```spel new i18n('MESSAGE_ID', <var-arg param1>, <var-arg param2> ... <var-arg paramN>) ``` -------------------------------- ### Define an Asynchronous API Request Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/asynchronous-api-request?locale=en-US Configure an API request action with the 'async: true' property to enable asynchronous behavior. ```yaml action_groups: - actions: - type: api-request method: POST async: true # This enables async behavior system_alias: Orbit path: "/thisIsMyEndpoint" headers: someHeaderKey: "someHeaderValue" body: { "someBodyKey": "someBodyValue" } result_variable: api_call_result ``` -------------------------------- ### Define an API Request Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Configuration schema for performing API requests, including support for headers, body content, and result variable mapping. ```yaml - type: api-request method: <GET | POST | OPTIONS | DELETE | PUT | PATCH> async: <TRUE | FALSE > #optional, available from 3.18.0 version (defaults to false) system_alias: <system alias name defined in capability.sapdas.yaml> path: <url path> #optional headers: #optional <header key>: <header value> timeout: 45 #optional body: <body value> #optional, must be a string if a header 'content-type' is defined and eq 'application/octet-stream', disallowed if 'content-type' is 'multipart/form-data' form_body: #allowed if `content-type` is 'multipart/form-data' - type: text key: mykey headers: #optional, such as content-type and content-disposition key: value value: <? result.body.file.id ?> # file id generated in previous response should be provided here. result_variable: <result context variable> #optional ``` -------------------------------- ### OData Batch Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Performs an OData batch call to an external API using a defined system alias. ```APIDOC ## OData Batch Action ### Description Executes multiple OData requests within a single batch call to an external system. ### Configuration - **type**: "odata-batch" - **system_alias**: <alias defined in capability.sapdas.yaml> - **path**: <base url path> (Optional) - **headers**: Map of header keys and values (Optional) - **timeout**: Integer (Optional) - **requests**: List of request objects (method, path, headers, body, result_key) - **result_variable**: Name of the variable to store the result (Optional) ``` -------------------------------- ### Configure API-request actions for multipart/form-body flow Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/attachment-handling-in-joule-4f5978a487fd411e8c80fc50b0d68b06?locale=en-US Use this configuration to upload multiple files or mixed content types to an external service. The form_body section allows defining specific file and text elements. ```yaml action_groups: - actions: - type: api-request method: GET headers: Accept: image/jpeg #To invoke attachment service flow Accept header need to be specified and the value should be equal with value of Content-Type header from binary response (file that should be downloaded) system_alias: JpgAlias path: /images/link-icon-png/link-icon-png-12.jpg result_variable: file_metadata - type: api-request method: POST headers: Content-Type: multipart/form-data #To invoke the form-body flow Accept: application/json system_alias: WebHookAlias path: /d50ddc33-2919-4531-9b5c-0622bf4eff53 form_body: - type: file key: myFile headers: # further headers to be provided for each form element content-type: application/pdf value: <? file_metadata.body.file.id ?> #File id generated in previous response should be provided here. - type: text key: myTextKey value: some test string result_variable: fileResponse ``` -------------------------------- ### Retrieve Month Component Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the month index (0-11) in UTC, where 0 is January. ```javascript future.getMonth() // =0 ``` -------------------------------- ### getTime() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the milliseconds since the Unix epoch. ```APIDOC ## getTime() ### Description Returns the milliseconds since the start of the unix epoch time (1st January 1970, 00:00 GMT/UTC). ### Output Long ### Example ```javascript today.getTime() // equals milliseconds since start of unix epoch time ``` ``` -------------------------------- ### Capability Folder Structure for i18n Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US The required directory layout for internationalization files within a capability. ```text sample_capability ├── i18n │ ├── messages.properties │ └── messages_en.properties └── capability.sapdas.yaml ``` -------------------------------- ### Frontend Action Definition Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Configures a frontend action to interact with the application, supporting optional execution and result variable storage. ```yaml - type: frontend-action name: <technical_frontend_action_name> optional: <TRUE | FALSE> # Optional parameters: # Optional - name: <parameter_name_1> value: <parameter_value_1> - name: <parameter_name_2> value: <parameter_value_2> ... - name: <parameter_name_n> value: <parameter_value_n> result_variable: <result_context_variable> # Optional ``` -------------------------------- ### Frontend Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines an action to interact with the application running alongside Joule, allowing for screen-based interactions or state refreshes. ```APIDOC ## Frontend Action ### Description A frontend action is used to interact with the application running next to Joule. This is useful for scenarios where a user wants to interact with the current screen or when specific backend APIs are unavailable. ### Configuration - **type**: "frontend-action" - **name**: Technical name of the action (Format: <lob_namespace>.<application_name>.<frontend_action_name>.<version>) - **optional**: Boolean (Default: false) - **parameters**: List of key/value pairs passed to the action - **result_variable**: Name of the variable where the result is stored ### Example ```yaml - type: frontend-action name: sap.ui.summarize.v1 result_variable: frontend_action_result ``` ``` -------------------------------- ### getDate() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the day of the month (1-31) as interpreted in UTC. ```APIDOC ## getDate() ### Description Returns the day of the month represented by this Date object, as interpreted in the UTC time zone. The value returned is between 1 and 31. ### Output Integer ### Example ```javascript future.getDate() // =1 ``` ``` -------------------------------- ### Retrieve Minute Component Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the minutes (0-59) in UTC. ```javascript future.getMinutes() // =40 ``` -------------------------------- ### compareTo(Date) Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Compares two dates and returns a value indicating their relative order. ```APIDOC ## compareTo(Date) ### Description Compares this date to the provided date, encompassing before, after, and equals logic. ### Parameters - **date** (Date) - Required - The date to compare against. ### Output Boolean ### Example ```javascript today.compareTo(past) // >0 ``` ``` -------------------------------- ### Java Resource Bundle Lookup Sequence Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US The fallback sequence used by the Joule runtime to resolve string IDs. ```text baseName + "_" + language + "_" + country.properties //es_CODE baseName + "_" + language.properties //es baseName.properties //default ``` -------------------------------- ### getMinutes() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the minutes (0-59) as interpreted in UTC. ```APIDOC ## getMinutes() ### Description Returns the number of minutes past the hour represented by this date, as interpreted in the UTC time zone. The value returned is between 0 and 59. ### Output Integer ### Example ```javascript future.getMinutes() // =40 ``` ``` -------------------------------- ### Define a function-type scenario in YAML Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/defining-scenarios?locale=en-US This YAML configuration defines a scenario of type function, mapping parameters to capability context values. ```yaml description: This functionality can be used to answer greetings. target: type: function name: greet parameters: - name: client_name value: $capability_context.client_name - name: greeting_message value: Hello ``` -------------------------------- ### Retrieve Second Component Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the seconds (0-59) in UTC. ```javascript future.getSeconds() // =41 ``` -------------------------------- ### Nested Dialog Function Frontend Dependencies Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Declares required frontend actions for nested dialog functions to ensure correct scenario preselection. ```yaml description: This functionality can be used to answer greetings. required_frontend_actions: - com.sap.ui.refresh.v1 - com.sap.ui.setTheme.v2 - com.sap.ui.changeCountryCode.v2 target: type: function name: module/another_function parameters: - name: location value: "Berlin" ``` -------------------------------- ### API Request Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines an action to perform an API call and store the result in a local context variable. ```APIDOC ## API Request Action ### Description Performs an API call and gathers the result into a defined local-context variable. ### Configuration - **type**: "api-request" - **method**: GET | POST | OPTIONS | DELETE | PUT | PATCH - **async**: Boolean (optional, default: false, available from 3.18.0) - **system_alias**: String (system alias name defined in capability.sapdas.yaml) - **path**: String (optional) - **headers**: Object (optional) - **timeout**: Integer (optional, default: 45) - **body**: String (optional) - **form_body**: Array (optional, allowed if content-type is 'multipart/form-data') - **result_variable**: String (optional) ``` -------------------------------- ### Dialog Function Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Executes another dialog function and optionally stores the result in a local context variable. ```APIDOC ## Dialog Function Action ### Description Used to trigger the execution of another dialog function. The result can be captured in a specified variable. ### Configuration - **type**: "dialog-function" - **name**: <full path of the dialog function> - **parameters**: List of name/value pairs (Optional) - **result_variable**: Name of the variable to store the result (Optional) ``` -------------------------------- ### getDay() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the day of the week (0-6) as interpreted in UTC. ```APIDOC ## getDay() ### Description Returns the day of the week (0 = Sunday, 1 = Monday, 2 = Tuesday, 3 = Wednesday, 4 = Thursday, 5 = Friday, 6 = Saturday) as interpreted in the UTC time zone. ### Output Integer ### Example ```javascript future.getDay() // =4 ``` ``` -------------------------------- ### Handlebars i18n syntax Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US General syntax for using i18n in Handlebars with variable arguments. ```handlebars {{i18n 'MESSAGE_ID' <var-arg param1> <var-arg param2> ... <var-arg paramN>}} ``` -------------------------------- ### Message Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines an action to return a message to the bot user. Messages are displayed in the order they are defined. ```APIDOC ## Message Action ### Description Allows returning a message to the bot user. Supports various message types including text, cards, buttons, and more. ### Configuration - **type**: "message" - **scripting_type**: <spel | handlebars> (Optional) - **message**: Object containing message details (e.g., type: text, content: string) ``` -------------------------------- ### getMonth() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the month (0-11) as interpreted in UTC. ```APIDOC ## getMonth() ### Description Returns a number representing the month that contains or begins with the instant in time represented by this Date object, as interpreted in the UTC time zone. The value returned is between 0 and 11, with 0 representing January. ### Output Integer ### Example ```javascript future.getMonth() // =0 ``` ``` -------------------------------- ### Compare Dates with compareTo Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Compares two dates and returns a value indicating their relative order. ```javascript today.compareTo(past) // >0 today.compareTo(future) // <0 today.compareTo(today) // =0 ``` -------------------------------- ### before(Date) Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Checks if the date is chronologically before the provided date. ```APIDOC ## before(Date) ### Description Checks whether a date is chronologically before the provided date. ### Parameters - **date** (Date) - Required - The date to compare against. ### Output Boolean ### Example ```javascript today.before(future) // =true ``` ``` -------------------------------- ### Define an Action Group Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Structure for defining an action group with an optional SpEL condition and a list of actions. ```yaml action_groups: - condition: <spel group condition> #optional actions: <dialog function actions> ``` -------------------------------- ### Streamed Message Action Configuration Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines the YAML structure for a streamed message action, including mandatory SSE headers. ```yaml - type: streamed-message method: <GET | POST | OPTIONS | DELETE | PUT | PATCH> system_alias: <system alias name defined in capability.sapdas.yaml> path: <url path> #optional headers: #optional <header key>: <header value> Accept: "text/event-stream" #SSE required value Connection: "keep-alive" #SSE required value Cache-Control: "no-cache" #SSE required value body: <body value> #optional response_chunk_ref: <path to chunk in streamed message request> result_variable: <result context variable> #optional ``` -------------------------------- ### Retrieve Year Component Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the year minus 1900 in UTC. ```javascript future.getYear() // =199 ``` -------------------------------- ### Retrieve Day of Week Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the day of the week (0-6) in UTC, where 0 is Sunday. ```javascript future.getDay() // =4 ``` -------------------------------- ### Merging Internationalized Strings in SpEL Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Demonstrates using .toString() when concatenating i18n helpers in SpEL to avoid type conversion errors. ```yaml - type: message message: type: text content: "ID_SAMPLE value in SPEL is <? new i18n('ID_SAMPLE').toString() ?>" ``` ```json { "level": "warning", "code": "ACTION_FAILED", "message": "Message action skipped due to invalid scripting expression in message", "data": { "warnings": [ { "invalid_expression": "ID_SAMPLE value in SPEL is <? new i18n('ID_SAMPLE') ?>", "scripting_error": "EL1001E: Type conversion problem, cannot convert from Translation to java.lang.String" } ] } } ``` -------------------------------- ### Retrieve Day of Month Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the day of the month (1-31) in UTC. ```javascript future.getDate() // =1 ``` -------------------------------- ### i18n Properties File Entry Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/handbook-for-internationalizing-capabilities?locale=en-US Definition of the localized message key using choice format for conditional text rendering. ```properties #XMSG, {1} is a person name, {2} is a person email FOUND_EMPLOYEE_WITHOUT_NAME=I found one employee {0,choice,0#matching the name you provided.|1#, {1}{2,choice,0#|1# ({2})} matching the name you provided.} ``` -------------------------------- ### POST Callback to Joule Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/asynchronous-api-request?locale=en-US Sends the result of an asynchronous task back to Joule using the target URL provided in the initial request headers. ```APIDOC ## POST [x-callback-target] ### Description Sends the result of the asynchronous task back to Joule. This must be performed within 5 minutes of the initial request. ### Method POST ### Headers - **x-correlationId** (string) - Required - The value received in the initial request header. - **x-joule-callback-request-type** (string) - Required - Must be set to "result". ### Request Body - **payload** (any) - Optional - The result data to be forwarded to the result_variable. ### Response #### Success Response (200) - Callback successfully executed. #### Error Response (400) - Callback does not meet API specification. #### Error Response (404) - No matching paused dialog found. ``` -------------------------------- ### streamed-message Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Configures an action to request data from a service supporting Server-Sent Events (SSE). ```APIDOC ## streamed-message ### Description Defines a request to a service that supports Server-Sent Events (SSE). Joule aggregates the streaming response into a final message. ### Configuration - **type**: "streamed-message" - **method**: GET | POST | OPTIONS | DELETE | PUT | PATCH - **system_alias**: System alias name defined in capability.sapdas.yaml - **path**: URL path (optional) - **headers**: Map of header keys and values (optional). Note: Accept, Connection, and Cache-Control are mandatory for SSE. - **body**: Request body (optional) - **response_chunk_ref**: Path to the chunk in the streamed message request (e.g., $.delta.content for JSON or $ for plain text) - **result_variable**: Result context variable (optional) ``` -------------------------------- ### Multiple Entities Response Context Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Use this structure for generating a list response containing multiple items with consistent field names. ```json { "latest_purchase_orders_and": [{ "Result from autosql virtual scenario latest_purchase_orders_and": { "result": [ { "CreationDate": "20260508", "DocumentCurrency": "EUR", "PurchasingOrganization": "0001", "PurchaseOrderDate": "20260508", "PurchaseOrder": "5716435679", "DocumentType": "Purchase Order", "action": "", "Supplier": "NPV_VEN2", "semanticObject": "" }, { "CreationDate": "20260508", "DocumentCurrency": "EUR", "PurchasingOrganization": "0001", "PurchaseOrderDate": "20260508", "PurchaseOrder": "5716435680", "DocumentType": "Purchase Order", "action": "", "Supplier": "AFT_GPD_VN", "semanticObject": "" } ] } }] } ``` -------------------------------- ### Check Chronological Order with after Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Determines if a date occurs after another date. ```javascript today.after(past) // =true today.after(future) // =false today.after(today) // =false ``` -------------------------------- ### Set Variables Action Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/action-group-70e471d4234b41e6b9b2b049fb0b514a?locale=en-US Defines an action to set or overwrite variables in the local context of a dialog function. ```APIDOC ## Set Variables Action ### Description Sets variables in the local context of the dialog function. Existing variables with the same name are overwritten. ### Configuration - **type**: "set-variables" - **scripting_type**: "spel" (default) | "handlebars" (optional) - **variables**: Array of objects with 'name' and 'value' keys ``` -------------------------------- ### Retrieve Unix Epoch Time Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the number of milliseconds since January 1, 1970, 00:00 GMT. ```javascript today.getTime() // equals milliseconds since start of unix epoch time past.getTime() // =0 future.getTime() // =4070961641000 ``` -------------------------------- ### Check Chronological Order with before Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Determines if a date occurs before another date. ```javascript today.before(past) // =false today.before(future) // =true today.after(today) // =false ``` -------------------------------- ### getYear() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the year minus 1900 as interpreted in UTC. ```APIDOC ## getYear() ### Description Returns a value that is the result of subtracting 1900 from the year that contains or begins with the instant in time represented by this Date object, as interpreted in the UTC time zone. ### Output Integer ### Example ```javascript future.getYear() // =199 ``` ``` -------------------------------- ### after(Date) Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Checks if the date is chronologically after the provided date. ```APIDOC ## after(Date) ### Description Checks whether a date is chronologically after the provided date. ### Parameters - **date** (Date) - Required - The date to compare against. ### Output Boolean ### Example ```javascript today.after(past) // =true ``` ``` -------------------------------- ### getSeconds() Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/date-operations?locale=en-US Returns the seconds (0-59) as interpreted in UTC. ```APIDOC ## getSeconds() ### Description Returns the number of seconds past the minute represented by this date, as interpreted in the UTC time zone. The value returned is between 0 and 59. ### Output Integer ### Example ```javascript future.getSeconds() // =41 ``` ``` -------------------------------- ### Single Entity Response Context Source: https://help.sap.com/docs/joule/joule-development-guide-ba88d1ec6a1b442098863d577c19b0c0/gen-ai-response-generation?locale=en-US Use this structure for generating a card response containing detailed information about a single department. ```json { "organization_departments/get_departments": [{ "Detailed info about a specific department": "Engineering", "Org departments use engagement_model as subtitle": [ { "code": "ENG", "organization": "Acme Corp", "name": "Engineering", "description": "Responsible for designing, developing, and maintaining the companys products and technical infrastructure.", "engagement_model": "In-house", "type": "Core" } ] }] } ```