Installing and Using the DataWeave Extension | MuleSoft Documentation
# Installing and Using the DataWeave Extension
Install and use DataWeave extension in Visual Studio Code (DataWeave extension) to develop, preview, test, and deploy custom mappings and modules into libraries in a DataWeave project. The extension also enables you to preview transformations similar to those you perform in the DataWeave Playground.
## Before You Begin
Before installing the DataWeave extension to Visual Studio Code, you must:
  * Install AdoptOpenJDK
  * Install Apache Maven (3.6.3 minimum)
  * Install Microsoft Visual Studio Code for your specific operating system


If you have any other prior extensions for DataWeave, whether experimental or from a third party, uninstall them.   
---  
## Install the DataWeave Extension
To install the extension:
  1. Open Visual Studio Code.
  2. In the **EXTENSIONS** tab, type `dataweave` to search the extension in the marketplace.
  3. Select **Anypoint Code Builder - DataWeave Extension** from the search results.


  5. After the installation finishes, restart Visual Studio Code.


## Developing DataWeave Libraries
A DataWeave library is a reusable package of DataWeave module and mapping files, and resource files, such as JSON, XML, and CSV. To develop DataWeave libraries, first create a new DataWeave project in Visual Studio Code where you then create, preview, and test custom mappings and modules.
If you want to try out your mapping without creating a DataWeave project, you can either open your `.dwl` mapping file directly in Visual Studio Code or create a new one and use sample data and scenarios.
### Understanding the DataWeave Project Structure
DataWeave projects use Apache Maven to build and declare project dependencies. The following diagram shows the DataWeave project structure:
```
├── src
│  ├── main
│  │  ├── dw // Put your DataWeave mappings and module files here
│  │  │  ├── MyMapping.dwl
|  |  |  └── MyModule.dwl
│  │  └── resources
│  └── test
│    ├── dw
│    │  └── MyModuleTest.dwl //Unit tests for the functions in your module
│    │  └── MyMappingTest.dwl //Integration test for your mapping using the saved scenarios
│    ├── resources
│    │    └── MyMapping //Contains the different scenarios for your mapping
│    │      ├── default
│    │      │  └── inputs
│    │      │    └── payload.json //[Sample data](#sample-data) for your mappings
│    │      └── SavedTestScenario //Scenario used for the integration test
├── pom.xml
```

### Create a DataWeave Project
To create a new project:
  1. Open Visual Studio Code.
  2. Click **View > Command Palette**.
  3. In the search bar, type `dataweave`.
  4. Select **DataWeave: Create New Library Project**.
  5. Follow prompts to complete an initial configuration for your project:
    1. **Organization ID** (Group ID)
    2. **Artifact ID**
    3. **Project name**
  6. Choose a directory folder for your new project.
  7. Select **OK**.
  8. When prompted, select **Yes** or **No** whether you want to open the project in a new Visual Studio Code window.


The following image shows a new DataWeave project in Visual Studio Code:
When creating a DataWeave project, the DataWeave extension requires all dependencies to be loaded and indexed before it can search the libraries and make them available in your project. Visual Studio Code provides a notification bar at the bottom of the screen editor that shows when the dependencies are loading and when the indexing is complete.
## Create a DataWeave Module
DataWeave modules are `.dwl` files that define functions, variables, types, and namespaces. These files cannot contain output directives, body expressions, or `---` separators between header and body sections. A DataWeave module enables you to share all the content defined in the `.dwl` file for reuse.
To create a new DataWeave module:
  1. In Visual Studio Code, click **View > Command Palette**.
  2. In the search bar, type `dataweave`.
  3. Select **DataWeave: Create New Module**.
  4. Add a name for the new module `dwl` file and press enter. This creates a new module `.dwl` file under the `src/main/dw` folder.


## Preview a DataWeave Module
For a better development experience, you can use the _preview_ view to develop your module’s functions. The _preview_ view lets you get instant feedback on how a mapping file is working by previewing its output. Use this view to develop the module’s functions by creating a DataWeave mapping inside the `src/test/dw` folder that imports your functions and calls them to check how they’re currently working.
To preview the module functionality, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Select your module `.dwl` file.
  4. Click the **Create Integration Mapping** button located at the top of your module `.dwl` file. This create a mapping file under the `src/test/dw` folder to test your module, which isn’t meant to be shared or reused.


  5. Either preview the module function by one of these options:
     * Click the **DataWeave: Run Preview** button (arrow icon) at the top right corner of your module `.dwl` file.
     * Right-click the editor and select **DataWeave: Enable AutoPreview** to run it on every file change.


## Test a DataWeave Module
There’re two ways to test your module:
  * By running a unit test
  * By creating a test mapping located in your `src/test/dw` folder to avoid exposing the test to consumers of your module


The tests use functions of the modules `dw::test::Tests` and `dw::test::Asserts` provided by the artifact `org.mule.weave:data-weave-testing-framework` of the DataWeave Testing Framework.
To generate a unit test for a DataWeave module, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Select your module `.dwl` file.
  4. In your module `.dwl` file, click the **Add Unit Test** button located above your function.


This behavior generates:
  * A new `.dwl` test file in `src/test/dw` that describes test cases and tests suites for the module.
    * A test case is a single test with the evaluation and assertion of the result.
    * A test suite groups tests with a name that better describes the intention of some related cases.
The test file defines a test case for the function that you call with specific arguments and use to make assertions over the output.
  * A new test case within a test suite for the function. If not present, the test suite is also created.


To run the test:
  1. In Visual Studio Code, go to the **TESTING** view.
  2. Select the dropdown arrows of your module test file.
  3. Click the **Run Test** arrow button.


## Create a DataWeave Mapping
A DataWeave mapping is a `.dwl` file that enables you to map and connect to anything, regardless of data type or structure. As when using a DataWeave module, you can use a mapping to define functions, variables, types, and namespaces, but you can additionally specify a body section after the separator `---`.
Unlike a DataWeave module file, a DataWeave mapping file is an executable unit that enables you to transform zero or more inputs into a single output. Using the DataWeave extension, you can develop these files to create reusable assets that you can deploy and share with others.
To create a new DataWeave mapping, follow these steps:
  1. In Visual Studio Code, click **View > Command Palette**.
  2. In the search bar, type `dataweave`.
  3. Select **DataWeave: Create New Mapping**.
  4. Add a name for the new mapping `dwl` file and press enter. This creates a new mapping `.dwl` file under the `src/main/dw` folder.


### Define Sample Data for DataWeave Mappings
Generate multiple sample data inputs for your mapping by clicking the **Define Sample Data** button at the top of your mapping `.dwl` file. Sample data is a key part of DataWeave project development to run your mappings.
To define sample data, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Select your mapping `.dwl` file.
  4. Click the **Define Sample Data** button located above your mapping `.dwl` file.
  5. Specify the name for the sample data file and press enter.
### Define Sample Data for DataWeave Mappings
Generate multiple sample data inputs for your mapping by clicking the **Define Sample Data** button at the top of your mapping `.dwl` file. Sample data is a key part of DataWeave project development to run your mappings.
To define sample data, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Select your mapping `.dwl` file.
  4. Click the **Define Sample Data** button located above your mapping `.dwl` file.
  5. Specify the name for the sample data file and press enter.


Using sample data generates a DataWeave _scenario_ that contains all the resources required to run the mapping in the context of that scenario.
## Understanding DataWeave Scenarios
A DataWeave _scenario_ is a group of inputs and outputs that you can inject into your mapping either to try out in the **Preview Output** view or to test your mapping using the input to evaluate it and compare its output with the desired saved output of your scenario. Scenarios also provide autocompletion based on the input structures.
These scenarios and their resources live in the `src/test/resources` folder and have the following structure:
```
├── src/test/resources
│    └── MyMapping //Contains the different scenarios for your mapping called "MyMapping"
│      ├── default //Name of your scenario
│      │  └── inputs //Folder where all of your inputs live
│      │  │  └── payload.json //Input for your mapping (you can use it in your script, naming it to be the same as the name of the file without the file's extension)
│      │  │  └── vars //Folder that represents a name for your input variable in your script: in this case vars
│      │  │    └── test.json //Input for your mapping (you can use it in your script, calling it vars.test)
│      │  └── out.json // Expected output of your mapping running against your inputs (only present when testing)
│      └── SavedTestScenario //Another scenario used for the integration test
```

### Using the DataWeave Scenarios View
The **DATAWEAVE SCENARIOS** view shows the available scenarios for the `.dwl` file. In this view, you can add, remove, or set the active scenario that is used for your preview execution, or you can choose that the values be autocompleted.
### Using Reader Properties for Inputs
If you want to set different reader properties to the inputs you use, create a properties file with the suffix `{fileName}-config.properties` in the same directory of your input. For example, if your input is called `payload.csv` then create a `payload-config.properties` file that contains all the reader properties required to run your scenario. Creating the properties file also applies while testing your DataWeave mappings.
## Preview a DataWeave Mapping
After you define sample data, get feedback on how your mapping is working by previewing the output.
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Select your module `.dwl` file.
  4. Either preview the mapping function by one of these options:
     * Click the **DataWeave: Run Preview** button (arrow icon) at the top right corner of your mapping `.dwl` file.
     * Right-click the editor and select **DataWeave: Enable AutoPreview** to run it on every file change.


## Run and Debug a DataWeave Mapping
Run and debug a DataWeave mapping to be guided through all of the mapping elements, which you can then fix or otherwise update. You can also set breakpoints to stop evaluating expressions and use all the debugging capabilities that Visual Studio Code provides. Debugging works on mapping tests as well.
To run and debug a DataWeave mapping, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Select your mapping `.dwl` file.
  4. Click the **Run Mapping** button located at the top of your `.dwl` file.


## Test a DataWeave Mapping
To test a DataWeave mapping, click the **Dataweave: Create Mapping Test** button located at the top of your `.dwl` file to create a new test scenario from a snapshot of your input and your current output. You can also use this newly created scenario as a normal scenario for your preview or autocompletion.
To test a DataWeave mapping, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Click the **DataWeave: Create Mapping Test** button (microscope icon) located at the top of your mapping `.dwl` file.
  4. Specify a name for the mapping test and press enter.


This creates a new mapping test `.dwl` file:
## Using the DataWeave Dependencies View
The **DATAWEAVE DEPENDENCIES** view shows all the dependencies resolved for a DataWeave project. The view enables you to navigate through all of your project’s dependencies and open DataWeave files inside those dependencies.
## Deploy DataWeave Libraries
Before deploying your DataWeave library to Anypoint Exchange, generate documentation for your mapping or module functions. When you deploy your DataWeave library to Exchange, the documentation is also published to the Exchange library page.
To generate documentation for the functions, follow these steps:
  1. In Visual Studio Code, open your DataWeave project.
  2. Navigate to the `src/main/dw` folder.
  3. Click the **Generate Weave Documentation** button located at the top of the function in the `.dwl` file.


The documentation template appears as a comment above the function:
To deploy a DataWeave library to Exchange:
  1. In Visual Studio Code, open your DataWeave project.
  2. Open and configure your `pom.xml` file.
    1. Ensure that your `groupId` is set to your `organization ID`.
    2. Add the Maven facade as a repository within the `<distributionManagement>` element.


  3. Update the `settings.xml` file in your Maven `.m2` directory with your Anypoint Platform credentials.
For guidance, refer to the Publish an Asset to Exchange Using Maven documentation.


  4. Execute the Maven `deploy` command to upload the DataWeave library to the deployment target and the auto-generated documentation to Exchange.
For guidance, refer to the DataWeave Maven Plugin documentation.


## Consume DataWeave Libraries
After deploying your DataWeave library to Exchange, the library appears as an asset for your organization in the Exchange marketplace.
To consume the DataWeave library:
  1. Add the library’s group ID, artifact ID, version, and classifier to the `dependencies` element in your project’s `pom.xml` file.
You can copy the dependency snippet from Exchange.
  2. Add the Maven facade as a repository in the `repositories` section.


For more details, refer to the Publish and Consume Federated Assets documentation.
## DataWeave Extension Language Edition Features
The Language Edition features of the DataWeave extension include completion, navigation, code editing, and code inspection.
### Completion
The completion feature enables you to autocomplete content for any visible functions, variables, or types. The feature also suggests fields based on the type inference.
### Navigation
You can navigate to any local definition or from any imported library.
### Code Editing Features
The following features help you to easily code in Visual Studio Code:
  * Find all references
  * Refactors (local and cross files)
  * Quick fixes:
    * Auto import when a function is present in a module
    * Create a function, variable, or type when one isn’t found
  * Outline
  * Show parameters information
  * Hover information with documentation


### Code Inspections
The DataWeave extension tries to detect and suggest replacements for idioms in expressions, as shown in the following examples:
  * Default Value


## DataWeave Extension Troubleshooting Logs
If an error occurs while you’re working with the DataWeave Extension, check the logs output of the DataWeave Language Server that provide details of what can cause the issue:
To check the logs, follow these steps:
  1. In Visual Studio Code, navigate to **View > Output** to open the **OUTPUT** view in the Visual Studio Code editor window.
  2. In the drop-down menu located on the left of the screen editor, select **Mule DX DataWeave LS** to show the logs.


## See Also
  * DataWeave Extension
  * DataWeave Maven Plugin
  * DataWeave Testing Framework