Merge pull request #582 from mulesoft/W-21202212-DataWeave-enhancement-for-Feb-17-CP

W-21202212-Add-DW-enhancements-CP

Author: Crispy-Salesforce

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

@@ -1,7 +1,7 @@
 = 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
 
-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*, or *Transformation Builder*, or by editing the configuration XML. Generate DataWeave transformations with AI help by providing input and output sample data, metadata, or both.
+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*, or *Transformation Builder*, or by editing the configuration XML. Generate DataWeave transformations with AI help by providing input and output sample data, metadata, or both. AI-powered auto mapping provides comprehensive error feedback for GenAI actions, including authorization, metadata, and request limits, ensuring a more reliable and guided mapping experience.
 
 image::int-dw-transform-ui.png["A configuration panel showing three numbered callouts: 1) fx button for Expression Field, 2) Expression Builder button, and 3) Transformation Builder button"]
 
@@ -105,7 +105,7 @@ 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"]
 |===
 
-Automatically generated strings 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 IDE shows the automatically generated strings as mock values and uses them 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 shows the structure of data entering (*Input*) and exiting (*Output*) components. For example:
 
@@ -121,7 +121,7 @@ To get a list of available functions from a component *Functions* tab, the *fx*
 For guidance, see <<open-fx-field>>.
 . List available functions:
 
-* To show a list of DataWeave functions from the Core module from an empty *fx* field, press Ctrl+Space in an _empty_ *fx* field. For example:
+* To show 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["DataWeave autocomplete dropdown menu showing available Core module functions like abs, avg, ceil, and floor with their descriptions"]
 * To show functions from all xref:dataweave::dw-functions.adoc#dw_modules[DataWeave modules], such as `String`, `Array`, and `Core` modules:
@@ -206,15 +206,18 @@ If using AI-assisted transformations, evaluate these considerations:
 
 * To generate a DataWeave script using *Map and Transform with AI*, provide input and output samples. While optional, providing metadata helps AI understand the data structure and improves the accuracy of the transformation.
 * Sample data provides the context to generate functions or expressions for calculations, conditions, and other operations. You can provide Web Services Description Language (WSDL) files with sample data. See <<sample-data>> for supported data formats (MIME types) for sample data.
-* For automatic field-to-field mapping using *Map with AI*, provide both input and output metadata. *Map with AI* works only if no DataWeave script exists in the component.
+* For field-to-field mapping using *Map with AI*, provide both input and output metadata. Use *Map with AI* even when a DataWeave script is already present in the component. Click *Map with AI* to trigger it.
 * AI requires valid data to create the transformation script. Write it manually if needed.
 * AI chat history isn't available in *Transformation Builder*.
 * Avoid using real personally identifiable information (PII) in sample data or AI inputs. Provide input and output sample data that contains only fictional or masked data.
+* AI-assisted transformations provide comprehensive error feedback for GenAI actions. If you encounter errors related to authorization, metadata, or request limits, the error messages guide you to resolve the issue. See <<troubleshoot-ai-assisted-transformations>> for detailed troubleshooting steps.
 
 [[map-with-ai]]
 === Map with AI
 
-The *Map with AI* feature automatically suggests a field-to-field mapping. This feature requires you to provide both input and output metadata for the component and triggers only when no DataWeave script is present. It performs auto-mapping based on the provided metadata.
+The *Map with AI* feature suggests a field-to-field mapping using AI-powered auto mapping. Click *Map with AI* to trigger it. Use it even when a DataWeave script is already present in the component. Provide both input and output metadata for the component. Mapping is performed based on the metadata you provide.
+
+*Map with AI* provides comprehensive error feedback for GenAI actions, including authorization errors, metadata issues, and request limits. If you encounter errors during the mapping process, see <<troubleshoot-ai-assisted-transformations>> for detailed guidance on resolving specific error types.
 
 If you don't have access to *Map with AI*, you must:
 
@@ -227,11 +230,9 @@ If you don't have access to *Map with AI*, you must:
 +
 image::int-map-with-ai.png["Transformation Builder showing 'Fetching metadata' status message with loading indicator for AI-assisted mapping functionality"]
 +
-The mapping starts automatically considering the sample data provided. 
-+
-The mapping is applied to the XML file.
+. Click *Map with AI* to start the mapping. Provide both input and output metadata if not already provided.
 +
-The *Preview* tab shows the output of the transformation.
+The mapping is applied to the XML file, and the *Preview* tab shows the output of the transformation.
 . 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.
@@ -265,11 +266,97 @@ After inserting a script, the XML file is updated, and you can regenerate the sc
 [[troubleshoot-ai-assisted-transformations]]
 === Troubleshoot AI-Assisted Transformations
 
-If you have issues with the AI-assisted transformations, follow these steps:
+AI-assisted transformations in *Transformation Builder* provide comprehensive error feedback to help you resolve issues. Error messages indicate the type of error and provide guidance to resolve it.
+
+If you encounter errors when using AI-assisted transformations, identify the error type and follow the corresponding resolution steps:
+
+* <<troubleshoot-authorization-errors, Authorization Errors>>
+* <<troubleshoot-metadata-errors, Metadata Errors>>
+* <<troubleshoot-request-limit-errors, Request Limit Errors>>
+* <<troubleshoot-general-ai-errors, General AI Errors>>
+
+[[troubleshoot-authorization-errors]]
+==== Authorization Errors
+
+Authorization errors occur when your Anypoint Platform account lacks the required permissions or when Einstein generative AI isn't properly configured for your organization.
+
+If you receive an authorization error:
+
+. Verify that you are logged in to Anypoint Platform from Anypoint Code Builder.
++
+For more information, see xref:start-acb.adoc#log-in-to-anypoint-platform-from-the-ide[Log in to Anypoint Platform from the IDE].
+. Contact your Anypoint Platform organization administrator to verify:
++
+* You have the *Mule Developer Generative AI User* permission assigned in Anypoint Platform access management.
+* Einstein generative AI is enabled for your organization. For more information, see xref:access-management::enabling-einstein.adoc[Enabling Einstein for Anypoint Platform].
+* You have accepted the terms and conditions for using Einstein generative AI.
+* Your Anypoint Platform organization is current and active.
+. If you are the organization administrator, verify that:
++
+* The Salesforce organization connected for requests has generative AI enabled.
+* The Salesforce organization has an xref:access-management::trusted-salesforce-org.adoc[established tenant relationship] with your Anypoint Platform organization, and the connection is enabled.
+* The Salesforce organization is valid and not expired or disabled.
+
+[[troubleshoot-metadata-errors]]
+==== Metadata Errors
+
+Metadata errors occur when the input or output metadata provided to *Map with AI* or *Map and Transform with AI* is invalid, missing, or improperly structured.
+
+If you receive a metadata error:
+
+. Verify that both input and output metadata are provided when using *Map with AI*.
++
+*Map with AI* requires both input and output metadata to perform automatic field-to-field mapping.
+. Check that your metadata structure is valid:
++
+* Ensure the metadata follows the expected schema format.
+* Verify that required fields are present in the metadata.
+* Confirm that data types match between input and output metadata where applicable.
+. Review the metadata source:
++
+* If metadata is generated from sample data, verify that the sample data structure is correct.
+* If metadata is imported from an API specification, verify the specification is valid and complete.
+* Refresh metadata by clicking *More Actions* in *Transformation Builder* and selecting *Refresh metadata*.
+. For *Map and Transform with AI*, verify that:
++
+* Input sample data is provided and valid.
+* Output sample data is provided and valid.
+* Sample data formats match the expected MIME types. See <<sample-data>> for supported formats.
+
+[[troubleshoot-request-limit-errors]]
+==== Request Limit Errors
+
+Request limit errors occur when you exceed the rate limits for GenAI API requests. These limits help ensure fair usage and system stability.
+
+If you receive a request limit error:
+
+. Wait before retrying your request:
++
+* The error message indicates when you can retry the request.
+* Avoid making multiple rapid requests in succession.
+. Reduce the frequency of AI-assisted transformation requests:
++
+* Batch multiple transformations when possible.
+* Use manual mapping for simple transformations to reduce API calls.
+. Contact your Anypoint Platform organization administrator if:
++
+* Request limits are consistently reached during normal usage.
+* You must understand your organization's specific rate limits.
+. Consider alternative approaches:
++
+* Use *Manually Adding Data Sources and Targets* for straightforward mappings. See <<manually-add-data-sources-targets>>.
+* Write DataWeave scripts manually for complex transformations that don't require AI assistance.
+
+[[troubleshoot-general-ai-errors]]
+==== General AI Errors
+
+If you encounter other errors with AI-assisted transformations:
 
 . Log in to Anypoint Platform and try again.
-. Ask your Anypoint Platform admin to verify that generative AI is enabled for your organization.
-. If you're logged in to Anypoint Platform, and your organization has access to Einstein generative AI, accept the terms and conditions for using Einstein generative AI.
+. Verify that your Anypoint Platform organization has access to Einstein generative AI.
+. Ensure you have accepted the terms and conditions for using Einstein generative AI.
+. Check your network connection and try again.
+. If the error persists, contact your Anypoint Platform organization administrator or MuleSoft support.
 
 [[manually-add-data-sources-targets]]
 === Manually Adding Data Sources and Targets