---
schema_version: "1"
id: 9a40e65717af74414e9b1f64c87e618044e81275a593fb999549a17c0ac06535
title: Create Custom Modules and Mappings
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/dataweave/2.6/dataweave-create-module.md
canonical_url: https://docs.mulesoft.com/dataweave/2.6/dataweave-create-module
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 8ef0072d278430496b4cc3ef44f5117b986209a02a0372fcecc0d6598ebb5c3d
description: MuleSoft Documentation Site
release: "2.6"
latest: false
---
---
product: DataWeave
version: 2.6
keywords: studio, anypoint, esb, transform, transformer, format, aggregate, rename, split, filter convert, xml, json, csv, pojo, java object, metadata, dataweave, data weave, datamapper, dwl, dfl, dw, output structure, input structure, map, mapping
---

# Create Custom Modules and Mappings

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

In addition to using the built-in DataWeave function modules (such as [dw::Core](https://docs.mulesoft.com/dataweave/2.6/dw-core) and
[dw::Crypto](https://docs.mulesoft.com/dataweave/2.6/dw-crypto)), you can also create and use custom modules and mapping files. The examples
demonstrate common data extraction and transformation approaches.

You write modules and mapping files in a DataWeave Language (`.dwl`) file and import into your Mule
app through DataWeave scripts in Mule components. Both modules and mapping files are useful when you
need to reuse the same functionality or feature over and over again.

- Custom modules can define functions, variables, types, and namespaces. You can import these
  modules into a DataWeave script to use the features.

- Custom mapping files are a type of module that contains a complete DataWeave script that you can
  import and use in another DataWeave script or reference in a Mule component.

Fields in many Mule connectors and components accept DataWeave expressions and scripts.

Note that if you want to import and use a built-in DataWeave function module, and not a custom one,
see [DataWeave Function Reference](https://docs.mulesoft.com/dataweave/2.6/dw-functions).

## Creating and Using DataWeave Mapping Files

You can store a DataWeave transformation in a `.dwl` mapping file (mapping module), then import the
file into another DataWeave script. Mapping files can be executed through the Transform Message
component, or you can import them into another mapping and execute them through the `main` function.

![A DataWeave script with a function to capitalize keys and map payload values](/mulesoft/current/en-us/dataweave/2.6/_images/dataweave-mapping-file.png)

Figure 1. Example: DataWeave Mapping File in a Studio Project

1.  In your Studio project, set up a subfolder and file for your mapping module:

    - You can create a subfolder in `src/main/resources` by navigating to New → Folder →
      \[your\_project\] → `src/main/resources`, then adding a folder named `modules`.

    - You can create a new file for your module in that folder by navigating to New → File →
      \[your\_project\] → `src/main/resources/modules`, then adding a DWL (DataWeave language) file
      such as `MyMapping.dwl`.

      Saving the module within `src/main/resources` makes it accessible for use in any DataWeave
      script within the Mule app in that project.

2.  Create your function in your mapping file, for example:

    Example: Mapping File Content

    ```dataweave
    %dw 2.0
    import dw::core::Strings
    fun capitalizeKey(value:String) = Strings::capitalize(value) ++ "Key"
    ---
    payload mapObject ((value, key) ->
        {
          (capitalizeKey(key as String)) : value
        }
      )
    ```

3.  Save your DWL function module file.

### Using a Mapping File in a DataWeave Script

To use a mapping file, you need to import it into a DataWeave script and use the `main` function to
access the body of the script in the mapping file.

Assume that you have created the [MyMapping.dwl](#mapping_file) file in
`/src/main/resources/modules` that contains this script.

To import and use the body expression from the `MyMapping.dwl` file (above) in DataWeave Mapping
file, you need to do this:

- Specify the `import` directive in the header.

- Invoke the `MyMapping::main` function. The function expects an input that follows the structure of
  the input that the mapping file uses. For example, the body of `MyMapping.dwl` expects an object
  of the form `{"key" : "value"}`.

Example: Importing and Using the Mapping in a DataWeave Script

```dataweave
%dw 2.0
import modules::MyMapping
output application/json
---
MyMapping::main(payload: { "user" : "bar" })
```

Here is the result:

Output

```json
{
  "UserKey": "bar"
}
```

Even though the [capitalizeKey](#mapping_file) function is private, it is still used through the
`main` function call, and the DataWeave mapping file is also able to import and reuse the
`dw::core::Strings` module.

## Creating and Using a Custom Module

The steps for creating a custom DataWeave module are almost identical to the steps for creating a
custom mapping file. The only difference is the contents of the `.dwl` file. Unlike a typical
DataWeave script or mapping file, a custom DataWeave module cannot contain an `output` directive,
body expression, or the separator (`---`) between header and body sections. (For guidance with
mappings, see [Creating and Using DataWeave Mapping Files](#create_dw_mapping).)

![A DataWeave script with a custom function module](/mulesoft/current/en-us/dataweave/2.6/_images/dataweave-function-custom.png)

Figure 2. Example: Custom Module in a Studio Project

A custom module file can only contain `var`, `fun`, `type`, and `ns` declarations, for example:

Example: Custom DataWeave Module

```dataweave
%dw 2.0
var name = "MyData"
fun myFunc(myInput: String) = myInput ++ "_"
type User = {
    name: String,
    lastname: String
}
ns mynamespace http://acme.com/bar
```

When you import a custom module into another DataWeave script, any functions, variables, types, and
namespaces defined in the module become available for use in the DataWeave body. In the next
example, a DataWeave script:

- Imports the module `MyModule` through the `import` directive in the header. In this case, the
  imported module is stored in a Studio project path `src/main/resources/modules/MyModule.dwl`

- Calls a function in `MyModule` by using `MyModule::myFunc("dataweave")`.

Example: Importing and Using a Custom DataWeave Module

```dataweave
%dw 2.0
import modules::MyModule
output application/json
---
MyModule::myFunc("dataweave") ++ "name"
```

There are several ways to import a module or elements in it:

- Import the module, for example: `import modules::MyModule`. In this case, you must include the
  name of the module when you call the element (here, a function) in it, for example:
  `MyModule::myFunc`.

- Import all elements from the module, for example: `import * from modules::MyModule`. In this case,
  you do not need to include the name of the module when you call the element. For example:
  `myFunc("dataweave") ++ "name"` works.

- Import specific elements from a module, for example: `import myFunc from modules::MyModule`. In
  this case, you do not need to include the name of the module when you call the element. For
  example: `myFunc("dataweave") ++ "name"` works. You can import multiple elements from the module
  like this, for example: `import myFunc someOtherFunction from modules::MyModule` (assuming both
  `myFunc` and `someOtherFunction` are defined in the module).

Output

```json
"dataweave_name"
```

## Assigning a Local Alias for an Imported Element

To avoid name clashes, you can use `as` to assign an alias for a custom module or its elements when
you import the module into a DataWeave script.

Assume that you define a custom module like this one in the file `MyModule.dwl`:

Example: Custom Module

```dataweave
%dw 2.0
fun myFunc(name:String) = name ++ "_"
var myVar = "Test"
```

When you import the custom module into a DataWeave script, you can create aliases to elements in the
custom module, for example:

Example: Applying an Alias to Imported Elements

```dataweave
%dw 2.0
import myFunc as appendDash, myVar as weaveName from modules::MyModule
var myVar = "Mapping"
output application/json
---
appendDash("dataweave") ++ weaveName ++ "_" ++ myVar
```

The script returns `"dataweave_Test_Mapping"`.

You can create an alias to the imported module, for example:

Example: Applying an Alias to an Imported Module

```dataweave
%dw 2.0
import modules::MyModule as WeaveMod
output application/json
---
WeaveMod::myFunc("dataweave")
```

## Referencing a DWL File

You can use DWL files directly in Mule connectors and components.

See [dwl File](https://docs.mulesoft.com/dataweave/2.6/dataweave-language-introduction#dwl_file) for details.

## Writing Documentation for Custom DataWeave Modules

DataWeave supports use of the AsciiDoc text format for documenting your functions, types,
annotations, and the modules that contain them.

### Documenting Your DataWeave Functions

DataWeave defines a multi-section template for documenting function code. The template provides
sections for the following:

- A description of the function.

- Parameter descriptions in an AsciiDoc table format.

- Example code that includes sections for any input, the DataWeave script, and the resulting output.

To define parameter and example sections below the function description, the template uses AsciiDoc
heading grammar:

- `=== Parameters`

- `=== Example`

  - `==== Source`

  - `==== Input`

  - `==== Output`

The following function template provides guidance on documenting the function. As the template
notes, some sections are optional.

```DataWeave
/**
* %Replace with your function description%
*
*
* %Add additional information to your function description% (optional section)
*
* === Parameters (optional section)
*
* [%header, cols="1,1,3"]
* |===
* | Name | Type | Description
* | %`The parameter name`% | %`The parameter type`% | %The parameter description%  (one row per param)
* |===
*
* === Example (optional section)
*
* %The example description% (optional)
*
* ==== Source (optional section)
*
* [source,%The language%,linenums] (optional)
* ----
* YOUR CODE
* ----
*
* ==== Input (optional section)
*
* The input description (optional)
*
* [source,%The language%,linenums] (optional)
* ----
* YOUR CODE
* ----
*
* ==== Output (optional section)
*
* %The output description% (optional)
*
* [source,%The language%,linenums] (optional)
* ----
* YOUR CODE
* ----
*/
```

#### Description Section

This section provides a description of the function. The section starts at the top of the comments
and extends to the line before the first section heading. If there is no section header, the
description extends to the end of the comments for the function.

A description consists of the following parts:

- Short description: The first paragraph, which provides the primary description of the function.

- Long description: Any additional information about the function. This optional description begins
  two line breaks below the short description.

See the [example](#example-documentation) that includes a description with sections for the
parameters and examples.

Each part is useful for auto-generated documentation.

#### Parameters Section

The optional `=== Parameters` section describes parameters of the function.

The template uses AsciiDoc table format to document each parameter in a table row.

\[%header, cols="1,1,3"\] |=== | Name | Type | Description | yourParameter1 | The parameter type |
Your description here. | yourParameter2 | The parameter type | Your description here. |===

#### Example Section

You can use zero or more `=== Example` sections to provide any examples needed to illustrate how
your function works.

This section contains the following optional subsections:

- `==== Input` for input to the DataWeave script.

- `==== Source` for the DataWeave script.

- `==== Output` for output generated by the script.

All subsections follow the same template, which includes an optional description and an optional
code section:

Your section description

\[source,%The language%,linenums\]
----

YOUR CODE
----

The following example shows the [log](https://docs.mulesoft.com/dataweave/2.4/dw-core-functions-log)
function documentation.

/\*\* \* Without changing the value of the input, \`log\` returns the input as a system \* log. So
this makes it very simple to debug your code, because any expression or subexpression can be wrapped
\* with \*log\* and the result will be printed out without modifying the result of the expression.
\* The output is going to be printed in application/dw format. \* (1) \* \* The prefix parameter is
optional and allows to easily find the log output. \* \* \* Use this function to help with debugging
DataWeave scripts. A Mule app \* outputs the results through the \`DefaultLoggingService\`, which
you can see \* in the Studio console. \* \* === Parameters \* \* \[%header, cols="1,13"\] \* |=== \*
| Name | Type | Description \* | \`prefix\` | \`String\` | An optional string that typically
describes the log. \* | \`value\` | \`T\` | The value to log. \* |=== \* \* === Example \* \* This
example logs the specified message. Note that the \`DefaultLoggingService\` \* in a Mule app that is
running in Studio returns the message \* \`WARNING - "Houston, we have a problem,"\` adding the dash
\`-\` between the \* prefix and value. The Logger component's \`LoggerMessageProcessor\` returns \*
the input string \`"Houston, we have a problem."\`, without the \`WARNING\` prefix. \* \* ====
Source \* \* \[source,DataWeave,linenums\] \* ---- \* %dw 2.0 \* output application/json \* --- \*
log("WARNING", "Houston, we have a problem") \* ---- \* \* ==== Output \* \* \`Console Output\` \*
\* \[source,XML,linenums\] \* ---- \* "WARNING - Houston, we have a problem" \* ---- \* \*
\`Expression Output\` \* \* \[source,XML,linenums\] \* ---- \* "Houston, we have a problem" \* ----
\* \* === Example \* \* This example shows how to log the result of expression \`myUser.user\`
without modifying the \* original expression \`myUser.user.friend.name\`. \* \* ==== Source \* \*
\[source,DataWeave,linenums\] \* ---- \* %dw 2.0 \* output application/json \* \* var myUser =
{user: {friend: {name: "Shoki"}, id: 1, name: "Tomo"}, accountId: "leansh" } \* --- \* log("User",
myUser.user).friend.name \* ---- \* \* ==== Output \* \* \`Console output\` \* \*
\[source,console,linenums\] \* ---- \* User - { \* friend: { \* name: "Shoki" \* }, \* id: 1, \*
name: "Tomo" \* } \* ---- \* \* \`Expression Output\` \* \* \[source,DataWeave,linenums\] \* ---- \*
"Shoki" \* ---- \*/

### Documenting Your DataWeave Modules

The DataWeave module description does not follow a structured template.

The only requirement is to place the documentation above the DataWeave version tag.

The following example documents the [dw::Core](https://docs.mulesoft.com/dataweave/2.4/dw-core)
module:

```dataweave
/**
 * This module contains core DataWeave functions for data transformations.
 * It is automatically imported into any DataWeave script. For documentation
 * on DataWeave _1.0_ functions, see
 * https://docs.mulesoft.com/dataweave/latest/dataweave-operators[DataWeave Operators].
 */
%dw 2.0
```

### Documenting Your Annotation and Types

Annotation and Types documentation do not follow a structured template.

The only requirement is to write the descriptions above the Annotation or Type definition.

The following example documents the `@StreamCapable` annotation.

```dataweave
/**
* Annotation that marks a parameter as stream capable, which means that this
* field will consume an array of objects in a forward-only manner.
*/
@AnnotationTarget(targets = ["Parameter", "Variable"])
annotation StreamCapable()
```

The following example documents the `EncodingSettings` type found in the
[dw::extension::DataFormat](https://docs.mulesoft.com/dataweave/2.4/dw-dataformat) module.

```dataweave
/**
 * Represents encoding settings.
 */
@Since(version = "2.2.0")
type EncodingSettings = {
    /**
    * Encoding that the writer uses for output. Defaults to "UTF-8".
    */
    encoding?: String {defaultValue: "UTF-8"}
}
```

## See Also

- [Reusing Types from DataWeave Modules](https://docs.mulesoft.com/dataweave/2.6/dataweave-type-reuse-modules)