W-18408079-Update-DW-content-with-AI-CP

modules/ROOT/pages/int-configure-dw-expressions.adoc

@@ -1,14 +1,16 @@
-= Configuring DataWeave Expressions
+= Using DataWeave Expressions and Transformations in Anypoint Code Builder
 :page-aliases: int-use-dw-to-transform-data.adoc, int-address-dw-errors.adoc, int-import-dw-libraries.adoc
+// TODO: Add "Einstein generative AI" to the appropriate topic titles.
 
-Configure DataWeave expressions in your integrations and implementations from *Expression Builder*, *Transformation Builder*, or from the configuration XML. DataWeave is the programming language designed by MuleSoft for data transformation and expressions in connector operations and other components that process messages, such as payload and attributes, and other Mule event data.
+DataWeave is the MuleSoft programming language for data transformation and for defining expressions. Use DataWeave to process Mule event data, such as `payload`, `attributes`, and `vars`, in connector operations and other components. Develop DataWeave expressions and transformations in your Mule applications using the *Expression Field*, *Expression Builder*, *Transformation Builder*, or by editing the configuration XML. Generate DataWeave transformations with AI assistance by providing input and output sample data or metadata.
 
+//TODO: Take a new screenshot with the new UI.
 image::int-dw-transform-ui.png["The *Expression Field*, *Expression Builder*, and *Transformation Builder* button location highlighted in a component"]
 
 [calloutlist]
 . *Expression Field*: Enter a DataWeave expression or script in a component configuration panel.
 . *Expression Builder*: Simplify and enhance the process of creating and managing expressions within your Mule applications.
-. *Transformation Builder*: Create DataWeave transformations in your Mule applications in a visual interface.
+. *Transformation Builder*: Create DataWeave transformations in your Mule applications in a visual interface assisted by AI.
 
 If you create an implementation or integration in Anypoint Code Builder, you create a Mule app that runs on an instance of the Mule runtime engine. 
 
@@ -31,28 +33,27 @@ Anypoint Code Builder supports these transform mapping use cases:
 * Concatenation of simple fields
 * `Array` to `Array` (same level)
 
-// TODO: The following images should be replaced with the new UI:
-// int-dw-fx-field-autocomplete.png
-// int-dw-fx-preview-tab-output.png
-// int-dw-sample-quick-fix-example-preview.png
-// int-dw-sample-quick-fix-example-preview-modified.png
-
+[[prereq-dw-transforms]]
 == Before You Begin
 
-Understand the basics of the DataWeave language. 
+* Understand the functions, operators, variables, and selectors of DataWeave expressions.
++
+xref:dataweave::dw-functions.adoc[DataWeave functions and operators], and data types that their parameters accept. For example, the concatenation function (xref:dataweave::dw-core-functions-plusplus.adoc[]) accepts strings, arrays, objects, and date-related data types. 
 
-DataWeave expressions accept the following: 
+* Review the built-in documentation for functions the IDE provides. For example, see <<tab-functions>>.
 
-* xref:dataweave::dw-functions.adoc[DataWeave functions and operators] and data types that their parameters accept.
-+
-For example, the concatenation function (xref:dataweave::dw-core-functions-plusplus.adoc[++]) accepts strings, arrays, objects, and date-related data types. 
-+
-The IDE also provides built-in documentation for functions. For example, see <<tab-functions>>.
-* xref:dataweave::dataweave-variables-context.adoc[Predefined Mule event variables] such as `payload`, `attributes`, `vars`.
-* xref:dataweave::dataweave-selectors.adoc[DataWeave selectors] for capturing the values of fields within the payload, an attribute, or a variable within the xref:mule-runtime::about-mule-event.adoc[Mule event]. 
+** xref:dataweave::dataweave-variables-context.adoc[Predefined Mule event variables] such as `payload`, `attributes`, `vars`.
 
+** xref:dataweave::dataweave-selectors.adoc[DataWeave selectors] for capturing the values of fields within the payload, an attribute, or a variable within the xref:mule-runtime::about-mule-event.adoc[Mule event]. 
++
 For more resources, see xref:dataweave::index.adoc[]. 
 
+* Ensure that you have these permissions to use the Anypoint Code Builder Agentforce feature:
+** Anypoint Code Builder Developer
+** Mule Developer Generative AI User
+
+* Enable Einstein in Access Management. For more information, see xref:access-management::enabling-einstein.adoc[Enabling Einstein for Anypoint Platform].
+
 [[open-fx-field]]
 == Open the Expression Field 
 
@@ -64,7 +65,7 @@ To open a component expression field (*fx*):
 +
 . Click *fx* to change the field from a string field to an expression field.
 +
-image::int-dw-fx-field-set-variable.png["Expression (fx) field in the *Set Variable* component"]
+image::int-dw-fx-field-set-variable.png["Expression field (fx) in the *Set Variable* component"]
 +
 The markup `#[]` in the *fx* field also appears in the XML to indicate that the field is for an expression.
 +
@@ -75,13 +76,15 @@ The markup `#[]` in the *fx* field also appears in the XML to indicate that the
 . Click the *Expression Builder* button to configure the component.
 +
 image::int-dw-fx-expression-builder.png["*Expression Builder* for the `Set Variable` component"]
+// TODO: Take a new screenshot with the new UI.
 +
 Use the *Data*, *Functions*, and *Preview* tabs to ease configuration of expressions in your components. Preview the expression output without the need to run your Mule app with data from external sources:
 
 * <<tab-data>>
 * <<tab-functions>>
 * <<tab-preview>>
 
+[[open-expression-builder]]
 == Open Expression Builder
 
 *Expression Builder* simplifies the process of creating and managing expressions within your Mule applications. The builder provides a visual interface to create DataWeave expressions and transformations.
@@ -101,26 +104,27 @@ image:int-dw-fx-data-tab.png["Data tab for expression field"]
 image:int-dw-fx-data-tab-attributes.png["Data tab for expression field with mock attributes"]
 |===
 
-Any autogenerated strings (such as "dictum" in the payload example) are displayed as mock values and are used to generate output for previews, such as in the <<tab-preview, Preview tab>>. The attribute metadata keys in the example come from an HTTP Listener configuration in the flow.
+Any autogenerated strings (such as "dictum" in the payload example) are displayed as mock values and are used to generate output for previews, such as in the <<tab-preview, Preview>> tab. The attribute metadata keys in the example come from the configuration of an `HTTP Listener` component in the flow.
 
 The *Input/Output* tab in component configuration panels provides the structure of the Mule event data as it enters the component (*Input*) and the structure that the component outputs (*Output*), for example:
 
+// TODO: Review this screenshot. It's too large for the page.Seems some padding is missing.
 image:int-dw-fx-input-output-sample.png["Input/Output tab for a component"]
 
 [[tab-functions]]
 === List DataWeave Functions and Get Documentation
 
 To get a list of available functions from a component's *Functions* tab, the *fx* field, or the auto-complete menu in the XML editor:
 
-. Open a component that has an *fx* expression field. 
+. Open a component that has the *fx* expression field. 
 +
 For guidance, see <<open-fx-field>>.
 . List available functions:
 
 * To display a list of DataWeave functions from the Core module from an empty *fx* field, press Ctrl+Space in an _empty_ *fx* field. For example:
 +
 image::int-dw-fx-field-autocomplete.png["*Expression Builder* for the `Set Variable` component"]
-* To display functions from all xref:dataweave::dw-functions.adoc#dw_modules[DataWeave modules], such as String, Array, and Core modules:
+* To display functions from all xref:dataweave::dw-functions.adoc#dw_modules[DataWeave modules], such as `String`, `Array`, and `Core` modules:
 
 .. Click the *fx* field to open *Expression Builder*. 
 .. Click the *Functions* tab.
@@ -181,15 +185,79 @@ image::function-validation-run-preview.png["Run Preview"]
 
 Anypoint Code Builder opens a new *Preview Output* tab with the result of the function:
 
-image::dataweave-function-preview-output.png["Preview Output tab]
+image::dataweave-function-preview-output.png["Preview Output tab"]
 
+[[open-transformation-builder]]
 == Open Transformation Builder
 
-Create DataWeave transformations in your Mule applications with the *Transformation Builder* tool.
+Create DataWeave transformations in your Mule applications with *Transformation Builder*, assisted by Einstein generative AI. Provide input and output sample metadata or data to generate DataWeave scripts.
 
+// TODO: Take a new screenshot with the new UI.
 image::int-dw-transform-builder-ui.png["The *Transformation Builder* window and its sections highlighted"]
 
-. Click on *Transformation Builder*.
+On *Transformation Builder*, choose the option that best suits your needs:
+
+* <<map-with-ai, Map with AI>>
+* <<map-and-transform-with-ai, Map and Transform with AI>>
+
+[[considerations-for-transformation-builder-with-ai]]
+=== Considerations for AI-Assisted Transformations
+
+When using AI-assisted transformations, consider the following:
+
+* Metadata provides the shape of the ‌output.
+* Sample data provides the context to generate functions or expressions for calculations, conditions, etc. WSDL files can be provided with sample data. See <<sample-data>> for supported data formats (MIME types) for sample data.
+* Valid data is required for the AI to create the transformation script. Write it manually if needed.
+* AI chat history isn't available in *Transformation Builder*.
+
+[[map-with-ai]]
+=== Map with AI
+
+Get an automatic field-to-field mapping when accessing *Transformation Builder*. The mapping starts automatically considering the sample data provided. 
+
+If you don't have access to *Map with AI*, you must:
+
+* Review that the provided input and output metadata are valid.
+* Ensure your configuration meets the prerequisites for using AI-assisted transformations. See <<prereq-dw-transforms>>.
+
+// TODO: Add a screenshot of the "Map with AI" button.
+. Open your Mule project.
+. Select a component that has a *fx* field.
+. Open *Transformation Builder*.
++ 
+The mapping starts automatically considering the sample data provided. The mapping is applied to the XML file.
+. After the mapping is complete, you must:
+.. Click *Apply Mapping* to apply suggested mapping to your project.
+.. Click *Revise Mapping* to get new suggestions from the AI.
+
+[[map-and-transform-with-ai]]
+=== Map and Transform with AI
+
+Create a DataWeave transformation script assisted by AI. Provide input and output sample data, the input and output metadata, and optional instructions to guide the AI.
+
+. Open your Mule project.
+. Select a component that has a *fx* field.
+. Open *Transformation Builder*.
++
+The mapping starts automatically considering the data provided. The mapping is applied to the XML file.
+. Click on *Map and Transform with AI*.
+. Provide this information if needed, or modify it as needed:
+* Input sample data 
+* Output sample data 
+* Optional instructions to guide the AI 
+. Click on *Transform*.
++
+Einstein AI analyzes your input and output samples, and the instructions -if any-, to generate DataWeave script suggestions that aim to perform the suggested transformation. 
+. Click *View Suggested Scripts* to insert one if appropriate, or copy the suggested script to the clipboard without losing its format.
++
+After inserting a script, the XML file is updated, and you can regenerate the script by clicking *Regenerate*.
+
+//TODO: Make sure we want to show this path to the user.
+[[manually-add-data-sources-targets]]
+=== Manually Adding Data Sources and Targets
+
+You can manually add data sources and targets to your transformation script.
+
 . In the *Transformation Workspace* section, drag the source field from the input payload to the target field to map the source data to the target data.
 +
 The mapped fields display a green dot and are highlighted to indicate that the mapping is successful. The *Script* section updates with the new mapping, and the *Output Preview*"* section displays the output of the transformation.
@@ -200,18 +268,31 @@ If needed, map multiple source field to a target field, and then the Transform B
 +
 You can select the generated sample or provide your own <<sample-data, sample data>>.
 
-// TODO: See if the supported use cases can be added or if such an info is already covered by DW docs. If ACB only supports a subset of DW features, then we should mention that here.
+// TODO: Add information about understanding and using generated transformations, including explanations, inserting/copying scripts, regenerating, and providing feedback.
+
+// TODO: Add a "Considerations" section for AI-assisted transformations, including details on metadata vs. sample data, supported MIME types, loading indicators, inability to change sample data during generation, cancellation, and the number of generated options.
+
+// TODO: Add a "Considerations on PII and Validations" section, warning against using PII and explaining how generated transformations are validated.
 
 [[sample-data]]
 == Provide Sample Data for a DataWeave Expression
 
-Test and preview DataWeave expressions locally in Anypoint Code Builder. Add sample data for Mule variables such as `payload` in *fx* fields to preview outputs without running your application.
+Test and preview DataWeave expressions locally in Anypoint Code Builder. Add sample data for Mule variables such as `payload` in *fx* fields to preview outputs without running your application. For AI-assisted transformations, providing sample input and output data helps AI understand the desired transformation and generate accurate DataWeave scripts.
 
 You can create sample data in the following formats:
 
 * JSON
 * XML
 * CSV
+* Java
+* Text
+* YAML
+* Avro
+* Excel
+* NDJSON
+* URL Encoded
+* Protobuf
+* Multipart
 
 [[important]]
 [IMPORTANT]